@webxr-input-profiles/registry

WebXR Input Profiles Registry

This package contains information for User Agents ensure they expose consistent intrinsic values for all WebXR XRInputSource objects. For each hardware device, this information currently includes:

• The profile id
• The ordered list of fallback profile ids as specified in the WebXR Device API
• The allowable XRInputSource.handedness values
• The component layouts for each handedness value
• The component responsible for causing select, selectstart, and selectend events to fire
• The presence of a non-null XRInputSource.gamepad. When non-null:
  • The appropriate Gamepad.mapping value
  • The relationship between physical hardware components (e.g. trigger, squeeze, button, touchpad, and thumbstick) to indices in the XRInputSource.gamepad.buttons array.
  • The relationship between physical touchpads and thumbsticks to indices in the XRInputSource.gamepad.axes array.

Contributing

Adding a vendor prefix

To reserve a new vendor prefix, submit a pull request that adds the vendor to the list in the in the vendor prefixes section of this document.

Adding a profile

First ensure that the desired vendor prefix has been reserved, and then add a profile JSON file that represents the new device in the prefix's subfolder. This file must conform with the schema and the package must build successfully before submitting a pull request. If adding an associated 3D asset in the same pull request, please also follow the instructions in the asset package.

Filing a bug

Bugs with existing profiles can be filed using this issue template. New profiles should added via pull requests to ensure the fastest turnaround.

Development

In general, this package should be built and tested from the root of the repository using the following command:

npm run test

To build just this package without running tests, invoke the following command from the root of the repository:

npm run build -- --scope @webxr-input-profiles/registry

Licence

See the LICENSE.md.

Usage

Getting started

In most cases is it not necessary to install this package. It is only intended for use by User Agents and as an input to the assets package build. However, when necessary, the package can be installed from npm by the following command.

npm install @webxr-input-profiles/registry.

Profile prefixes

Each profile has a unique id that must begin with a generic or vendor prefix as described in the WebXR Device API. Profile JSON files are found in './profiles/[prefix] folders.

Generic prefix

The "generic" prefix is reserved for all profiles not associated with a specific vendor

Reserved vendor prefixes

The following prefixes are reserved for companies with XR hardware

• google - Google
• hp - Hewlett-Packard
• htc - HTC
• magicleap - Magic Leap
• microsoft - Microsoft Corp
• oculus - Oculus
• samsung - Samsung
• valve - Valve Corporation
• pico - Pico Interactive

Schema

Profile id and fallback profile ids

Profiles are required to have a profileId that uniquely identifies the profile and must conform to the format specified by the WebXR Device API. A profileId cannot be changed once added to the registry; if changes are necessary a new profileId must be defined.Profiles are also required to have a fallbackProfileIds array containing profile ids defined in the registry that are considered acceptable fallback substitutes for profile. The contents of this array may be modified after the profile has been added to the repository, however changes should be avoided if at all possible due to the potential for conformance mismatches. Profiles with the generic prefix may leave the fallbackProfileIds array empty. All other profiles must have at least one fallback profile id, and the the last entry in the array must have the generic vendor prefix.

For example

{
    "profileId" : "vendorprefix-profileId",
    "fallbackProfileIds" : ["vendorprefix-otherProfileId", "generic-trigger"]
}

The XRInputSource.profiles array is comprised of these two properties; the profileId is the first element followed by the elements in the fallbackProfileIds property.

Deprecated profile ids

In some cases an input source may have been identified by a non-standard profile id in the past or in some user agents. These can be listed in the deprecatedProfileIds array, which will cause those ids to be associated with the correct profile and assets so that user agents advertising the non-standard id still provide users with the right resources.

{
    "profileId" : "vendorprefix-profileid",
    "deprecatedProfileIds" : ["vendorprefix-oldprofileid"]
}

User agents should always prefer reporting the standard profile ids, and should not intentionally report deprecated ids, even as a fallback profile. User agents that currently report a deprecated profile id should make an effort to change to the standard profile id instead.

Layouts

Profiles are required to have a layouts property which contains the layouts for each supported handedness. The layouts property must have one, and only one, of the following arrangements of keys to be considered valid:

• none
• left and right
• left and right and none
• left-right
• left-right and none
• left-right-none

For example:

{
    "layouts": {
        "none" : {},
        "left-right": {}
    }
}

Components

Each layout is required to have a components property which contains information about all the individual parts of an XRInputSource. Components are comprised of a key which uniquely identifies them and a which describes their behavior. Component keys must not contain spaces at the beginning or end. Currently, the valid types are: trigger, squeeze, touchpad, thumbstick, and button

Each layout is also required to have a selectComponentId property which refers to an entry in the components object. This component will cause the WebXR select, selectStart, and selectEnd events to fire.

For example:

{
    "layouts": {
        "left-right": {
            "selectComponentId": "my-hardware-trigger-name",
            "components": {
                "my-hardware-trigger-name": { "type": "trigger" },
                "my-hardware-touchpad-name": { "type": "touchpad" }
            }
        }
    }
}

Gamepads

If an XRInputSource will have a non-null XRInputSource.gamepad, the profile must contain information which allows all User Agents to report identical data in Gamepad.mapping, Gamepad.buttons, and Gamepad.axes. These details are enumerated in the layout's gamepad property.

The gamepad.mapping string must follow the rules laid out in the WebXR Gamepads Module. The gamepad.buttons property is an array which matches index-for-index with the web platform's Gamepad.buttons array. Each index contains either null or the id of the component from which the data must be populated. The gamepad.axes property is an array which matches index-for-index with the web platform's Gamepad.axes array. Each index contains either null or the combination of component id and axis from which the data must be populated.

For example:

{
    "layouts": {
        "left-right": {
            "components": {
                "my-hardware-trigger-name": { "type": "trigger" },
                "my-hardware-touchpad-name": { "type": "touchpad" }
            },
            "gamepad" : {
                "mapping" : "xr-standard",
                "buttons" : [
                    "my-hardware-trigger-name",
                    null,
                    "my-hardware-touchpad-name"
                ],
                "axes" : [
                    { "componentId": "my-hardware-touchpad-name", "axis":"xAxis"},
                    { "componentId": "my-hardware-touchpad-name", "axis":"yAxis"}
                ]
            }
        }
    }
}