chore: W1 项目骨架 — 基线 v1.0 架构落盘(Godot 4.7.2 / gl_compatibility)

架构基线: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 侧)
This commit is contained in:
程基岩(engineering-lead) committed 2026-10-19 15:13:10 +08:00
commit 856326a766
42 files changed
+1814

No files matched your search

+74
View File
@@ -0,0 +1,74 @@
# 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 流程,不擅自挪目录。