外观
工程
技术基础
游戏工程使用 Rust 2024 与 Bevy 0.19.1。空间表现、镜头与交互通过可玩实验验证，以城市生活、探索与潜梦行动的体验为判断依据
工程组织
源码与运行资产位于 game/，可编辑源文件位于 source-assets/
地图运行时位于 game/src/world/，负责地图校验、几何、表现资产与场景生成，正式游戏和独立 map_viewer 入口共同使用。白天照明共用 world::visual，正式入口 app 管理 Bevy 状态与异步场景准备，Viewer 保留独立的自由相机，运行和验证命令见仓库中的 game/README.md
source-assets/district-map/district.json 是空间设计的唯一编辑源，启动时解析为运行数据；材质和模型规则独立保存在 source-assets/district-scene/。坐标统一由地图 [x,y,h] 转换为 Bevy [x,h,-y]，1 unit = 1 m，几何计算使用 f64，生成顶点时转换为 f32
启动完成以资产递归依赖和模型实例化均成功为准。正式入口的地图、几何或必需资产失败显示可恢复的失败页；Viewer 与 capture 的失败返回非零退出码，日志保留文件、字段路径、源对象、材质槽和底层原因；显式可选模型可以带警告省略，启动摘要记录降级数量
实现按输入、玩法状态、数据与表现组织。内容 ID 关联设计、数据和资产；存档记录任务、阶段、物件与一次性事件的稳定标识
家庭 Agent 的云端身份属于角色设定，其游戏表现与行为按制作需求实现
验证
代码变更执行项目的格式、编译与测试命令。图形验证记录场景、设备、分辨率、输入方式、帧时间、内存与加载时间
连续输入、离屏 capture 与状态断言采用运行验证，命令入口为仓库 game/README.md 与 tools/capture.py。开发证据、参考帧和缓存放在忽略的 output/，运行资产保持独立
按项目的平台定位，在 Linux 和 Windows 上验证 Vulkan 渲染与手柄、键鼠输入。性能目标依据原型和完整样板的实际测量制定
已有排错入口
当前 Cargo.lock 锁定 Bevy 0.19.1，jpeg 和 dds 特性已开启，分别服务 glTF 图像与现有环境贴图。新增格式先核对资产实际编码及加载日志，不仅看文件扩展名。新增插件先用 cargo tree --manifest-path game/Cargo.toml -d 核对重复的 Bevy 小版本，再决定兼容方案
模型空白时先看递归依赖加载与材质槽诊断；程序几何不可见时看三角形绕序、法线与背面剔除，层级不可见时看祖先的 Visibility 和变换。相应校验集中在 world::assets、world::geometry 与 world::scene，具体问题通过相关测试复现
场景启动就绪沿用 [world/ready]；WorldScenePlugin 可先于 SceneLoading 安装，插入一次资源启动一轮加载，失败交由宿主处理。clear_scene 清理带 MapSource 的场景根及其后代和加载状态，保留宿主镜头、灯光与 UI；正式入口返回标题还取消未完成的准备任务，避免旧结果在退出后进入场景。现有 dev profile 已对依赖启用优化，capture 的固定步长与逐帧落盘不能当成正常游玩性能成绩
人物尺度实验复用正式入口，通过静态网格查询与胶囊移动验证室外路线、坡阶、墙角和跟随镜头