Kōtuku Manual

Provides support for reading state-based game controllers.

Use the Controller class to read the state of game controllers that are recognised by the operating system.

Unlike analog devices that stream input commands (e.g. mice), gamepad controllers maintain a state that can be read at any time. The controller state is normally read at least once per frame, which can be achieved in a program's inner loop, or in a separate timer.

On Linux, controllers are read through the /dev/input/js* joystick API. The user running the application must have read access to these device nodes.

Controller input management is governed by the Display class. The GRAB_CONTROLLERS flag should be defined in the active Display⇒Flags field in order to ensure that controller input can be received from the host. Failure to do so may mean that the Controller object works inconsistently across different systems.

Structure

The Controller class consists of the following fields:

Access

Name

Type

Comment

Buttons CON Button values expressed as bit-fields.

Name	Description
CON::DPAD_DOWN	Directional pad down.
CON::DPAD_LEFT	Directional pad left.
CON::DPAD_RIGHT	Directional pad right.
CON::DPAD_UP	Directional pad up.
CON::GAMEPAD_E	East button (B)
CON::GAMEPAD_N	North button (Y)
CON::GAMEPAD_S	South button (A)
CON::GAMEPAD_W	West button (X)
CON::LEFT_BUMPER_1	Gamepad left-hand bumper 1 (top, primary).
CON::LEFT_BUMPER_2	Gamepad left-hand bumper 2 (lower).
CON::LEFT_THUMB	Left thumb stick depressed.
CON::RIGHT_BUMPER_1	Gamepad right-hand bumper 1 (top, primary).
CON::RIGHT_BUMPER_2	Gamepad right-hand bumper 2 (lower).
CON::RIGHT_THUMB	Right thumb stick depressed.
CON::SELECT	Gamepad select or back button.
CON::START	Gamepad start button.

LeftStickX DOUBLE Left analog stick value for X axis, between -1.0 and 1.0.

LeftStickY DOUBLE Left analog stick value for Y axis, between -1.0 and 1.0.

LeftTrigger DOUBLE Left trigger value between 0.0 and 1.0.

Port INT The port number assigned to the controller.

Set the port number to choose the controller that will be queried for state changes. The default of -1 is used to indicate the primary (first available) controller. Fixed port numbers start from zero. There is no guarantee that the existence of a port means that a controller is connected to it.

On Windows, XInput user indices occupy ports zero through three. DirectInput controllers use stable slots from four through 31 while connected. This reservation means that a DirectInput-only controller can produce a TotalPorts value of five while ports zero through three remain disconnected.

It is acceptable to set the port number post-initialisation, so multiple controllers can be queried through one interface at the cost of overwriting the previous state. Enumeration for the discovery of controllers can be achieved by calling Query() for each port and checking for ERR::Okay.

Read TotalPorts to get the maximum number of controller ports.

RightStickX DOUBLE Right analog stick value for X axis, between -1.0 and 1.0.

RightStickY DOUBLE Right analog stick value for Y axis, between -1.0 and 1.0.

RightTrigger DOUBLE Right trigger value between 0.0 and 1.0.

TotalPorts INT Reports the number of controller ports that should be scanned.

Port values range from zero to TotalPorts - 1. Some platforms, including Linux and Windows, may expose sparse controller indices, so an individual port in that range can fail to query if its device is not currently connected. Windows DirectInput mappings support two sticks, two triggers, the first POV hat and the first 12 common gamepad buttons. Additional or specialist controls are ignored.

Actions

The following actions are currently supported:

Query Get the current controller state.

ERR acQuery(*Object)

Query will update the controller field values with the state of the controller connected to the specified port. On failure, all axis and button fields are cleared while Port is preserved. Repeated calls to Query() return ERR::Disconnected until a controller is connected to the selected port, or any port when Port is -1.

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function
NoSupport	The host does not support controller input.
OutOfRange	The port number is outside of acceptable range.
AccessObject	Attempting to lock an object failed
NotInitialised	Controller access is not enabled on a suitable display.
SystemCall	A call to the host system failed.
Disconnected	No controller is connected to the specified port.

Controller Class

Structure

Actions

CON Type