Add a profile-to-report conformance matrix for gamepad outputs #9

Selected for Cycle 2

Selection: Rank 2 in research issue #7, under umbrella issue #5. This is an independent build slice; it does not depend on issue #8.

Persona and situation

An OpenController integrator emits Xbox, PlayStation, Switch, or generic HID input through a report adapter or native bridge, then tests that input in SDL- or Steam-based games. They need confidence that each profile's logical controls reach the expected report fields and that richer profile controls are not silently lost when a compatibility format is selected.

Direct evidence

• SDL issue #16220, opened 2026-08-31: a PDP Switch-style controller's SDL3 mapping assigns right-stick axes a2/a3 to triggers, despite raw Linux input and SDL2 mapping behaving correctly. The report includes the incorrect and corrected mappings and a reproduction using SDL3 testcontroller.
• SDL issue #14829, opened 2026-01-15: SDL's input-gamepad-events example prints controller-database identifiers instead of labels for non-Xbox-style controllers. The observed consequence is incorrect naming in the example output.
• Steam for Linux issue #13492, opened 2026-08-06: a DualSense touchpad region maps incorrectly in Mortal Kombat 1 with Steam Input enabled. The user's workaround is disabling Steam Input; after reconnecting, the game no longer accepts controller input until the game is restarted.

These are three reports across SDL and Steam, not prevalence estimates. Each currently has zero comments and no reactions listed, so recurrence and community engagement are unestablished. The SDL mapping report provides a corrected mapping as a workaround; the SDL example report gives no workaround. The Steam reporter worked around the touchpad issue by disabling Steam Input, then needed a game restart after reconnect; no recurrence confirmation is recorded in that issue. The SDL mapping report is a confirmed upstream mapping defect. The symptoms span distinct upstream layers, so this issue proposes output conformance checks rather than asserting a common root cause.

OpenController fit

@opencontroller/core already defines Xbox, PlayStation, Switch, generic HID, and keyboard/mouse profiles; normalized state and profile aliases; XInput and generic HID encoders; and PlayStation/Switch extended HID reports. Core tests already decode several encoded reports. This work can verify OpenController-controlled profile-to-report behavior in fixtures. It cannot correct SDL or Steam's external device databases, physical-controller discovery, game-specific mappings, reconnect bugs in those consumers, or guarantee that a host OS/game interprets a virtual device as intended.

Proposed outcome

A documented, table-driven conformance suite that drives each supported gamepad profile with distinct sentinel values and asserts the fields and control bits emitted by supported report adapters. Make profile-only fields and lossy compatibility outputs explicit in the matrix so integrators can select the report format intentionally.

Acceptance criteria

• A checked-in matrix lists supported gamepad profiles, logical face buttons, shoulders, triggers, D-pad, sticks, and any profile-only controls, alongside the report formats that carry them.
• Table-driven tests assert distinct button, trigger, and axis inputs encode into the intended fields for each applicable profile and report format; tests would fail for swapped axes/triggers or profile button aliases.
• PlayStation touchpad/motion and Switch motion are explicitly tested in their profile-specific reports, and their omission from XInput/generic reports is documented as a format limitation.
• The documented test workflow runs without physical controllers and makes no claim of SDL, Steam, OS, or game compatibility based on fixture results alone.
• Documentation identifies the current output/report support and how to contribute a new profile conformance case.

Non-goals and risks

• No device-specific SDL mapping database, Steam Input layout, game patch, driver workaround, physical-controller ingest, reconnect repair, or native-backend readiness work.
• No claim that a passing encoder fixture proves the host or game consumes the virtual report correctly; a separate manual/platform validation may be needed after research selection.
• The matrix must distinguish OpenController's logical naming from platform-specific glyph labels and must not imply that similarly named buttons have identical semantics across every game.