diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f0fc529..af59dbc4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,7 +52,8 @@ SIM_E2E=1 node --test 'test/sim/*.browser.test.js' # 浏览器里 activity_table 的 act2autochess、enemy_database、关卡文件）和 [PRTS](https://prts.wiki/)（干员页、技能和天赋的「备注」、 卫戍协议相关页面）。数值尽量取 blackboard，不要凭记忆写数字。官方实测的截图或录像也很有价值，请附在 Issue / PR 里。 - **查不到出处**的细节按最简单、最接近官方的方式实现，在代码注释和 PR 描述里标 `[ASSUMED]`。维护者拍板的写成 - “the owner's decision of YYYY-MM-DD”。有意和官方不同的规则只能由维护者决定，并写进 docs/DESIGN.md。 + “the owner's decision of YYYY-MM-DD”。有意和官方不同的规则只能由维护者决定，并写进设计文档（[docs/DESIGN.md](docs/DESIGN.md) + 是索引：现行规则在 `docs/design/`，各版本的修订与依据在 `docs/history/`）。 - **版权**：不要把技能描述、剧情等受版权保护的文本大段复制进代码、文档或 PR，引一小句并注明出处即可。不要提交任何游戏 素材文件（`public/assets/` 已被 `.gitignore` 排除）。 - **数据**：不要手改 `data/*.json`。改 `tools/build-data.mjs`，用 `node tools/build-data.mjs --offline` 重新生成，再比较 @@ -66,7 +67,8 @@ SIM_E2E=1 node --test 'test/sim/*.browser.test.js' # 浏览器里 里写明并致谢作者。 - PR 描述写：改了什么、为什么、出处（数据表字段、PRTS 链接）、`[ASSUMED]` 的地方、跑了哪些测试、黄金结果里哪些场景变了。 界面改动附截图。 -- 规则改了，相关文档一起改：docs/DESIGN.md（规则与契约）、docs/SIM.md、docs/META.md、docs/DATA.md 等。 +- 规则改了，相关文档一起改：`docs/design/` 里对应的规则（章节号与文件见 docs/DESIGN.md 的索引）、`docs/history/` 里当前版本的 + 修订记录、docs/SIM.md、docs/META.md、docs/DATA.md 等。 `test/docs-consistency.test.js` 固定了文档里的一些句子，改文档后跑一下。 - 代码和注释用英文；玩家文档（README、PLAYING、DEPLOY）用简体中文，技术文档用英文。界面上的文字写中文并用 `t('…')` 包起来，英文放进 `public/i18n/en.json`（[docs/I18N.md](docs/I18N.md)）。 @@ -100,8 +102,9 @@ SIM_E2E=1 node --test 'test/sim/*.browser.test.js' # 浏览器里 `npm run golden:update` and commits the digests with the change, naming the scenarios that moved. - **Fidelity**: the official tables (`.cache/gamedata/excel/`) and PRTS (including the 备注 notes) are the sources; numbers come from the blackboards. Anything no source settles is marked `[ASSUMED]` in the code and the pull - request; owner decisions are cited with their date; deliberate deviations are the owner's call and go into - docs/DESIGN.md. Do not paste copyrighted game text at length (quote briefly, cite) and never commit game assets. + request; owner decisions are cited with their date; deliberate deviations are the owner's call and go into the design + document (docs/DESIGN.md is its index: the rules in `docs/design/`, the per-release revisions in `docs/history/`). + Do not paste copyrighted game text at length (quote briefly, cite) and never commit game assets. Never hand-edit `data/*.json`: change `tools/build-data.mjs`, rebuild with `--offline`, compare the JSON. - **Commits and pull requests**: one change per pull request, one operator per kit pull request. A one-line commit message saying what changed, with the issue number; no attribution trailers such as `Co-Authored-By:` or diff --git a/README.md b/README.md index 80b5ed8a..143b84c9 100644 --- a/README.md +++ b/README.md @@ -173,7 +173,7 @@ npm start # 启动服务器：http://localhost:3000 | [docs/PLAYING.md](docs/PLAYING.md) | 玩法指南：流程、经济、招募与晋升、摆阵、联防、盟约、最终攻势、结算称号 | | [docs/DEPLOY.md](docs/DEPLOY.md) | 部署指南：Windows 开服与开机自启、防火墙、组网 / 隧道、反向代理与 HTTPS、Docker、systemd、排错 | | [docs/WINDOWS.md](docs/WINDOWS.md) | Windows 便携包：怎么打一份「零安装」包（`scripts/make-windows-bundle.mjs`）、包里放了什么、授权注意事项 | -| [docs/DESIGN.md](docs/DESIGN.md) | 架构与契约（英文）：技术栈、目录分工、网络协议、渲染与 UI、各次试玩后的规则修订 | +| [docs/DESIGN.md](docs/DESIGN.md) | 架构与契约（英文）：索引，按章节号找到文件；现行规则在 `docs/design/`（范围与目录分工、坐标与时间、战斗引擎、对局、网络协议、渲染与 UI），各次试玩和各版本的规则修订与依据在 `docs/history/` | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 代码地图（英文）：服务器、联机协议和前后端共用的战斗模拟，0.2.0 重构后的目录，数据流，黄金结果与导入边界，常见改动从哪里入手 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 参与贡献：准备环境、运行测试、忠实原则、提交与 PR 约定、怎样添加自选干员（中文，末尾附英文摘要） | | [docs/SIM.md](docs/SIM.md) | 战斗模拟引擎参考（英文）：钩子、技能描述格式、职业默认行为 | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b0c95d91..425dda40 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,7 +1,10 @@ # ARCHITECTURE.md — a map of the code For a newcomer who wants to find their way before changing something. This file only maps the code. The contracts are -in [DESIGN.md](DESIGN.md) (§5 the battle engine, §6 the match, §8 the protocol, §9 rendering, §14 client-side combat); +in the design document — [DESIGN.md](DESIGN.md) is its index, the current rules are in `docs/design/` (§5 the battle +engine: [design/engine.md](design/engine.md); §6 the match: [design/match.md](design/match.md); §8 the protocol and §14 +client-side combat: [design/network.md](design/network.md); §9 rendering: [design/client.md](design/client.md)), the +per-release revisions and their evidence in `docs/history/`; the details in [SIM.md](SIM.md) (battle engine, hooks, SkillSpec), [META.md](META.md) (match engine, prep-phase effects), [DATA.md](DATA.md) (generated data), [ASSETS.md](ASSETS.md) (art and audio) and [I18N.md](I18N.md) (languages). How to set up, test and send a change: [CONTRIBUTING.md](../CONTRIBUTING.md). @@ -105,9 +108,9 @@ so old imports keep working: `public/js/ui/gameLogic.js` (`public/js/ui/gameLogi |---|---| | `data/*.json` | generated by `tools/build-data.mjs` and committed — never edited by hand (DATA.md); `data/backups.json` holds the 补位 and 自选 data, `data/i18n/en.json` the English game texts, `data/assets.json` the art manifest | | `tools/` | `build-data.mjs`, `build-i18n.mjs`, `i18n.mjs` (UI strings), `setup.mjs` / `fetch-assets.mjs` / `tools/assets/` (art and audio), `tools/local-extract/` (art from a local game client), `vendor.mjs`, `golden.mjs`, `check-imports.mjs`, `package.mjs` (the release zip), `doctor.mjs`; sweeps: `matchrun.mjs`, `simrun.mjs`, `botbench.mjs`, `balance.mjs` | -| `test/` | `node:test` suites by area: `test/content/` (kits, enemies, bonds, items), `test/sim/` (the engine), `test/match/` (match engine, bots), `test/ui/`, `test/render/`, `test/golden/` (the stored digests), `test/helpers/` (`battleHarness.js`), `test/e2e/` (browser and bot runs) | +| `test/` | `node:test` suites by area: `test/content/` (kits, enemies, bonds, items), `test/sim/` (the engine), `test/match/` (match engine, bots), `test/ui/`, `test/render/`, `test/golden/` (the stored digests), `test/helpers/` (`battleHarness.js`; `designDocs.js`, the design document in § order for the doc tests), `test/e2e/` (browser and bot runs) | | `types/` | JSDoc typedefs of the type-checked slice (`types/README.md`) | -| `docs/` | the documents; `docs/research/` the research on the official mode | +| `docs/` | the documents; `docs/DESIGN.md` the index of the design document, `docs/design/` its current rules, `docs/history/` its per-release revisions; `docs/research/` the research on the official mode | ## 4. Data flow @@ -180,5 +183,6 @@ public/assets/ ─────────▶ public/js/render/, public/js/audio | a UI text | `t('…')` in the code, the English in `public/i18n/en.json` | I18N.md | | HTTP, headers, static routes | `server/http/` | `test/version.test.js`, `test/client-static.test.js` | -Before changing a rule, read the DESIGN section that owns it (module headers cite their sections) and the official -source; a rule no source settles is marked `[ASSUMED]` ([CONTRIBUTING.md](../CONTRIBUTING.md) §3). +Before changing a rule, read the DESIGN section that owns it (module headers cite their sections; the table in +DESIGN.md names the file that holds each) and the official source; a rule no source settles is marked `[ASSUMED]` +([CONTRIBUTING.md](../CONTRIBUTING.md) §3). diff --git a/docs/META.md b/docs/META.md index 7548518c..6a13b581 100644 --- a/docs/META.md +++ b/docs/META.md @@ -2,7 +2,8 @@ Audience: **content authors** writing prep-side ("SERVER_*") effects in `server/sim/content/*.js → registerMeta(registry)`, the **UI owner** consuming `m.public` / `m.private` / `m.result`, and anyone driving matches in tests or tools. -Normative contracts stay in DESIGN.md §6 and §8; this file documents the implementation and every assumption it makes. +Normative contracts stay in DESIGN.md §6 and §8 ([design/match.md](design/match.md), +[design/network.md](design/network.md)); this file documents the implementation and every assumption it makes. ``` server/match/ diff --git a/docs/SIM.md b/docs/SIM.md index d466e4f4..acd71c3e 100644 --- a/docs/SIM.md +++ b/docs/SIM.md @@ -1,9 +1,9 @@ # SIM.md — battle simulation engine reference (server/sim) Audience: **content authors** (kits, bonds, garrisons, items, bands, enemies, bosses, devices, choices) and the -**match owner** who drives `Battle`. The normative contract is DESIGN.md §5; this file documents the concrete -implementation, every hook and helper, the SkillSpec schema with worked examples, the profession defaults and -the test harness. Everything here is deterministic: the only randomness is `battle.rng()`. +**match owner** who drives `Battle`. The normative contract is DESIGN.md §5 ([design/engine.md](design/engine.md)); +this file documents the concrete implementation, every hook and helper, the SkillSpec schema with worked examples, +the profession defaults and the test harness. Everything here is deterministic: the only randomness is `battle.rng()`. ``` server/sim/ diff --git a/docs/design/overview.md b/docs/design/overview.md index e29194bf..f00b972f 100644 --- a/docs/design/overview.md +++ b/docs/design/overview.md @@ -130,7 +130,9 @@ tools/ fetch-assets.mjs downloads/optimizes assets → public/assets + data/assets.json vendor.mjs copies vendor libs from node_modules → public/vendor test/ node:test suites; test/e2e/ browser + bot tests -docs/ DESIGN.md (this), DATA.md, SIM.md, META.md, ASSETS.md, BALANCE.md, DEPLOY.md, PLAYING.md, research/ +docs/ DESIGN.md (the index of this document: the rules in design/, the per-release revisions in + history/), ARCHITECTURE.md, DATA.md, SIM.md, META.md, I18N.md, ASSETS.md, BALANCE.md, + DEPLOY.md, PLAYING.md, WINDOWS.md, research/ (the wire protocol is normative in shared/protocol.js itself) LICENSE GPL-3.0-or-later (the project's code); NOTICE.md: scope, non-commercial game assets, the Spine Runtimes linking permission; THIRD-PARTY-NOTICES.md: libraries, fonts, data sources