Cinder v0.1.0
DocsAPI reference

cinder.input

cinder.input #

Source: cinder/input/__init__.mojo

Input: action and axis mapping over keyboard, mouse and gamepad, rebindable and saved to disk.

cinder.input.map #

Source: cinder/input/map.mojo

Input mapping: named actions (buttons) and axes over keyboard, mouse and gamepad, rebindable at runtime and saved as a diffable text file. Feed every platform Event to process, call end_frame once per frame (it clears the just-pressed and just-released edges and the per-frame mouse deltas), and query by name. An axis sums its bindings: a key contributes scale while held, an analog source its value times scale after the dead zone. listen arms a capture: the next key, button or axis event becomes the binding, which is how a settings menu rebinds a control.

  • comptime DEVICE_KEY = 0 — Keyboard source; code is an SDL scancode (0-511 are tracked).
  • comptime DEVICE_MOUSE_BUTTON = 1 — Mouse button source; code is the SDL button (1 = left, 2 = middle, 3 = right; 0-7 are tracked).
  • comptime DEVICE_MOUSE_AXIS = 2 — Codes: 0 = x delta, 1 = y delta, 2 = wheel.
  • comptime DEVICE_GAMEPAD_BUTTON = 3 — Gamepad button source; code is an SDL_GamepadButton (0-31 are tracked). All connected gamepads share one state.
  • comptime DEVICE_GAMEPAD_AXIS = 4 — Gamepad axis source; code is an SDL_GamepadAxis (0-7 are tracked), value in [-1, 1]. All connected gamepads share one state.
  • comptime INPUT_MAP_VERSION = 1 — Version in the cinder-input header; InputMap.from_text rejects any other.

struct Binding #

mojo
struct Binding(Equatable, ImplicitlyCopyable, Movable, Writable)

One source: device and its code (scancode, button or axis index). scale multiplies the contribution to an axis (digital sources contribute scale while held), dead_zone applies to analog sources.

Fields:

  • device: Int

  • code: Int

  • scale: Float32

  • dead_zone: Float32

  • key key(scancode: Int, scale: Float32 = 1.0) -> Binding
    A keyboard binding for SDL scancode scancode.

  • mouse_button mouse_button(button: Int, scale: Float32 = 1.0) -> Binding
    A mouse button binding (1 = left, 2 = middle, 3 = right).

  • mouse_axis mouse_axis(axis: Int, scale: Float32 = 1.0) -> Binding
    A mouse axis binding: 0 = x delta, 1 = y delta, any other code = wheel.

  • gamepad_button gamepad_button(button: Int, scale: Float32 = 1.0) -> Binding
    A gamepad button binding (SDL_GamepadButton index).

  • gamepad_axis gamepad_axis( axis: Int, scale: Float32 = 1.0, dead_zone: Float32 = 0.15 ) -> Binding
    An analog gamepad axis binding (SDL_GamepadAxis index) with a dead zone.

  • same_source same_source(self, o: Binding) -> Bool
    True when both bindings read the same device and code, whatever their scale and dead zone.

  • write_to write_to(self, mut w: Some[Writer])

struct InputMap #

mojo
struct InputMap(Movable)

Named actions and axes with their bindings, plus the device state they are evaluated against. Text format (to_text, from_text): a cinder-input 1 header, then one action NAME DEVICE CODE SCALE DEAD_ZONE or axis NAME ... line per binding, where DEVICE is key, mouse_button, mouse_axis, gamepad_button or gamepad_axis; an entry without bindings is a bare action NAME or axis NAME line. Fields are separated by single spaces, so names must not contain spaces.

Fields:

  • actions: List[_Action]

  • axes: List[_Axis]

  • keys_down: List[Bool]

  • mouse_buttons_down: List[Bool]

  • gamepad_buttons_down: List[Bool]

  • gamepad_axes: List[Float32]

  • mouse_delta_x: Float32

  • mouse_delta_y: Float32

  • wheel: Float32

  • listening_action: Int

  • listening_axis: Int

  • listening_scale: Float32

  • __init__ __init__(out self)

  • add_action add_action(mut self, name: String) raises -> Int
    Adds an action without bindings and returns its index; raises when the name is taken.

  • add_axis add_axis(mut self, name: String) raises -> Int
    Adds an axis without bindings and returns its index; raises when the name is taken.

  • find_action find_action(self, name: String) -> Int
    Index of the action called name, or -1.

  • find_axis find_axis(self, name: String) -> Int
    Index of the axis called name, or -1.

  • bind_action bind_action(mut self, name: String, binding: Binding) raises
    Appends binding to the action, creating the action when it does not exist. When the new source is already down the action becomes held (with a just-pressed edge).

  • bind_axis bind_axis(mut self, name: String, binding: Binding) raises
    Appends binding to the axis, creating the axis when it does not exist.

  • clear_action_bindings clear_action_bindings(mut self, name: String) raises
    Removes every binding of the action; raises for an unknown action. An action held at that moment is released (pressed turns False and just_released fires), so it cannot stay stuck with no binding to release it.

  • clear_axis_bindings clear_axis_bindings(mut self, name: String) raises
    Removes every binding of the axis; raises for an unknown axis.

  • rebind_action rebind_action(mut self, name: String, binding: Binding) raises
    Replaces every binding of the action with binding.

  • action_bindings action_bindings(self, name: String) raises -> List[Binding]
    A copy of the action's bindings; raises for an unknown action.

  • axis_bindings axis_bindings(self, name: String) raises -> List[Binding]
    A copy of the axis' bindings; raises for an unknown axis.

  • listen_action listen_action(mut self, name: String) raises
    The next key, mouse button or gamepad button event replaces the action's bindings. An action held through its old bindings is released at that point (see clear_action_bindings).

  • listen_axis listen_axis(mut self, name: String, scale: Float32 = 1.0) raises
    The next key, button or analog event is added to the axis with scale.

  • is_listening is_listening(self) -> Bool
    True while listen_action or listen_axis waits for an event.

  • cancel_listening cancel_listening(mut self)
    Disarms a pending listen_action or listen_axis without changing any binding.

  • process process(mut self, ev: Event)
    Updates device state from one platform event (and captures it while listening).

  • end_frame end_frame(mut self)
    Clears edges and per-frame deltas; call once per frame after reading input.

  • pressed pressed(self, name: String) raises -> Bool
    True while any key or button bound to the action is held; mouse and gamepad axis bindings never press an action. Raises for an unknown action.

  • just_pressed just_pressed(self, name: String) raises -> Bool
    True when the action went from released to held since the last end_frame; raises for an unknown action.

  • just_released just_released(self, name: String) raises -> Bool
    True when the action went from held to released since the last end_frame; raises for an unknown action.

  • axis axis(self, name: String) raises -> Float32
    Sum of the axis' bindings, clamped to [-1, 1] for digital-only axes; analog and mouse contributions are not clamped (mouse deltas are in pixels).

  • to_text to_text(self) -> String
    Diffable text: one action/axis line per binding, sorted as defined.

  • from_text from_text(text: String) raises -> InputMap
    Parses the text format written by to_text; blank lines are skipped. Raises on a missing header, another version, a line that is not 2 or 6 fields, an unknown entry or device, or a malformed number.

  • save save(self, path: String) raises
    Writes to_text() to path; raises when the file cannot be written.

  • load load(path: String) raises -> InputMap
    Reads path and parses it with from_text; raises when the file cannot be read or does not parse.

View as MarkdownSource: docs/api/input.md