该技能面向使用 @pmndrs/viverse 构建游戏输入层的场景,核心目标是把硬件输入与游戏逻辑解耦。整体链路为:输入 → Binding → Action → 游戏逻辑。技能明确只覆盖输入层:角色移动意图应先交给 Acta(动画),再由其产生速度交给 BvhCharacterPhysics,不要用原始输入直接驱动物理控制器。
动作类型分为两类。StateAction 表示持久状态(如移动、奔跑),多个写入者的值通过 .get() 合并读取;EventAction 表示一次性事件(如跳跃、开火),通过 .emit() 发出、用 .subscribe() 消费。内置动作包括 MoveForwardAction、MoveBackwardAction、MoveLeftAction、MoveRightAction、RunAction(状态类,每帧用 .get() 读取),以及 JumpAction、RotateYawAction、RotatePitchAction、ZoomAction(事件类,需订阅)。事件类在初始化时订阅一次,绝不能在更新循环中订阅,否则会不断产生重复监听器。
内置绑定都接收 domElement 和 AbortSignal,并在中止时自动清理。键盘绑定支持通过 requiresPointerLock 要求指针锁定,并可用 keys 自定义按键。鼠标绑定基于指针锁定,可开启 lockOnClick。旋转增量通过订阅 RotateYawAction 和 RotatePitchAction 并累加实现,约定正俯仰向上、正偏航向左,使用 Euler(pitch, yaw, 0, 'YXZ') 顺序应用到相机。触摸使用指针捕获绑定;移动端还提供屏幕摇杆与屏幕跳跃按钮绑定,桌面端通过 .mobile-only 类自动隐藏。
自定义方面,可用 mapFrom 把键盘事件转换为动作值,再用 KeyboardActionBinding 绑定;也可创建自定义 StateAction(需提供合并函数和中性值,否则 .get() 会报错)与 EventAction(普通 emit/subscribe 模式可不传参)。写入 StateAction 需先创建 writer,再在状态变化时调用 .write(),多个 writer 自动合并。EventAction 在事件发生时调用 .emit();手柄等连续轮询场景要记录前一帧状态,仅在按下瞬间发出。
生命周期管理统一使用 AbortController:绑定和订阅共享同一 signal,调用 abort() 可一次性清理。技能特别强调按模式隔离控制:菜单、游戏中、暂停、过场、结束界面应各自拥有独立的 AbortController,进入某模式时中止上一模式,从而避免控件误触发。典型错误是启动时创建且从不销毁的 lockOnClick 指针锁定绑定,导致玩家点击菜单按钮时被锁指针、菜单不可用。若某模式同时需要实时控制和可点击 DOM UI,应把 canvas 作为绑定目标而非 document.body,或在 UI 的 pointerdown 中调用 stopPropagation(),避免点击事件冒泡到锁定监听器。模式切换时,控制、模拟系统冻结/恢复和相机归属应一起切换。
限制方面,内置绑定覆盖键盘、鼠标(指针锁定)、触摸和屏幕移动控件;手柄、重映射按键、游戏专属动作(蹲伏、侧身、技能等)需自定义 StateAction/EventAction 并用 mapFrom 或自建 DOM/手柄监听器写入。该输入层本就设计为可扩展,游戏系统中不应直接读取原始输入。