Common Organization of Controls Kit Manual

Basic use

The library designed to be reasonably easy to use while maintain great flexibility and features.

Preparations

First thing you need to do is, obviously, require the library. Then, you create a new control object. You can optionally fill it with data at instant, or may do it later. Or, instead, you may hook up XBox360 controller default configuration which covers it's entire layout. Then you optionally load saved settings, by pushing your device-key pairs to the object, and also pushing joystick and mouse related data. After that (but not before!) you can reload joystick, that essentially will search for previously used joystick and set it up. If you don't have controls to load, you assign default controls, joystick modes and mouse values.

Controls data format

cock.new and cock.setControls are accepting data in specific format that needs to be maintained. It is defined as following:

{ default1 = {
  up = { primary = { "keyboard", "up" }, secondary = { "mouse axis", "y", "-", "++" },
  down = { primary = { "keyboard", "down" }, secondary = { "mouse axis", "y", "+", "++" } },
 default2 = { ... }
}

It will define you controls "up" and "down" to be accessed later, with two options to use ("primary" and "secondary"), one with keyboard only control and another with mouse only, and pushes it to "default1" controls set. You can then use defined defaults to e.g. restore controls to default, or set them up as such if there's no user-edited controls.

Obtaining the values

This is done really easy: you simply access your control class "current" or "previous" table's child named as your defined control.

if control.current.up > 0 then player.y = player.y - 100 * dt 
elseif control.current.down > 0 then player.y = player.y + 100 * dt

These variables (except for mouse axis) contain decimal values ranged -1 to 1 (0 to 1 in negative cutoff mode), which you can use for analog control. Mouse axis-bound variables would store pretty arbitrary numbers, with undefined range, only influenced by mouse factor and offset.

The library also have effecient getters and setters for that, but you are strongly discouraged to use them.

Updating controls

You simply put update function to your "love.update" callback, and that's it. It is suggested to put it to beginning of the function. Placing it to other callbacks, such as "love.keypressed" is not necessary at all due to LÖVE's way of handling them.

Enabling user to edit controls

The library have special function to assume "input capture" mode, in which any incoming user input will be captured and automatically binded to provided key. You may specify whether or not you want to lock input callbacks and update function, and ignore mouse motion, during input capture mode. You can abort this mode using corresponding function. In input capture mode, if mouse motion capture is enabled, the library will temporairly center the mouse and then set it back once input is captured, but it will not hide it because, with all the possible user implementations of mouse cursor, it's simply meaningless, so make sure you hide your cursor during capture, otherwise it'll weirdly jump to the center of the screen and back.

You can bind the device and key manually, using the "bind" function.

You can implement "arbitrary binds per action" using search for unused options function. It will return next unused option, and since for gathering input, option name is irrelevant, you can simply bind keys to free options arbitrairly. If the function fails to find empty option, you'd have to create a new option rather than binding to unexisted option. This is due to internal structure of the library.

NOTE: in input capture mode, the library would temporary replace your input callbacks and update function with it's own wrappers for them, until some input is provided, which could interfere with other libraries/modules that would do the same, so use it with care. The rule of thumb is to only allow one callbacks replacement at a time, or only allow nested replacements, but never intersecting replacements. If none of your other code would do that in a separate thread, but would do that in main thread, enabling both locks ensures safe capture. If your code doesn't do that at all, having locks enabled may be not necessary.

Advanced features

This library was created with robust design in mind, so it supports a bit of handy advanced features that otherwisely would be needed to implemented by the programmer, which is not always convenient.

Mouse offset and scaling factor

For simplicity of aquiring values from control table, it handles this two math operations for you. It subtracts actual mouse position from an offset, and then multiplies result by scaling factor, per axis. This creates an easy way to set mouse centre point and mouse sensevity.

Delta and inversion modes

Inversion mode is pretty straightforward, it simply negates input. Delta mode is a little bit trickier. In this mode, instead of reporting absolute value, the control object reports delta value, that is how much input have changed since last update. Both delta and inversion modes have "negative cutoff" mode to prevent it from returning negative values.

Delta mode is particularry useful when used with joystick; this opens possibility to implement obscure and cunning ways of using analog sticks and XBox360 triggers, that aren't normally can be seen in the games. When used with mouse, this simply returns distance travelled from previous coordinate. Note that if you want FPS-like controls where you would constantly set mouse back to the center of the screen, you should instead use "bypass" mode, since in this state, delta mode would yield acceleration of the mouse rather than distance travelled. You can still use that nevertheless, if you may.

Psychoanatomic joystick hat adjustments

Default mode for joystick hat is diagonal, the other general mode is lateral, i.e. 4-directional. But, since that mode would discard all diagonal input, the update handler have 4 modes that specifically tell how to resolve diagonal input:

• Prefer vertical input
  • convert diagonal up to up and diagonal down to down
• Prefer horizontal input
  • convert diagonal left to left and diagonal right to right
• Prefer clockwise input
  • "turn" diagonal input 45 degrees clockwise, e.g. down-left becomes left, etc.
• Prefer counter-clockwise input
  • "turn" diagonal input 45 degrees counter-clockwise, e.g. down-left becomes down, etc.

As the name suggests, first two modes are axially biased and will more likely result in getting corresponding direction when actively working on D-pad, and this is more of a gameplay-related setting than actual adjustment, e.g. if you use left and right to move the block in a tetris game, having it accidntally dropped because player would hit the D-pad diagonally down is not desired, and this is when you enable horizontal bias.

The other two are radially biased (in some way they are unbiased) and although they don't make any direction pressed any more likely, they make changing D-pad direction more fluent in one way and more stiff in the other way. This modes give better feel of purely 4-directional D-pad on immediate hat presses, while maintaining only allowing one direction at a time. You may, in fact, just randomly use either of them, but you may also provide choosing between them as an option, since not all joysticks' hats are made so great, and specific mode enabled may actually improve players' accuracy.

You can change the modes on fly as necessary.

Joystick hat remapping

Due to the way some joysticks' hats are handled, you may want to map some of joysticks' buttons to a virtual joystick hat. To do that, you simply use corresponding function and pass it exactly 4 joystick buttons to use. After that, the joystick will have specified hat "remapped", and it'll work like regular joystick hat.

Displaying setup

Library provides handful of feedback functions, such as conversion from literal to numerical values and vice versa, for returning binded controls, for finding unused options.

Function index

cock.addJoystick	Hooks up new joystick.
cock.addOption	Creates new input option.
cock.bind	Binds given input.
cock.cancelCapture	Cancels input capture.
cock.convertAxis	Converts axis.
cock.convertDelta	Converts delta.
cock.convertDevice	Converts device.
cock.convertInverse	Converts inverse.
cock.convertJoystick	Converts joystick.
cock.convertJoystickHat	Converts joystick hat.
cock.convertJoystickHatMode	Converts hat mode.
cock.convertKey	Converts key.
cock.delete	Deletes object.
cock.deleteJoystick	Deletes joystick.
cock.deleteOption	Deletes input option.
cock.explodeCapturedData	Explodes longdata.
cock.find	Find object.
cock.getBinded	Gets binded controls.
cock.getCapture	Gets capture state.
cock.getEmptyOption	Finds unused option.
cock.getJoystickDeadzone	Gets deadzones.
cock.getJoystickHatMode	Sets hat modes.
cock.getJoysticksList	Lists joysticks.
cock.getMouseFactor	Gets mouse factor.
cock.getMouseOffset	Gets mouse offset.
cock.new	Creates new object.
cock.reloadJoysticks	Reloads joysticks.
cock.remapJoystickHat	Maps buttons to hats.
cock.setCallbacks	Toggles callbacks.
cock.setCapture	User-edit controls.
cock.setControls	Creates control layouts.
cock.setDefault	Reverts to defaults.
cock.setDefaultXBox360	(BROKEN) Creates XBox360 layout.
cock.setJoystickDeadzone	Sets deadzones.
cock.setJoystickHatMode	Sets hat modes.
cock.setMouseFactor	Sets mouse factor.
cock.setMouseOffset	Sets mouse offset.
cock.unbind	Unbinds map.
cock.update	Updates object.
cock.updateAll	Updates all objects.

See also

• Common Organization of Controls Kit