# Gameplay Room Map Navigation

> 为多层 3D 地图实现以选中房间为中心的导航：房间选择、受限环绕与缩放、房间间平滑聚焦、选中房间隔离显示及退出交接；隔离只过滤地图呈现，不改变世界房间、探索资格或秘密状态。

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

---


# 房间焦点式 3D 地图导航与隔离查看

## 效果预览

相同A/B/C房间及选择顺序；右焦点移到B再C，最后隔离C；原鸟位置始终属于A，不传送角色。

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

![先选房间，再围绕它看：使用前后对比](assets/before-after.webp)

## 触发与边界

自由飞行地图难以用手柄定位房间或跨高度层查阅时，改为先选房间，再绕该房间查看。需要近看单房间线索时，可在同一选中状态上增加“只看此房间”过滤。此入口管理持续的地图浏览状态，不创建世界拓扑，也不改变角色所在房间或执行传送。聚焦改变观察中心，隔离改变可见集合，两项控制独立。

## 输入与前置条件

- 项目房间注册表：稳定 roomId、当前可浏览性、地图坐标中的焦点及有效取景范围。明确世界到地图坐标变换、地图上方向和投影方式；焦点可由项目提供标记或计算器，但必须得到可验证的结果。
- 项目选择解析器：接收当前房间 ID 与导航意图，返回一个有效目标 ID 或无目标；点击/列表选择也必须经过相同有效性校验。沿用项目的楼层、已探索状态与邻接规则，不从画面猜连接关系。尚无解析器时，只接已知 ID 的直接选择接口，明确方向导航仍待实现。
- 初始房间/无有效房间时的处理、地图相机和输入归属接口、退出后接管者，以及暂停期间仍可更新的地图时钟。
- 各房间的缩放范围、环绕俯仰限制与默认取景；选择跨房间时保留朝向还是恢复房间预设。具体距离、角度和过渡参数按项目尺度配置，不硬编码通用值。
- 使用隔离时，还需地图专属呈现代理/过滤接口及其生命周期、roomId 到地图几何/注释的归属、当前基础可见性与变化通知。基础资格来自探索/楼层/项目既有筛选，不等同注册表全集；过滤必须可单独撤销且不能触及真实世界对象、碰撞、流送或共享资源的全局可见性。没有地图专属控制点时，先补适配器，不直接停用世界房间来凑效果。

## 实施步骤

1. 建立 Closed、Focused、Transitioning 三种状态，保存 selectedRoomId、当前显示焦点、目标焦点、环绕角、缩放量和本次会话/过渡标识。打开时先解析有效初始房间，再独占地图相机和地图输入；不能取得控制权就不部分开启。没有有效房间时显示不可浏览状态或返回原界面，不能把空值当坐标原点。
2. 将选择与查看输入分开：导航意图仅送选择解析器；环绕只改角度；缩放只改距离或正交尺寸。按项目输入系统设置摇杆死区、选择重复节奏和取消键，禁止同一次输入同时驱动角色、菜单焦点及地图相机。按键提示使用实际映射，不假定某个手柄键位。
3. Focused 每帧从选中房间焦点和当前环绕/缩放值重建视图，不累计自由平移。透视相机可由焦点加旋转后的距离向量得到位置，再朝向焦点；正交相机保持投影约定并调尺寸。限制俯仰以避免翻转或退化朝向，归一化偏航，并夹紧缩放。这里限制的是相对焦点的观察行为，不要求相机位置位于房间几何内部。
4. 收到不同且有效的目标 ID 后，立即更新逻辑选择及其标记，进入 Transitioning；从当前显示焦点开始过渡到目标焦点，按已选朝向策略同步过渡取景参数。使用地图可运行的时钟与有明确终点的曲线；结束时将数值收敛至目标并进入 Focused，不能永远渐近而无法完成。同一房间重复选择保持幂等；重置视角必须是独立命令。
5. 明确过渡中输入策略。可先采用“允许重新选房，暂缓环绕/缩放”：新目标从当前显示值接续，旧过渡标识及回调失效，不回跳到旧房间，也不无限排队；暂缓的模拟输入不积攒后补。若项目要求过渡中继续环绕/缩放，必须由同一状态更新器合成，不能让插值器和输入同时写相机。跨房间时根据目标房间范围重算并夹紧目标缩放，避免沿用小房间近景裁掉大房间。
6. 在切换前和每次更新时验证目标仍可浏览。目标失效时取消旧过渡，向项目请求有效回退房间；无回退则退出地图。对焦点非有限值、错误坐标系或非法缩放范围，保留上一有效视图并禁用该目标，报告数据错误，不放宽边界掩盖问题。
7. 关闭、切场或相机归属丢失共用幂等出口：作废会话与过渡回调，清除地图输入状态并注销监听，停止写相机，通过归属接口交还控制。只有自己仍持有控制权时才恢复允许恢复的状态；不得覆盖已经接管的过场或新场景相机。

## 选中房间隔离显示分支

1. 将可见模式 Normal/Isolated 与 Focused/Transitioning 相机状态正交保存，共用唯一 selectedRoomId 和地图会话。打开先采用 Normal，除非项目另有明确的偏好恢复规则。提供幂等 SetIsolation(bool)；Toggle 只接一次有效按下事件，不随按住每帧翻转。实际按键、提示和按钮选中态由当前输入映射与已接受模式驱动。
2. 通过地图呈现接口注册本会话独有的过滤贡献。每次从最新基础可见房间集合 B 求最终集合：Normal 不限制 B；Isolated 只保留 B 中等于 selectedRoomId 的房间。没有有效可浏览选择时拒绝开启；选中房间不满足某个基础显示筛选时，先按项目规则解决选择与筛选的冲突，不用隔离提升资格或强制显示。不要保存整张可见性数组再覆盖恢复，其他系统可能已改变探索、楼层或显示状态。
3. 过滤作用于地图房间代理、附属几何和明确归属该房间的注释。与显示一起更新地图拾取、悬停、工具提示、焦点和无障碍节点，防止透明/隐藏对象仍泄露信息或挡住操作；允许的全局玩家标记或总览 UI 需有单列规则，不随意猜所属房间。共享网格/材质不能通过全局开关影响真实世界。隐藏秘密图标只影响呈现，不修改另一模块的剩余秘密聚合、解锁或发现记录。
4. 保留基础可浏览房间作为选择解析器的候选，不能把隔离后的单元素集合喂回导航而永远无法离开。三维点击拾取只命中当前可见房间；控制器方向导航或已声明的房间列表仍可选择其它有资格的房间，之后隔离集合跟随新选择。列表可用信息仍受探索规则约束，不能借隔离列出未知房间。
5. 房间选择变更与该选择对应的过滤更新在同一次状态提交中生效。采用简单策略：逻辑选择 A→B 时立即只显示 B，相机从当前显示焦点继续向 B 过渡；不要等旧相机回调才切过滤。切换隔离本身不重置房间、相机角度或缩放。若新代理尚未就绪，保留过滤并显示加载/不可用状态，不偷偷显示 A 或全部房间；后到结果必须匹配当前会话与选择/呈现代次。
6. 地图几何新建、房间资格/探索或其它筛选变化时重算交集。新来的非选中代理在首次可见帧前就受当前过滤约束；若选中房间仍可浏览、却被最新基础显示筛选排除，重新执行项目已声明的冲突政策：显示不可用、改选合法目标，或经正常命令关闭隔离；不得扩大基础资格或偷偷强显该房间。选中房间失效时沿主流程解析合法回退并同步更新过滤，无回退则退出。异步刷新提交前重验选择及基础集合版本，旧结果不能让房间重新出现。
7. 关闭隔离仅移除本会话的过滤贡献，使当前其它过滤继续生效；不强行把所有房间设为可见，不改相机取景。关闭地图、切场或呈现归属丢失时，幂等释放自己拥有的过滤句柄及监听；旧会话清理不能移除新会话的贡献。重开从当前基础资格重建，不能恢复过期的可见快照。退出后实际世界房间、流送、碰撞和收集状态须完全不受影响。

## 调参与失败定位

先确认房间 ID、焦点坐标和上下层选择正确，再调房间取景范围与环绕限制，最后调过渡时间、曲线及输入灵敏度。减少运动模式可缩短或直接完成房间切换，但仍执行同一选择与交接流程。

- 选错上下层：检查选择解析器及导航意图，不用相机自由升降补救。
- 环绕后焦点漂走：检查相机是否累计世界位移、焦点是否混用世界/地图坐标；恢复基于焦点重建视图。
- 大小房间切换后截断或过远：检查各房间取景范围与屏幕比例，再调缩放边界。
- 过渡跳变或回到旧房间：记录会话/过渡标识及每个相机写入者，取消陈旧回调并从当前显示值重定向。
- 其它房间遮住目标：检查隔离模式、代理归属与最终过滤集合；若是目标房间自己的墙体，隔离不能解决，墙面剖切仍是独立渲染需求，不扩大自由飞行或误删世界墙体。
- 隔离后不能换房：检查选择解析器是否误用了渲染过滤集合。关闭后未探索房间突然出现：移除整表快照恢复，检查本会话贡献是否独立撤销、基础资格是否重新求值。

## 验收

- [ ] 在上下堆叠、大小悬殊的房间之间，用项目实际手柄映射可选择并稳定聚焦；无目标时保留当前选择，不跳原点。
- [ ] 持续环绕/缩放不会脱离选中焦点的观察模型、穿越配置边界或翻转；相机位于房间外不单独视为失败。
- [ ] 连续快速 A→B→C、同房间重复选择和过渡中退出，最终只保留最新有效状态，没有旧回调拉回视图或残留输入。
- [ ] 目标卸载/不可浏览、暂停游戏、关闭重开与其他镜头接管均无输入锁或双写；退出不会传送角色或修改探索状态。
- [ ] 不同屏幕比例及减少运动模式下仍能识别所选房间；测试结果记录为项目验证，不由观感推断手柄效率或优越性。

- [ ] 切换隔离只改变地图可见集合，保持当前选择、环绕/缩放和真实世界状态；反复提交同一模式不振荡，按住切换键不连跳模式。
- [ ] 隔离 A 时用控制器选 B，再快速选 C，过滤与逻辑选中始终一致，旧过渡/加载回调不显示 A/B；即使只有一个房间可见，导航仍可到其它基础允许房间。
- [ ] 隔离期间探索、楼层或其它筛选改变，再关闭隔离，只恢复当前仍有资格的集合；新代理首次显示就遵守过滤，无快照覆盖、泄露未知房间或一帧闪现。
- [ ] 隐藏房间的三维拾取、标签、提示和读屏节点按规则隐藏，房间列表/导航的资格另行保持；秘密记录不变，真实世界对象和共享材质未被停用。
- [ ] 目标失效、地图关闭重开、切场及旧会话延迟清理只处理各自过滤贡献；目标自有墙面仍遮挡时不得报告隔离已解决全部室内观察问题。

## 相邻工作流

后期解锁后只显示房间是否仍有秘密，使用[房间剩余秘密标记](../gameplay-room-secret-markers/SKILL.md)；它按发现记录聚合，不由当前地图焦点或相机状态判断。

选中/不可用样式复用[交互状态反馈](../gameplay-contextual-ui/SKILL.md)；它不拥有地图焦点或环绕状态。单次事件的短促镜头效果见[镜头冲击](../gameplay-camera-feedback/SKILL.md)，结算到下一状态的交接见[完成事件组合](../gameplay-completion-sequences/SKILL.md)，不要将持续地图浏览并入这两类流程。

需要核查出处和实现选择边界时，读取[来源参考](references/sources.md)。

