feedback5 WW: links after the DESIGN split — README's docs table (DESIGN.md is the index, the rules in docs/design/, the revisions in docs/history/), ARCHITECTURE.md (§5 / §6 / §8 / §9 / §14 link their design/ files; the docs/ and test/helpers/ rows), CONTRIBUTING.md (deviations and rule changes go into docs/design/ with the release's revision in docs/history/; 中文 and English), SIM.md (§5 → design/engine.md), META.md (§6 / §8 → design/match.md, design/network.md), DESIGN §2's docs/ line names the index, its parts and the newer docs; citations "DESIGN §N" stay as they are (the index resolves them)
This commit is contained in:
sganggs committed
1 parent
38f4a3d9ba
commit
a7fbc7da33
6 files changed
+25
-15
No files matched your search
+7
-4
@@ -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
|
||||
|
||||
@@ -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) | 战斗模拟引擎参考（英文）：钩子、技能描述格式、职业默认行为 |
|
||||
|
||||
@@ -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).
|
||||
+2
-1
@@ -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/
|
||||
|
||||
+3
-3
@@ -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/
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user