Globally Exposed Helper Functions

Functions

Function	Description
Init_InputCandy_Advanced(bootstrap)	Call this to initialize the InputCandy library. It needs to be called exactly once, usually in the Startup Room's creation code, or in a start room's controller object's Creation Event. Usually at the same time you will also create your master list of actions. This master list of actions should be ready when frame 5 is hit and the settings and setup is loaded. bootstrap refers to a struct with a single property init that defines the function which creates your game's actions. This must be provided because the Init_InputCandy_Advanced function must load settings knowing what your actions table looks like. An example is provided in the sample project. It looks something like: Init_InputCandy_Advanced( { init: function() { /* create your IC actions here */ } );
IC_Step()	Call this function in your game's controller objects. It should be called exactly once per frame for any room where you want to read from the InputCandy input states (generally once per frame in every room the player interacts with, including the main menu).
IC_NewAction()	Returns an empty ICAction object as described in Input:Advanced Class Reference, you can modify the values on this object and then use IC_ActionPush() to add it to your action list.
IC_ActionPush( action_object )	After you customize the struct returned from IC_NewAction(), you can pass it to this function to add it to the master action list __INPUTCANDY.actions[]
IC_Action_ext( name, group, gamepad, gamepad_is_combo, keyboard, keyboard_is_combo, mouse, mouse_is_combo, keyboard_mouse_are_combo, is_directional, requires_angle, held_for_seconds, fire_limit_count, fire_on_release, enabled, forbid_rebinding )	This function provides a functional way to create a new action providing you with a way to access __IC.Action_ext(). Read the section below that highlights exactly how you can use this function by breaking down each parameter and its possible values.
IC_GetAction( action_name, [action_group] )	Retrieves the action index from the master list by name or by name and group.
IC_Match( player_number, action_index )	Checks if a player is currently invoking an action by index. A binding may override the default input configuration. This is how you "check for" an action in your game.
IC_Action( verb_string, default_gamepad, default_keyboard [mouse, group, is_directional, requires_angle, enabled] )	The simplest way to define a new action, but it doesn't expose a ton of options. The final five options are all optional parameters.
IC_ClearActions()	This function clears all actions from the master __INPUTCANDY.actions[] list. It isn't that useful since you generally want one set master list of actions that persists for the entire game, defining them in the very beginning before settings are even loaded.
ICDeviceTypeString(i)	Pass in ICDeviceType_* and get back a string version.

IC_Action(verb_string, default_gamepad, default_keyboard, [mouse, group, is_directional, requires_angle, enabled] )

This function is a simpler way to define an action. It lets you define the bare minimum for most simple actions. The action is then appended to the master action list.

A breakdown of the options in the function IC_Action:

Parameter	Purpose and Value Options
verb_string	The action's name, for later lookup when using IC_Match(). A string like "Jump"
default_gamepad	The action's IC_code or an array of codes providing options for the gamepad. For example if you want two buttons assigned to this action, you would provide [ IC_A, IC_B ] otherwise only one like IC_Y
default_keyboard	The key or keys IC_code or array of codes providing options for the keyboard. For example if you want two keys assigned to this action, you would provide [ IC_lshift, IC_rshift ] otherwise just one like IC_pgdn
mouse	(optional) A mouse-related IC_code or codes. Related to the mouse wheel or buttons.
group	(optional) A string defining the name of the group that this action is a part of. It should match exactly with other actions in the same group.
is_directional	(optional) Set to true to indicate this is a directional and should accept the 4-way combination IC-codes like IC_WASD and IC_dpad
requires_angle	(optional) A true false value, where true means "requires an angle" -- setting this value is just to "remind" you which actions require an angle read from them, as all directionals will have angles calculated from their movement combination.
enabled	(optional) You generally want this to be true, otherwise the action will be ignored until you change the value in the master list.

IC_Action_ext

This function maps its parameters to the ICAction object type. It lets you define all of the features of an action in a function call, and appends that action to the master action list.

A breakdown of the options in IC_Action_ext( n, g, gp, gpcombo, kb, kcombo, m, mcombo, kmcombo, UDLR, angled, held_s, flimit, on_rel, enabled, forbid ):

Parameter	Purpose and Value Options
n	Action Name, a string
g	Action Group, a string that groups actions together
gp	Gamepad settings. Like all three device signal types (keyboard, mouse, gamepad), you can pass either a single IC_code or an array [ a,b,c ] of codes.
gpcombo	If this parameter is true, all of the codes provided for the "gp" parameter must be present to create a match. If false, only one must match.
kb	Keyboard IC_code or array of codes for default keyboard input for this action.
kbcombo	If this parameter is true, all of the codes provided for the "kb" parameter must be present to create a match. If false, only one must match.
m	Mouse IC_code or an array of codes for the mouse buttons and mouse wheel.
mcombo	If this parameter is true, all of the codes provided for the "m" parameter must be present to create a match. If false, only one must match.
kmcombo	If this parameter is true, all of the codes provided for both the "kb" parameter and the "m" parameter must be present to create a match. If false, only one must match.
UDLR	A true false value, where true means "is_directional" -- that this is a 4-way directional control, like WASD or DPad or a Hat or Axis.
angled	A true false value, where true means "requires an angle" -- setting this value is just to "remind" you which actions require an angle read from them, as all directionals will have angles calculated from their movement combination.
held_s	Number of seconds (a decimal value) before the action is triggered. Set to 0 if you don't care to wait.
flimit	The number of times this will fire once it has been triggered. An example is, if you want something to "power up then fire 3 times" before the player must release the button to reset the action counter.
on_rel	When this parameter is set to true, the action will only match on the frame when the button is released.
enabled	Generally you want this to be true. If you set it to be false, the action will be ignored until the value is changed to true.
forbid	When you set this to true it won't let the player customize this option in the ICUI.

IC Codes Table

Where to find IC codes? See them in the signals array __INPUTCANDY.signals, found in InputCandy.gml

/*
 Button signals
 I'm from the US so it's US-based, but provides AZERTY and QWERTZ alternative names to rectify this.
 Call it by the QWERTY name
 */
#macro IC_none 0
#macro IC_anykey 1
#macro IC_left 2		// Not directly tied to a key, this maps specially to indicate "left" similar to InputCandySimple see below
#macro IC_right	3		// Not directly tied to a key, this maps specially to indicate "left" similar to InputCandySimple see below
#macro IC_up 4			// Not directly tied to a key, this maps specially to indicate "left" similar to InputCandySimple see below
#macro IC_down 5			// Not directly tied to a key, this maps specially to indicate "left" similar to InputCandySimple see below
#macro IC_A 6
#macro IC_B 7
#macro IC_AandB 8
#macro IC_X 9
#macro IC_Y 10
#macro IC_XandY 11
#macro IC_start 12
#macro IC_back_select 13
#macro IC_Ltrigger 14
#macro IC_Rtrigger 15
#macro IC_Lshoulder 16
#macro IC_Rshoulder 17
#macro IC_Lstick 18
#macro IC_Rstick 19
#macro IC_padu 20
#macro IC_padd 21
#macro IC_padl 22
#macro IC_padr 23
#macro IC_mouse_left 24
#macro IC_mouse_right 25
#macro IC_mouse_middle 26
#macro IC_mouse_scrollup 27
#macro IC_mouse_scrolldown 28
#macro IC_key_arrow_L 29
#macro IC_key_arrow_R 30
#macro IC_key_arrow_U 31
#macro IC_key_arrow_D 32
#macro IC_backspace 33
#macro IC_any_alt 34
#macro IC_any_shift 35
#macro IC_any_control 36
#macro IC_lalt 37
#macro IC_ralt 38
#macro IC_lctrl 39
#macro IC_rctrl 40
#macro IC_lshift 41
#macro IC_rshift 42
#macro IC_tab 43
#macro IC_pause 44
#macro IC_print 45
#macro IC_pgup 46
#macro IC_pgdn 47
#macro IC_home 48
#macro IC_end 49
#macro IC_insert 50
#macro IC_delete 51
#macro IC_numpad0 52
#macro IC_numpad1 53
#macro IC_numpad2 54
#macro IC_numpad3 55
#macro IC_numpad4 56
#macro IC_numpad5 57
#macro IC_numpad6 58
#macro IC_numpad7 59
#macro IC_numpad8 60
#macro IC_numpad9 61
#macro IC_numpad_multiply 62 /* numpad * */
#macro IC_numpad_divide 63  /* numpad / */
#macro IC_numpad_subtract 64 /* numpad - */
#macro IC_numpad_add 65 /* numpad + */
#macro IC_numpad_decimal 66 /* numpad . */
#macro IC_f1 67
#macro IC_f2 68
#macro IC_f3 69
#macro IC_f4 70
#macro IC_f5 71
#macro IC_f6 72
#macro IC_f7 73
#macro IC_f8 74
#macro IC_f9 75
#macro IC_f10 76
#macro IC_f11 77
#macro IC_f12 78
#macro IC_key_A 79
#macro IC_key_B 80
#macro IC_key_C 81
#macro IC_key_D 82
#macro IC_key_E 83
#macro IC_key_F 84
#macro IC_key_G 85
#macro IC_key_H 86
#macro IC_key_I 87
#macro IC_key_J 88
#macro IC_key_K 89
#macro IC_key_L 90
#macro IC_key_M 91
#macro IC_key_N 92
#macro IC_key_O 93
#macro IC_key_P 94
#macro IC_key_Q 95
#macro IC_key_R 96
#macro IC_key_S 97
#macro IC_key_T 98
#macro IC_key_U 99
#macro IC_key_V 100
#macro IC_key_W 101
#macro IC_key_X 102
#macro IC_key_Y 103
#macro IC_key_Z 104
#macro IC_key_0 105
#macro IC_key_1 106
#macro IC_key_2 107
#macro IC_key_3 108
#macro IC_key_4 109
#macro IC_key_5 110
#macro IC_key_6 111
#macro IC_key_7 112
#macro IC_key_8 113
#macro IC_key_9 114
#macro IC_key_backtick 115
#macro IC_key_comma 116
#macro IC_key_period 117
#macro IC_key_slash 118
#macro IC_key_backslash 119
#macro IC_key_minus 120
#macro IC_key_equals 121
#macro IC_key_lbracket 122
#macro IC_key_rbracket 123
#macro IC_key_semi 124
#macro IC_key_apostrophe 125
#macro IC_enter 126
#macro IC_space 127
#macro IC_key_escape 128
#macro IC_hat0_U 129
#macro IC_hat0_D 130
#macro IC_hat0_L 131
#macro IC_hat0_R 132
#macro IC_hat1_U 133
#macro IC_hat1_D 134
#macro IC_hat1_L 135
#macro IC_hat1_R 136
#macro IC_hat2_U 137
#macro IC_hat2_D 138
#macro IC_hat2_L 139
#macro IC_hat2_R 140
#macro IC_hat3_U 141
#macro IC_hat3_D 142
#macro IC_hat3_L 143
#macro IC_hat3_R 144
#macro IC_hat4_U 145
#macro IC_hat4_D 146
#macro IC_hat4_L 147
#macro IC_hat4_R 148

#macro IC_MAX_SIGNAL 148

////// Action pad indications.  A special category of action.

/* 
  Unlike buttons, a single signal, Axis, Hats and DPads are different.
  
  Actions that are for movement (usually) but may be used
  with secondary movement (aiming a turret for example), the user may want
  to swap Axis 0 for Axis 1, or Hat 1 for the Dpad
   */

// Directional pad.  Controllers tend to have 1 of these. LRUD
#macro IC_dpad 200

// Hats are a strange hybrid between Dpad and simply an array of 4 buttons.  LRUD usually
// Sometimes "Hats" are the joystick itself.  Hats can also be thumb buttons.
// Hats can also be unidirectional (up/down)
#macro IC_hat0 300
#macro IC_hat1 301
#macro IC_hat2 302
#macro IC_hat3 303
#macro IC_hat4 304
#macro IC_hat5 305
#macro IC_hat6 306
#macro IC_hat7 307
#macro IC_hat8 308
#macro IC_hat9 309


// Axis sticks are usually "horizontal and vertical" 0-1, where 0.5, 0.5 would mean "up right"
// The Classic Controller "Twist" on the Atari is only horizontal and is a special case.
// Axis sticks can also be used to define a slider control on some specialty joysticks.
// You can convert an Axis H/V value into an angle-of-direction with point_direction or __IC.AxisToAngle
// Axis values can also be converted into 4-directional indicators similar to DPads and Hats
#macro IC_axis0 400
#macro IC_axis1 401
#macro IC_axis2 402
#macro IC_axis3 403
#macro IC_axis4 404
#macro IC_axis5 405
#macro IC_axis6 406
#macro IC_axis7 407
#macro IC_axis8 408
#macro IC_axis9 409


/// BUTTONS

#macro IC_btn0   440
#macro IC_btn1   441
#macro IC_btn2   442
#macro IC_btn3   443
#macro IC_btn4   444
#macro IC_btn5   445
#macro IC_btn6   446
#macro IC_btn7   447
#macro IC_btn8   448
#macro IC_btn9   449
#macro IC_btn10  450
#macro IC_btn11  451
#macro IC_btn12  452
#macro IC_btn13  453
#macro IC_btn14  454
#macro IC_btn15  455
#macro IC_btn16  456
#macro IC_btn17  457
#macro IC_btn18  458
#macro IC_btn19  459
#macro IC_btn20  460
#macro IC_btn21  461
#macro IC_btn22  462
#macro IC_btn23  463
#macro IC_btn24  464
#macro IC_btn25  465
#macro IC_btn26  466
#macro IC_btn27  467
#macro IC_btn28  468
#macro IC_btn29  469
#macro IC_btn30  470
#macro IC_btn31  471
#macro IC_btn32  472
#macro IC_btn33  473
#macro IC_btn34  474
#macro IC_btn35  475
#macro IC_btn36  476
#macro IC_btn37  477
#macro IC_btn38  478
#macro IC_btn39  479

// Arrow keys, a movement option
#macro IC_arrows 500
#macro IC_wasd   501
#macro IC_numpad 502