InputCandy:Advanced global.IC Reference

Everything about the global.IC (instance of InputCandy) object explained, starting with the global settings object.

You can reference this object with __INPUTCANDY or __IC instead of typing out global.IC

You can also define your own custom one somewhere in your game:

#macro INPUT __INPUTCANDY

For default settings, modify global.INPUTCANDY_DEFAULTS prior to invoking Init_InputCandy_Advanced() or modify InputCandy.gml at your peril.

global.INPUTCANDY_DEFAULTS

These default settings can be modified to change the behavior of INPUTCANDY. You should do so by modifying InputCandy.gml, where it "lives". Half of the values are actually just the starting structure of InputCandy, and shouldn't be modified. Anything above the line //// External and Internal interface objects can be changed, but most of these settings you won't need to touch. You will probably only want to modify the max_players setting, possibly a few others.

If you need to modify these values after initialization, these are copied to the global.INPUTCANDY object during initialization.

Option	Values and Description
ready	This value should always be false. It turns to true when you have initialized InputCandy. You can check against this value to determine if InputCandy is being used.
steps	This value should always be unknown. It becomes a step counter used by __IC.Step() to load the settings and setup. Once these things are loaded and activated, this value will be >= 5.
max_players	This is the value fed to SetMaxPlayers() during __ICI.Init()
player_using_keyboard_mouse	This value is 0 indicating that player 1 uses the keyboard and mouse by default.
allow_multicapture_button	When true, this allows players to assign multi-button combos to a single action, set to false for simplicity
allow_keyboard_mouse	This value is true and allows the keyboard and mouse options to be shown in the ICUI. It can be turned off when publishing to linux-based consoles, if you don't want a keyboard and mouse interface option.
allow_SDL_remapping	This value is false because if you do allow remapping, it may not work as expected. This means it will attempt to automatically pair SDL remapping strings based on your input devices. SDL remapping doesn't really help that much, so I'd leave it off.
keyboard_layout	There are several values for ICKeyboardLayout_* that can be set to EU, French and German keyboards. (qwerty is default). There is no way to detect this in GameMaker, so if you do wish to attempt to support a specific area, you will need to somehow set this value at some point after you initialize.
skip_simplified_axis	Set this value to true to stop IC from registering simplified axis movements. I'm not sure if this really does what it claims. Originally I think this was an optimization that is no longer in use.
use_network	The value false indicates the network module is going to be used. Since there is no network module yet, this value has no effect.
settings_filename	Where player-defined settings are saved.
setup_filename	This file is saved and attempts to remember which settings go with which player and which device, and which SDL remappings are desired

The rest of the values are covered in the following section, as they are part of the global.IC object. You should not modify any other values in the global.INPUTCANDY_DEFAULTS prototype.

global.IC

Property	Purpose / Description
actions	The global actions list. You use Globally Exposed Helper Functions related to actions to define these.
devices	The global devices list that is managed for you. A list of detected devices and their capabilities and remappings. On any given frame it contains a list of connected devices. You probably won't be access this directly.
states	A list of detected states for gamepads and controllers only, collected for each frame that correspond in index to their associated device on the devices list. You can check this directly but it is better not to, and to use IC_Match(...) and the actions system.
keys	A list of detected keys being held for the keyboard. You don't need to access this directly, but you could.
mouseStates
mouse	A snapshot of the mouse from the current frame, collected ideally at the beginning of the frame. You can check against this to determine mouse position and button states. It is a struct that looks like { x: none, y: none, left: false, middle: false, right: false, up: false, down: false } "up" and "down" refer to the scroll wheels.
wasMouse	The previous frame's snapshot of the mouse.
signals	Master collection of signals from all device types supported. This is populated during initialization. It contains a special table containing the IC_code values, their friendly names and other useful data. It is indexed by IC_code values up to IC_MAX_SIGNAL, so you can iterate through this if you want.
directionals	Master collection of directional signal combinations, being a combination of keys, D-Pad, axis values or a hat 4-way encoded value. You can test a device's support for a specific value with __ICI.DirectionalSupported(..) explained in the InputCandy:Advanced Private Class Reference, a method used in the ICUI. These are also IC_code values but are not in the signals list, and do not refer directly to an atomic signal. Instead, they represent conceptual signal groupings that create "sticks" ... specifically for directional movement. You do not need to use directionals in your actions definition and can, instead, allow players to map specific directions like "Move Left" and "Move Up" without delving into this concept at all. It may be easier for players to use the ICUI if you do not use Directionals, however it is provided for convenience. You should only set is_directional to true on actions that are going to use this type of IC code, not on individual movement directions.
previous_devices	This is not currently used. It was originally planned to somehow detect changes to the system and use this to do matching against multiple ICSetup and ICSettings. Because there is no good way to use this yet discovered, it is no longer used.
players	The list of players and their chosen device and active ICSettings reference.
settings	The list of settings (config and bindings) saved in the system that are referenced by players to activate them.
setup	The current state or a snapshot of the current state of all players, their chosen devices and settings, used to create a feeling of persistence when reloading the same game with the same controllers connected.
network	TBD. Not currently used.
platform	Contains information from __ICI.GetPlatformSpecifics() populated during initialization. Contains information about the host computer/console and basic support questions that you can ask with GameMaker.
e_controller_connected	Event function called when a controller is connected. It can be overridden. See below.
e_controller_disconnected	Event function called when a controller is disconnected. It can be overridden. See below.
e_save_file	Event function called when a file is saved. It can be overridden to make it save in a different app/work folder. See below.
e_load_file	Event function called when a file is loaded. It can be overridden to make it load from a different app/work folder. See below.

Event Functions

You can override functions e_controller_connected, e_controller_disconnected, e_save_file, e_load_file only if you absolutely need to. These events are triggered when a file is saved or loaded, or the controller is connected or disconnected. Use the existing functions as templates. Replacement functions must have the same number of default parameters and the same return format.

InputCandy:Advanced global.IC Methods Reference