← 返回记录总览

代码架构与目录约定

来源:游戏-鲸鱼魔盗团/docs/代码架构与目录约定.md · 8.9 KB


《鲸鱼魔盗团》代码架构与目录约定

本文是当前代码库的维护入口。它描述已经存在的目录边界、运行时依赖方向、资源来源和构建产物,帮助后续开发在不破坏现有流程的情况下继续扩展。

1. 当前目录分层

游戏-鲸鱼魔盗团/
├─ 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 中修复问题,也不要把截图或压缩包反向提交为运行时依赖。

2. 运行时依赖方向

依赖关系从上到下保持单向,避免模块互相操作 DOM 或互相持有完整游戏对象:

index.html
  └─ src/main.mjs                    # 组合根(composition root)
      ├─ core/                       # 规则、状态、存档
      ├─ game/                       # 世界模拟和输入适配
      │   └─ core/、assets 目录数据
      ├─ render/                     # 纯绘制与资源适配
      │   └─ game 世界快照、assets catalog
      └─ ui/                         # DOM 视图与用户反馈
          └─ core/game 的只读 view

src/core/:可验证的状态层

这一层不能依赖 Canvas、DOM、window 或音频。动作层先验证碰撞和距离,再用带 attemptId 的事件调用核心 API。核心 API 返回结果对象,UI 不应直接修改内部状态。

src/game/:玩法适配层

src/render/:绘制和资源适配层

绘制函数应接收世界快照和只读参数,不能在绘制过程中调用 GameCore 的变更 API。所有新增图片先登记到 runtime-catalog.json,再由 AssetLibrary 使用。

src/ui/:界面表现层

UI 读取 view() 或事件回执,按钮事件通过 main.mjs 暴露的回调回到玩法层。UI 不应直接改变 world 内的角色、碰撞或资源字段。

3. 文件命名约定

4. 资源与构建约定

资产的事实来源分三层:

  1. assets/asset-manifest.json 记录制作状态、来源、提示词和验收信息。
  2. assets/runtime-catalog.json 记录游戏实际加载的图片和采样坐标。
  3. src/render/assets.mjs 提供运行时加载 API;业务代码只使用资源 ID,不拼接散落的图片路径。

开发入口使用 .mjs,生产构建由 scripts/build-game.mjs 清理并复制 src/,再将导入扩展名转换为 .js。构建后的 dist/index.html 和 dist/src 应能在静态 HTTP 服务下直接运行。新增源码模块后必须确认构建脚本会复制它,并运行 node scripts/verify-build.mjs 检查所有本地引用;不要依赖上一次构建残留的文件。

5. 修改流程

  1. 先判断改动属于核心规则、世界玩法、绘制适配还是 UI 表现,再修改对应目录。
  2. 如果增加状态字段,先修改 core/state.mjs、归一化逻辑和存档版本策略,再接入 UI 或世界层。
  3. 如果增加地图事件,修改地图/房间数据与 world.mjs,不要在 renderer.mjs 里用章节 ID 判断任务完成。
  4. 如果增加资产,更新 manifest、runtime catalog 和预览,再接入资源 ID。
  5. 修改后至少运行相关 verify-*.mjs,最后运行 node scripts/build-game.mjs 检查部署目录。

6. 当前兼容债务与后续演进

7. 最小验收清单

这份约定描述的是当前可运行架构;未来目录重构应先更新本文和构建/验证脚本,再移动文件。