# 中文 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`。