ScriptENGINE:

Keymap example.
Keymapping makes it easy to allow the user to decide what keys should be assigned to program actions.
Your program refers to the keymap action name,
rather than the direct key code, so the key code
can change without breaking your scripts.
---------------------------
---------------------------
-- Keymap example
-- Copyright (c) 2007-09 Capricorn 76 Pty. Ltd.
--
-- Keymapping makes it easy to allow the user to
-- decide what keys should be assigned to program actions.
--
-- Your program refers to the keymap action name,
-- rather than the direct key code, so the key code
-- can change without breaking your scripts.
--
-- NOTE:
-- The ./Demos/runDemo.e76script is a utility script used to run all the examples.
-- It loads the world, calls the OnWorldLoad(), OnWorldUnload() functions, and runs the graphics engine loop, waiting for the user to press escape.
---------------------------
---------------------------

local subGui;
local subKey;

---------------------------
-- runDemo.e76script calls this function when the world is loaded
---------------------------
function OnWorldLoad(worldName)
    --print('OnWorldLoad');

    ---------------------------
    -- The SDK world editor creates a worldIds.e76script when the world is saved. It contains all the entity ids.
    -- We load the IDs so that we can refer to the world entities using friendly names.
    ---------------------------
    IApp:loadScript(IWorld:getNameLong() .. '/worldIds');
    IWorld:setActiveCameraId(idCamera_cam1);

    ---------------------------
    -- Load constants used with this example
    ---------------------------
    IApp:loadScript(IApp:getExeFilePath() .. './Constants/constantsKeyCodes');      -- These constants make it simpler to reference key codes rather than use their hexadecimal codes

    ---------------------------
    -- Load the key code translations (this will translate hex codes like 0x70 to readable strings like 'F1')
    ---------------------------
    IApp:loadSingleTranslation('english.e76language');  -- Load this single language file. As opposed to loadTranslations() which will load all language files matching the given file mask in the filesystem.

    -- Load this example's GUI
    OnWorldLoadGui();

    ---------------------------
    -- Subscribe to gui events.
    -- We need to know when the user has changes the combobos selection.
    ---------------------------
    subGui = IEvents:subscribeGui('OnGui');

    ---------------------------
    -- Subscribe to key events.
    -- We will rotate Agent when the user presses the correct keys.
    ---------------------------
    subKey = IEvents:subscribeKey('OnKey');

    ---------------------------
    -- Example:
    -- Show how we can iterate over the internally managed camera key codes.
    -- The callback function will be called for each key code.
    --
    -- The IKey:forEachKeyCode() will iterate over all key codes
    ---------------------------
    IKey:forEachCameraKeyCode('OnCameraKeyCode');
end

function OnCameraKeyCode(actionName)
    --print('[OnCameraKeyCode]', actionName);
end

---------------------------
-- Load this examples gui
---------------------------
function OnWorldLoadGui()
    ---------------------------
    -- Let's show the run mode gui
    ---------------------------
    IGraphics:loadGui('help');

    ---------------------------
    -- Add some key codes to our map specifically for use with this example
    ---------------------------
    IKey:addActionKeyCode('exampleStepAgentLeft',   'Step left',  KEY_LEFT, false,  false);
    IKey:addActionKeyCode('exampleStepAgentRight',  'Step right', KEY_RIGHT,    false,  false);
    IKey:addActionKeyCode('exampleSpinAgentLeft',   'Spin left',  KEY_LEFT, false,  true);
    IKey:addActionKeyCode('exampleSpinAgentRight',  'Spin right', KEY_RIGHT,    false,  true);

    ---------------------------
    -- Change the auto-camera keycodes
    -- Uncomment these lines to change the key codes used to move the camera about.
    -- Note that these will remain after the world is unloaded.
    ---------------------------
    --[[
        IKey:setActionKeyCode('cameraMoveForward',  0, KEY_UP);
        IKey:setActionKeyCode('cameraMoveBackward', 0, KEY_DOWN);
        IKey:setActionKeyCode('cameraStrafeLeft',   0, KEY_LEFT);
        IKey:setActionKeyCode('cameraStrafeRight',  0, KEY_RIGHT);
    ]]

    -- Load the keymap into the listbox
    refreshKeyList();
end

---------------------------
-- runDemo.e76script calls this function when the world is unloaded
---------------------------
function OnWorldUnload(worldName)
    --print('OnWorldUnload');

    ---------------------------
    -- Unsubscribe to events.
    -- We will no longer be notified of gui or key events.
    ---------------------------
    IEvents:unsubscribe(subGui);
    IEvents:unsubscribe(subKey);

    ---------------------------
    -- remove the keymap actions we previously added for this example
    ---------------------------
    IKey:removeAction('exampleStepAgentLeft');
    IKey:removeAction('exampleStepAgentRight');
    IKey:removeAction('exampleSpinAgentLeft');
    IKey:removeAction('exampleSpinAgentRight');
end

------------------------
-- Handle gui event
------------------------
function OnGui(callerId, eventType, userData)

    --------------------------
    -- If the combo is change then we set new action key codes
    --------------------------
    if (IGraphics:comboChanged('comboKeyMap', callerId, eventType)) then
        selection = IGraphics:getComboboxSelection('comboKeyMap');

        if (selection == 0) then
            IKey:setActionKeyCode('exampleStepAgentLeft',   0,  KEY_LEFT);
            IKey:setActionKeyCode('exampleStepAgentRight',  0,  KEY_RIGHT);
            IKey:setActionKeyCode('exampleSpinAgentLeft',   0,  KEY_LEFT);      -- control is still defined
            IKey:setActionKeyCode('exampleSpinAgentRight',  0,  KEY_RIGHT); -- control is still defined

        elseif (selection == 1) then
            IKey:setActionKeyCode('exampleStepAgentLeft',   0,  KEY_KEY_N);
            IKey:setActionKeyCode('exampleStepAgentRight',  0,  KEY_KEY_M);
            IKey:setActionKeyCode('exampleSpinAgentLeft',   0,  KEY_KEY_N); -- control is still defined
            IKey:setActionKeyCode('exampleSpinAgentRight',  0,  KEY_KEY_M); -- control is still defined

        else
            IKey:setActionKeyCode('exampleStepAgentLeft',   0,  KEY_KEY_9);
            IKey:setActionKeyCode('exampleStepAgentRight',  0,  KEY_KEY_0);
            IKey:setActionKeyCode('exampleSpinAgentLeft',   0,  KEY_KEY_9); -- control is still defined
            IKey:setActionKeyCode('exampleSpinAgentRight',  0,  KEY_KEY_0); -- control is still defined
        end

        refreshKeyList();
    end
end

------------------------
-- Handle gui event
------------------------
function OnKey(keyCode, keyState, controlKeyDown, shiftKeyDown, userData)
    -- any keypresses on actions we've defined?

    ----------------------------
    -- Did the user press the left action?
    ----------------------------
    if (IKey:isActionClicked('exampleStepAgentLeft') or
        IKey:isActionOn('exampleSpinAgentLeft')) then
        IWorld:manipulateEntity(idAgent_Mech, 'rotate', 0, -3, 0);

    ----------------------------
    -- Did the user press the right action?
    ----------------------------
    elseif (IKey:isActionClicked('exampleStepAgentRight') or
            IKey:isActionOn('exampleSpinAgentRight')) then
        IWorld:manipulateEntity(idAgent_Mech, 'rotate', 0, 3, 0);

    end
end

------------------------
-- Load the keycodes into the listbox
------------------------
function refreshKeyList()
    IGraphics:clearListbox('list');

    ---------------------------
    -- Iterate over all the assigned key codes,
    -- and fire our callback function.
    -- For each key code, we will check if it's one we added
    -- for this example (ie. starts with 'example')
    ---------------------------
    IKey:forEachKeyCode('addKeyToList');
end

function addKeyToList(actionName)
    ----------------------
    -- We are only interested in the actions we have created for this example.
    ----------------------
    if (string.find(actionName, 'example') == 1) then
        for i = 0, IKey:getActionKeyCount(actionName)-1 do
            ----------------------
            -- Format the key code (e.g "Ctrl + Shift + a")
            ----------------------
            label = '(';

            if (IKey:getActionKeyControlState(actionName, i)) then
                label = label .. IApp:translate('keyCodes', '0x11') .. ' + ';   -- Use the language file to translate the 0x11 into a text string (eg. Ctrl)
            end

            if (IKey:getActionKeyShiftState(actionName, i)) then
                label = label .. IApp:translate('keyCodes', '0x10') .. ' + '; -- Use the language file to translate the 0x10 into a text string (eg. Shift)
            end

            ----------------------
            -- Translate the hex key repesentation (eg. 0x55) into a text string
            -- The translations are loaded from the keyCodes.e76language file
            ----------------------
            label = label .. IApp:translate('keyCodes', IKey:getActionKeyCodeHex(actionName, i));
            label = label .. ')     ';

            ----------------------
            -- Display the description
            ----------------------
            label = label .. IKey:getActionKeyDescription(actionName, i);

            ----------------------
            -- Add the test to the listbox
            ----------------------
            idx = IGraphics:addListboxItem('list', label);

            ----------------------
            -- Set the listbox key
            ----------------------
            IGraphics:setListboxData('list', idx, actionName .. ':' .. tostring(i));
        end
    end
end