ClayEvents

View source
clay.Events → backend.ClayEvents (Class)

Event handler for the Clay backend that bridges low-level Clay engine events to high-level Ceramic framework events.

This class processes all input events from the Clay engine including:

  • Mouse events (desktop/web platforms)
  • Touch events (mobile platforms)
  • Keyboard events
  • Gamepad events with button mapping and axis-to-button conversion
  • Application lifecycle events
  • Window events
  • Text input events

Platform-specific behavior:

  • Desktop (Mac/Windows/Linux): Mouse input only, no touch
  • Mobile (iOS/Android): Touch input only, no mouse
  • Web: Mouse input with optional gamepad button remapping

The class includes gamepad normalization to ensure consistent button mappings across different controller types and platforms.

Instance Members

clay
ready(): Void

Called when the Clay engine is ready. Initializes the backend reference and triggers the ready callback.

clay
tick(delta: Float): Void

Called every frame update.

Name Type Description
delta Float Time elapsed since last frame in seconds
clay
render(): Void

Called when a frame needs to be rendered.

clay
sdlEvent(event: clay.sdl.SDLEvent): Void

Handles raw SDL events for platform-specific functionality.

Name Type Description
event clay.sdl.SDLEvent The SDL event to process
clay
appEvent(type: clay.AppEventType): Void

Handles application lifecycle events.

Name Type Description
type clay.AppEventType The type of application event
clay
mouseDown(x: Int, y: Int, button: Int, timestamp: Float, windowId: Int): Void

Handles mouse button press events. Converts physical pixel coordinates to logical coordinates using screen density. Ensures proper handling of multiple presses of the same button by triggering mouseUp first.

Platform availability: Desktop (Mac/Windows/Linux) and Web only.

Name Type Description
x Int Physical X coordinate in pixels
y Int Physical Y coordinate in pixels
button Int Mouse button ID (0=left, 1=middle, 2=right)
timestamp Float Event timestamp in seconds
windowId Int ID of the window that received the event
clay
mouseUp(x: Int, y: Int, button: Int, timestamp: Float, windowId: Int): Void

Handles mouse button release events. Converts physical pixel coordinates to logical coordinates using screen density. Ignores mouse up events for buttons that weren't previously pressed down.

Platform availability: Desktop (Mac/Windows/Linux) and Web only.

Name Type Description
x Int Physical X coordinate in pixels
y Int Physical Y coordinate in pixels
button Int Mouse button ID (0=left, 1=middle, 2=right)
timestamp Float Event timestamp in seconds
windowId Int ID of the window that received the event
clay
mouseMove(x: Int, y: Int, xrel: Int, yrel: Int, timestamp: Float, windowId: Int): Void

Handles mouse movement events. Converts physical pixel coordinates to logical coordinates using screen density. Updates internal mouse position tracking and emits movement events.

Platform availability: Desktop (Mac/Windows/Linux) and Web only.

Name Type Description
x Int Physical X coordinate in pixels
y Int Physical Y coordinate in pixels
xrel Int Relative X movement in pixels (not used)
yrel Int Relative Y movement in pixels (not used)
timestamp Float Event timestamp in seconds
windowId Int ID of the window that received the event
clay
mouseWheel(x: Float, y: Float, timestamp: Float, windowId: Int): Void

Handles mouse wheel scroll events. Passes through wheel delta values directly without coordinate transformation.

Platform availability: Desktop (Mac/Windows/Linux) and Web only.

Name Type Description
x Float Horizontal scroll delta (positive = right, negative = left)
y Float Vertical scroll delta (positive = up, negative = down)
timestamp Float Event timestamp in seconds
windowId Int ID of the window that received the event
clay
keyDown(keyCode: clay.KeyCode, scanCode: clay.ScanCode, repeat: Bool, mod: clay.ModState, timestamp: Float, windowId: Int): Void

Handles keyboard key press events. Emits both input events for game logic and text input events for text editing. Supports key repeating when a key is held down.

Name Type Description
keyCode clay.KeyCode Virtual key code representing the key's logical meaning
scanCode clay.ScanCode Physical scan code representing the key's hardware position
repeat Bool Whether this is a repeat event from holding the key down
mod clay.ModState Modifier key state (Shift, Ctrl, Alt, etc.)
timestamp Float Event timestamp in seconds
windowId Int ID of the window that received the event
clay
keyUp(keyCode: clay.KeyCode, scanCode: clay.ScanCode, repeat: Bool, mod: clay.ModState, timestamp: Float, windowId: Int): Void

Handles keyboard key release events. Emits both input events for game logic and text input events for text editing.

Name Type Description
keyCode clay.KeyCode Virtual key code representing the key's logical meaning
scanCode clay.ScanCode Physical scan code representing the key's hardware position
repeat Bool Should always be false for key up events
mod clay.ModState Modifier key state (Shift, Ctrl, Alt, etc.)
timestamp Float Event timestamp in seconds
windowId Int ID of the window that received the event
clay
gamepadAxis(id: Int, axisId: Int, value: Float, timestamp: Float): Void

Handles gamepad analog stick and trigger movement events. Auto-enables gamepads on first input. Converts triggers to button presses when value >= 0.5. Rounds axis values to reduce noise and only emits events when values change meaningfully.

Platform behavior:

  • Desktop: Full gamepad support with axis-to-button mapping for triggers
  • Web: Gamepad support with potential button remapping for Nintendo controllers
  • iOS: Disabled by default
Name Type Description
id Int Gamepad device ID (0-3 typically)
axisId Int Axis identifier (0=left stick X, 1=left stick Y, 2=right stick X, etc.)
value Float Axis value from -1.0 to 1.0 (or 0.0 to 1.0 for triggers)
timestamp Float Event timestamp in seconds
clay
gamepadDown(id: Int, buttonId: Int, value: Float, timestamp: Float): Void

Handles gamepad button press events. Auto-enables gamepads on first input and applies platform-specific button remapping. Prevents duplicate button press events and handles Nintendo controller button swapping on web.

Button mapping:

  • Standard: 0=A, 1=B, 2=X, 3=Y, 4=LB, 5=RB, etc.
  • Nintendo on Web: A/B and X/Y positions are swapped to match Nintendo layout
  • SDL platforms: Uses custom mapping to match HTML5 gamepad API
Name Type Description
id Int Gamepad device ID (0-3 typically)
buttonId Int Physical button identifier from the platform
value Float Button pressure (0.0 to 1.0, usually 0.0 or 1.0 for digital buttons)
timestamp Float Event timestamp in seconds
clay
gamepadUp(id: Int, buttonId: Int, value: Float, timestamp: Float): Void

Handles gamepad button release events. Auto-enables gamepads on first input and applies the same button remapping as gamepadDown. Only emits events for buttons that were previously pressed to prevent spurious releases.

Uses identical button mapping logic to gamepadDown to ensure consistent behavior.

Name Type Description
id Int Gamepad device ID (0-3 typically)
buttonId Int Physical button identifier from the platform
value Float Button pressure (usually 0.0 for button release)
timestamp Float Event timestamp in seconds
clay
gamepadGyro(id: Int, dx: Float, dy: Float, dz: Float, timestamp: Float): Void

Handles gamepad gyroscope/motion sensor events. Auto-enables gamepads on first input and applies scaling to convert raw sensor data to degrees per second. On web with native bridge, this is handled elsewhere.

The scaling factor (360.0 / 1550.0) converts platform-specific gyro units to standard degrees per second for consistent cross-platform behavior.

Platform availability:

  • Desktop: Gyro data from supported controllers (PS4, PS5, Switch Pro)
  • Web: Available unless ceramic_native_bridge is used
  • Mobile: Depends on controller support
Name Type Description
id Int Gamepad device ID
dx Float Gyro rotation rate around X-axis (raw platform units)
dy Float Gyro rotation rate around Y-axis (raw platform units)
dz Float Gyro rotation rate around Z-axis (raw platform units)
timestamp Float Event timestamp in seconds
clay
gamepadDevice(id: Int, name: String, type: clay.GamepadDeviceEventType, timestamp: Float): Void

Handles gamepad connection and disconnection events. Manages gamepad lifecycle including proper cleanup of pressed buttons on disconnect and initialization of button state on connect. Uses temporary tracking to prevent immediate re-detection of removed gamepads.

When a gamepad is removed:

  • All pressed buttons are released with gamepadUp events
  • The gamepad is disabled and marked as temporarily removed
  • Removal tracking is cleared on the next frame update

When a gamepad is added:

  • Button state is initialized to all unpressed
  • Gamepad-specific configuration is applied (button swapping, etc.)
  • The gamepad is enabled and ready for input
Name Type Description
id Int Gamepad device ID
name String Gamepad name/identifier string for device detection
type clay.GamepadDeviceEventType Device event type (DEVICE_ADDED or DEVICE_REMOVED)
timestamp Float Event timestamp in seconds
clay
text(text: String, start: Int, length: Int, type: clay.TextEventType, timestamp: Float, windowId: Int): Void

Handles text input events for text editing functionality. Only processes text input when text input mode is active, allowing for proper text editing in text fields while ignoring text when not needed.

This is separate from keyboard events and provides the actual character input including support for international keyboards, input methods, and composed text.

Name Type Description
text String The text string that was input (may be multiple characters)
start Int Starting position for text editing (not used)
length Int Length of text selection/replacement (not used)
type clay.TextEventType Type of text event (input, editing, etc.)
timestamp Float Event timestamp in seconds
windowId Int ID of the window that received the event
clay
windowEvent(type: clay.WindowEventType, timestamp: Float, windowId: Int, x: Int, y: Int): Void

Handles window-related events such as focus changes, resize, and fullscreen transitions. Most events are handled automatically by the Clay engine, but fullscreen state changes need to be synchronized with the Ceramic app settings.

Fullscreen events:

  • ENTER_FULLSCREEN: Updates app settings to reflect fullscreen state
  • EXIT_FULLSCREEN: Updates app settings to reflect windowed state

Other events (SHOWN, HIDDEN, MINIMIZED, etc.) are currently not handled but could be extended for application-specific window management needs.

Name Type Description
type clay.WindowEventType The type of window event that occurred
timestamp Float Event timestamp in seconds
windowId Int ID of the window that generated the event
x Int X coordinate data (usage depends on event type)
y Int Y coordinate data (usage depends on event type)

Private Members

clay
GAMEPAD_STORAGE_SIZE: Int

Internal value to store gamepad state. Each gamepad can have up to 32 buttons/axes tracked.

clay
backend: Backend

Reference to the main backend instance

clay
lastDensity: Float

Cached screen density to detect changes

clay
lastWidth: Float

Cached screen width to detect changes

clay
lastHeight: Float

Cached screen height to detect changes

clay
mouseDownButtons: ceramic.IntBoolMap

Tracks which mouse buttons are currently pressed

clay
mouseX: Float

Current mouse X position in logical coordinates

clay
mouseY: Float

Current mouse Y position in logical coordinates

clay
activeGamepads: ceramic.IntBoolMap

Tracks currently connected gamepad IDs

clay
removedGamepads: ceramic.IntBoolMap

Temporarily tracks removed gamepads to prevent immediate re-detection

clay
gamepadAxisToButton: ceramic.IntIntMap

Maps gamepad axis IDs to virtual button IDs (for triggers)

clay
gamepadButtonMapping: ceramic.IntIntMap

Remaps physical button IDs to standardized button IDs

clay
gamepadPressedValues: ceramic.IntIntMap

Stores pressed state for each gamepad button (packed storage)

clay
gamepadAxisValues: ceramic.IntFloatMap

Cached gamepad axis values for change detection (packed storage)

clay
gamepadGyroValues: ceramic.IntMap<Array<Float>>

Cached gyroscope values for change detection

clay
gamepadsEnabled: Bool

Whether gamepad input processing is enabled

clay
handleReady(): Void

Callback invoked when the event system is ready

clay
configureGamepadMapping(): Void

Configures gamepad button mapping to normalize differences between SDL gamepad API and HTML5 gamepad API. This ensures consistent button IDs across platforms.

clay
triggerResizeIfNeeded(): Void

Checks if screen dimensions or density have changed and triggers a resize event if needed. This handles cases where the engine might miss resize events.

clay
new(handleReady: Function): Void

Creates a new Clay events handler.

Name Type Description
handleReady Function Callback invoked when the event system is ready

Metadata

Name Parameters
:access backend.Backend
:access backend.Screen
:access backend.Input
:access backend.TextInput
:access ceramic.App