-
Notifications
You must be signed in to change notification settings - Fork 0
InputCandy:Advanced Class Reference
h3rb edited this page Apr 2, 2021
·
6 revisions
A complete developers reference to the internal functions of InputCandy. These functions are invoked within the master global.INPUTCANDY interface class, or are used in lists or for defining things like actions and bindings.
Created with: __IC.New_ICDevice()
This class is used to build the gamepad device table of __INPUTCANDY.devices
| Property | Default | Description |
|---|---|---|
| index | none | The index of the device in the device list. Usually an integer. A value of none indicates this device is not in the master list of connected devices |
| type | ICDeviceType_nothing | The value of the #macro/enum ICDeviceType, that indicates if the device is a gamepad, keyboard/mouse or otherwise. |
| slot_id | none | The slot ID that can be used to pass to GML's built-in gamepad functions. The slot ID is the address of the gamepad. |
| hat_count | 0 | A value for ICDeviceType_gamepad that indicates the number of "directional hats" present on the gamepad or flight stick |
| button_count | 0 | A value for gamepads that indicates the total number of buttons, usually inclusive of the start and select or menu and back buttons, not just activity buttons like ABXY. |
| button_thresholds | empty array | An array of thresholds, usually all the same value. Only one button threshold is assigned to each device, even though this array attempts to map the thresholds to the number of buttons indicated by button_count. This feature in previous versions of GameMaker supported multiple thresholds, and some devices may as well, but in GMS2 you can only set a master threshold for the button. Generally a value of 0.5, this is the amount a person has to push down on a button for it to register as a press. |
| axis_count | 0 | A value for gamepads that indicates the total number of "analog axis" - it takes two axis to create a "thumbstick", but this axis may indicate something else entirely. For example, on the Atari VCS Classic Controller (joystick), it indicates the amount of "Twist" rotation. Usually the first two axis are the left thumbstick of an XInput style Xbox controller, or a PS2/3/4 USB DirectInput controller. These have a special name in GameMaker as "lh_axis" "lv_axis" (or left vertical/horizontal axis, making up the left thumbstick) and there is also the "rh_axis" and "rv_axis" that are supposed to indicate a "right thumbstick", but this may not always be the case. Since these values have special meaning, they are assigned to a special property in a given ICDeviceState class (see below). |
| axis_deadzones | empty array | Similar the button_thresholds array, there is one element in the array for each axis present in axis_count. However, there is actually only one master threshold that effects all of the settings. In most cases, you will want a 0.1 value at minimum to help avoid the axis from indicating a position when the thumbstick isn't being touched. It basically means "ignore values below this number" on a given analog axis. |
| guid | "none" | The GUID is a special string that contains device and manufacturer information, similar to a model number, but not quite. Used in identifying specific gamepads and their features to some degree of accuracy, and is used with SDL to work with the Game Controller Database. |
| desc | "" | A name, usually read from the manufacturer's settings on the device |
| sdl | object | Contains SDL informational object from the Game Controller Database. If the index of this object is -1, then it is unset. ie if sdl.index == -1 then no value present |
| SDL_Mapping | "None" | An indicator that a special SDL Remapping String has been deployed on this device. A value of "None" means that no remapping is present. (Usually the case.) |
Created with: __IC.New_ICButtonState()
This class is used to contain the instantaneous signal reading of a specific button, key or gamepad hat.
This method is applied to the following locations: __INPUTCANDY.keys, __INPUTCANDY.mouseStates, and individual ICDeviceStates
| Property | Default | Description |
|---|---|---|
| button | IC_none | Refers to the master index of signal values |
| signal_index | none | Usually the same as the button value, but indicates where exactly in the __INPUTCANDY.signals[] array |
| is_held | false | A boolean value indicating if the state of this signal is "currently depressed" |
| was_held | false | A boolean value indicating if the state of this signal is "not currently depressed but was depressed in the last frame" |
| held_for | 0 | A number indicating the number of frames this signal has remained in the is_held state. |
| Method | Description |
|---|---|
| __IC.ICButtonStatePrintDiagnostics(thisclass) | Returns a string containing the values of ICButtonState passed to it in human readable form for debugging purposes. |
Created with: __IC.New_ICDevice()
Populates the list __INPUTCANDY.devices and holds information about the device. The index of the device in this array directly correlates to the same element in __INPUTCANDY.devicestates
| Property | Default | Description |
|---|---|---|
| signals | empty array | An array containing detected ICButtonStates that is updated each frame. |
| buttons | empty array | An array of buttonstates from 0...button_count for a given ICDevice |
| hats | empty array | An array of hat states from 0...hat_count for a given ICDevice; note that the values here are integer bitvectors matching the specification provided by GMS |
| axis | empty array | An array of axis states from 0...axis_count for a given ICDevice; note that the values here are decimal values |
| LH | AXIS_NO_VALUE | Value of the Left Horizontal (lh_axis) |
| LV | AXIS_NO_VALUE | Value of the Left Vertical (lv_axis) |
| RH | AXIS_NO_VALUE | Value of the Right Horizontal (rh_axis) |
| RV | AXIS_NO_VALUE | Value of the Right Vertical (rv_axis) |
| slot_id | none | Contains a duplicate of the ICDevice slot for up-referencing to the ICDevice table __INPUTCANDY.devices slot values |
| Method | Description |
|---|---|
| __IC.ICDeviceStatePrintDiagnostics(thisclass) | Returns a string containing the values of ICDevice passed to it in human readable form for debugging purposes. |
| __IC.ICDeviceStatePrintDiagnostics_Verbose(thisclass) | Same as above but shows each button, hat and axis value. |
| __IC.GetDeviceStates() | Gets the current gamepad device states, along with the keyboard states in __IC.keys and the mouse states in __IC.mouseStates, and is called once per frame by __INPUTCANDY.Step() |
Created with: __IC.New_ICAction()
Holds the value of an action, along with its default settings.
| Property | Default | Description |
|---|---|---|
| index | none | The index in the master actions list __INPUTCANDY.actions, a value of none indicates it is not added to this list. |
| name | "New Action" | A human-readable name that is also a matching string. Examples: "Jump", "Shoot Primary", "A", "Menu", "Go Left", "Up" |
| group | "None" | An indicator of a group of actions that can be matched on the group itself or in combination with the name. "None" means this is an ungrouped action. |
| gamepad | IC_none | The default signal we are seeking for a match against this action when checking actions. If this is an array, then it can mean any or all signals must be matched. |
| gamepad_combo | false | When set to true, all signals in the list must be matched for the gamepad. |
| keyboard | IC_none | The default signal we are seeking for a match against this action. If this is an array, then it can mean any or all signals. |
| keyboard_combo | false | When set to true, all signals in the list must be matched for keyboard users. |
| mouse | IC_none | The default signal we are seeking for a match against this action. Usually only the mouse buttons make sense. Can be an array, and can mean any or all signals must be matched. |
| mouse_combo | false | When set to true, all signals in the list must be matched for mouse users. |
| mouse_keyboard_combo | false | When set to true, all signals must be matched not only for the keyboard but also the mouse. Use this setting to indicate "SHIFT-Left-Mouse" or "Alt-Left-Click" type actions. |
| is_directional | false | Use this to indicate that this action is a four-way movement action like a "dpad", "hat", or "WASD"/"arrows", or "move the mouse" |
| requires_angle | false | When this is set to true, it indicates this action requires an angle be calculated from an axis, hat or other movement action. This value is usually here just for convenience to the interface designer. |
| held_for_seconds | 0.0 | When this value is set to a value in seconds, the action will only trigger after it is held for a certain amount. |
| fire_limit | 0 | This value is the number of frames that limit the frequency when it is fired. For example, if you wish to limit the number of detections to a certain number of frames. For example 1 frame would mean the action occurs only the first time the action is matched. The counter continues until the action is released. This value is usually here just for convenience to the interface designer. |
| released | false | This means the action only triggers when it is released, not when it is held or while being held. |
| enabled | true | Toggling this value to false ignores the action and it won't be matched. |
| forbid_rebinding | false | When you set this to true, the user cannot rebind the action and it won't appear in the rebinding UI. |
| Method | Description |
|---|---|
| __IC.CopyOfAction(action) | Pass an action into this function and a copy of the action will be returned. |
Created with: __IC.New_ICPlayer()
This class contains information about a player, their settings. It helps populate __INPUTCANDY.players
| Property | Default | Description |
|---|---|---|
| index | none | The index is "one less than the player number" and indicates the index in the __INPUTCANDY.players list. A value of none means the player is not in that list. Add 1 to this to get the player_number |
| settings | none | Index for settings profile in __INPUTCANDY.settings, a value of none indicates that the player does not yet have any custom settings. |
| device | none | The index of the device the player is using from the __INPUTCANDY.devices list. |
| active | false | It's up to you to maintain this. Set to true once a player is "in the game", and false once they are "out of the game" |
| data | empty object | Any data you wish to assign to the player can be set here. |
Created with: __IC.New_ICSettings(), but you should probably use __IC.AddSettings() instead.
This class is used to populate the __INPUTCANDY.settings list, and is saved and loaded. Settings contain information about the device it was originally created with (if a gamepad was used) and also any keyboard or mouse settings. This is the thing that gets edited in the ICUI.
| Property | Default | Description |
|---|---|---|
| index | none | The index in the __INPUTCANDY.settings master settings list. |
| deviceInfo | none | Information copied from any device used while setting up these settings. For example, if a player creates these settings after choosing a device, this will be here to remind the player next time which device was used, so that they can pick an appropriate settings configuration for the device they are now using. Since players cannot name the settings in any other way, only a number is used. If you used a 4-button controller |
| to create settings, then picked up another controller, you would want to create settings specifically for that distinct controller. | ||
| deadzone1 | 0.5 | The value set for the button threshold seen in the settings ICUI panel where you can slide the threshold slider for buttons. |
| deadzone2 | 0.1 | The value set for the axis threshold seen in the settings ICUI panel where you can slide the threshold slider for axis. |
| bindings | Empty array | A list of bindings that override the default values of actions. Note that bindings create a copy of the original action. If you were to modify your game's actions, the bindings may persist in an older form, so it is best that players clear out their configurations in the cases that you have not simply added new actions to your game. They can do so by deleting the settings file. |
| Method | Description |
|---|---|
| __IC.GetSettings(player_number) | Retrieves a player's actual settings object from the __INPUTCANDY.settings list, or none if there is no customization for that player. |
| __IC.GetSettingsIndex(player_number) | Instead of retrieving the actual settings object, simply return the index for the settings in the master __INPUTCANDY.settings list |
| __IC.SetSettings(player_number, settings_index) | Sets the settings for a player by its master list index reference. |
| __IC.AddSettings() | Adds a new settings object to the __INPUTCANDY.settings list and returns its index. If you pass in a player_number as the only parameter, it will immediately call __ICSetSettings() to assign this new settings index to the player_number provided. |
| __IC.RemoveSettings(settings_index) | Not implemented. Reserved for future use. |
| __IC.AssociateSettingsWithDevice(settings_index,device_index) | Assigns a device to a setting. Again, this is used only to look it up in the future, so assigning a device to a setting has no other purpose. Currently this method is not in use in the ICUI. |
| __IC.SaveSettings() | Saves all settings to the settings file. |
| __IC.LoadSettings() | Loads all settings from the settings file. |
Created with: __IC.New_ICBinding()
This class populates an ICSettings' bindings array.
| Property | Default | Description |
|---|---|---|
| index | none | The index in the ICSetting's bindings list. A value of none means that it is not yet in a bindings list. |
| action | none | Saves a string that matches an action by name, but when it is loaded it is transformed into an integer that matches the action's index in the master action list, __INPUTCANDY.actions |
| group | "" | Used in the saving and loading process, it matches the group the action is in. |
| bound_action | none | This usually starts its life as a copy of the action we are overriding. It can be modified to suit the player's desires by mapping new values to it. It is of the type ICAction and contains the action matching criteria required for this binding. |
| Method | Description |
|---|---|
| __IC.AddBinding( settings_index, from_action_index ) | Adds a new custom binding to an ICSettings from a specific master list action. |
| __IC.GetBinding( settings_index, action_index ) | Performs a simple lookup in a specific ICSettings based on a specific master action index. The returned values is the index of the binding in the bindings list, or none. |
| __IC.GetBindingData( settings_index, action_index ) | Returns the action ICBinding object, rather than its index in the bindings list, or none if there isn't one matching the provided action. |
| __IC.RemoveBinding( settings_index, action_index ) | Removes the binding from an ICSettings binding list. |
Created with: __IC.New_ICSetup()
A setup is a list of associations between devices, settings and players. This is used to create a persistent experience as long as players don't go pulling out and reordering devices. Otherwise, they have to re-choose their desired gamepad and re-choose the settings to go along with that gamepad.
There is only one setup. If you unplug controllers, there is no guarantee this setup will load correctly.
Most of this is done automatically in __INPUTCANDY.Init() and related __INPUTCANDY.Step() -- it waits a few frames after the game starts, to make sure all attached devices have populated the __INPUTCANDY.devices list. Then, the previous setup is loaded from disk and activated if it matches the currently connected gamepads. It checks to make sure no settings have been lost and no gamepads have been disconnected. For that reason, if you simply add a gamepad it will not void your previous setup, but if you remove one, it may not match properly and be tossed out. It's very difficult to detect how and in what order gamepads are connected, but if you plug them in they will not change order even if you reboot the computer because it is based on the USB socket you plug into.
This class is currently unused, but reserved for future use.
Created with: __IC.GetPlatformSpecifics()
Already created as: __INPUTCANDY.platform
This class contains a summary of platform specific information for the active host OS.
| Property | Description |
|---|---|
| device | Value of the GML built-in variable os_device |
| emulated | true: running on a device emulator, false: no |
| type | Value of the GameMaker variable os_type |
| version | Value of the GML built-in variable os_version |
| browser | Value of the GML built-in variable os_browser |
| keypad_open | Result of GML's device_is_keypad_open() at creation time |
| touchscreen_supported | True when on a platform that supports touch |
| keyboard_mouse_supported | True when on a platform that supports keyboard and mouse |
| gamepads_supported | Result of GML's gamepad_is_supported() |
| internet | Result of GML's os_is_network_connected() |
| region | Result of GML's os_get_region() |
| config | Result of GML's os_get_config() |