# Gameplay Gamepad Pitch Limits

> 当手柄抬头/低头在视角上、下限突然撞停时，为趋近边界的俯仰输入减速，同时让鼠标绕过此边界缓动；保留硬限位、反向离界响应和设备切换，不替代震动、速度 FOV 或基础 up 选择。

- Skill: `ziyou-lu/gameplay-gamepad-pitch-limits` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add ziyou-lu/gameplay-gamepad-pitch-limits`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ziyou-lu/gameplay-gamepad-pitch-limits/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ziyou-lu (https://skillmd.com/u/ziyou-lu)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/ziyou-lu/gameplay-gamepad-pitch-limits

---


# 手柄俯仰限位缓动与鼠标直通

## 效果预览

同一手柄请求向上、顶住、反向；左硬夹突然停，右只在逼近上界时减速，反向立即普通速率。

左侧为使用前，右侧为使用后；斜视 2.5D 短循环，用途示意（非引擎实测；音频相关预览仅示意触发关系，不含声音）。

![靠近观察边界，再柔和地停下：使用前后对比](assets/before-after.webp)

## 触发与输入

手柄抬头/低头在上下限突然撞停，但鼠标需要保持手部位移对应时使用。

确认基础观察控制器的唯一俯仰状态、角度单位及正负号、合法下限/上限、当前活动设备与输入仲裁、手柄死区后的有符号角速度、鼠标本次采样位移和灵敏度、输入更新时钟。先查项目的反转 Y 设置、瞄准与相机是否共享俯仰、暂停/失焦/控制权交接接口。

将俯仰作为受限的标量管理，不从每帧包装后的 Euler 角反复推回状态。所有角度、带宽和时间步必须有限，lo < hi、带宽为正、时间步非负。范围尚未定义、基础相机无明确写入者或输入单位不清时先补控制契约，不凭画面选角度与速度。

## 实施步骤

1. 记录关闭本机制的基线：固定手柄输入分别靠近上下限，再反向离开；记录鼠标等位移对应的俯仰增量。日志至少包含设备、原始请求、基础俯仰、距离目标边界、缓动增益与最终增量。临时震动不得写回这份基础状态。
2. 将两种输入分路。手柄角速度按观察更新的时间步积分；鼠标位移按现有灵敏度转角，已是位移的输入不再乘时间步。按项目确定的有效输入/优先级仲裁同帧设备输入，不因手柄噪声或仅连接设备就切模式。
3. 在统一为“正值朝上限”的计算坐标中，正请求只查询上限距离，负请求只查询下限距离，零请求输出零。分别配置上下限缓动带宽；带外增益为 1，带内随剩余距离缩小连续降到边界处的 0。只缩减朝目标边界的手柄增量，不使用“离最近边界很近”这种无方向判据。
4. 对反向离开刚接近的边界，当次更新即撤销该边界的减速，恢复既有普通输入响应。不要携带旧方向速度、平滑目标或减速权重。约束两侧缓动带不重叠；若配置范围太窄，先修正带宽，不让离开一侧马上受另一侧的带宽误伤。
5. 从当前合法俯仰推进并在每次写回前硬夹到上下限。防止大时间步在一次更新中跨过整个缓动带：按带入口拆分积分或用有界子步，重新计算距离。丢弃被硬限位裁掉的超额请求，不积累不可见目标角，否则反向会先偿还“欠账”。
6. 鼠标直接提交本次位移对应的俯仰增量，只执行同一合法范围硬夹，不套手柄边界增益或新增全局鼠标平滑。边界外不可达的那部分位移被裁掉是限位行为，不通过改变其余范围的灵敏度来补偿。
7. 切设备时保留当前合法基础俯仰，清除本层旧增益/速度/待积分输入，不把切换前的累计鼠标位移重放，也不丢掉切换后的有效采样。恢复控制权、失焦后回归或切镜头时从新控制器合法状态重建；不要以旧相机目标拉回。若项目另有手柄加速或鼠标处理，保持原契约并单独验证，避免双重平滑。

## 调参与失败恢复

- 先定合法范围，再调每侧带宽，最后调增益形状。带宽越大越早减速；形状决定接近末端的速度变化。各项均配置化，上下限可独立调节，不使用固定角度、速度或时间作为通用默认。
- 增益必须有界、随剩余距离单调不减，带入口与普通响应连续；验证微小反向、满杆及部分杆量。优先采用只依赖本次方向和距离的无历史增益，不增加全局跟随延迟。
- 若渐近方案始终留极小角距，明确项目是否接受；需要到达精确端点时设置可验证的收敛/吸附容差，限制其跳变量，并确保只向边界吸附、不锁住反向输入。
- 边界仍撞停：查看大步跨带、带入口不连续或过窄，再调整积分和带宽；勿用 shake 掩盖。离界发黏：先查方向判据、超额目标积累及旧平滑状态。鼠标边界外也变慢：检查设备分支和单位，恢复原位移映射。
- 配置非法或本层不可用时，退回既有普通观察加硬限位；禁止解除合法范围或静默改变 yaw。

## 验收

- [ ] 上/下限分别以满杆和部分杆量持续接近，带外与基线一致、带内减速、全程不越界；持续顶住后反向当次更新即可离界。
- [ ] 同一侧带内来回反向无额外迟滞、回弹或旧目标追赶；零输入不漂移，另一边界不误触发本侧增益。
- [ ] 鼠标在中段及边界内等位移产生相同未裁剪角度增量，抵达边界仅裁剪越界部分；反向立即离界，无手柄缓动残留。
- [ ] 不同帧率、大时间步、暂停恢复和反转 Y 设置下方向正确、无越界；可接受误差由项目确定并记录。
- [ ] 近限位切换鼠标/手柄、同帧混合事件、手柄漂移噪声、失焦及镜头交接均不跳角、不重放输入，不改变 yaw、FOV、玩法瞄准契约。

## 相邻任务

- [静态摇杆响应](../gameplay-stick-response/SKILL.md)：仅按当前杆量调整基础命令，先完成曲线与角速度换算，再进入本页按角度距离计算的边界减速；两层独立记录，不能用本页替代全杆程微调。

- [镜头冲击](../gameplay-camera-feedback/SKILL.md)：处理事件驱动的临时偏移，不管理基础观察输入。
- [速度镜头](../gameplay-speed-camera/SKILL.md)：处理速度到 FOV/边缘效果，不管理俯仰限位。
- [表面相机上方向](../gameplay-surface-camera-up/SKILL.md)：确定 up 参考；在其确定的局部观察坐标内实施本页，不复制其表面查询。

需要归因、证据边界或候选数学方案时，读取[来源参考](references/sources.md)。

