Skip to content

controller-profiles.md

Latest commit

 

History

History
103 lines (84 loc) · 4.35 KB

controller-profiles.md

File metadata and controls

103 lines (84 loc) · 4.35 KB
Raw

Controller Profiles

Supported profile names:

  • xbox
  • playstation
  • switch
  • generic-hid
  • keyboard-mouse

Profiles expose native button names while also mapping to a universal model. For example, Xbox A, PlayStation CROSS, and Switch B all map to the universal SOUTH face button.

PlayStation aliases are supported:

await controller.press("X", 100); // resolves to CROSS
await controller.press("O", 100); // resolves to CIRCLE
await controller.dpad("UP_RIGHT", 100); // presses UP and RIGHT together

Keyboard-Mouse Profile Reports

The keyboard-mouse profile accepts KEY_SPACE, KEY_ESCAPE, KEY_E, KEY_F, KEY_W, KEY_A, KEY_S, KEY_D, MOUSE_LEFT, MOUSE_RIGHT, MOUSE_MIDDLE, and the four DPAD_* directions. Accepted names are stored in controller state, but only controls with a universal mapping appear in XInput and generic HID gamepad reports:

Profile control Universal control XInput/HID control Alias
KEY_SPACE SOUTH A A
KEY_ESCAPE EAST B B
KEY_F WEST X X
KEY_E NORTH Y Y
MOUSE_RIGHT LEFT_TRIGGER Left trigger LT
MOUSE_LEFT RIGHT_TRIGGER Right trigger RT
DPAD_UP, DPAD_DOWN, DPAD_LEFT, DPAD_RIGHT Corresponding universal D-pad control Corresponding D-pad direction —

KEY_W, KEY_A, KEY_S, KEY_D, and MOUSE_MIDDLE are accepted into state but have no universal mapping, so XInput and generic HID gamepad reports omit them. In this profile, KEY_* names do not emit operating-system keyboard events. Mouse names do not produce screen coordinates, cursor movement, coordinate clicks, or window targeting. The mapped mouse buttons are gamepad triggers, not desktop mouse events. Generic HID output is a gamepad report; host applications determine how, or whether, to consume it.

Touchpad And Motion

The runtime includes first-class state for PlayStation touchpad input and PlayStation/Switch motion input:

await controller.touchpad(
  {
    pressed: true,
    contacts: [{ id: 0, x: 0.5, y: 0.35, pressure: 0.8 }],
  },
  120,
);

await controller.motion({
  acceleration: { x: 0, y: 0, z: 1 },
  gyroscope: { x: 0.1, y: 0, z: 0 },
});

Touchpad coordinates and pressure are normalized to 0..1. Touchpad input is enabled for the playstation profile. Motion input is enabled for playstation and switch.

Dry-run and WebSocket adapters can carry these commands and state snapshots. Native bridge adapters also advertise touchpad and gyro support because PlayStation state messages include a hid-playstation-extended profile HID payload with packed touch contacts and motion vectors, and Switch state messages include a hid-switch-extended profile HID payload with motion vectors. The compatibility XInput payload and generic hid-gamepad payload still encode the common gamepad subset, so platform helpers should consume the profile HID payload when they need those richer channels.

Motion values and coordinate frames

controller.motion() accepts caller-provided numeric components for acceleration, gyroscope, and orientation. The API does not define their units, calibrate them against a sensor, or derive one quantity from another. Treat them as application-supplied values; this API does not promise physical units such as meters per second squared, radians per second, or radians.

The PlayStation and Switch extended HID encoders clamp finite component values to -1..1 and serialize them as signed 16-bit fields. Each x, y, and z component is written to the corresponding report field. This describes report serialization, not a normalized physical measurement or a conversion performed by controller.motion(). See HID report formats, report conformance, and the existing PlayStation and Switch motion fixtures for these encoder and component-mapping guarantees.

OpenController does not promise that these axes use a common controller-body, world, gravity, player, screen, or game coordinate frame across devices, hosts, or consumers. The component names identify the report slots; they do not establish a universal human-centric orientation. Apply any consumer-specific transform in the application before passing values to controller.motion().