Skip to content

Controller Definition

Jump to bottom
GitHub Action edited this page Oct 23, 2025 · 31 revisions

Schema Docs

Title: Controller
Type object
Required No
Additional properties Not allowed
Defined in #/definitions/ControllerDefinition

Description: Controller Definition Note: Any consideration related to buttons and their categorization should be related to the default mapping of said buttons

1. [Required] Property Controller > name

Title: Name
Type string
Required Yes

Description: Name of the device

2. [Required] Property Controller > functions

Title: Functions
Type object
Required Yes
Additional properties Not allowed
Defined in #/definitions/Functions

Description: Functionalities of the controller

2.1. [Required] Property Controller > functions > analog_sticks
Type array or null
Required Yes
Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
Analog Stick Control stick offering fine-tuned control beyond the traditional 8 directions of a directional pad ...

2.1.1. Controller > functions > analog_sticks > Analog Stick

Title: Analog Stick
Type object
Required No
Additional properties Not allowed
Defined in #/definitions/AnalogStick

Description: Control stick offering fine-tuned control beyond the traditional 8 directions of a directional pad e.g. The Left and Right stick of the Sony Dualsense

2.1.1.1. [Required] Property Controller > functions > analog_sticks > Analog Stick > name
Type string
Required Yes
2.1.1.2. [Required] Property Controller > functions > analog_sticks > Analog Stick > has_button
Type boolean
Required Yes
2.2. [Optional] Property Controller > functions > scroll_wheel

Title: Scroll Wheel
Type boolean
Required No

Description: Whether or not the controller has a scroll wheel

2.3. [Required] Property Controller > functions > digital_sticks
Type array or null
Required Yes
Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
Digital Stick Control stick only capable of transmitting up to 8 discrete inputs ...

2.3.1. Controller > functions > digital_sticks > Digital Stick

Title: Digital Stick
Type object
Required No
Additional properties Not allowed
Defined in #/definitions/DigitalStick

Description: Control stick only capable of transmitting up to 8 discrete inputs e.g. The stick of a Street Fighter II Arcade Cabinet

2.3.1.1. [Required] Property Controller > functions > digital_sticks > Digital Stick > name
Type string
Required Yes
2.3.1.2. [Required] Property Controller > functions > digital_sticks > Digital Stick > has_button
Type boolean
Required Yes
2.4. [Required] Property Controller > functions > action_buttons
Type array or null
Required Yes
Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
Action Button Button traditionally mapped to performing an action in video games (e.g. Jump, Punch, Kick, Interact…) ...

2.4.1. Controller > functions > action_buttons > Action Button

Title: Action Button
Type object
Required No
Additional properties Not allowed
Defined in #/definitions/ActionButton

Description: Button traditionally mapped to performing an action in video games (e.g. Jump, Punch, Kick, Interact…) Can be Analog or Digital e.g.: A, B, X, Y, LT, LB, RT, RB

2.4.1.1. [Required] Property Controller > functions > action_buttons > Action Button > name
Type string
Required Yes
2.4.1.2. [Required] Property Controller > functions > action_buttons > Action Button > analog
Type boolean
Required Yes
2.4.1.3. [Optional] Property Controller > functions > action_buttons > Action Button > clickable
Type boolean
Required No
2.5. [Required] Property Controller > functions > menu_buttons

Title: Menu Buttons
Type array of string or null
Required Yes

Description: Buttons traditionally mapped to open an in-game menu e.g.: Start, Select

Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
menu_buttons items -

2.5.1. Controller > functions > menu_buttons > menu_buttons items
Type string
Required No
2.6. [Optional] Property Controller > functions > system_buttons

Title: System Buttons
Type array of string or null
Required No

Description: Buttons traditionally mapped to open a system menu or perform an OS-level operation e.g.: Share, Home

Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
system_buttons items -

2.6.1. Controller > functions > system_buttons > system_buttons items
Type string
Required No
2.7. [Required] Property Controller > functions > other_buttons

Title: Other Buttons
Type array of string or null
Required Yes

Description: Buttons which do not perform any software-level or OS-level operation on the console or PC they are connected to, and are not recognized as buttons by the software or OS e.g.: Power, Sync, Turbo, Profile

Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
other_buttons items -

2.7.1. Controller > functions > other_buttons > other_buttons items
Type string
Required No
2.8. [Required] Property Controller > functions > trackpads
Type array or null
Required Yes
Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
Trackpad Tactile sensor commonly found on laptops to emulate a mouse

2.8.1. Controller > functions > trackpads > Trackpad

Title: Trackpad
Type object
Required No
Additional properties Not allowed
Defined in #/definitions/Trackpad

Description: Tactile sensor commonly found on laptops to emulate a mouse

2.8.1.1. [Required] Property Controller > functions > trackpads > Trackpad > name
Type string
Required Yes
2.8.1.2. [Required] Property Controller > functions > trackpads > Trackpad > clickable
Type boolean
Required Yes
2.9. [Required] Property Controller > functions > touch_screens
Type array or null
Required Yes
Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
Touch Screen -

2.9.1. Controller > functions > touch_screens > Touch Screen

Title: Touch Screen
Type object
Required No
Additional properties Not allowed
Defined in #/definitions/TouchScreen
2.9.1.1. [Required] Property Controller > functions > touch_screens > Touch Screen > resolution
Type array of integer
Required Yes
Array restrictions
Min items 2
Max items 2
Items unicity False
Additional items False
Tuple validation See below
Each item of this array must be Description
resolution items -
2.9.1.1.1. Controller > functions > touch_screens > Touch Screen > resolution > resolution items
Type integer
Required No
Restrictions
Minimum ≥ 0
2.9.1.2. [Required] Property Controller > functions > touch_screens > Touch Screen > type
Type enum (of string)
Required Yes

Must be one of:

  • "resistive"
  • "capacitive"
2.10. [Required] Property Controller > functions > directional_buttons
Type array or null
Required Yes
Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
Directional Button Set Set of Individual Buttons which, together, can transmit direction-based inputs to a game similar to a Digital Stick

2.10.1. Controller > functions > directional_buttons > Directional Button Set

Title: Directional Button Set
Type object
Required No
Additional properties Not allowed
Defined in #/definitions/DirectionalButton

Description: Set of Individual Buttons which, together, can transmit direction-based inputs to a game similar to a Digital Stick

2.10.1.1. [Required] Property Controller > functions > directional_buttons > Directional Button Set > set
Type array of string
Required Yes
Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
set items -
2.10.1.1.1. Controller > functions > directional_buttons > Directional Button Set > set > set items
Type string
Required No
2.10.1.2. [Required] Property Controller > functions > directional_buttons > Directional Button Set > socd_prevention

Title: SOCD Prevention
Type object
Required Yes
Additional properties Not allowed
Defined in #/definitions/SocdPrevention

Description: Hardware or software-based solutions which may prevent sending two Simultaneously Opposite Cardinal Direction inputs to the console or PC

2.10.1.2.1. [Required] Property Controller > functions > directional_buttons > Directional Button Set > socd_prevention > hardware

Title: Hardware SOCD Prevention
Type boolean
Required Yes

Description: Whether or not there is a hardware-based solution which may physically prevent two Simultaneously Opposite Cardinal Direction to be pressed at the same time, e.g. a D-Pad’s pivot

2.10.1.2.2. [Required] Property Controller > functions > directional_buttons > Directional Button Set > socd_prevention > software

Title: Software SOCD Prevention
Type object or null
Required Yes
Defined in #/definitions/SoftwareSOCD

Description: List of software-based solutions offered by the controller’s firmware which may prevent sending two Simultaneously Opposite Cardinal Direction inputs to the console or PC, if any

  • neutral: Pressing Left+Right or Up+Down cancels the input and sends a Neutral position to the console or PC
  • last_input: Pressing Left+Right or Up+Down sends the last pressed direction to the console or PC
  • first_input: Pressing Left+Right or Up+Down will ignore the new direction being sent and sends the first pressed direction to the console or PC
  • up: (Only for Up+Down) Pressing Up+Down always sends Up to to the console or PC
  • disable: Software SOCD Prevention can be disabled, leading to both Left & Right inputs or Up & Down inputs being sent to the console or PC
2.10.1.2.2.1. [Required] Property Controller > functions > directional_buttons > Directional Button Set > socd_prevention > software > left_right
Type array of enum (of string)
Required Yes
Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
left_right items -
2.10.1.2.2.1.1. Controller > functions > directional_buttons > Directional Button Set > socd_prevention > software > left_right > left_right items
Type enum (of string)
Required No

Must be one of:

  • "neutral"
  • "last_input"
  • "disable"
2.10.1.2.2.2. [Required] Property Controller > functions > directional_buttons > Directional Button Set > socd_prevention > software > up_down
Type array of enum (of string)
Required Yes
Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
up_down items -
2.10.1.2.2.2.1. Controller > functions > directional_buttons > Directional Button Set > socd_prevention > software > up_down > up_down items
Type enum (of string)
Required No

Must be one of:

  • "neutral"
  • "last_input"
  • "first_input"
  • "disable"
  • "up"
2.11. [Required] Property Controller > functions > gyroscope

Title: Gyroscope
Type boolean
Required Yes

Description: Whether or not the controller has an integrated gyroscope

2.12. [Required] Property Controller > functions > accelerometer

Title: Accelerometer
Type boolean
Required Yes

Description: Whether or not the controller has an integrated accelerometer

2.13. [Required] Property Controller > functions > macro

Title: Macro
Type boolean
Required Yes

Description: Indicates if the buttons of the controller can be mapped to perform a sequence of and/or simultaneous standard button presses automatically Not to be confused with Turbo Includes the simultaneous pressing of directional buttons

2.14. [Required] Property Controller > functions > turbo

Title: Turbo
Type boolean
Required Yes

Description: Indicates if the buttons of the controller can be mapped to simulate the frequent and periodic pressing and unpressing of said button when held Not to be confued with Macro

2.15. [Required] Property Controller > functions > ir_reciever

Title: Infrared Receiver
Type boolean
Required Yes

Description: Whether or not the controller has an integrated Infrared Receiver

2.16. [Required] Property Controller > functions > extension_ports

Title: Extension Ports
Type integer
Required Yes

Description: Number of additional data ports present on the controller, excluding any cable port used for connecting or charging the device, or the Headset Port

Restrictions
Minimum ≥ 0
2.17. [Required] Property Controller > functions > headset_port

Title: Headset Port
Type boolean
Required Yes

Description: Whether or not the controller has an integrated Jack headphone port

2.18. [Required] Property Controller > functions > speaker

Title: Speaker
Type boolean
Required Yes

Description: Whether or not the controller has an integrated speaker

2.19. [Required] Property Controller > functions > microphone

Title: Microphone
Type boolean
Required Yes

Description: Whether or not the controller has an integrated microphone

2.20. [Required] Property Controller > functions > cable

Title: Cable
Type object or null
Required Yes
Defined in #/definitions/Cable

Description: Cable or cable port allowing for a connection between a console or PC and the controller

2.20.1. [Required] Property Controller > functions > cable > interface
Type enum (of string)
Required Yes

Must be one of:

  • "USB-A"
  • "USB-C"
  • "Mini USB-A"
  • "Micro USB-A"
  • "GameCube Controller Port"
2.20.2. [Required] Property Controller > functions > cable > removable
Type boolean
Required Yes
2.21. [Required] Property Controller > functions > bluetooth

Title: Bluetooth
Type boolean
Required Yes

Description: Whether or not the controller is capable to connect wirerlessly to a device via Bluetooth

2.22. [Required] Property Controller > functions > 2_4ghz

Title: 2.4GHz
Type boolean
Required Yes

Description: Whether or not the controller is capable to connect wirerlessly to a device via a 2.4GHz connection, including if said connection requires an additional dongle provided with the controller

2.23. [Required] Property Controller > functions > rumble

Title: Rumble
Type enum (of null or string)
Required Yes

Description: Type of rumble functionnality offered by the controller, if it applies.

  • standard: Refers to traditional rumble motors found in the Nintendo GameCube controller for instance
  • enhanced: Refers to any kind of haptic feedback implemented other than the former, as seen for instance in the Nintendo Switch Joy-Con or the Sony Dualsense

Must be one of:

  • "enhanced"
  • "standard"
  • null
2.24. [Required] Property Controller > functions > digital_to_analog_conversion
Type array or null
Required Yes
Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
Digital-to-Analog Conversion Digital-to-analog conversion capabilities the controller may be able to perform ...

2.24.1. Controller > functions > digital_to_analog_conversion > Digital-to-Analog Conversion

Title: Digital-to-Analog Conversion
Type object
Required No
Additional properties Not allowed
Defined in #/definitions/DigitalToAnalogConversion

Description: Digital-to-analog conversion capabilities the controller may be able to perform

  • 8_way: The device is only capable of emulating the 8 extreme cardinal inputs for said analog stick
  • button: The device is only capable of emulating the full press of said button
  • precision: The exact output of said button or analog stick axis can be controlled and fine-tuned either via hard mapping in the controller’s firmware, or using modifier buttons
2.24.1.1. [Required] Property Controller > functions > digital_to_analog_conversion > Digital-to-Analog Conversion > emulated_analog
Type string
Required Yes
2.24.1.2. [Required] Property Controller > functions > digital_to_analog_conversion > Digital-to-Analog Conversion > type
Type enum (of string)
Required Yes

Must be one of:

  • "8_way"
  • "precision"
  • "button"
2.24.1.3. [Required] Property Controller > functions > digital_to_analog_conversion > Digital-to-Analog Conversion > modifier_buttons

Title: Modifier Button
Type integer
Required Yes

Description: Number of modifier buttons whose sole purpose is to change the value of the analog output value of a button press or analog stick axis

Restrictions
Minimum ≥ 0
2.25. [Required] Property Controller > functions > pc_xinput

Title: XInput compatibility
Type boolean
Required Yes

Description: Whether or not the controller can be recognized by Windows and Windows games as an XInput controller with no additional drivers or adapters, and as such behave as an Xbox 360 controller would

2.26. [Required] Property Controller > functions > pc_steaminput

Title: Steam Input compatibility
Type boolean
Required Yes

Description: Whether or not the controller can be recognized by Steam on Windows and Linux with no additional drivers or adapters, and translate the controller inputs to XInput via Steam Input

2.27. [Required] Property Controller > functions > native_consoles

Title: Native Consoles
Type array of enum (of string) or null
Required Yes

Description: Lists the consoles on which the controller can be used without the use of an adapter, for most games. In the case of the PS5, applies if the controller is recognized by the PS4 compatibility layer implemented in Street Fighter 6 and other fighting games as well.

Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
native_consoles items -

2.27.1. Controller > functions > native_consoles > native_consoles items
Type enum (of string)
Required No

Must be one of:

  • "ps1"
  • "ps2"
  • "ps3"
  • "ps4"
  • "ps5"
  • "nsw"
  • "wiiu"
  • "wii"
  • "ngc"
  • "n64"
  • "snes"
  • "nes"
  • "xbox"
  • "xb360"
  • "xb1"
  • "xbs"
  • "smd"
  • "saturn"
  • "dc"
  • "nsw2"
3. [Optional] Property Controller > source

Title: Source
Type string
Required No
Format uri

Description: Main source for information on the controller specifications Ideally either a link to a manual on the Internet Archive or to an archived webpage on the Wayback Machine

Restrictions
Must match regular expression https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_\+.~#?&//=]*) Test
4. [Optional] Property Controller > variants
Type array
Required No
Array restrictions
Min items N/A
Max items N/A
Items unicity True
Additional items False
Tuple validation See below
Each item of this array must be Description
Variant A different way to use the controller than the one seen on the base image.png file, usually through the use of additional accessories which may attach to the controller ...

4.1. Controller > variants > Variant

Title: Variant
Type object
Required No
Additional properties Not allowed
Defined in #/definitions/Variant

Description: A different way to use the controller than the one seen on the base image.png file, usually through the use of additional accessories which may attach to the controller May be omitted if the controller only has one variant Note: Must include a name for the base variant

4.1.1. [Required] Property Controller > variants > Variant > name

Title: Name
Type string
Required Yes
4.1.2. [Required] Property Controller > variants > Variant > image

Title: Image
Type string
Required Yes

Description: Name of a PNG image showing the mentionned variant The image must be placed in the same folder as this config file Note: At least one of the variants must use the default image.png file

Restrictions
Must match regular expression (.*)\.(p|P)(n|N)(g|G) Test
5. [Optional] Property Controller > short_name

Title: Short name
Type string
Required No

Description: Shorter display name for the device

Generated using json-schema-for-humans on 2025-10-23 at 12:27:07 +0000

Clone this wiki locally