Abstract

The Gamepad specification defines a low-level interface that represents gamepad devices.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

If you have comments for this spec, please send them to public-webapps@w3.org with a Subject: prefix of [gamepad]. See Bugzilla for this specification's open bugs.

This document was published by the Web Platform Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). All comments are welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 September 2015 W3C Process Document.

1. Introduction

This section is non-normative.

Some user agents have connected gamepad devices. These devices are desirable and suited to input for gaming applications, and for "10 foot" user interfaces (presentations, media viewers).

Currently, the only way for a gamepad to be used as input would be to emulate mouse or keyboard events, however this would lose information and require additional software outside of the user agent to accomplish emulation.

Meanwhile, native applications are capable of accessing these devices via system APIs.

The Gamepad API provides a solution to this problem by specifying interfaces that allow web applications to directly act on gamepad data.

This specification references interfaces from a number of other specifications:

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, MUST NOT, RECOMMENDED, and SHOULD are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL] as this specification uses that specification and terminology.

A conforming implementation is required to implement all fields defined in this specification.

3. Scope

Interfacing with external devices designed to control games has the potential to become large and intractable if approached in full generality. In this specification we explicitly choose to narrow scope to provide a useful subset of functionality that can be widely implemented and broadly useful.

Specifically, we choose to only support the functionality required to support gamepads. Support for gamepads requires two input types: buttons and axes. Both buttons and axes are reported as analog values, buttons ranging from [0..1], and axes ranging from [-1..1].

While the primary goal is support for gamepad devices, supporting these two types of analog inputs allows support for other similar devices common to current gaming systems including joysticks, driving wheels, pedals, and accelerometers. As such, the name "gamepad" is exemplary rather than trying to be a generic name for the entire set of devices addressed by this specification.

We specifically exclude support for more complex devices that may also be used in some gaming contexts, including those that that do motion sensing, depth sensing, video analysis, gesture recognition, and so on.

4. Gamepad Interface

This interface defines an individual gamepad device.

interface Gamepad {
    readonly        attribute DOMString           id;
    readonly        attribute long                index;
    readonly        attribute boolean             connected;
    readonly        attribute DOMHighResTimeStamp timestamp;
    readonly        attribute GamepadMappingType  mapping;
    readonly        attribute double[]            axes;
    readonly        attribute GamepadButton[]     buttons;
};

4.1 Attributes

axes of type array of double, readonly
MUSTSHOULDSHOULDSHOULDRECOMMENDED
buttons of type array of GamepadButton, readonly
RECOMMENDED
connected of type boolean, readonly
connectedMUST
id of type DOMString, readonly
index of type long, readonly
user agentMUSTMUST NOTMUST
mapping of type GamepadMappingType, readonly
SHOULD"standard"Standard Gamepad layoutMUSTmapping
timestamp of type DOMHighResTimeStamp, readonly
axesbuttonnavigationStarttimestampnavigationStart

5. GamepadButton Interface

This interface defines the state of an individual button on a gamepad device.

interface GamepadButton {
    readonly        attribute boolean pressed;
    readonly        attribute boolean touched;
    readonly        attribute double  value;
};

5.1 Attributes

pressed of type boolean, readonly
MUSTMUSTSHOULDSHOULD
touched of type boolean, readonly
MUSTMUSTMUST
value of type double, readonly
MUSTMUSTMUSTMUSTMUST

6. GamepadMappingType enum

This enum defines the set of known mappings for a Gamepad.

enum GamepadMappingType {
    "_",
    "standard"
};
Enumeration description
The empty string indicates that no mapping is in use for this gamepad. Note: the WebIDL here is currently wrong due to a ReSpec bug. The actual enum value is the empty string ("").
standard The Gamepad's controls have been mapped to the Standard Gamepad layout.

8. GamepadEvent Interface

[Constructor(GamepadEventInit eventInitDict)]
interface GamepadEvent : Event {
    readonly        attribute Gamepad gamepad;
};

8.1 Attributes

gamepad of type Gamepad, readonly
dictionary GamepadEventInit : EventInit {
    required Gamepad gamepad;
};

8.2 Dictionary GamepadEventInit Members

gamepad of type Gamepad, required
The gamepad associated with this event.

9. Remapping

Each device manufacturer creates many different products and each has unique styles and layouts of buttons and axes. It is intended that the user agent support as many of these as possible.

Additionally there are de facto standard layouts that have been made popular by game consoles. When the user agent recognizes the attached device, it is RECOMMENDED that it be remapped to a canonical ordering when possible. Devices that are not recognized should still be exposed in their raw form.

There is currently one canonical device, the "Standard Gamepad". The standard gamepad has 4 axes, and up to 17 buttons. When remapping, the indices in axes[] and buttons[] should correspond as closely as possible to the physical locations in the diagram below. Additionally, the mapping property of the Gamepad SHOULD be set to the string "standard".

10. Usage Examples

This section is non-normative.

The example below demonstrates typical access to gamepads. Note the relationship with the WindowAnimationTiming interface.

Example 2
function runAnimation()
{
    window.requestAnimationFrame(runAnimation);

    var gamepads = navigator.getGamepads();

    for (var i = 0; i < gamepads.length; ++i)
    {
        var pad = gamepads[i];
        // todo; simple demo of displaying pad.axes and pad.buttons
    }
}

window.requestAnimationFrame(runAnimation);

Best Practice 1: Coordination with WindowAnimationTiming

Interactive applications will typically be using the WindowAnimationTiming interface to drive animation, and will want coordinate animation with user gamepad input. As such, the gamepad data should be polled as closely as possible to immediately before the animation callbacks are executed, and with frequency matching that of the animation. That is, if the animation callbacks are running at 60Hz, the gamepad inputs should also be sampled at that rate.

11. The gamepadconnected event

User agents implementing this specification must provide a new DOM event, named gamepadconnected. The corresponding event MUST be of type GamepadEvent and MUST fire on the window object. Registration for and firing of the gamepadconnected event MUST follow the usual behavior of DOM4 Events. [DOM4]

A user agent MUST dispatch this event type to indicate the user has connected a gamepad. If a gamepad was already connected when the page was loaded, the gamepadconnected event SHOULD be dispatched when the user presses a button or moves an axis.

12. The gamepaddisconnected event

User agents implementing this specification must provide a new DOM event, named gamepaddisconnected. The corresponding event MUST be of type GamepadEvent and MUST fire on the window object. Registration for and firing of the gamepaddisconnected event MUST follow the usual behavior of DOM4 Events. [DOM4]

When a gamepad is disconnected from the user agent, if the user agent has previously dispatched a gamepadconnected event for that gamepad to a window, a gamepaddisconnected event MUST be dispatched to that same window.

13. Other events

More discussion needed, on whether to include or exclude axis and button changed events, and whether to roll them more together (gamepadchanged?), separate somewhat (gamepadaxischanged?), or separate by individual axis and button.

A. Acknowledgements

This section is non-normative.

Many have made contributions in code, comments, or documentation:

Please let me know if I have inadvertently omitted your name.

B. References

B.1 Normative references

[ANIMATION-TIMING]
James Robinson; Cameron McCormack. W3C. Timing control for script-based animations. 22 September 2015. W3C Note. URL: https://www.w3.org/TR/animation-timing/
[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C. W3C DOM4. 19 November 2015. W3C Recommendation. URL: https://www.w3.org/TR/dom/
[HIGHRES-TIME]
Ilya Grigorik; James Simonsen; Jatinder Mann. W3C. High Resolution Time Level 2. 20 July 2016. W3C Working Draft. URL: https://www.w3.org/TR/hr-time-2/
[NAVIGATION-TIMING]
Zhiheng Wang. W3C. Navigation Timing. 17 December 2012. W3C Recommendation. URL: https://www.w3.org/TR/navigation-timing/
[NAVIGATOR]
Robin Berjon et al. W3C. Navigator interface in HTML5. W3C Editor's Draft. URL: https://www.w3.org/html/wg/drafts/html/master/webappapis.html#navigator
[RFC2119]
S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]
Cameron McCormack; Boris Zbarsky. W3C. WebIDL Level 1. 15 September 2016. W3C Proposed Recommendation. URL: https://www.w3.org/TR/WebIDL-1/