Difference between revisions of "Common Organization of Controls Kit Manual"

m (Psychoanatomic joystick hat adjustments)
Line 60: Line 60:
 
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.  
 
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  changeing D-pad direction more fluent in one way and more stiff in another 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.  
+
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.
 
You can change the modes on fly as necessary.

Revision as of 06:54, 30 July 2013

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. 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:

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

It will define you controls "up" and "down" to be accessed later, and sets up two defaults for each controls, one with keyboard only control and another with mouse only. 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 0 to 1, which you can use for analog control. Mouse axis-bound variables would store pretty arbitrary non-negative 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.

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

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 axis mode

In this mode, instead of reporting absolute axis value, the control object reports delta value, that is how much an axis have been moved further since last update. To ensure consistency, delta axis only works one way, i.e. moving axis back does not yields negative delta.

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 regular 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 mode is lateral. But, since that 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.

Function index

cock.addJoystickHooks up new joystick.
cock.addOptionCreates new input option.
cock.bindBinds given input.
cock.cancelCaptureCancels input capture.
cock.convertAxisConverts axis.
cock.convertDeltaConverts delta.
cock.convertDeviceConverts device.
cock.convertInverseConverts inverse.
cock.convertJoystickConverts joystick.
cock.convertJoystickHatConverts joystick hat.
cock.convertJoystickHatModeConverts hat mode.
cock.convertKeyConverts key.
cock.deleteDeletes object.
cock.deleteJoystickDeletes joystick.
cock.deleteOptionDeletes input option.
cock.explodeCapturedDataExplodes longdata.
cock.findFind object.
cock.getBindedGets binded controls.
cock.getCaptureGets capture state.
cock.getEmptyOptionFinds unused option.
cock.getJoystickDeadzoneGets deadzones.
cock.getJoystickHatModeSets hat modes.
cock.getJoysticksListLists joysticks.
cock.getMouseFactorGets mouse factor.
cock.getMouseOffsetGets mouse offset.
cock.newCreates new object.
cock.reloadJoysticksReloads joysticks.
cock.remapJoystickHatMaps buttons to hats.
cock.setCallbacksToggles callbacks.
cock.setCaptureUser-edit controls.
cock.setControlsCreates control layouts.
cock.setDefaultReverts to defaults.
cock.setDefaultXBox360(BROKEN) Creates XBox360 layout.
cock.setJoystickDeadzoneSets deadzones.
cock.setJoystickHatModeSets hat modes.
cock.setMouseFactorSets mouse factor.
cock.setMouseOffsetSets mouse offset.
cock.unbindUnbinds map.
cock.updateUpdates object.
cock.updateAllUpdates all objects.

See also