From 6c68927c7466dfa988a52933a29d487222cf3211 Mon Sep 17 00:00:00 2001 From: "Somhairle H. Marisol" Date: Tue, 29 Sep 2026 10:05:58 +0800 Subject: p71: 中文 API/模块说明（docs/api-reference） MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 docs/api-reference/：README + 6 模块（Sim/地图生成/桌面渲染/交互交易/职业/存读档） 每节含 职责·对外 API 概览·单位与量纲·不变量·失败分支·算法与性能取舍 - 口径以当前源码为准；性能引用实测 p70 基准（不含未测宣称） - P71ApiDocsTests（3 例，红先→绿）：文件齐备/章节齐备/关键接口与单位锚点 - Desktop 341/341、Kernel 120/120；未改生产 .fs/.fsproj、未 push --- docs/api-reference/README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/api-reference/README.md (limited to 'docs/api-reference/README.md') diff --git a/docs/api-reference/README.md b/docs/api-reference/README.md new file mode 100644 index 0000000..26db279 --- /dev/null +++ b/docs/api-reference/README.md @@ -0,0 +1,41 @@ +# 中文 API / 模块说明（api-reference） + +本目录为《活着的村庄》玩家可见代码模块的系统性中文说明，面向维护者与验收者。 +每条口径以**当前源码**为准（F# 8 / .NET 8）；文档只描述既有实现，不发明接口。 + +## 阅读约定 + +- **单位**：模拟时间以 `tick` 为基本单位，`1 tick = 1/60 秒`；`1 模拟日 = 86,400 秒 = 5,184,000 tick`。 + 位置以**像素**为单位（`Sim.tilePixels = 32` 像素/瓦片）；地图以**瓦片**为单位。 +- **确定性**：世界推进只由 `World.Rng`（splitmix64 同源）与 `seed` 派生，禁止墙钟与 `System.Random`。 +- **性能**：只引用**实测**基准（`docs/evidence/p70-*.txt`），不外推、不宣称未测数字。 +- **交叉引用**：`docs/维护说明.md`（模块职责 / 状态不变量 / 已验证命令）、 + `docs/chinese-village-art-direction.md`（中文与美术方向）。 + +## 模块索引 + +| 文件 | 覆盖模块 | 关键接口 | +| --- | --- | --- | +| `sim-kernel.md` | `LivingVillage.Kernel/Sim.fs` | `Sim.step`、`World`、`chat`、`trade`、`chooseDialogueWith` | +| `map-and-mapgen.md` | `MapGen.fs`、`ProceduralMap.fs`、`MapSnapshot.fs` | `MapGen.generateWithSize`、`MapGen.serialize`、`MapSnapshot.renderPng` | +| `rendering-desktop.md` | `Game.fs`、`VillageArt.fs`、`CjkGlyphAtlas.fs` | `LivingVillageGame` 主循环、`VillageArt.drawWorld`、`CjkGlyphAtlas.sourceRectangle` | +| `interaction-and-trade.md` | `Interaction.fs`、`PlayerTrade.fs` | `M5Interaction.apply`、`M5View`、`PlayerTrade.buy/sell` | +| `occupation.md` | `Occupation.fs` | `Occupation.saveToken`、`Occupation.dailyTaskOfWith`、`Occupation.applySignal` | +| `world-save.md` | `WorldSave.fs` | `WorldSave.save/saveWith`、`WorldSave.loadFromFileWith` | + +## 统一小节口径 + +每个模块文件固定包含六节： + +1. **职责**：一句话说明该模块负责什么、不负责什么。 +2. **对外 API 概览**：公开类型与函数的真实签名/语义。 +3. **单位与量纲**：输入/输出的单位、取值范围。 +4. **不变量**：可验收的硬约束。 +5. **失败分支**：错误/拒绝/异常路径与处理方式。 +6. **算法与性能取舍**：算法要点与**实测**性能引用。 + +## 相关证据与基准 + +- Kernel 吞吐 / GC：`docs/evidence/p70-kernel-baseline.txt`（`--performance-baseline`）。 +- Desktop 帧率 / 每帧分配：`docs/evidence/p70-analysis.txt`、`docs/evidence/p70-frames-sample.txt`。 +- 复跑：`bash scripts/bench-p70.sh /tmp/opencode/lv-p70`。 -- cgit v1.2.3