build-game-map-editor

构建游戏地图编辑器

围绕真实游戏世界构建一个暂停状态下的导演工具。让设计师能够快速检查并草拟摆放，同时明确区分生产数据、游戏存档和发布集成。

明确权威边界

在设计编辑器之前检查代码仓库：

• 定位权威的世界、区域、遭遇、刷出点、拾取物、闸门、可交互对象和敌人 AI 定义。
• 定位生产环境的世界构建器和可复用的运行时资源。
• 定位碰撞、导航、平面、持久化和部署约定。
• 确认仓库批准使用的浏览器、测试、发布流程和访问控制要求。

不要创建独立的地图事实来源。通过适配器从生产定义派生初始编辑器文档。保留稳定的源 ID，让每个草稿值都能追溯到编写它的代码。

在 UI 和实现中说明生命周期：

生产源 -> 编辑器文档 -> 隔离草稿 -> 已验证导出 -> 经审核的源代码集成

将导出视为提案。不要声称草稿会改变游戏玩法，除非另行更新权威源、通过游戏玩法测试、完成提交并发布。

定义带版本的编辑器文档

使用轻量、可序列化的文档，而不是存储 Three.js 对象或 React 状态。

包括：

• 固定的 schema 标识符和文档版本；
• 世界或关卡版本；
• 保存时间戳；
• 带类型设置的稳定实体 id、sourceId、kind、标签、区域、位置和朝向；
• 明确的实体类型，例如敌人、玩家出生点、拾取物、可交互对象和闸门。

将编辑器位置数据保持在游戏平面上。对于平面世界游戏，使用 { x, y: 0, z }，并拒绝非零 Y 值，不要静默地将导入数据压平。

在每个导入和集成边界进行验证：

• 要求 schema 和受支持版本完全匹配；
• 限制文档大小、文件大小、实体数量、坐标和设置范围；
• 拒绝重复 ID、非有限值、未知类型、无效边界和格式错误的嵌套设置；
• 要求导入的实体清单与当前生产清单一致，除非实体创建或删除是明确支持的功能；
• 在编辑过程中保留源 ID 和区域归属。

将详细的游戏专用适配器和限制置于可复用的编辑器组件之外。

渲染暂停状态下的导演场景

以明确的导演或预览模式复用生产环境的世界构建器。不要在编辑器中运行战斗、进度系统、持久化、敌人模拟或实时存档变更。

• 对等距或平面世界的摆放，优先使用正交俯视摄像机。
• 在可用时渲染生产几何体、标准实体视觉效果和标准图标。
• 重型资源加载失败时提供简单的回退方案，并将其标记为回退方案。
• 为每个实体提供一个根组、一个可见标记、一个图标或参考精灵，以及一个独立的不可见选择代理。
• 对选择使用代理进行光线投射，对拖动使用固定地面进行光线投射。
• 将变换编辑应用于 X、Z 和朝向，同时锁定 Y。
• 在拆卸时释放几何体、材质、纹理、渲染器、动画帧、观察器和事件监听器。

让视觉图层与编辑器数据彼此独立。图层可见性可以隐藏根对象和叠加层，但不能删除或重写实体。

让导航和选择行为可预测

提供：

• 点击即可选择，选择后聚焦；
• 按标签、源 ID 和区域搜索大纲；
• 显示对象数量的类型图层；
• 全部适配和区域适配操作；
• 带项目专属限制的滚轮缩放；
• 使用中键、右键或按住 Space 键拖动平移；
• 使用 F 快捷键调整地图视图；
• 适配减少动态效果设置的镜头聚焦。

聚焦所选点并充分放大，以便识别它。聚焦用户已近距离查看的实体时，绝不缩小。用户开始手动操作镜头时，取消聚焦动画。

确保指针手势是原子操作：

• 拖动或平移时捕获指针；
• 保持实体与指针之间的偏移量；
• 按所选增量对 X 和 Z 进行吸附；
• 拖动期间更新草稿；
• 在拖动结束时创建一条撤销记录，而不是每次指针移动都创建一条；
• 将未发生移动的点击视为选择并聚焦。

在检查器中展现游戏含义

显示每个实体的标识、规范资源路径、源 ID、区域、位置、朝向和源设置。

对于敌人，仅公开具有明确游戏契约的设置：

• 仇恨半径和目标获取时间；
• 目标丢失和边界停留时间；
• 定点、区域或路径巡逻模式；
• 巡逻半径或明确的路径路点；
• 脱离范围边界和返回容差。

在世界空间中绘制朝向、仇恨、脱离范围、巡逻区域和路点覆盖层。确保覆盖层颜色和图例标签保持一致。

除非编辑器具有经过验证的回写路径，否则将源拥有的设置设为只读。不要把任意运行时状态转换为可编辑 JSON。

保持草稿可撤销且相互隔离

使用不可变的文档快照和有界历史记录。

• 在启用自动持久化之前恢复有效的本地草稿。
• 忽略无效的本地草稿，并报告已加载生产源数据。
• 新编辑后清除重做历史。
• 为已提交的编辑和导出文件添加时间戳。
• 导出和导入前进行验证。
• 拒绝过大、不可读、架构无效或清单不匹配的导入文件。
• 重置所有草稿更改前要求确认。
• 将游戏存档、账户状态和服务器状态排除在草稿存储之外。
• 持续显示 Draft only 或同等状态。

如果之后需要协同编辑、服务器持久化或源数据回写，应将其设计为独立的身份验证工作流，并支持冲突处理、审计历史和明确的发布审批。

保护私有生产工具

不要将私有 URL 视为充分的保护措施。

• 动态渲染路由，并设置 noindex, nofollow。
• 缺少访问配置时默认拒绝访问。
• 根据该部署所使用的可信边缘 IP 请求头，执行精确的 IP 允许列表检查。
• 比较密码时，不要使用会提前退出的明文比较。
• 使用 HMAC 或等效的服务端机制对短期会话声明签名。
• 将会话绑定到允许的客户端 IP 和过期时间。
• 将令牌存储在安全、仅限 HTTP 的严格同站 Cookie 中。
• 拒绝过大的凭据和格式错误的令牌。
• 将密码、允许列表和签名材料存储在部署机密中；绝不将其打包、记录日志、导出或纳入测试快照。
• 未授权请求不得渲染编辑器客户端或画布。
• 提供 POST 登出操作，使 Cookie 失效。

测试缺失配置、IP 被拒绝、密码错误、令牌有效、IP 错误、密钥错误、过期和登出。

集成经过审核的草稿

将导出的文档视为按稳定源 ID 标记差异的内容来读取。

1. 验证架构、版本、清单、边界、平面规则和各类型设置。
2. 将每个已更改字段与生产环境定义进行比较。
3. 将获批更改映射回最小范围的权威源模块。
4. 运行关卡、导航、碰撞、敌人、持久化和编辑器覆盖测试。
5. 在仓库批准的浏览器中游玩受影响的路线和遭遇战。
6. 按照仓库的常规流程提交并发布。

在弄清楚每个字段由哪个系统负责之前，切勿将草稿整体复制到生产环境中。

验证编辑器

为以下项目添加确定性测试：

• 按实体类型验证生产环境到文档的覆盖情况；
• 稳定 ID、架构验证、平面限制、边界和设置范围；
• 规范图标或模型解析，以及已发布文件的存在性；
• 摄像机聚焦、缩放限制和减少动态效果；
• 撤销、重做、拖动原子性、吸附、本地恢复、导入、导出、重置和清单检查；
• 访问配置、精确允许列表、密码比较、令牌绑定、过期时间、Cookie 标志，以及失败时关闭的服务器端渲染。

然后运行定向测试、完整测试、构建、lint 和差异检查。在获批的浏览器中，验证未授权和已授权状态、大纲和图层行为、选择和聚焦、拖动和吸附、检查器编辑、叠加层、撤销和重做、本地恢复、导入和导出的拒绝路径、重置确认、注销、桌面布局、支持时的移动端或窄屏布局、控制台状态，以及渲染器清理。

在 Vesperfall 中工作或需要具体的生产实现映射时，请阅读 references/vesperfall-implementation.md。