该技能说明如何用 @pmndrs/viverse 的动作与动作绑定系统,把玩家输入(键盘、鼠标、触摸、手柄)映射到游戏逻辑。其核心思路是用“输入 → 绑定 → 动作 → 游戏逻辑”的链路将输入与逻辑解耦:系统消费的是动作,而不是原始输入事件。
一、用途。动作负责抽象“前进”“跳跃”“旋转”等语义,绑定负责把硬件事件转换成动作,游戏系统每帧读取或订阅动作值,从而在不改动逻辑的情况下更换或叠加多种输入源。
二、动作类型。StateAction 表示持续状态(如移动、奔跑),多个写入者的值通过 .get() 合并为单一值,适合每帧轮询。EventAction 表示一次性事件(如跳跃、开火),通过 .emit() 发出、.subscribe() 消费,订阅应在初始化时完成一次,不能在更新循环中重复订阅。
三、内置动作。移动类(MoveForwardAction、MoveBackwardAction、MoveLeftAction、MoveRightAction)为状态动作,取值 0–1,每帧用 .get() 读取;RunAction 为状态动作,控制冲刺开关;JumpAction 为事件动作;RotateYawAction、RotatePitchAction 为事件动作,提供可直接使用的弧度旋转增量,需订阅后累加;ZoomAction 为事件动作,提供相机缩放增量。
四、使用方式示例。系统在 init() 中订阅一次事件并配合 abortController.signal,在 update() 中轮询状态;不要在 update() 里订阅事件,否则会每帧累积重复监听器。
五、内置绑定。所有内置绑定都接收 (domElement, abortSignal),中止时自动清理。KeyboardLocomotionActionBindings 支持可选指针锁定(moveForwardBinding.requiresPointerLock)、自定义按键(默认 WASD、Shift、Space),可用 keys 改写。PointerLockRotateZoomActionBindings 处理鼠标指针锁定,支持 lockOnClick。PointerCaptureRotateZoomActionBindings 处理触摸。ScreenJoystickLocomotionActionBindings 与 ScreenButtonJumpActionBindings 提供移动端 UI,桌面端通过 .mobile-only CSS 类自动隐藏。
六、旋转增量消费。订阅 RotateYawAction 与 RotatePitchAction,将增量累加到 pitch/yaw,并按 Math.PI/2 限制 pitch;约定正 pitch 向上看、正 yaw 向左转,应用时使用 Euler(pitch, yaw, 0, 'YXZ')。
七、自定义映射与动作。可用 mapFrom 把键盘事件转换为动作值,再交给 KeyboardActionBinding 并设置 keys;也可用 new StateAction(mergeFn, neutralValue) 或 new EventAction() 创建自定义动作,通过 createWriter(abortSignal).write() 写入状态,通过 .emit() 发出事件。对持续轮询场景(如手柄),需记录上一次按压状态,仅在按下瞬间发出事件。
八、生命周期。用 AbortController 统一管理绑定与订阅,调用 abortController.abort() 即可一并清理。
限制与依赖:资料仅覆盖上述 API 与示例,其他功能、版本要求、收费与支持平台暂未提供。