keybinds - MSUTeam/MSU GitHub Wiki

• Description
• Info
  • Key Combinations
    • Example
  • Game State
  • Key State
• Keybind
  • Squirrel Keybind
  • Squirrel Passive Keybind
  • Javascript Keybind
• getKeybind
  • getKeyCombinations
  • getKeyCombinationsCapitalized
• Update Keybind Key Combination
• Add a divider
• Add a title
• Check Key Combination Status
• Example
• Key Reference

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

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.

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

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 |.

::MSU.Key.State.World

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

::MSU.Key.State.Tactical

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

::MSU.Key.State.MainMenu

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

::MSU.Key.State.All

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

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.

::MSU.Key.KeyState.Press

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

::MSU.Key.KeyState.Release

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

::MSU.Key.KeyState.Continuous

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

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.

<Mod>.Keybinds.addSQKeybind( _id, _keyCombinations, _state, _function, _name = null, _keyState = null, _description = "" )
// returns the newly created keybind of class ::MSU.Class.KeybindSQ
// _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.

<Keybind>.setBypassInputDenied( _bool )

By default, MSU SQ keybinds do not trigger when a JS input or textarea element is focused.
The point of this is to avoid the keybind triggering while the user is typing in something like a name setter text element.
This behavior can be enabled or disabled for individual SQ keys with the member setBypassInputDenied. The corresponding property BypassInputDenied is initialized to false.

Key input denial can be entirely disabled with the MSU mod setting with the ID blockSQInput, found under the General page.
This should only be done in extreme cases and should be seen as a failsave.

<Mod>.Keybinds.addPassiveKeybind( _id, _keyCombinations, _name = null, _description = "")
// returns the newly created keybind of class ::MSU.Class.KeybindSQPassive
// _id, _keyCombinations, _name, _description are 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

Will do nothing, should be used with isKeybindPressed to check if it is pressed.

<Mod>.Keybinds.addJSKeybind( _id, _keyCombinations, _name = null, _description = "" )
// returns the newly created keybind of class ::MSU.Class.KeybindJS
// _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.

<Mod>.Keybinds.getKeybind( _id )
// _id is a string

Returns the keybind object of your mod with the id _id.

<keybind>.getKeyCombinations()

Returns the key combinations of this keybind as a string e.g. "h / k".

<keybind>.getKeyCombinationsCapitalized()

Returns the key combinations of this keybind as a string where the first letter of each key is capitalized e.g. "H / K".

<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

<Mod>.Keybinds.addDivider( _id )
// _id is a string

_id must be unique for all Keybinds and Settings Elements in the mod.\

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

<Mod>.Keybinds.addTitle( _id, _name )
// _id and _name are strings

_id must be unique for all Keybinds and Settings Elements in the mod.
_name will be displayed as the title.

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

<Mod>.Keybinds.isKeybindPressed(_id)
// _id is a string

_id is the id of the keybind to check\

Returns true if the Keybind with _id is currently being held down, false otherwise.

Enable the keybindsLog setting in the MSU modsettings to log a variety of debug messages, such as the pressed key and the final key combination.

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

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"
    }