程基岩（engineering-lead）
856326a766
架构基线：docs/architecture/2026-10-19-F-architecture.md（v1.0） 范围：WRATH OF THE DEAD《怨返》单人挂机 · GDScript · 1280×720 · 12 班底数据驱动 - 骨架：project.godot（4.7 + GL Compatibility）、架构 §2.1 完整目录树（含占位说明）、 .gitignore/.gitattributes（LF 纪律）、README.md、CLAUDE.md、export_presets.cfg 占位、 pipeline/README.md（3ds Max 侧契约） - 数据管线段 1：data/sheets/generators.csv（GDD §3.1 十二班底逐值抄录） + data/schema/generators.schema.json（v0）+ src/tools/sheet_importer.gd （import_all/import_sheet/validate + ImportReport + .tres stub + 行号/列名/原因失败策略） + src/tools/import_main.gd（CI CLI 入口）+ data/build/generators.json（字节级确定性产物） - 探针：P1（SCREEN_TEXTURE/CanvasLayer 排序）与 P3（NoiseTexture2D seamless）场景代码与 截图/统计工具；实测手册与结论模板在工作区 docs/engineering/（随仓库外文档树） - CI：数据门激活（import_all + schema validate + build 漂移门）；单测/sim/导出 W3+ 注释占位； 4.7.2 headless CLI 行为标注待本机验证 待用户侧：P1/P3 实测回填结论；P6 字体许可 / P7 GPU 实测；look-dev 游魂初版（Max 侧）
75 lines
4.3 KiB
Markdown
75 lines
4.3 KiB
Markdown
# CLAUDE.md —— F《WRATH OF THE DEAD / 怨返》工程偏好
|
||
|
||
> 由 `docs/architecture/2026-10-19-F-architecture.md`（v1.0）派生 · 2026-10-19 · W1
|
||
> 本文件为工程宪法摘要；**冲突时以架构文档为准**；架构更新须两边同步。目标 ≤100 行。
|
||
|
||
## 引擎版本纪律
|
||
|
||
- **钉 Godot 4.7.x 补丁线，当前 4.7.2**（`project.godot` config/features）；小版本补丁可升，**跨 minor（4.8）上线后不追**；
|
||
- GDScript + GodotSteam **v4.23.1**（GDExtension 构建必须与 4.7.x 匹配；升级引擎 = 重新获取匹配构建）；
|
||
- renderer：`gl_compatibility`（2D 合成 + 核显底线；改 renderer = ADR 级动作）；
|
||
- ⚠ **知识缺口**：4.7.x 超出训练数据。API 不确定 → 先查官方文档/探针实测，**不臆造 API**；缺口持续标注，`docs/engine-reference/` 待补（架构 §11 P0）。
|
||
|
||
## 路径作用域编码标准（架构 §2.2）
|
||
|
||
| 作用域 | 纪律 |
|
||
|---|---|
|
||
| `src/core/` | 纯逻辑；禁 `extends Node`/访问场景树；`tick()` 零分配；100% 被 sim 与 GUT 无头复用 |
|
||
| `src/game/` | 唯一权威状态持有者；系统在此 tick；不直连 Steam（走 platform/）；不碰渲染 |
|
||
| `src/presentation/` | **只读快照 + 发命令**；UI 不持有游戏状态（仅视图本地态）；禁反向写 core |
|
||
| `src/platform/` | Steam API 唯一出口；`game/` 禁直调 `Steam.*` |
|
||
| `src/tools/` | `@tool` 标注；CI 可 headless；运行时场景禁引用 |
|
||
| `data/` | 零代码；稳定字符串 ID；**不重编号**；schema 违规 = CI 红 |
|
||
| `pipeline/` | 契约 = 命名 + 导出参数；唯一逐资产代码 = sprite 路径 |
|
||
| network | **不适用**：单人买断无网络代码 |
|
||
|
||
依赖方向：`presentation → game → core`；`game → platform`；`tools → data`。禁反向、禁跨层。
|
||
|
||
## 数据驱动红线（架构 §9.2 + ADR-3）
|
||
|
||
1. 零硬编码：一切数值进 `data/sheets/` → JSON → Resource；
|
||
2. **新资产 = 加行**；唯一逐资产代码 = `GeneratorDef.sprite_row`；
|
||
3. 新增资产若需改代码 = **设计失败，回退重做**；
|
||
4. 稳定 ID 永不重编号/复用；schema 违规 = CI 红（行号+列名+原因，禁跳过坏行）；
|
||
5. 数值列禁千分位；`_cn/_en` 本地化后缀；引用列填目标 ID；
|
||
6. "AI 让加一个班底变便宜了"禁用作加范围理由。
|
||
|
||
## ADR 一句话（架构 §8，均已接受）
|
||
|
||
- **ADR-1**：预渲染 2 朝向 billboard，不用实时 3D（用户比较优势在批渲染）；
|
||
- **ADR-2**：单趟 fused 全屏后处理 shader（posterize→LUT→纸纹→暗角），UI 层在其上；
|
||
- **ADR-3**：美术数据行纪律（新资产=加行；唯一逐资产代码 = sprite 路径）；
|
||
- **ADR-4**：AI 仅内部使用（mood board/概念），不进包体、不出厂、商店页披露填 No。
|
||
|
||
## 探针状态（W1）
|
||
|
||
| 探针 | 状态 | 手册 / 结论 |
|
||
|---|---|---|
|
||
| P1 SCREEN_TEXTURE/CanvasLayer | ⏳ 待用户实测 | `docs/engineering/2026-10-19-f-w1-probe-p1-manual.md` → `docs/engineering/probes/P1-result.md` |
|
||
| P3 noise seamless 平铺 | ⏳ 待用户实测 | `docs/engineering/2026-10-19-f-w1-probe-p3-manual.md` → `docs/engineering/probes/P3-result.md` |
|
||
| P6 字体许可 / P7 用户 GPU | ⏳ 用户侧任务（W1） | 不在本仓库；结论回填 probes/ |
|
||
| P2/P4/P5/P8-P11 | 未启动 | 架构 §11 排期（W2-W5） |
|
||
|
||
**不过的回退**：P1 → SubViewport+BackBufferCopy（+2-4h）；P3 → 脚本预烘焙无缝纹理（+0.5-1h）。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 数据门（导入 + 校验）
|
||
godot --headless --path . --import
|
||
godot --headless --path . -s res://src/tools/import_main.gd # import_all
|
||
godot --headless --path . -s res://src/tools/import_main.gd -- --validate-only
|
||
# 运行：编辑器 F5（main scene W2 起）；探针：打开 tests/probe_* 场景 F6
|
||
```
|
||
|
||
## 数据管线速查
|
||
|
||
`data/sheets/*.csv` →（SheetImporter，本仓库 `src/tools/`）→ `data/build/*.json`（提交）→（W3 `.tres`）→ DataRegistry。
|
||
单向流动：游戏永不写 `data/`；sim 与游戏读同一份 build。契约见 `README.md` + 架构 §3。
|
||
|
||
## 纪律提醒
|
||
|
||
- 写代码前**先写测试**（GUT W3 起）；每个 Story 留测试证据路径；
|
||
- 高影响动作（提交/删除/上线）须用户审批；本仓库 `git` 提交信息写架构基线；
|
||
- 目录微调 = 架构 §2.1 变更 = ADR 流程，不擅自挪目录。
|