Input

View source
Entity → ceramic.Input (Class)

Manages all input handling for keyboard and gamepad devices.

The Input system provides:

  • Keyboard input detection (key press, release, and hold states)
  • Gamepad support (buttons, analog axes, gyroscope)
  • Input state queries (pressed, just pressed, just released)
  • Gamepad vibration/rumble control
  • Integration with UI elements to prevent input conflicts

The system tracks three states for inputs:

  • Just pressed: True only on the frame the input was pressed
  • Pressed: True while the input is held down
  • Just released: True only on the frame the input was released
See: Key, KeyCode, ScanCode, GamepadButton, GamepadAxis

Instance Members

activeGamepads: ReadOnlyArray<Int>

List of currently connected gamepad IDs. Updated automatically when gamepads are connected or disconnected.

keyPressed(keyCode: KeyCode): Bool

Checks if a key is currently pressed (held down). Returns true for every frame while the key is held.

Name Type Description
keyCode KeyCode The key code to check
Returns Description
Bool True if the key is currently pressed
keyJustPressed(keyCode: KeyCode): Bool

Checks if a key was just pressed this frame. Returns true only on the frame the key was initially pressed.

Name Type Description
keyCode KeyCode The key code to check
Returns Description
Bool True if the key was just pressed this frame
keyJustReleased(keyCode: KeyCode): Bool

Checks if a key was just released this frame. Returns true only on the frame the key was released.

Name Type Description
keyCode KeyCode The key code to check
Returns Description
Bool True if the key was just released this frame
scanPressed(scanCode: ScanCode): Bool

Checks if a key is currently pressed using scan code. Scan codes represent physical key positions and are layout-independent.

Name Type Description
scanCode ScanCode The scan code to check
Returns Description
Bool True if the key is currently pressed
scanJustPressed(scanCode: ScanCode): Bool

Checks if a key was just pressed this frame using scan code.

Name Type Description
scanCode ScanCode The scan code to check
Returns Description
Bool True if the key was just pressed this frame
scanJustReleased(scanCode: ScanCode): Bool

Checks if a key was just released this frame using scan code.

Name Type Description
scanCode ScanCode The scan code to check
Returns Description
Bool True if the key was just released this frame
gamepadPressed(gamepadId: Int, button: GamepadButton): Bool

Checks if a gamepad button is currently pressed.

Name Type Description
gamepadId Int The ID of the gamepad to check
button GamepadButton The button to check
Returns Description
Bool True if the button is currently pressed
gamepadJustPressed(gamepadId: Int, button: GamepadButton): Bool

Checks if a gamepad button was just pressed this frame.

Name Type Description
gamepadId Int The ID of the gamepad to check
button GamepadButton The button to check
Returns Description
Bool True if the button was just pressed this frame
gamepadJustReleased(gamepadId: Int, button: GamepadButton): Bool

Checks if a gamepad button was just released this frame.

Name Type Description
gamepadId Int The ID of the gamepad to check
button GamepadButton The button to check
Returns Description
Bool True if the button was just released this frame
gamepadAxisValue(gamepadId: Int, axis: GamepadAxis): Float

Gets the current value of a gamepad analog axis.

Name Type Description
gamepadId Int The ID of the gamepad to check
axis GamepadAxis The axis to check (e.g., LEFT_X, RIGHT_TRIGGER)
Returns Description
Float The axis value (-1.0 to 1.0 for sticks, 0.0 to 1.0 for triggers)
gamepadGyroDeltaX(gamepadId: Int): Float

Gets the accumulated gyroscope delta for the X axis since last frame.

Name Type Description
gamepadId Int The ID of the gamepad
Returns Description
Float Angular velocity around X axis (radians/second)
gamepadGyroDeltaY(gamepadId: Int): Float

Gets the accumulated gyroscope delta for the Y axis since last frame.

Name Type Description
gamepadId Int The ID of the gamepad
Returns Description
Float Angular velocity around Y axis (radians/second)
gamepadGyroDeltaZ(gamepadId: Int): Float

Gets the accumulated gyroscope delta for the Z axis since last frame.

Name Type Description
gamepadId Int The ID of the gamepad
Returns Description
Float Angular velocity around Z axis (radians/second)
startGamepadRumble(gamepadId: Int, duration: Float, lowFrequency: Float, highFrequency: Float): Void

Starts a controller rumble.

Name Type Description
gamepadId Int The id of the gamepad getting rumble
duration Float The duration, in seconds
lowFrequency Float Low frequency: value between 0 and 1
highFrequency Float High frequency: value between 0 and 1
stopGamepadRumble(gamepadId: Int): Void

Stops any active rumble on the specified gamepad.

Name Type Description
gamepadId Int The ID of the gamepad
keyCodeForScanCode(scanCode: ScanCode): KeyCode

Key code produced by the physical key scanCode with the current keyboard layout, that is the key printed on it: KEY_Z gives KEY_W on an AZERTY keyboard. Use KeyCode.name() on the result to display it. Returns KeyCode.UNKNOWN when the backend can't tell (on web, before the layout is known and before that key was pressed, if the browser has no keyboard layout API).

Name Type Description
scanCode ScanCode The physical key
Returns Description
KeyCode The key code for the current layout, or KeyCode.UNKNOWN
gamepadName(gamepadId: Int): String

Gets the name/description of a connected gamepad.

Name Type Description
gamepadId Int The ID of the gamepad
Returns Description
String The gamepad name, or null if not connected
gamepadLabels(gamepadId: Int): GamepadLabels

The labels printed on the buttons of a connected gamepad (Xbox, PlayStation, Nintendo...), resolved from its name. GamepadButton is positional on every backend: use this to show the player the label of a button on their gamepad.

Name Type Description
gamepadId Int The ID of the gamepad
Returns Description
GamepadLabels The labels of the gamepad, GENERIC if unknown or not connected

Events

@event keyDown(key: Key)

Triggered when a key from the keyboard is being pressed. This event fires repeatedly while a key is held down.

Name Type Description
key Key The key being pressed, containing both keyCode and scanCode
onKeyDown(owner, handler) onceKeyDown(owner, handler) offKeyDown(?handler) listensKeyDown()
@event keyUp(key: Key)

Triggered when a key from the keyboard is being released.

Name Type Description
key Key The key being released, containing both keyCode and scanCode
onKeyUp(owner, handler) onceKeyUp(owner, handler) offKeyUp(?handler) listensKeyUp()
@event gamepadAxis(gamepadId: Int, axis: GamepadAxis, value: Float)

Triggered when a gamepad analog axis value changes.

Name Type Description
gamepadId Int The ID of the gamepad (0-based index)
axis GamepadAxis The axis that changed (e.g., LEFT_X, RIGHT_TRIGGER)
value Float The new axis value (-1.0 to 1.0 for sticks, 0.0 to 1.0 for triggers)
onGamepadAxis(owner, handler) onceGamepadAxis(owner, handler) offGamepadAxis(?handler) listensGamepadAxis()
@event gamepadDown(gamepadId: Int, button: GamepadButton)

Triggered when a gamepad button is pressed.

Name Type Description
gamepadId Int The ID of the gamepad (0-based index)
button GamepadButton The button being pressed
onGamepadDown(owner, handler) onceGamepadDown(owner, handler) offGamepadDown(?handler) listensGamepadDown()
@event gamepadUp(gamepadId: Int, button: GamepadButton)

Triggered when a gamepad button is released.

Name Type Description
gamepadId Int The ID of the gamepad (0-based index)
button GamepadButton The button being released
onGamepadUp(owner, handler) onceGamepadUp(owner, handler) offGamepadUp(?handler) listensGamepadUp()
@event gamepadGyro(gamepadId: Int, dx: Float, dy: Float, dz: Float)

Triggered when gamepad gyroscope data is received.

Name Type Description
gamepadId Int The ID of the gamepad (0-based index)
dx Float Angular velocity around X axis (radians/second)
dy Float Angular velocity around Y axis (radians/second)
dz Float Angular velocity around Z axis (radians/second)
onGamepadGyro(owner, handler) onceGamepadGyro(owner, handler) offGamepadGyro(?handler) listensGamepadGyro()
@event gamepadEnable(gamepadId: Int, name: String)

Triggered when a gamepad is connected and enabled.

Name Type Description
gamepadId Int The ID assigned to the gamepad (0-based index)
name String The name/description of the gamepad device
onGamepadEnable(owner, handler) onceGamepadEnable(owner, handler) offGamepadEnable(?handler) listensGamepadEnable()
@event gamepadDisable(gamepadId: Int)

Triggered when a gamepad is disconnected or disabled.

Name Type Description
gamepadId Int The ID of the gamepad being disabled
onGamepadDisable(owner, handler) onceGamepadDisable(owner, handler) offGamepadDisable(?handler) listensGamepadDisable()

Private Members

GAMEPAD_STORAGE_SIZE: Int

Internal value to store gamepad state

pressedScanCodes: IntIntMap
pressedKeyCodes: IntIntMap
pressedGamepadButtons: IntIntMap
gamepadAxisValues: IntFloatMap
gamepadGyroDeltas: IntMap<Array<Float>>
gamepadGyroKeys: Array<Int>
gamepadNames: IntMap<String>
gamepadLabelsById: IntIntMap
emitKeyDown(key: Key): Void

Triggered when a key from the keyboard is being pressed. This event fires repeatedly while a key is held down. @event keyDown

Name Type Description
key Key The key being pressed, containing both keyCode and scanCode
emitKeyUp(key: Key): Void

Triggered when a key from the keyboard is being released. @event keyUp

Name Type Description
key Key The key being released, containing both keyCode and scanCode
emitGamepadAxis(gamepadId: Int, axis: GamepadAxis, value: Float): Void

Triggered when a gamepad analog axis value changes. @event gamepadAxis

Name Type Description
gamepadId Int The ID of the gamepad (0-based index)
axis GamepadAxis The axis that changed (e.g., LEFT_X, RIGHT_TRIGGER)
value Float The new axis value (-1.0 to 1.0 for sticks, 0.0 to 1.0 for triggers)
emitGamepadDown(gamepadId: Int, button: GamepadButton): Void

Triggered when a gamepad button is pressed. @event gamepadDown

Name Type Description
gamepadId Int The ID of the gamepad (0-based index)
button GamepadButton The button being pressed
emitGamepadUp(gamepadId: Int, button: GamepadButton): Void

Triggered when a gamepad button is released. @event gamepadUp

Name Type Description
gamepadId Int The ID of the gamepad (0-based index)
button GamepadButton The button being released
emitGamepadGyro(gamepadId: Int, dx: Float, dy: Float, dz: Float): Void

Triggered when gamepad gyroscope data is received. @event gamepadGyro

Name Type Description
gamepadId Int The ID of the gamepad (0-based index)
dx Float Angular velocity around X axis (radians/second)
dy Float Angular velocity around Y axis (radians/second)
dz Float Angular velocity around Z axis (radians/second)
emitGamepadEnable(gamepadId: Int, name: String): Void

Triggered when a gamepad is connected and enabled. @event gamepadEnable

Name Type Description
gamepadId Int The ID assigned to the gamepad (0-based index)
name String The name/description of the gamepad device
emitGamepadDisable(gamepadId: Int): Void

Triggered when a gamepad is disconnected or disabled. @event gamepadDisable

Name Type Description
gamepadId Int The ID of the gamepad being disabled
resetDeltas(): Void
willEmitKeyDown(key: Key): Void
Name Type
key Key
willEmitKeyUp(key: Key): Void
Name Type
key Key
willEmitGamepadEnable(gamepadId: Int, name: String): Void
Name Type
gamepadId Int
name String
willEmitGamepadDisable(gamepadId: Int): Void
Name Type
gamepadId Int
willEmitGamepadDown(gamepadId: Int, button: GamepadButton): Void
Name Type
gamepadId Int
button GamepadButton
willEmitGamepadUp(gamepadId: Int, button: GamepadButton): Void
Name Type
gamepadId Int
button GamepadButton
willEmitGamepadGyro(gamepadId: Int, dx: Float, dy: Float, dz: Float): Void
Name Type
gamepadId Int
dx Float
dy Float
dz Float
willEmitGamepadAxis(gamepadId: Int, axis: GamepadAxis, value: Float): Void
Name Type
gamepadId Int
axis GamepadAxis
value Float
new(): Void

Private constructor. Input is managed as a singleton through App.

elements
canEmitKeyDown(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool
elements
canEmitKeyUp(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool
elements
canEmitGamepadDown(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool
elements
canEmitGamepadUp(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

Metadata

Name Parameters
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()
:allow ceramic.App