游戏手柄

如果以完全通用的方式处理与控制游戏的外部设备进行接口对接，其工作量可能会变得巨大且难以处理。在本规范中，我们明确选择缩小范围，提供一个可被广泛实现且具有普遍实用性的功能子集。

具体而言，我们选择仅支持支持游戏手柄所需的功能。支持游戏手柄需要两种输入类型：按钮和轴。按钮和轴均报告为模拟值，按钮范围为 [0 .. 1]，轴范围为 [-1 .. 1]。

虽然主要目标是支持游戏手柄设备，但支持这两种类型的模拟输入也允许支持当前游戏系统中常见的其他类似设备，包括操纵杆、方向盘、踏板和加速度计。因此，“gamepad”（游戏手柄）这个名称是示例性的，而不是试图成为本规范所涉及的整套设备的总称。

我们明确排除了对某些可能在特定游戏场景中使用且更为复杂的设备的支持，包括那些涉及运动传感、深度传感、视频分析、手势识别等的设备。

一个 游戏手柄 是输入控件和输出控件的集合。一个 输入控件 拥有随时间更新的 输入值 集合。输入控件包括 游戏手柄 的按钮、触发器、操纵杆、拇指摇杆和触摸表面。一个 输出控件 是一种通过改变 游戏手柄 的行为来向用户提供反馈的特性。输出控件包括 游戏手柄 的触觉执行器。如果 用户代理 可以读取其 输入控件 的当前状态，则称该 游戏手柄 是 可用的。不可用的 游戏手柄 被称为 不可用的。在 游戏手柄 可用 期间，其 输入控件 和 输出控件 不能改变。

用户代理 负责以下工作：

• 枚举 可用 的 游戏手柄，
• 检测 游戏手柄 何时变得 可用 或 不可用，
• 检测 输入控件 何时更新了 输入值，
• 读取 输入值 的当前状态，以及
• 命令 游戏手柄 使用其 输出控件。

游戏手柄 具有一个 游戏手柄标识字符串，这是一个标识 游戏手柄 品牌或样式的易读字符串。其内容由 用户代理 决定。

该接口定义了一个独立的游戏手柄设备。

WebIDL[Exposed=Window]
interface Gamepad {
  readonly attribute DOMString id;
  readonly attribute long index;
  readonly attribute boolean connected;
  readonly attribute DOMHighResTimeStamp timestamp;
  readonly attribute GamepadMappingType mapping;
  readonly attribute FrozenArray<double> axes;
  readonly attribute FrozenArray<GamepadButton> buttons;
  readonly attribute FrozenArray<GamepadTouch> touches;
  [SameObject] readonly attribute GamepadHapticActuator vibrationActuator;
};

用于与系统通信的算法通常异步完成，在 游戏手柄任务源 上排队工作。

Gamepad 的实例在创建时带有下表中描述的内部槽位：

id 属性

游戏手柄的识别字符串。该字符串标识已连接的游戏手柄设备的品牌或样式。

id 字符串的确切格式未指定。建议 用户代理 选择一个能识别产品但不能唯一识别设备的字符串。例如，USB 游戏手柄可以通过其 idVendor 和 idProduct 值来识别。序列号或蓝牙设备地址等唯一标识符 绝不能 包含在 id 字符串中。

index 属性

游戏手柄在 Navigator 中的索引。当多个游戏手柄连接到 用户代理 时，索引 必须 从零开始按先到先得的原则分配。如果游戏手柄断开连接，之前分配的索引 绝不能 重新分配给持续连接的游戏手柄。然而，如果一个游戏手柄断开连接，随后连接了相同或不同的游戏手柄，则 必须 重用最低的先前使用过的索引。

connected 属性

指示此对象表示的物理设备是否仍连接到系统。当游戏手柄变得不可用时（无论是物理断开、关机还是以其他方式不可用），connected 属性 必须 设置为 false。

connected 获取器的步骤为：

1. 返回 this.[[connected]]。

timestamp 属性

timestamp 允许作者确定此游戏手柄的 axes 或 buttons 属性最后一次更新的时间。每当系统 收到来自设备的新按钮或轴输入值 时，该值 必须 设置为 当前高分辨率时间。如果未从硬件接收到任何数据，timestamp 必须 为 Gamepad 首次对脚本可用时的 当前高分辨率时间。

Warning

用户代理 应该 将 timestamp 属性的最小分辨率设置为 5 微秒，遵循 [HR-TIME] 的时钟分辨率建议。

timestamp 获取器的步骤为：

1. 返回 this.[[timestamp]]。

mapping 属性

该设备正在使用的映射。如果 用户代理 了解设备的布局，则它 应该 通过将 mapping 设置为相应的 GamepadMappingType 值来指示映射正在使用中。

要为游戏手柄设备 选择映射，请执行以下步骤：

1. 如果游戏手柄设备的按钮和轴布局符合 标准游戏手柄 布局，则返回 "standard"。
2. 返回 ""。

axes 属性

游戏手柄所有轴的值数组。所有轴值 必须 线性归一化到 [-1 .. 1] 范围。如果控制器垂直于地面且方向摇杆指向向上，-1 应该 对应于“向前”或“左”，1 应该 对应于“向后”或“右”。从 2D 输入设备获取的轴 应该 在轴数组中彼此相邻，X 在前，Y 在后。建议 轴按重要性递减顺序出现，使得元素 0 和 1 通常代表方向摇杆的 X 和 Y 轴。在 用户代理 需要返回不同值（或不同顺序的值）之前，必须 返回相同的对象。

axes 获取器的步骤为：

1. 返回 this.[[axes]]。

buttons 属性

游戏手柄所有按钮的按钮状态数组。建议 按钮按重要性递减顺序出现，使得主按钮、次要按钮、第三按钮等分别作为按钮数组的元素 0、1、2...。在 用户代理 需要返回不同值（或不同顺序的值）之前，必须 返回相同的对象。

buttons 获取器的步骤为：

1. 返回 this.[[buttons]]。

touches 属性

由所有触摸表面生成的 GamepadTouch 对象的 列表。

touches 获取器的步骤为：

1. 返回 this.[[touches]]。

vibrationActuator 属性

表示设备主要振动执行器的 GamepadHapticActuator 对象。

vibrationActuator 获取器的步骤为：

1. 返回 this.[[vibrationActuator]]。

此接口定义了游戏手柄设备上单个按钮的状态。

WebIDL[Exposed=Window]
interface GamepadButton {
  readonly attribute boolean pressed;
  readonly attribute boolean touched;
  readonly attribute double value;
};

GamepadButton 实例创建时带有下表中描述的内部槽位

pressed 属性

按钮的按下状态。如果按钮当前处于按下状态，则此属性 必须 为 true，否则为 false。对于没有数字开关来指示纯粹按下或释放状态的按钮，用户代理 必须 选择一个 按钮按下阈值，以在值高于一定数值时指示按钮被按下。如果平台 API 提供了建议值，用户代理 应该 使用该值。在其他情况下，用户代理 应该 选择其他合理的数值。

pressed 获取器步骤为

1. 返回 此.[[pressed]]。

touched 属性

按钮的触摸状态。如果按钮能够检测触摸，则此属性 必须 在按钮当前被触摸时为 true，否则为 false。如果按钮不能检测触摸但能报告模拟值，则此属性 必须 在 value 属性大于 0 时为 true，value 为 0 时为 false。如果按钮不能检测触摸且只能报告数字值，则此属性 必须 反映 pressed 属性。

touched 获取器步骤为

1. 返回 此.[[touched]]。

value 属性

对于带有模拟传感器的按钮，此属性 必须 表示按钮被按下的程度。所有按钮值 必须 线性归一化到 [0 .. 1] 范围。0 必须 表示完全未按下，1 必须 表示完全按下。对于没有模拟传感器的按钮，必须仅提供 0 和 1 的值，分别代表完全未按下和完全按下。

value 获取器步骤为

1. 返回 此.[[value]]。

此接口定义了支持此类输入的游戏手柄触摸表面上的触摸。该对象包含一个 touchId，它从输入介质（例如手指、触控笔等）接触触摸设备那一刻起，直到输入介质不再与触摸设备接触为止，唯一地标识该触摸点。

WebIDLdictionary GamepadTouch {
  unsigned long touchId;
  octet surfaceId;
  DOMPointReadOnly position;
  DOMRectReadOnly? surfaceDimensions;
};

touchId 属性

触摸的唯一 ID。范围为 [0 .. 4294967295]。

surfaceId 属性

生成触摸的表面的唯一 ID。

position 属性

一个 DOMPointReadOnly，它保存了触摸的 x, y 坐标。z 和 w 值当前未使用。每个坐标的范围归一化为 [-1 .. 1]。沿 x 轴，-1 指最左侧坐标，1 指最右侧坐标。沿 y 轴，-1 指最顶部坐标，1 指最底部坐标。

surfaceDimensions 属性

一个使用整数单位的触摸表面 width 和 height 初始化的 DOMRectReadOnly。如果不可用，则为 null。

此枚举定义了游戏手柄的一组已知映射。

WebIDLenum GamepadMappingType {
  "",
  "standard",
  "xr-standard",
};

""

空字符串表示此游戏手柄未使用任何映射。

"standard"

游戏手柄的控件已映射到 标准游戏手柄 布局。

"xr-standard"

游戏手柄的控件已映射到 "xr-standard" 游戏手柄映射。此映射保留供 WebXR 游戏手柄模块 - 1 级 使用。getGamepads() 返回的 Gamepad 对象 绝不 报告 "xr-standard" 的 mapping。

GamepadHapticActuator 对应于可施加力以实现触觉反馈的电机或其他执行器的配置。

WebIDL[Exposed=Window]
interface GamepadHapticActuator {
  [SameObject] readonly attribute FrozenArray<GamepadHapticEffectType> effects;
  Promise<GamepadHapticsResult> playEffect(
      GamepadHapticEffectType type,
      optional GamepadEffectParameters params = {}
  );
  Promise<GamepadHapticsResult> reset();
};

GamepadHapticActuator 实例创建时带有下表中描述的内部槽位

effects 属性

表示执行器支持的所有触觉效果类型的 GamepadHapticEffectType 值数组。此属性列出了执行器支持的 GamepadHapticEffectType 值，除非 用户代理 不支持播放该类型的效果。

effects 获取器步骤为

1. 返回 此.[[effects]]。

playEffect() 方法

调用 playEffect() 方法的步骤，使用 GamepadHapticEffectType type 和 GamepadEffectParameters params，为

1. 如果 params 没有描述 type 类型的 有效效果，则返回 一个被拒绝的 promise，并附带一个 TypeError。
2. 令 document 为 当前设置对象的 相关全局对象的 关联 Document。
3. 如果 document 为 null 或 document 不是 完全激活的，或者 document 的 可见性状态 为 "hidden"，则返回 一个被拒绝的 promise，并附带 "InvalidStateError" DOMException。
4. 如果 此.[[playingEffectPromise]] 不为 null
   1. 令 effectPromise 为 此.[[playingEffectPromise]]。
   2. 将 此.[[playingEffectPromise]] 设置为 null。
   3. 在 游戏手柄任务源上，使用 此 对象的 相关全局对象，排入一个全局任务，以用 "preempted" 解决 (resolve) effectPromise。
5. 如果 此 GamepadHapticActuator 不能 播放 type 类型的效果，则返回 一个被拒绝的 promise，理由为 NotSupportedError。
6. 令 [[playingEffectPromise]] 为 一个新的 promise。
7. 令 playEffectTimestamp 为基于 document 的 相关全局对象的 当前高分辨率时间。
8. 并行执行以下步骤
   1. 对执行器 发布一个触觉效果，参数为 type, params 和 playEffectTimestamp。
   2. 当效果完成时，如果 此.[[playingEffectPromise]] 不为 null，则在 游戏手柄任务源上，使用 此 对象的 相关全局对象，排入一个全局任务，以运行以下步骤
      1. 如果 此.[[playingEffectPromise]] 为 null，则中止这些步骤。
      2. 解决 此.[[playingEffectPromise]]，使用 "complete"。
      3. 将 此.[[playingEffectPromise]] 设置为 null。
9. 返回 [[playingEffectPromise]]。

reset() 方法

reset() 方法的步骤为

1. 令 document 为 当前设置对象的 相关全局对象的 关联 Document。
2. 如果 document 为 null 或 document 不是 完全激活的，或者 document 的 可见性状态 为 "hidden"，则返回 一个被拒绝的 promise，并附带 "InvalidStateError" DOMException。
3. 令 resetResultPromise 为 一个新的 promise。
4. 如果 此.[[playingEffectPromise]] 不为 null，则并行执行以下步骤
   1. 令 effectPromise 为 此.[[playingEffectPromise]]。
   2. 停止触觉效果，在 此 游戏手柄的执行器上。
   3. 如果效果已成功停止，执行
      1. 如果 effectPromise 和 此.[[playingEffectPromise]] 仍然相同，则将 此.[[playingEffectPromise]] 设置为 null。
      2. 在 游戏手柄任务源上，使用 此 对象的 相关全局对象，排入一个全局任务，以用 "preempted" 解决 (resolve) effectPromise。
   4. 解决 (resolve) resetResultPromise，使用 "complete"
5. 返回 resetResultPromise。

如果 type 可以在 [[effects]] 列表中找到，则 GamepadHapticActuator 可以 播放 type 类型的效果。

要检查 GamepadHapticEffectType type 和 GamepadEffectParameters params 是否描述了一个 有效效果，请执行以下步骤

1. 根据 GamepadHapticEffectType type 的值，切换

   "dual-rumble"

   如果 params 没有描述 有效的双重震动效果，则返回 false。

   "trigger-rumble"

   如果 params 没有描述 有效的触发器震动效果，则返回 false。

2. 返回 true

要对执行器 发布触觉效果，用户代理 必须 向设备发送命令以呈现 type 类型的效果，并尝试使用提供的 params。当 params.startDelay 不为 0.0 时，用户代理 应该 使用提供的 playEffectTimestamp 以获得更精确的播放时序。用户代理 可以 修改效果以增加兼容性。例如，为震动电机设计的效果可以转换为支持波形触觉但缺少震动电机的设备的波形效果。

要对执行器 停止触觉效果，用户代理 必须 向设备发送命令以中止当前正在播放的任何效果。如果触觉效果被中断，执行器 应该 尽可能快地恢复到静止状态。

WebIDLenum GamepadHapticsResult {
  "complete",
  "preempted"
};

complete

触觉效果播放完成。

preempted

当前效果被另一个效果停止或替换（即“抢占”）。

效果类型定义了执行器如何解释效果参数。

WebIDLenum GamepadHapticEffectType {
  "dual-rumble",
  "trigger-rumble"
};

"dual-rumble" 效果类型

"dual-rumble" 描述了一种触觉配置，在标准游戏手柄的每个手柄中都有一个偏心旋转质量 (ERM) 振动电机。在这种配置中，任一电机都能使整个游戏手柄振动。每个电机产生的振动效果是不等的，因此可以将它们结合起来以产生更复杂的触觉效果。

"dual-rumble" 效果是一种针对此类执行器的固定持续时间、恒定强度的振动效果。"dual-rumble" 效果由 startDelay、duration、strongMagnitude 和 weakMagnitude 定义，这些都不是必需的，因为它们默认为 0。

strongMagnitude 和 weakMagnitude 设置低频和高频振动的强度级别，归一化到 [0 .. 1] 范围，默认值为 0。

给定 GamepadEffectParameters params，一个 有效的双重震动效果 必须具有 有效的 duration，有效的 startDelay，并且 strongMagnitude 和 weakMagnitude 都必须在 [0 .. 1] 范围内。

"trigger-rumble" 效果类型

"trigger-rumble" 描述了一种触觉配置，在 标准游戏手柄 的每个底部前部按钮（规范索引 6 和 7 的按钮）中都有一个振动电机，此外还有用于 "dual-rumble" 的两个手柄电机。这些按钮通常采用弹簧触发器的形式。在这种配置中，任一电机都能在按钮表面提供局部的触觉反馈。

"trigger-rumble" 效果是一种针对此类执行器的固定持续时间、恒定强度的振动效果。"trigger-rumble" 效果由 startDelay、duration、strongMagnitude、weakMagnitude、leftTrigger 和 rightTrigger 定义，这些都不是必需的，因为它们默认为 0。

startDelay, duration, strongMagnitude, weakMagnitude 与 "dual-rumble" 具有相同的定义。leftTrigger 和 rightTrigger 分别设置左侧和右侧底部前部按钮振动的强度级别，归一化到 [0 .. 1] 范围，默认值为 0。

给定 GamepadEffectParameters params，一个 有效的触发器震动效果 必须具有 有效的 duration，有效的 startDelay，并且 strongMagnitude, weakMagnitude, leftTrigger, 和 rightTrigger 必须都在 [0 .. 1] 范围内。

GamepadEffectParameters 字典包含触觉效果所使用的参数键。每个键的含义由触觉效果定义，某些键可能未使用。

为了减少不必要的长时间运行效果，用户代理 可以 将 有效效果 的总持续时间限制为某个最大持续时间。用户代理 建议 使用最长 5 秒的时间。

WebIDLdictionary GamepadEffectParameters {
    unsigned long long duration = 0;
    unsigned long long startDelay = 0;
    double strongMagnitude = 0.0;
    double weakMagnitude = 0.0;
    double leftTrigger = 0.0;
    double rightTrigger = 0.0;
};

duration 成员

duration 设置振动效果的持续时间（以毫秒为单位）。

startDelay 成员

startDelay 设置从调用 playEffect() 到振动开始之间的延迟持续时间（以毫秒为单位）。在延迟间隔期间，执行器 不应该 振动。

strongMagnitude 成员

"dual-rumble" 或 "trigger-rumble" 效果中低频震动的振动幅度。

weakMagnitude 成员

"dual-rumble" 或 "trigger-rumble" 效果中高频震动的振动幅度。

leftTrigger 成员

"trigger-rumble" 效果中左下前按钮（规范索引 6）震动的振动幅度。

rightTrigger 成员

"trigger-rumble" 效果中右下前按钮（规范索引 7）震动的振动幅度。

WebIDL[Exposed=Window]
partial interface Navigator {
  sequence<Gamepad?> getGamepads();
};

Navigator 实例创建时带有下表中描述的内部槽位

WebIDL[Exposed=Window]

interface GamepadEvent: Event {
  constructor(DOMString type, GamepadEventInit eventInitDict);
  [SameObject] readonly attribute Gamepad gamepad;
};

gamepad 属性

gamepad 属性提供对与此事件关联的游戏手柄数据的访问。

WebIDLdictionary GamepadEventInit : EventInit {
  required Gamepad gamepad;
};

每个设备制造商都创造了许多不同的产品，每种产品都有独特的按钮和轴样式及布局。预期 用户代理 将尽可能多地支持这些产品。

此外，还有游戏机普及的事实标准布局。当 用户代理 识别出连接的设备时，建议 在可能的情况下将其重新映射为规范顺序。未识别的设备仍应以其原始形式暴露。

目前有一个规范布局，即 标准游戏手柄。重新映射时，axes 和 buttons 中的索引应尽可能紧密地对应于下图中的物理位置。此外，mapping 应该 设置为 "standard"。

标准游戏手柄 按钮布局包括左侧四个按钮的簇、右侧四个按钮的簇、中心三个按钮的簇，以及游戏手柄左右两侧的一对前置按钮。"标准游戏手柄"的四个轴与一对模拟摇杆相关联，一个在左，一个在右。下表描述了按钮/轴及其物理位置。

如果轴输入报告了拇指摇杆轴的输入值，该拇指摇杆位于与对应 标准游戏手柄 拇指摇杆大致相同的位置，并且轴的方向（上下或左右）与 标准游戏手柄 轴的方向匹配，则该轴输入 代表一个标准游戏手柄轴。如果有多个轴代表同一个 标准游戏手柄 轴，则 用户代理 应该 选择一个作为 标准游戏手柄 轴，并为另一个轴分配不同的索引。

如果按钮输入报告了按钮或触发器的输入值，且该按钮或触发器位于与对应 标准游戏手柄 按钮大致相同的位置，则该按钮输入 代表一个标准游戏手柄按钮。

如果轴或按钮输入代表 标准游戏手柄 轴或按钮，则其 规范索引 是对应 标准游戏手柄 轴或按钮的索引。

当系统中有手柄可用时，执行以下步骤：

1. 设 document 为 当前全局对象 的 关联 Document；否则为 null。
2. 如果 document 不为 null 且 不允许使用 "gamepad" 权限，则中止这些步骤。
3. 在 手柄任务源 上对 当前全局对象 排入一个全局任务，以执行以下步骤：
   1. 设 gamepad 为表示该手柄的 新的 Gamepad。
   2. 令 navigator 为 gamepad 的 相关全局对象 的 Navigator 对象。
   3. 将 navigator.[[gamepads]][gamepad.index] 设置为 gamepad。
   4. 如果 navigator.[[hasGamepadGesture]] 为 true
      1. 将 gamepad.[[exposed]] 设置为 true。
      2. 如果 document 不为 null 且 完全活跃，则在 gamepad 的 相关全局对象 上，使用其 gamepad 属性初始化为 gamepad 的 GamepadEvent，触发一个名为 gamepadconnected 的事件。

实现本规范的 用户代理 必须提供一个名为 gamepadconnected 的新 DOM 事件。相应的事件 必须 为 GamepadEvent 类型，并 必须 在 Window 对象上触发。

当用户连接手柄时，用户代理 必须 分发此事件类型以作指示。如果页面加载时手柄已连接，则 应该 在用户按下按钮或移动轴时分发 gamepadconnected 事件。

当系统中有手柄变为不可用时，执行以下步骤：

1. 设 gamepad 为代表不可用设备的 Gamepad。
2. 在 手柄任务源 上对 gamepad 的 相关全局对象 排入一个全局任务，以执行以下步骤：
   1. 将 gamepad.[[connected]] 设置为 false。
   2. 令 document 为 gamepad 的 相关全局对象 的 关联 Document；否则为 null。
   3. 如果 gamepad.[[exposed]] 为 true，且 document 不为 null 且 完全活跃，则在 gamepad 的 相关全局对象 上，使用其 gamepad 属性初始化为 gamepad 的 GamepadEvent，触发一个名为 gamepaddisconnected 的事件。
   4. 令 navigator 为 gamepad 的 相关全局对象 的 Navigator 对象。
   5. 将 navigator.[[gamepads]][gamepad.index] 设置为 null。
   6. 当 navigator.[[gamepads]] 不为空 且 navigator.[[gamepads]] 的最后一个 项 为 null 时，移除 navigator.[[gamepads]] 的最后一个 项。

实现本规范的 用户代理 必须提供一个名为 gamepaddisconnected 的新 DOM 事件。相应的事件 必须 为 GamepadEvent 类型，并 必须 在 Window 对象上触发。

当手柄与 用户代理 断开连接时，如果 用户代理 此前已向某个 Window 分发过该手柄的 gamepadconnected 事件，则 必须 向同一个 Window 分发一个 gamepaddisconnected 事件。

仍需讨论是否包含或排除轴和按钮变更事件，以及是否将它们合并（"gamepadchanged"？）、稍微分离（"gamepadaxischanged"？）或者按单个轴和按钮进行分离。

本规范扩展了来自 HTML 的 WindowEventHandlers 接口混合，以添加 事件处理程序 IDL 属性，从而促进事件处理程序的注册。

WebIDLpartial interface mixin WindowEventHandlers {
  attribute EventHandler ongamepadconnected;
  attribute EventHandler ongamepaddisconnected;
};

本规范定义了一个由策略控制的功能，标识为字符串 "gamepad"。其 默认允许列表 为 *。

除了标记为非规范性的章节外，本规范中的所有创作指南、图表、示例和注释均为非规范性内容。本规范中的其他所有内容均为规范性内容。

本文档中的关键词 MAY（可以）、MUST（必须）、MUST NOT（不得）、RECOMMENDED（推荐）、SHOULD（应该）和 SHOULD NOT（不应该）仅在它们以全大写形式出现时，按 BCP 14 [RFC2119] [RFC8174] 中的描述进行解释，如此处所示。