LGUI2:Input Bindings

From Lavish Software Wiki
Jump to navigation Jump to search

LavishGUI 2 implements an input bindings system with support for various types of input controls including axis (thumbsticks, triggers, etc) and directional pad (D-pad) controls. Input bindings designed in JSON format.

An Input Binding binds an input control combination to an Event Handler. When all input controls are moved into the required position for the Input Binding to activate, the Event Handler fires with an "activated" boolean value, and then again when controls are no longer in the required position with the "activated" value set to false. LavishGUI 2 has several options for identifying Input Controls, and multiple ways to configure Event Handlers.

Here is an example Input Bindings list that can be loaded into LavishGUI 2
[
	{
		"name":"I did it!",
		"controls":"VK_LBUTTON",
		"modifiers":"alt",
		"eventHandler":["method","MyBindingController","IDidIt"]
	}
]

The above example will execute the LavishScript method MyBindingController:IDidIt when pressing or releasing Alt+Mouse1. Event Handlers may also opt to directly embed LavishScript code (as done with LavishGUI), but we recommend providing a controller object as best practice.

Defining an Input Binding

Each Input Binding is defined by a JSON object, enclosed by {}.

Each binding must have at least a "name", "controls", and "eventHandler", and can optionally have "modifiers". Please note that these are case sensitive, so "Name" is incorrect, while "name" is correct.

name

The name of the Input Binding may be displayed to the user, for example to re-configure the required controls. It should therefore make some sort of sense to the user, and should usually be related to the intention of the Event Handler -- what is it going to do?

controls

"controls" may be provided as a string, or in more complicated cases may be provided as an array of strings and/or objects.

As a string

When providing controls as a string, one or more buttons (and only button controls) may be specified and separated by +. For example, "A+B" would require both A and B be pressed at the same time.

Control Names

LGUI 2 can interpret control names provided as part of a string in a few different ways:

  • A Virtual-key code number, in base 10, will be recognized as the appropriate keyboard button. Noting that 1 through 0 are actual key names, this only applies to virtual-key code numbers 10-255, and therefore the mouse buttons (with their code numbers under 10) are also excluded.
  • A Virtual-key code name such as VK_LBUTTON or VK_A will be recognized as the appropriate mouse or keyboard button
  • Mouse1 through Mouse5 will be recognized as the appropriate mouse button
  • Any other value is assumed to be the control name itself, with no assumption about which input device the control comes from (examples: A, B, C, D, G15-G1, etc)

It is acceptable to mix any combination of these, for example VK_LBUTTON+A is the same as VK_LBUTTON+VK_A or VK_LBUTTON+65 -- 65 being the code number for 'A'.

Objects in an array

More complicated control requirements, such as the use of axis/trigger or directional pad controls, can each be defined with an object. The values provided in the object will later determine if a control being moved matches the given parameters.

Input Control matching
All values optional, although at least one value must be provided.
controlName The name of the Input Control, according to Inner Space, such as "A" or "B"
controlVKeyName The Virtual-key code name for the control, such as "VK_LBUTTON" or "VK_A"
controlID The input device's ID number for the control, such as 1 or 2
controlType One of the following values: "button" "mousebutton" "dpad" "axis" "mousewheel" "cursor" "note"
controlChannel For MIDI controls, the MIDI Channel
deviceName "Keyboard" or "Mouse", or Inner Space's name for an alternative Input Device, such as "G15 Keyboard (22-input)" or "XBOX 360 For Windows (Controller) (16-input)"
deviceProductID The device manufacturer's Product ID number for the device. Provide as a JSON string in base 16, or as a JSON number in base 10. For example from "045E-028E XBOX 360 For Windows (Controller) (16-input)" the base 16 Product ID is 028E, which is the number 654. This would be provided like "deviceProductID":654 or "deviceProductID":"028E"
deviceManufacturerID The device manufacturer's USB ID number. Provide as a JSON string in base 16, or as a JSON number in base 10. For example from "045E-028E XBOX 360 For Windows (Controller) (16-input)" the base 16 Manufacturer ID is 045E, which is the number 1118. This would be provided like "deviceManufacturerID":1118 or "deviceManufacturerID":"045E"
deviceType One of the following values: "keyboard" "mouse" "midi" "other"
devicePort For MIDI devices, the name of the MIDI "port" as specified by Inner Space
minValue A number usually between 0.0 and 1.0 representing the minimum position of the control in order to activate the binding.
maxValue A number usually between 0.0 and 1.0 representing the maximum position of the control in order to activate the binding. By default, this is inclusive.
value A number usually between 0.0 and 1.0 representing both the minimum and maximum position of the control in order to activate the binding. (For example, a button may use 1.0 to mean the button is pressed, or 0.0 to mean the button is not pressed)
minX A minimum X value, used only for "Cursor"
maxX A maximum X value, used only for "Cursor"
minY A minimum Y value, used only for "Cursor"
maxY A minimum Y value, used only for "Cursor"
valuesRelative Specifies whether the X and Y values provided are relative. By default, absolute cursor position is used.
maxValuesExclusive Specifies whether the maximum value (or in the case of "Cursor", the maximum X and Y values) is exclusive. By default, the maximum value is inclusive and thus may match the minimum.

Control Types and their values

  • button and mousebutton: 1.0 for pressed, or 0.0 for not pressed
  • axis: Values 0.0 to 1.0
  • note: Values 0.0 to 1.0
  • dpad: -1.0 at rest. 0.0-359.99 for direction, being degrees clockwise from up=0.0, so right=90.0, down=180.0, left=270.0
  • mousewheel: Mouse wheel ticks are 120.0, with up being negative. -120.0 is up one tick, -240.0 is up two ticks. 240.0 is down two ticks.
  • cursor: The cursor has both an X and Y value. In absolute positioning mode, the top left corner of the client area of the host window (Inner Space Uplink, the game, etc) is 0,0, with X increasing to the right and Y increasing downward. The values are tied to the host window's 3D resolution. In relative positioning mode (used if valuesRelative is specified as true), the difference from the previous position is used; for example, if the cursor moved from 100,100 to 125,75, the relative X,Y values are 25,-25.

modifiers

"modifiers" specifies the set of Alt, Ctrl, Shift, and Win keys that must be pressed with the list of controls for the input binding to activate. This can be specified as one string with plus-separated modifier names, as an array of modifier names, or a JSON object with boolean properties for each required modifier.

As a string

When listing modifiers this way, one or more modifiers may be specified, and separated by +. For example, "alt+ctrl" would require both alt and ctrl be pressed at the same time.

Modifier names

Modifier names
alt Either Alt
ctrl Either Ctrl
shift Either Shift
win Either Win
lalt Left Alt
lctrl Left Ctrl
lshift Left Shift
lwin Left Win
ralt Right Alt
rctrl Right Ctrl
rshift Right Shift
rwin Right Win

As an array of strings

When provided as an array of strings, the same modifier names are used but are separated in the array rather than separated by a plus. For example, ["alt","ctrl"] would require both alt and ctrl be pressed at the same time.

As an object

When provided as an object (which have case sensitive), camelCase is used to specify modifier names that begin with l or r -- so lalt becomes lAlt, lshift becomes lShift, and so on. Otherwise, use any modifier name from the above table and specify a boolean value (true or false), such as {"alt":true,"ctrl":true} to require both alt and ctrl be pressed at the same time.

eventHandler

The Event Handler specifies what should happen when the input binding is activated or deactivated. It is specified as either an array or an object. Although this page provides an example, please refer to the main Event Handler page for details!

Loading Input Bindings into LavishGUI 2

The LGUI2 object includes a LoadBindingsFile method, which will load a bindings file containing an array of JSON objects and apply the bindings to the LavishGUI 2 root.

LGUI2:LoadBindingsFile[somefile.json]

LavishGUI 2 is currently in active development. There will be additional ways to load input bindings in future updates. Feel free to put in requests!

LavishGUI 2 Topics