npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@webxr-input-profiles/registry

v1.0.3

Published

Registry for profile ids and their associated button layouts

Downloads

15

Readme

WebXR Input Profiles Registry

This package contains information for User Agents to 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

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 the 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 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 type 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"}
                ]
            }
        }
    }
}