InputCandy:Advanced Under The Hood

InputCandy has the following concepts and assumptions in its design:

• All input devices are physical state machines.
• Input interpretation requires both state and time-based state using historical snapshots.
• "Controllers" (aka Gamepads, Keyboards) come in many varieties and have Buttons, Axis, Hats and the concept of Sticks.
• Most input reads from a "signal" from the device.
• "Actions" have a default signal chosen by the game designer and are assigned a name for reference.
• Actions can have custom "bindings" provided by the user, saved as a "Setting"
• Bindings are remappings of default signal to alternative signals.
• Bindings can have additional settings provided by the user, like inverting an axis value, for example.
• "Directionals" are combinations of signals that mimic an analog stick or directional pad, and therefore produce Up/Down/Left/Right states as well as an angle and overall horizontal-vertical magnitude.
• "Sticks" are a combination of two axis signals, and is a type of directional. This is also known as an "analog stick"
• "Axis" may represent things other than a "stick", like a trigger or twist sensor, and is just a value read from the device. Some devices
• "Hat" is similar to a D-Pad.
• Bindings and Actions both reference signals or directionals, but only directions when the designer allows it.
• Use of the concept of Directionals is up to the designer. It certainly complicates matters in the name of convenience.
• Reading directly from signals and devices is possible, but not recommended. Most of this has been done for game designers by correctly implementing and using Actions to describe input, rather than direct device querying. Abstractions allowing Bindings is an offshoot of this Actions systems, permitting the player to customize their input experience.

Optimized with Integer-based Lookups and Compares

To optimize InputCandy, signals for all buttons, hats, axis, "sticks" are all assigned unique integer values. These values are called "IC codes" and begin with IC_xxxx and they appear in InputCandy.gml. These codes allow designers to assign specific default signal sources or directionals to a given action that can be looked up. Bindings use the same signal codes to override the designer's default. This means signals are collected and referenced by their IC code integer value, and actions can also be indexed by integers and therefore most of the "lookups" are integer-based and most of the comparisons are also integer-based. This means its pretty fast during interpretive (VM) and using the Yoyo Compiler (YYC) is even faster. So, when you do a match for an action, it is preferred to use its action_index value rather than the action's description strings.

INPUTCANDY and its related parts

All of INPUTCANDY exists either as globally accessible functions (for binding to your game) or as the object global.INPUTCANDY.

Once initialized, InputCandy has a "pseudo-private" section that is called __ICI or "Input Candy Internal" that hides most of the code in a sub-object. You don't really need to call any of these methods, unless you are doing a custom UI for your game's input configuration and not using ICUI. There also may be some corner cases not yet identified which encourage the use or modification of the methods in __ICI. You can learn more about these methods by reading InputCandy:Advanced Private Class Reference

The global InputCandy object (__INPUTCANDY or just __IC) also has methods that are one level above private. You could call these directly, but the few that are needed in the simplest implementation case have been exposed through global functions, like IC_Step() for example. You can read more about these by reading Globally Exposed Helper Functions. There are additional methods here, described in InputCandy:Advanced global.INPUTCANDY Methods Reference that work with some of the smaller object classes found in InputCandy:Advanced Class Reference.

Additionally, the InputCandy object also holds the ICUI, a style-able user interface that has all of the functionality necessary for players to assign controllers, rebind input, test their rebindings and capture input to identify how their controller is interpreted by SDL.