# Gameplay Contextual UI

> 为游戏内按钮、按住操作、拾取/近物扫描提示、指令选择及紧凑设置面板区分可用、焦点、执行中、成功/失败，并组织菜单非物理退出；卡牌布局、对话、机关、连接和切场使用独立入口。

- Skill: `ziyou-lu/gameplay-contextual-ui` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add ziyou-lu/gameplay-contextual-ui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ziyou-lu/gameplay-contextual-ui/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-contextual-ui

---


# 游戏内交互状态与提交反馈

## 效果预览

保留原有扫描内容与操作：左侧先切扫描视图，右侧在普通探索画面中靠近目标后直接扫描。

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

![不用切换视图，也能扫描：使用前后对比](assets/before-after.webp)

## 触发条件

按钮、按住操作或指令焦点看似成功，却不符合真实交互结果；或菜单入场热闹但当前选择与其他选项难以区分，以及希望点击后按钮向外散开淡出但不引入刚体模拟。也用于持续扫描界面遮住探索画面，需要只在靠近可扫描物时提供操作提示；或图形设置菜单遮住结果，需要侧边调节并看到真实变化。

按住动作要新增多次轻点输入方式，使用[可选轻点入口](../gameplay-hold-to-multitap/SKILL.md)；本入口只呈现已确定的策略与真实结果。房间的剩余秘密提示使用[房间级标记](../gameplay-room-secret-markers/SKILL.md)，不把发现记录聚合塞进按钮状态。

多格物品放置使用[网格背包](../gameplay-grid-inventory-placement/SKILL.md)处理足迹、占用和原子落位；本入口只呈现资格、请求与真实结果。

## 输入与前置条件

可用、聚焦、按下、执行中、成功/失败事件；输入映射；目标/焦点归属；保持、释放及取消条件。

## 实施步骤

1. 建立状态到显示的映射，聚焦、按下和提交成功分别表示；显示订阅业务状态，不让动画结束调用一次额外提交。
2. 按钮按下可压缩、回弹和扩散波纹；成功提示仅由确认结果触发，失败/不可用采用可辨认的不同显示。
3. 按住操作绑定真实保持进度，松开或取消按规则清空/保留；满进度仍需确认结果，切换焦点不得把旧进度提交给新对象。
4. 拾取提示沿项目距离/朝向和输入映射显示；成功后同步持有状态及世界对象，等待确认时避免重复请求。
5. 战斗指令用焦点滑动、放大与说明框表达唯一选择和可执行性；卡牌布局、对话与机关执行交给独立入口。

## 菜单焦点对比与错峰入场

1. 先保留稳定的逻辑选项顺序、唯一焦点、可用状态和提交接口。将视觉变换放到独立容器上，不让缩放/倾斜反过来修改选中项或触发选择；焦点移动和真正执行是两个事件。
2. 同时定义选中与未选中样式：选中项相对基准放大，并反转底板/文字的明暗关系；其他项适度缩小或变暗，仍保留标签可读性。不可用项另有标记，不能只靠同一种变暗把“未选中”误作“不可执行”。焦点指示箭头可提供额外形状线索，不只用颜色。
3. 若采用斜切底板和级联排列，按选项索引计算布局锚点，再让各项动效绕自身锚点播放。布局位移与动画位移分开；不同分辨率、长文本和本地化下重新检查裁剪、间距与文字阅读，不盲抄固定坐标。倾斜装饰不要求文字也倾斜。
4. 开菜单时按稳定顺序错峰播放各项进入，可用有轻微过冲的回弹缓动。错峰只控制显示时间；若未出现的项不可交互，就同步门控输入，或采用立即完整可交互的低运动方案，避免玩家选到看不见的目标。关闭/重开取消旧序列，不累计重复弹入。
5. 快速导航时从当前视觉值过渡到最新焦点目标；撤销旧动画的完成回调，不叠加多次缩放。每次先恢复旧焦点的普通样式，再更新新焦点，使所有项最终收敛到一组状态。鼠标命中区域要与实际呈现策略一致：若用固定逻辑热区，避免明显偏离可见选项；若变换热区，保持导航顺序和最小可用面积。
6. 确认反馈可加轻小整板缩放脉冲；闪光与大幅移动均应有关闭/减弱路径，不能成为唯一成功信号。对异步操作，点击只表示已请求，成功仍待真实结果。面板遮挡切换复用[切场遮蔽与就绪恢复](../gameplay-scene-transitions/SKILL.md)，不在动画时间点私自重复提交或假设页面已就绪。

调参先比较选中/未选中的相对尺度和明暗，再调过冲与错峰间隔，最后加入整板脉冲。对照静止、慢导航、连续快速导航、关闭重开与减少运动模式：焦点唯一、文字清楚、无旧项残留放大、隐藏项不会误触且业务动作只提交一次。降低动效后也必须能看出当前选项和不可用项。

## 不依赖物理模拟的菜单散开退出

已有稳定菜单、按钮身份和业务提交接口，希望接受选择后各按钮向外移动、转动、改变尺度并淡出时，使用此分支。它只负责 UI 退出表现，不建立碰撞/刚体，不接管真实场景加载；若效果要求按钮碰撞或受外力持续模拟，应另行评估物理需求。

1. 先明确退出适用的动作、业务接受/拒绝信号、何时执行目的操作、取消是否允许，以及失败后显示什么。点击不是成功。第一次有效激活即在跨菜单对象生命周期的既有导航/业务协调器登记一次操作标识并锁存待处理态；资格校验或接受若需等待，等待期间就拒绝重复激活，不等退出动画开始才上锁。该次操作被拒绝时清理待处理态并显示原因，获准退出时才开始本次视觉阶段。实际请求只在约定的一处发出，不同时由点击和每个按钮的完成回调发出；纯视觉完成不能成为业务成功信号。没有可靠提交/恢复接口时先补齐契约，不用销毁菜单代替执行操作。
2. 对此次退出创建唯一的视觉代号并停止旧入场/焦点 tween；从每项当前可见的局部位置、旋转、尺度和透明度快照开始，避免先跳回默认值。布局锚点、按钮逻辑身份与退出动画偏移分开；确定一个共同 UI 坐标空间和散开参考点，不能混用屏幕坐标、父容器局部坐标和缩放后的位移。
3. 按项选择一次有界的向外方向、距离、旋转增量和正值尺度目标。可以在从参考点到按钮的方向附近扰动；重合时使用项目定义的非零备选方向。随机值只在本次退出开始时生成，不逐帧重抽，不把无单位的“冲量”送进不存在的刚体。范围按可见边界和版式限定，避免路径遮住仍需读取的确认/错误信息；需要可复现验收时固定测试种子。
4. 以有限时长的进度控制位置偏移、旋转、尺度及 alpha，分别选择缓动；视觉结束时明确写入终值。若存在错峰，各项开始延迟和结束期限都计入总完成条件。用菜单暂停时仍可推进的既定 UI 时钟，零时长/减少运动直接落到终值或短淡化，不能除零或等待不会再跳动的模拟时钟。平滑跟随不等同于有限退出，不能用每帧插值永远逼近而没有明确完成。
5. 退出期间保留逻辑选择和状态，不让飞出的元素继续命中、抢焦点或执行动作；移除/重建单项也不能使整组永远等它的回调。对本次有效代号汇总完成一次，且正常完成、跳过和销毁均有清理路径。若项目要求先播完再离开，协调器同时检查视觉完成和真实业务/目的地条件；加载失败时走明确的错误/返回界面，不把按钮飞完当场景已就绪。需要遮蔽与就绪恢复时组合[切场入口](../gameplay-scene-transitions/SKILL.md)。
6. 关闭、返回、重新打开或界面销毁时使旧视觉代号失效，取消本组动画与回调；仅释放本组取得的输入/焦点所有权。允许取消的业务动作通过其正式取消接口处理，不能仅停动画就宣称已撤销。已经接受、不能撤销的业务操作继续由协调器负责，重开界面读取其当前状态而不重新发送。恢复菜单时从有效布局和焦点重新构建完整样式，不留下 alpha 为零或半途尺度的按钮。

先验证一次接受只发生一次业务请求，再调有限退出时长与淡化，然后调外移距离、旋转和尺度范围，最后加错峰。焦点放大与其他项变暗复用上节，不为每个风格再建 owner；指针尾迹不是键盘/手柄导航的必需反馈。

- [ ] 入场未结束时激活、快速双击、键鼠同时确认只接受一次操作；散开从当前可见变换连续开始，不额外触发业务。
- [ ] 暂停、低帧率、大帧间隔、零时长、错峰与减少运动下都能到达有限终态；随机范围不出现负尺度、无穷位移或每帧跳变。
- [ ] 激活后返回/关闭/重开、移除按钮与销毁父界面，不让旧完成回调切换新菜单或永久锁住输入；业务已接受但仍待完成时显示真实状态，不自动重试。
- [ ] 目的地失败或请求拒绝有可读、可操作的出口；调整视口/本地化布局时采用已声明的冻结当前布局或重新布局策略，清理后按钮恢复有效锚点与样式。

## 普通视图中的近物扫描提示

已有扫描内容与交互接口，但持续扫描模式遮住场景、迫使玩家每到一处就切换视图时，使用这个分支。它复用可用/焦点/执行/结果状态，不新建扫描能力或自动探测整个关卡。

1. 取得项目可扫描对象 ID、内容记录、接近资格与输入接口。检查权威扫描动作是否被旧扫描模式门控；若是，只解耦已批准移除的面罩/显示前置，保留距离、解锁、目标有效性和成本等玩法资格。不能仅隐藏面罩却在后台强制启用一个仍会改变玩法的模式，也不能把所有模式资格一起删除。列出每项提供的局部叙事、背景细节或邻近谜题线索；优先保留有具体用途的内容，不以扫描数量为目标。标出重复或空泛项供内容取舍，处理依赖任务/教程的记录后再改数量，不凭展示层删掉权威任务对象。
2. 在正常环境渲染中按已有距离、遮挡和可用规则产生附近候选；没有规则时先让项目定义范围与资格，不从外观推测。扫描提示由接近资格门控，不要求先进入永久滤镜/面罩视图。局部轮廓或图标不能让本来不可发现的目标穿墙显露；更强发现性效果按[世界目标提示](../gameplay-world-readability/SKILL.md)的允许信息范围处理。
3. 复用现有焦点解析，只对当前有效对象显示其可操作提示和真实键位。多个候选重叠时沿用已声明优先级；若需要新的区域选择算法，另用[多射线物件选择](../gameplay-multiray-object-selection/SKILL.md)，不是本分支自动加上的能力。进入范围只出现提示，不自动开始、读完或登记扫描。
4. 玩家明确激活后向扫描接口提交对象 ID。若操作有过程，UI 读取其权威进度与结果；没有时长规则就不添加装饰计时器冒充完成。扫描中目标失效、离开范围或切换焦点时，按项目确定的继续/取消规则处理；显示不能擅自迁移旧对象的进度到新对象。读取内容、已读标记和再次扫描规则来自已有内容系统，不由圆环填满决定。
5. 接近/离开、关闭内容、目标消失和控制模式切换时重新核验资格并清理旧提示与回调。需要抑制距离边界闪烁时选择项目的滞回/稳定规则，但显示宽容不自动扩大真正操作距离；提交前仍检查当前对象资格。正常场景渲染持续保留，内容结果面板可以按项目需要短暂出现，不能把它误作必须常驻的扫描视图。
6. 比较原常驻界面与近物提示：同场景中环境仍可见，提示有足够对比而不覆盖关键线索，已读与未读状态可辨。覆盖接近/后退、边界移动、多对象、失效对象、反复激活和已有输入重映射；确认提示出现不发扫描请求、失败不记已读、一次成功只登记一次。减少项目数量的取舍用实际内容覆盖核对，不能凭更少图标宣称更好体验。

## 紧凑设置面板的实时结果反馈

用于图形菜单遮住场景、调一次就得关闭菜单才能比较结果的情况。只负责已具备设置接口的展示与应用反馈；渲染器初始化、配置存储和高风险显示模式的恢复流程不是本节的实现范围。

先取得每项设置的稳定 ID、合法值/可用条件、读取当前生效值的接口、应用接口、当前待处理状态和带版本的完成/失败通知；区分可即时应用、需明确提交和需重启的项。另确认菜单输入与暂停归属、渲染刷新是否独立于世界模拟，以及项目现有的关闭、取消和保存约定。没有可靠应用/回读接口时先明确设置服务契约，接口实现尚缺就停在该依赖，不扩写渲染后端或只改控件数值宣布生效。

1. 在安全区域内将面板靠屏幕一侧，保留能判断变化的场景区域；文字、当前值、焦点和不可用状态仍需清楚。避免整屏不透明遮罩或强模糊盖住比较目标；窄屏、长文本和大字号下优先使用局部滚动/分页，不为紧凑而压小操作目标。背景必须来自当前游戏渲染，不能复用[暂停地图截图背景](../gameplay-paused-map-backdrop/SKILL.md)的冻结图来声称实时预览。
2. 用项目输入映射提供直接打开/关闭动作，按一次输入边沿只切换一次；菜单入口和快捷入口调用同一开关接口。打开时取得唯一 UI 焦点并阻止同次输入穿透触发角色动作；暂停策略沿用项目约定，不因“实时预览”自行恢复世界模拟。
3. 打开面板时从设置服务读取实际生效值，以不触发 change 事件的方式初始化控件。分开保存用户目标值、正在应用的值与已确认生效值；控件拖动/聚焦只表示意图。不支持或条件不足的项禁用并说明原因；需提交或重启的项明确标记，不混入即时生效的成功提示。
4. 对可即时应用项，先按合法范围/枚举校验，再调用设置接口。连续拖动时按实际成本选择直接应用或合并中间请求；异步接口的排队、待处理值和请求版本由跨面板会话的设置服务/既有协调器持有，按项串行并保留最新待应用值；互相依赖的项沿用服务定义的事务组。关闭重开不得另建能与旧请求并行写入的新队列，避免仅丢弃旧回调却让旧写入在渲染器中最后落地。完成后回读实际值并更新显示；失败则显示可理解的原因并回到服务确认的有效值，不把滑块位置或动画结束当成功。
5. 设置应用后允许场景继续提交新渲染帧，即使世界模拟已暂停，也要能看到静态画面的变化。需要时间推进才能观察的效果，按项目约定使用允许的预览更新路径，或说明当前暂停状态下不能完整预览，不偷偷解除暂停。若某项需要资源重建或重启，转交既有提交/恢复流程并保留明确状态，不强行伪装成即时更新。
6. 关闭、切场和重开时取消本面板的输入/显示订阅并使会话回调失效，只释放自己取得的焦点和暂停所有权。已发出的应用由跨会话设置服务按项目契约完成或取消，旧面板回调不得重新显示面板。重开时订阅当前服务状态并读取有效值、待处理值及版本，处理读取与订阅之间的版本变化；旧请求若随后完成，新面板通过自己的有效订阅再次回读并显示当前结果，新输入也进入同一服务队列，不能只在打开时读取一次。服务若不能提供一致的进行中状态与完成通知，先补齐该依赖契约，不让面板本地缓存冒充权威。实时生效不等于已保存，也不意味着关闭会撤销，保存/取消严格沿用已确认的项目规则。缺少这些规则时先确定契约，不自行补造持久化行为。

调参顺序：先验证控件值与真实渲染状态一致，再调面板占屏、背景可见范围和文字对比，最后测连续拖动的应用频率与帧耗时。合并更新的节奏按目标设备实测选择；不能用固定等待时间替代应用完成信号。

- [ ] 不关闭面板即可在同一场景/视角观察可即时应用项的实际结果；面板没有遮住关键比较区域，也没有用冻结图冒充新画面。
- [ ] 快速连续调节，以及 A 未完成就关闭重开再改 B，最终均收敛到服务确认的最新有效目标；旧 A 完成会同步新面板，不与 B 并行覆盖。失败/不支持/需重启均不显示已生效；初始化和回读同步不产生重复写入。
- [ ] 键鼠及项目支持的手柄可直接进入、导航和退出；快捷键重映射、长按、关闭重开及切场不会双切换、穿透操作或遗留焦点/暂停锁。
- [ ] 世界暂停时渲染可刷新；动画效果无法完整预览时提示符合实际。关闭、取消、保存和再次打开均符合既定设置服务契约。

值已变但画面不变时，依次检查实际应用结果、是否取了旧截图、渲染刷新与暂停时钟、该项是否需要重建/重启；不要用更强的确认动画掩盖未生效。拖动卡顿时先测应用成本再合并更新；异常关闭后状态不明时重新回读，不能用面板缓存覆盖设置服务。

## 参数调整

按下位移、回弹幅度与波纹寿命先小后大；保持时长属于输入规则，不能仅为动画好看改变。优先修焦点/状态错误，再调动效。

## 验收与失败处理

- [ ] 鼠标、键盘及适用手柄焦点唯一，按下/松开/取消不误提交。
- [ ] 重复点击、关闭重开与拾取竞态不双发结果；条件不足不播成功。
- [ ] 减少运动后仍读得懂结果，旧目标消失时焦点与待完成显示被撤销。

## 按需组合

- [奖励揭示](../gameplay-reward-reveal/SKILL.md)
- [事件形变](../gameplay-motion-deformation/SKILL.md)
- [卡牌交互](../gameplay-card-interaction/SKILL.md)
- [对话进度](../gameplay-dialogue-presentation/SKILL.md)
- [世界内指示](../gameplay-worldspace-indicators/SKILL.md)
- [目标可见性](../gameplay-world-readability/SKILL.md)
- [机关运动](../gameplay-mechanical-interactions/SKILL.md)
- [挂脱连接](../gameplay-connection-transitions/SKILL.md)
- [切场恢复](../gameplay-scene-transitions/SKILL.md)

需要核查出处、示例参数或证据限制时，读取[来源参考](references/sources.md)。

