Keybinds

• Description
• Info
  • Key Combinations
    • Example
  • Game State
  • Key State
• Keybind
  • Squirrel Keybind
  • Javascript Keybind
• Update Keybind Key Combination
• Add a divider
• Example
• Key Reference

Description

This system allows a mod to easily add a user-configurable function to be run when a user presses a specific key-combination. It works closely with the Mod Settings system to make the keybinds modifiable.

Info

Key Combinations

A key combination is a group of keys which will run the keybind function when pressed. Key combinations are handled as a string in the form: "key1+key2+key3" where key1...keyX are the keys that need to be pressed simultaneously for the function to be executed. The number of keys is completely arbitrary.

Key combinations are usually handled as a group, since any keybind can have any number of key combinations that will call the function in the keybind. These are then passed in the form "keycombination1/keycombination2", where a keycombinationX is a combination of keys as described above.

Example

local keyCombinations = "ctrl+c/ctrl+a/shift+alt+a";

Game State

The game has 3 distinct game states, Squirrel keybinds can be set up to be call on any of the game states by passing any combination of the below states separate by a |.

World

::MSU.Key.State.World

This is the state the game is in while the player is on the map.

Tactical

::MSU.Key.State.Tactical

This is the state the game is in during player combat.

Main Menu

::MSU.Key.State.MainMenu

This is the state the game is in while no campaign has been loaded.

All

::MSU.Key.State.All

A convenience key to be used instead of ::MSU.Key.State.World | ::MSU.Key.State.Tactical | ::MSU.Key.State.MainMenu

Key State

This is the point during a keypress that the squirrel keybind will be called.

These can also be passed as | separate keys like game states.

Press

::MSU.Key.KeyState.Press

Will call the keybind when the appropriate key combination is first pressed.

Release

::MSU.Key.KeyState.Release

Will call the keybind when the player releases any key after pressing the key combination.

Continuous

::MSU.Key.KeyState.Continuous

Will call the keybind every frame the key combination is pressed.

Keybind

MSU has 2 types of keybinds, these each have their own functions as described below. In the vast majority of circumstances, a modder should probably use a Squirrel Keybind which calls squirrel code when an appropriate key combination is pressed. For a Javascript Keybind, the keybind has to be defined in squirrel code, and the system just acts as a way to verify if the right key combination is being pressed.

Squirrel Keybind

<Mod>.Keybinds.addSQKeybind( _id, _keyCombinations, _state, _function, _name = null, _keyState = null, _description = "" )
// _id, _keyCombinations, _name, _description are strings
// _state is an entry in ::MSU.Key.State
// _function is a function
// _keyState is an entry in ::MSU.Key.KeyState

_id must be unique for all Keybinds and Settings Elements in the mod.
_keyCombinations is the default set of Key Combinations that the keybind will be usable with
_state is a Game State
_name is an optional user facing name that defaults to _id and will be used to generate a keybind setting.
_function is the function that will be called when the keybind is pressed. In the function this will be whatever state the game is currently in.
_keyState is a Key State, defaults to ::MSU.Key.KeyState.Release
_description is the description for the mod setting that will be generated

Adds a Squirrel keybind that will call _function when any key combination in _keyCombinations is in the correct _keyState and the game is in the game state _state.

JavaScript Keybind

<Mod>.Keybinds.addJSKeybind( _id, _keyCombinations, _name = null, _description = "" )
// _id, _keyCombinations, _name and _description are all strings

_id must be unique for all Keybinds and Settings Elements in the mod.
_keyCombinations is the default set of Key Combinations that the keybind will be usable with
_name is an optional user facing name that defaults to _id and will be used to generate a keybind setting.
_description is the description for the mod setting that will be generated

Adds a Javascript 'keybind' in that it allows javascript code to check if any of the key combinations are pressed by checking

MSU.Keybinds.isMousebindPressed(_modID, _id, _event)
// if the final key being pressed is a mouse button or
MSU.Keybinds.isKeybindPressed(_modID, _id, _event)
// if the final key being pressed is a key.

// _modID, _id are strings
// _event is the event passed to an eventlistener

_modID is the id of your mod passed to MSU
_id is the id of the keybind
These function should be called inside an eventListener, and therefore _event is the parameter that such a callback should have as described on the MDN Web Docs.

Update Keybind Key Combination

<Mod>.Keybinds.update( _id, _keyCombinations )
// _id and _keycombinations are strings

_id is the id of the keybind to update
_keyCombinations is the a set of key combinations

Changes the key combinations used for the Keybind to _keyCombinations

Add a Divider

<Mod>.Keybinds.addDivider( _id, _name = "" )
// _id and _name are strings

_id must be unique for all Keybinds and Settings Elements in the mod.
_name is an optional title for the Divider

Adds a Settings Divider to the keybinds page in the mod's mod settings to allow for better organization of keybinds.

Example

local mymod = ::MSU.Class.Mod("myID", "1.0.0", "Pretty Name");
// Create a mod
mymod.Keybinds.addSQKeybind("printHi", "shift+a", ::MSU.Key.State.MainMenu | ::MSU.Key.State.World, function()
{
    ::logInfo("hi");
}, "Print Hi", ::MSU.Key.KeyState.Pressed);
// add a keybind that prints "hi" when shift+a are clicked by default
mymod.Keybinds.update("printHi", "ctrl+x/shift+a");
// make ctrl+x an available key combination for the keybind

Key Reference

The values for the tables below are what a key combination can use separated by + characters

    MouseMapSQ = {
        "1" : "leftclick",
        "2" : "rightclick",
    },
    KeyMapSQ = {
        "1" : "1",
        "2" : "2",
        "3" : "3",
        "4" : "4",
        "5" : "5",
        "6" : "6",
        "7" : "7",
        "8" : "8",
        "9" : "9",
        "10" : "0",
        "11" : "a",
        "12" : "b",
        "13" : "c",
        "14" : "d",
        "15" : "e",
        "16" : "f",
        "17" : "g",
        "18" : "h",
        "19" : "i",
        "20" : "j",
        "21" : "k",
        "22" : "l",
        "23" : "m",
        "24" : "n",
        "25" : "o",
        "26" : "p",
        "27" : "q",
        "28" : "r",
        "29" : "s",
        "30" : "t",
        "31" : "u",
        "32" : "v",
        "33" : "w",
        "34" : "x",
        "35" : "y",
        "36" : "z",
        "37" : "backspace",
        "38" : "tab",
        "39" : "enter",
        "40" : "space",
        "41" : "escape",
        "44" : "end",
        "45" : "home",
        "46" : "pagedown",
        "47" : "pageup",
        "48" : "left",
        "49" : "up",
        "50" : "right",
        "51" : "down",
        "53" : "insert",
        "54" : "delete",
        "55" : "n0", // numpad keys
        "56" : "n1",
        "57" : "n2",
        "58" : "n3",
        "59" : "n4",
        "60" : "n5",
        "61" : "n6",
        "62" : "n7",
        "63" : "n8",
        "64" : "n9",
/*
        While technically present, these keys are unreliable
        "66" : "*",
        "67" : "+",
        "68" : "-",
        "70" : "/",
*/
        "71" : "f1",
        "72" : "f2",
        "73" : "f3",
        "74" : "f4",
        "75" : "f5",
        "76" : "f6",
        "77" : "f7",
        "78" : "f8",
        "79" : "f9",
        "80" : "f10",
        "81" : "f11",
        "82" : "f12",
        "83" : "f13",
        "84" : "f14",
        "85" : "f15",
        "86" : "f16",
        "87" : "f17",
        "88" : "f18",
        "89" : "f19",
        "90" : "f20",
        "91" : "f21",
        "92" : "f22",
        "93" : "f23",
        "94" : "f24",
        "95" : "ctrl",
        "96" : "shift",
        "97" : "alt"
    }