本文是当前代码库的维护入口。它描述已经存在的目录边界、运行时依赖方向、资源来源和构建产物,帮助后续开发在不破坏现有流程的情况下继续扩展。
游戏-鲸鱼魔盗团/
├─ index.html # 开发入口;只负责挂载画布、UI 容器和 src/main.mjs
├─ 启动游戏.ps1 # Windows 本地启动器
├─ src/ # 可编辑源码(唯一运行时源码来源)
│ ├─ main.mjs # 应用组装层:创建核心、世界、渲染、输入、音频和 UI
│ ├─ core/ # 与画面无关的主线状态和存档
│ ├─ game/ # 玩法运行时:世界、地图、输入、剧情、教程和规则适配
│ ├─ render/ # 资源加载、DPR 分辨率、动作采样和场景绘制
│ │ └─ scene-renderer.mjs # 主绘制器(旧 src/game/renderer.mjs 为兼容门面)
│ └─ ui/ # HTML UI、样式和 SVG 图标表现层
├─ assets/ # 美术和运行时资源
│ ├─ runtime-catalog.json # 运行时图像坐标与采样区的事实来源
│ ├─ asset-manifest.json # 资产制作、来源和验收登记
│ ├─ atlases/ backgrounds/… # 运行时 PNG
│ ├─ prompts/ provenance/ # 生成提示词和来源记录
│ ├─ concepts/ references/ # 方向稿、用户参考和已归档旧稿
│ └─ preview/ # 离线资产预览页
├─ scripts/ # 构建、打包和无浏览器自动校验脚本
├─ docs/ # 设计、实现、验收和资产说明
├─ output/ # 本地验证日志、截图和审阅输出(可覆盖)
├─ dist/ # build-game.mjs 生成的静态部署目录(不要手改)
└─ deliverables/ # finalize-delivery / package 脚本生成的交付压缩包
dist/、output/ 和 deliverables/ 是派生目录。修改功能时只编辑 src/、assets/、index.html 或脚本;构建后再检查派生结果。不要在 dist/src 中修复问题,也不要把截图或压缩包反向提交为运行时依赖。
依赖关系从上到下保持单向,避免模块互相操作 DOM 或互相持有完整游戏对象:
index.html
└─ src/main.mjs # 组合根(composition root)
├─ core/ # 规则、状态、存档
├─ game/ # 世界模拟和输入适配
│ └─ core/、assets 目录数据
├─ render/ # 纯绘制与资源适配
│ └─ game 世界快照、assets catalog
└─ ui/ # DOM 视图与用户反馈
└─ core/game 的只读 view
src/core/:可验证的状态层chapters.mjs:五章配置、规则常量、评级和剧情标记;配置应保持只读。state.mjs:GameCore 主线状态机,负责资源、任务、结算暂存、提交、失败回滚和事件去重。storage.mjs:版本化检查点和本地存储容错。experience-storage.mjs:跨章节体验、档案、导入导出和备份。这一层不能依赖 Canvas、DOM、window 或音频。动作层先验证碰撞和距离,再用带 attemptId 的事件调用核心 API。核心 API 返回结果对象,UI 不应直接修改内部状态。
src/game/:玩法适配层world.mjs:平台、机关、角色、警戒和世界事件;把玩家输入转换为核心事件。maps.mjs、rooms.mjs:地图和房间数据;不要在渲染器里硬编码章节逻辑。input.mjs:键盘和触控输入归一化。player-guidance.mjs:只读下一步建议,按真实库存、机制与合法出口决定目标;不提交世界事件。story.mjs、tutorial.mjs、lesson-bridge.mjs:剧情步骤、首分钟教学和教学与世界事件的桥接。prompts.mjs、safe-vuln.mjs、contracts.mjs:提示词、离线漏洞分析沙盒和挑战契约。preferences.mjs、session.mjs、audio.mjs:设置、最佳成绩和程序音效。renderer.mjs:保留为历史兼容门面;实际绘制实现位于 ../render/scene-renderer.mjs。src/render/:绘制和资源适配层assets.mjs:按 runtime-catalog.json 加载和裁切资源。resolution.mjs:逻辑坐标 1280×720 与设备像素比的映射。character-motion.mjs:动作采样、残影和局部特效;不负责推进任务或扣资源。绘制函数应接收世界快照和只读参数,不能在绘制过程中调用 GameCore 的变更 API。所有新增图片先登记到 runtime-catalog.json,再由 AssetLibrary 使用。
src/ui/:界面表现层ui.mjs:GameUI 兼容入口和控制器装配。player-polish.css:任务层次、角色区分、目标对侧停靠的指令面板与触屏排版;由统一样式入口加载。ui-v3.mjs:当前主界面、HUD、指令、剧情、档案和设置视图。game.css、ui-v3.css、ui-polish.css、ui-icon-polish.css:基础布局、版本样式、全局抛光和 SVG 状态样式。UI 读取 view() 或事件回执,按钮事件通过 main.mjs 暴露的回调回到玩法层。UI 不应直接改变 world 内的角色、碰撞或资源字段。
experience-storage.mjs、character-motion.mjs;不要新增同义缩写或 utils2 一类临时名。GameCore、GameWorld、GameRenderer);纯函数使用 camelCase;常量使用大写下划线。deepseek-actions.png、scan-grid-atlas.png。scripts/verify-*.mjs,构建或打包脚本使用动作开头的名称(build-game.mjs、package-game.py)。资产的事实来源分三层:
assets/asset-manifest.json 记录制作状态、来源、提示词和验收信息。assets/runtime-catalog.json 记录游戏实际加载的图片和采样坐标。src/render/assets.mjs 提供运行时加载 API;业务代码只使用资源 ID,不拼接散落的图片路径。开发入口使用 .mjs,生产构建由 scripts/build-game.mjs 清理并复制 src/,再将导入扩展名转换为 .js。构建后的 dist/index.html 和 dist/src 应能在静态 HTTP 服务下直接运行。新增源码模块后必须确认构建脚本会复制它,并运行 node scripts/verify-build.mjs 检查所有本地引用;不要依赖上一次构建残留的文件。
core/state.mjs、归一化逻辑和存档版本策略,再接入 UI 或世界层。world.mjs,不要在 renderer.mjs 里用章节 ID 判断任务完成。verify-*.mjs,最后运行 node scripts/build-game.mjs 检查部署目录。src/game/renderer.mjs 现在是兼容门面,实际绘制实现位于 src/render/scene-renderer.mjs;后续可把纯展示快照进一步抽到 src/game/presentation-state.mjs,迁移时保持兼容导出。src/ui/ui-v3.mjs 仍承担较多模板和交互分支。后续可按 screens/、components/、formatters/ 拆分,但先通过导出函数和快照测试固定行为。game.css、ui-v3.css 和两套抛光样式存在历史层叠。新增规则应优先写入设计 token 或组件类,并逐步删除重复选择器;不要为单个页面继续复制一整套颜色和阴影。assets/ui/game-ui.css 是旧资源说明中的设计系统,当前入口未直接加载。src/ui/styles.css 是运行时 CSS 聚合入口;将组件样式集中在此文件后,index.html 应只加载这一份样式入口,避免维护多份加载顺序。node src/core/verify-core.mjsnode scripts/verify-main-flow.mjsnode scripts/verify-rendering.mjsnode scripts/verify-art.mjsnode scripts/build-game.mjsnode scripts/verify-build.mjsdist/,确认模块、图片和 SVG 图标没有 404。这份约定描述的是当前可运行架构;未来目录重构应先更新本文和构建/验证脚本,再移动文件。