# kids-war

**Repository Path**: kevinlights/kids-war

## Basic Information

- **Project Name**: kids-war
- **Description**: 国家和城镇，战争，但是主要靠学习挣钱
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-20
- **Last Updated**: 2026-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 少年战记 · Kids War Chronicle

A 2D top-down "mount and blade" style strategy web game, built as a single-page Vue app and playable on a home LAN.
一款 2D 俯视视角的「骑马与砍杀」风格策略网页游戏，用单页 Vue 应用实现，可在家庭局域网里直接游玩。

This README is written so a new contributor can get productive fast: read it top to bottom, then open the key files listed in the Maintenance section.
本 README 面向后续接手修改和扩展的人：从头往下读一遍，再打开「游戏维护」里列出的关键文件即可上手。

The game is drawn on `<canvas>` and in CSS, with 32x32 pixel-art sprites generated by `tools/pixel-assets/generate.mjs`; there is no audio at all, so it loads instantly and runs fully offline.
游戏画面由 `<canvas>` 与 CSS 绘制，像素素材是 `tools/pixel-assets/generate.mjs` 生成的 32×32 像素画；没有任何音频，因此加载即秒开，并且可以完全离线运行。

---

## 目录 · Table of Contents

1. [项目介绍 · Introduction](#1-项目介绍--introduction)
2. [目标对象群体 · Target Audience](#2-目标对象群体--target-audience)
3. [主要玩法 · Core Gameplay](#3-主要玩法--core-gameplay)
4. [核心机制 · Core Mechanics](#4-核心机制--core-mechanics)
5. [势力与兵种 · Factions and Units](#5-势力与兵种--factions-and-units)
6. [游戏界面 · Game Screens](#6-游戏界面--game-screens)
7. [游戏操作 · Controls](#7-游戏操作--controls)
8. [游戏分享 · Sharing](#8-游戏分享--sharing)
9. [奖励与惩罚 · Rewards and Penalties](#9-奖励与惩罚--rewards-and-penalties)
10. [游戏数据 · Game Data](#10-游戏数据--game-data)
11. [手机端支持 · Mobile Support](#11-手机端支持--mobile-support)
12. [游戏部署 · Deployment](#12-游戏部署--deployment)
13. [游戏维护 · Maintenance](#13-游戏维护--maintenance)
14. [项目结构 · Project Structure](#14-项目结构--project-structure)
15. [常见问题 · Troubleshooting](#15-常见问题--troubleshooting)
16. [战团玩法对照 · Comparison with Mount & Blade](#16-战团玩法对照--comparison-with-mount-and-blade)
17. [学习主线的改进 · Improving the exam spine](#17-学习主线的改进--improving-the-exam-spine)

---

## 1. 项目介绍 · Introduction

`kids-war-game` is a single-page Vue application: an endlessly generated world map that you walk around by
tapping, settlements you enter to recruit troops and promote them along four ranks, town exams that pay gold for
correct answers, and real-time battles where every squad gets its own order, formation and density.
`kids-war-game` 是一个单页 Vue 应用：一张程序生成的无限世界地图，点击即可移动；进入村庄与城镇招募士兵并沿四个档位升级；在城镇参加考试，答对题目才能拿到金币；遇到敌人时先与敌将对话，可以逃跑或开战，开战后进入实时战斗，每支小队都能单独下达命令、设置队形与密度。

The core design rule is that **gold comes only from answering questions correctly**.
核心设计原则是：**金币只能通过答对题目获得**。

Recruiting, upgrading and supplies all cost gold, so progress in the war game is paid for by practising
grade-3 / grade-4 English, Chinese, math, logic and general knowledge.
招募、升级和物资都要花金币，所以打仗的进度本质上是用三年级、四年级的英文、语文、数学、逻辑和百科知识练习换来的。

Tech stack · 技术栈：

- Vue 3 (`<script setup>` composition API) + Pinia + Vue Router (hash history)
- Vite 6 as the build tool, `@vitejs/plugin-vue` for SFC compilation
- Canvas 2D for the world map and battle arena; no rendering library
- `qrcode-generator` — the only runtime dependency beyond Vue/Pinia/Router, used for the share QR
- All art is 32x32 pixel art generated with Pixelorama, see 「美术素材 · Pixel art assets」
  所有美术资源都是用 Pixelorama 生成的 32×32 像素画，见「美术素材 · Pixel art assets」

---

## 2. 目标对象群体 · Target Audience

Primary players are primary-school children, roughly 8–12 years old, with question banks graded for grade 3
and grade 4.
主要玩家是小学生，大约 8–12 岁，题库按三年级和四年级分级。

The world is read-only fantasy: the "special faction" bandits are the only always-hostile force, and a
defeat never wipes out your progress permanently — you keep whatever soldiers actually survived.
世界观是轻度奇幻：只有「强盗」这一特殊势力始终敌对，战败也不会把进度彻底清零——战场上的幸存者仍然留在队伍里。

Secondary audience is the adult who deploys it: a parent or teacher who wants a LAN game with no install,
no account and no internet connection.
次要使用者是部署它的成年人：家长或老师，希望在局域网上跑一个游戏，不装客户端、不注册账号、不联网。

---

## 3. 主要玩法 · Core Gameplay

The loop is: explore → recruit → earn gold by passing exams → fight → grow → fight bigger.
玩法循环是：探索 → 招募 → 靠考试赚钱 → 战斗 → 变强 → 挑战更强的敌人。

1. **Explore.** Tap anywhere on the world map; the character pathfinds there. Towns and villages sit on the map.
   移动为主。点击世界地图任意位置，角色自动寻路前往；地图上分布着城镇与村庄。
2. **Recruit.** Villages sell basic militia; towns roll four random offers from the whole roster, ranks and all.
   招兵买马。村庄只卖普通民兵；城镇随机滚出四个兵种档位组合，低级常见、精英稀少。
3. **Pass exams.** Enter a town, take an exam, and answer questions correctly to earn gold.
   考试赚钱。进入城镇参加考试，答对题目获得资金。
4. **Fight.** Walk into a hostile warband to start a battle; pick a squad, give it an order, and set its formation.
   排兵布阵。靠近敌对部队即进入战斗，先选部队再下命令，还能单独设置队形与密度。
5. **Upgrade.** Spend gold to promote militia into spearmen, archers or cavalry, then climb four ranks to elite.
   升级变强。用金币把民兵升级成长枪兵、弓箭手或骑兵，再一路升到精英档。

---

## 4. 核心机制 · Core Mechanics

### 4.1 世界地图与移动 · World map and movement

The world is a fixed **80 × 64** tile grid at **32 px** per tile (2560 × 2048 px), generated from a seed with
value-noise terrain.
世界是一张固定的 **80 × 64** 格地图，每格 **32 px**（合计 2560 × 2048 px），由种子驱动的值噪声地形生成。

Terrain affects movement cost, not passability, except for water and mountains which are impassable.
地形影响移动开销而非阻挡（水域和山地不可通行）。

| 地形 Terrain | 可通行 Walkable | 移动开销 Cost |
| --- | --- | --- |
| 平原 Plain | 是 Yes | 1.0 |
| 森林 Forest | 是 Yes | 1.6 |
| 沙漠 Desert | 是 Yes | 1.3 |
| 山地 Mountain | 否 No | — |
| 水域 Water | 否 No | — |

Generation keeps only the **largest connected walkable landmass** as the mainland, and every town, village,
enemy warband and the player spawn are placed inside it, so any two landmarks are always reachable.
生成时只保留**最大的一块连通陆地**作为主大陆，所有城镇、村庄、敌方部队和玩家出生点都放在其中，因此任意两个地标之间都可达。

Long clicks use A* with a **best-effort fallback**: if the exact target is unreachable (water, a mountain or an
island), the character walks as close to it as the land allows instead of standing still.
远距离点击使用 A* 寻路，并带**尽力靠近回退**：若目标本身不可达（水域、山地或孤岛），角色会走到陆地上最接近的位置，而不是原地不动。

The player walks at **3.9 tiles/s**; enemy parties roam at **1.7 tiles/s** (bandits ×1.15).
玩家移动速度 **3.9 格/秒**；敌方部队游荡速度 **1.7 格/秒**（强盗 ×1.15）。

Game time only runs while the lord is on the move: **24 seconds of walking is one day**, and a lord standing
still freezes the clock *and* the world — roaming parties stop, party cooldowns pause and the day counter holds.
游戏时间只在主角移动时流逝：**连续行走 24 秒为一天**；主角站着不动会同时冻结时钟**与世界**——游荡的敌军停止移动、敌方冷却暂停、天数也不再增加。

Camping (⛺) is the only way to let time pass without moving: the lord rests in place while the clock and every
roaming party keep running, which is how you wait out an enemy respawn or bait a warband into walking past. Tap
「⛺ 扎营」 to pitch camp (this cancels the march in progress) and 「🔥 拔营」, or tap anywhere on the map, to
break it.
扎营（⛺）是唯一能原地让时间流逝的方式：主角原地休息，但时钟与所有游荡部队照常运转，可以用它等敌方复活，或者把敌军引到别处。点「⛺ 扎营」就地扎营（会中断当前行军），点「🔥 拔营」或点地图任意位置即可拔营。

The **day clock** in the status bar shows the campaign clock: the day counter, the hour inside that day and a bar
that fills up as the day passes. On the world map a day lasts 24 game seconds and one game second is one in-game
hour, so the clock runs from 00:00 to 23:59 and then the day counter turns over. The bar is green while the clock is
running (on the march or camping) and gold while it is frozen. The last fifth of the bar is the night.
状态栏的**时钟**显示战役时钟：天数、当天的时间点，以及一条随一天推进而填满的进度条。地图上的一天是 24 秒游戏时间，而 1 秒游戏时间正好是游戏里的 1 小时，因此时钟从 00:00 走到 23:59 后天数加一。时钟在走动（行军或扎营）时进度条是绿色，冻结时是金色；进度条的最后五分之一是夜晚。

#### 昼夜 · Day and night

**The last fifth of every day is night** (from 19:12 to 24:00). At night the sky darkens and everything moves
slower: the deepest night is **25% slower**, so the lord covers less ground — and so do the warbands that roam the
map. The night is not a hard switch: the first and last quarter of it are dusk and dawn, where the darkness fades
in and out, and the lord keeps a lantern light around himself so the ground stays readable.
**每天的最后五分之一是夜晚**（19:12 – 24:00）。夜里天会黑下来，整个世界都变慢：最深的夜里**慢 25%**，主角能走的距离更短，地图上游荡的部队同样变慢。夜晚不是瞬间切换的：夜晚的前四分之一是黄昏、后四分之一是黎明，黑度渐变渐退；主角身边始终有一圈灯光，脚下依旧看得清。

The night does not change the clock: a day is still 24 seconds of game time, so the lord simply gets less done in
the dark.
夜晚不会改变时钟：一天仍然是 24 秒游戏时间，只是主角在黑暗里能做的事更少。

The same clock appears in the settlement screen (where time passes while the lord rests) and in the lord panel, and
the day chip also carries the clock state — ⏸ 停滞 (frozen), ⏳ 流逝 (on the march) or 🔥 扎营 (camping) — and a
camped lord is drawn beside a tent and campfire, so the state is readable on the map itself. Time is not part of
the save: loading always resumes with the lord standing still and the clock frozen.
同一个时钟也出现在据点界面（主角休整时时间在走）与角色信息面板里；天数芯片同时显示时钟状态——⏸ 停滞、⏳ 流逝 或 🔥 扎营——扎营的主角身边会画出帐篷与篝火，状态在地图上直接可见。时间状态不写进存档：读档后总是站在原地、时钟冻结。

**Town time is slower on purpose.** Inside a settlement one real second is one in-game minute, so a day of town
business takes **24 real minutes** instead of 24 seconds. Reading a panel, recruiting or upgrading no longer burns
campaign days. The trade-off is that resting uses the same slow clock, so a long rest is a long wait; marching and
camping keep the fast 24-second day.
**城镇里的时间刻意放慢。** 进入据点后，现实 1 秒等于游戏里的 1 分钟，因此城镇里的一天是 **24 分钟**而不是 24 秒。看面板、招兵、升级不会再顺手烧掉战役里的天数。代价是休整也用同一口慢钟，想靠休息养伤就得真的等；行军与扎营仍然是 24 秒一天。

### 4.2 小地图与全图 · Minimap and detailed atlas

The top-right corner holds a **minimap** of the whole world: blocky terrain, a square per settlement in the colour of
its owner (a gold square per unclaimed town, a pale square per unclaimed village), a faction-coloured dot per roaming
warband, the rectangle the main map is currently looking at, and the lord as a pulsing blue dot. It is drawn from one
cached 1-px-per-tile picture of the terrain, so it costs a single `drawImage` per frame.
右上角是整张世界的**小地图**：方块化地形、每个据点一个归属色方块（无主的城镇是金色方块、无主的村庄是浅色方块）、每支游荡部队一个势力色圆点、主地图当前视野的矩形框，以及作为脉动蓝点的主角。小地图由一张缓存的「一格一像素」地形图绘制，因此每帧只要一次 `drawImage`。

Tapping the minimap opens the **detailed atlas** (🗺️ 世界全图): the same world at 16 px per tile — larger than a
phone screen in both directions, so a finger drag pans across it — with the settlement sprites and name plates (each
settlement is circled by an ownership ring and carries an owner-coloured name plate, so who holds every patch of land
is readable at a glance), every faction commander, every companion and the lord, each with its troop badge (a
companion's badge is one size smaller, and a companion with no soldiers carries none). 「🎯 回到主角」 recentres
the view, and ✕ or Esc closes it.
点击小地图会打开**详细地图**（🗺️ 世界全图）：同一张世界以每格 16 px 渲染——两个方向都比手机屏幕更大，因此可以用手指拖动查看不同区域——上面画出据点素材与名字牌（每个据点周围都有一圈归属色光环、名字牌也用归属色，一眼就能看出每片地盘属于谁）、所有势力将领、每位随从与主角，每个图标右上角都有兵力角标（随从的徽章小一号，没有分到兵的随从不挂）。点「🎯 回到主角」把视野拉回主角，点 ✕ 或按 Esc 关闭。

The **legend** under the minimap lists exactly the icons the world map draws — the lord, one commander per faction in
its faction colour, a town and a village — so a recoloured faction can never go missing from the legend. Everything
that sits above the world map — the chips and buttons of the top bar, the minimap button, the legend and its
「收起 / 展开」 toggle — shares one translucent black glass; a hover only deepens the black, and each label keeps its
own colour.
小地图下方的**图例**列出的正是世界地图上绘制的图标——主角、每个势力一位穿着势力色战袍的将领、城镇与村庄——因此给势力改色绝不会在图例里漏掉。漂浮在地图上方的所有控件——顶部状态栏的芯片与按钮、小地图按钮、图例与它的「收起 / 展开」——共用同一块黑色透明玻璃；悬停时只是加深黑色，各标签保留自己的颜色。

### 4.3 据点 · Settlements

Every world holds up to **8 towns** and up to **24 villages**, spawned with a minimum spacing so they do not
overlap. The map itself is twice as big in each direction: **160 × 128 tiles**.
每个世界最多生成 **8 个城镇**和最多 **24 个村庄**，生成时保证最小间距，避免重叠。地图本身在两个方向上都扩大了一倍：**160 × 128 格**。

Standing within about 1.4 tiles of a settlement shows an "enter" button.
站在据点约 1.4 格范围内时，界面会出现「进入」按钮。

- **村庄 Village** — 只能招募普通民兵，价格便宜。Only basic militia, cheap.
- **城镇 Town** — 可招募高级兵种，并且是唯一能参加考试的地方。Advanced troops and the only place with exams.

### 4.4 招募与升级 · Recruiting and upgrades

Villages offer militia only. Towns roll **4 unique offers** from the whole roster — every family and rank from
初级 to 精英 — weighted so low ranks are common and elites are rare, plus militia, with a **×1.15 price markup**;
the offers are seeded per settlement, so a given town keeps the same stock.
村庄只提供民兵。城镇从整个兵种表里随机滚出 **4 个不重复的档位**——三个家族 × 初级到精英——权重让低级常见、精英稀少，再附加民兵，价格 **×1.15**；因为按据点种子生成，同一个城镇的兵源是固定的。

Every family has four ranks — 初级 (basic) → 中级 (intermediate) → 高级 (advanced) → 精英 (elite) — and a soldier
is always stored as `{ type, tier, count }`, so a promotion never changes its family, only its tier.
每个家族都有四个档位：初级 → 中级 → 高级 → 精英；士兵始终以 `{ type, tier, count }` 存储，所以升级只改档位，不改家族。

```
民兵 Militia (T1) ─┬─ 长枪兵 Spearman ── 中级 ── 高级 ── 精英
                   ├─ 弓箭手 Archer   ── 中级 ── 高级 ── 精英
                   └─ 骑兵 Cavalry    ── 中级 ── 高级 ── 精英
```

Rank multiplies statistics, price and wage: **攻击 / 防御 / 生命 ×1 / 1.3 / 1.65 / 2.05**,
**兵价 ×1 / 1.9 / 3.1 / 4.7**, **日薪 ×1 / 1.5 / 2 / 2.5**, and 弓箭手射程每档 +10%（150 → 165 → 180 → 195）。
档位会成倍放大属性、兵价与日薪：**攻击 / 防御 / 生命 ×1 / 1.3 / 1.65 / 2.05**、**兵价 ×1 / 1.9 / 3.1 / 4.7**、**日薪 ×1 / 1.5 / 2 / 2.5**，弓箭手射程每档 +10%（150 → 165 → 180 → 195）。

Upgrading costs `max(8, round((to.recruitCost − from.recruitCost) × 0.7))` gold per soldier. Climbing the ladder
rank by rank is always cheaper than buying the elite rank straight from a town, so militia are worth raising.
每名士兵的升级费用为 `max(8, round((目标兵种招募价 − 当前兵种招募价) × 0.7))` 金币。逐级升级总是比直接在城镇买精英便宜，所以民兵值得养。

The full ladder, per-rank statistics and per-rank upgrade prices are drawn as a **兵种升级图 · unit upgrade
diagram** in the in-game guide, generated straight from `src/game/units.js`.
完整的升级路线、各档属性与逐档升级价，都以 **兵种升级图** 的形式画在游戏介绍里，数据直接由 `src/game/units.js` 生成。

### 4.5 考试 · Exams

Only towns host exams, and only correct answers pay out — a wrong answer pays nothing.
只有城镇能参加考试，且只有答对才有钱——答错不发放任何奖励。

You pick a grade (三年级 / 四年级), one or more subjects, and a paper length of **5, 8 or 12** questions.
你可以选择年级（三年级 / 四年级）、一个或多个科目，以及 **5 / 8 / 12** 道题的题量。

An exam is scored `通过 / 结束` by `correct ≥ ceil(questions / 2)`, but the gold is paid per correct answer as
you go, so a failed paper still pays for what you got right.
考试以「答对 ≥ ceil(题数 / 2)」判定「通过 / 结束」，但金币是按答对逐题结算的，所以即使没通过，答对的题也照样给钱。

#### 难度 · Difficulty

The difficulty never changes the questions: all three levels ask exactly the same paper. It changes three things —
what a correct answer pays, what the army costs and how strong the factions are. It is picked on the home screen
before a new campaign and can be changed at any time from the 🎚 chip on the world map; the setting belongs to the
lord and is saved with the campaign, while the chip also shows the current threat.
难度不改题目：三档考的是同一张卷子，只改三件事——答对值多少钱、养兵花多少钱、敌人有多强。开新局前在首页选择，
游戏过程中也能随时用世界地图的 🎚 芯片修改；难度属于领主本人，会随存档保存，芯片上还会显示当前威胁。

| 难度 Difficulty | 每题金币 Gold per answer | 开局 Start | 军粮 / 战 Food a battle | 招募价 Recruit price | 敌军 Enemies |
| --- | --- | --- | --- | --- | --- |
| 🟢 简单 Easy | **5**（整卷封顶 ×2） | 150 金 / 8 粮 | 2 | ×0.90 | ×0.90 |
| 🟡 普通 Normal | 三年级 19 / 四年级 25 | 120 金 / 5 粮 | 3 | ×1.00 | ×1.00 |
| 🔴 困难 Hard | 三年级 14 / 四年级 19 | 90 金 / 3 粮 | 4 | ×1.15 | ×1.10 |

The **easy** level is the practice level: every correct answer pays a flat **5 gold**, whatever the subject and
the grade are, and one paper can never pay more than **twice the price of its questions**, so it cannot be farmed
into a big army. Its start is the most generous and its factions are the weakest.
**简单**是练习档：每答对一题固定 **5 个金币**，不分科目也不分年级，而且一张卷子的收入不会超过**题目基础价的 2 倍**，
因此没法靠简单档刷钱养大军；它的开局最宽裕，敌人也最弱。

The **normal** level keeps the numbers the game shipped with: grade 3 pays 19 and grade 4 pays 25 per correct
answer, the town markup stays 15% and a battle eats three rations.
**普通**保留游戏原本的数值：三年级每题 19 金、四年级 25 金，城镇加价仍是 15%，每场战斗吃 3 份军粮。

The **hard** level takes the normal price, subtracts two gold and then cuts it by a fifth (grade 3 pays 14, grade 4
pays 19). The lord starts with 90 gold and three rations, every recruit costs 15% more, a battle eats four rations
and the factions field one tenth more soldiers and grow faster.
**困难**先按普通公式减去 2 金，再打八折（三年级 14 金、四年级 19 金）。领主只带 90 金与 3 份军粮开局，招募价贵 15%，
每场战斗吃 4 份军粮，敌军人数多十分之一、成长也更快。

The subject bonus (逻辑推理 +6、百科知识 +4) applies to normal and hard, and a reward never drops below one gold.
科目加成（逻辑推理 +6、百科知识 +4）在普通与困难两档照常叠加，而且奖励最低为 1 个金币。

##### 威胁递增 · The campaign threat

On top of the level, the world escalates inside one campaign. The threat starts at **1.00** and rises with the
battles won and the towns the lord holds, capped per level (easy 1.2, normal 1.8, hard 2.0), so a child who is
stuck is never punished:
除了档位之外，同一局战役里世界还会逐渐变强。威胁从 **1.00** 开始，随胜场与占领的城镇上升，每档有上限
（简单 1.2、普通 1.8、困难 2.0），因此卡住不前的孩子不会被系统惩罚：

```
威胁 T = 1 + 胜场 × A + 占领城镇 × B
简单 A=0.01 B=0.02 · 普通 A=0.02 B=0.04 · 困难 A=0.025 B=0.05

新刷部队人数 = 原人数 × 档位规模 × (1 + (T − 1) / 2)
敌军总上限   = (20 + 自有城镇繁荣度 × 0.6) × 档位上限 × T
普通在 T ≥ 1.25 起出现 2 级兵；困难在 T ≥ 1.5 起出现少量 3 级兵
```

The world map chip reads 「🎚 难度 · 威胁 1.36×」 and the difficulty sheet spells out the current enemy size, the
ceiling, the food cost and the recruit markup.
世界地图芯片写着「🎚 难度 · 威胁 1.36×」，难度面板会列出当前的敌军规模、上限、军粮与招募加价。

An old save without a difficulty is an easy game, and old parties keep the size they already have; only the
warbands raised after the change follow the new rules.
旧存档没有难度字段时按「简单」处理；地图上已有的部队保持原人数，只有之后新刷或增援的部队才按新规则成长。

Subjects · 科目：英文 English · 语文 Chinese · 数学 Math · 逻辑推理 Logic · 百科知识 Encyclopedia.

The subject list is not hard-coded — it is whatever the mod registry currently holds, so a new question pack appears
in the exam setup as soon as it is registered. See 「题库扩展 · Question mods」 in section 13.
科目列表不是写死的：考试设置里显示的就是题库注册表当前持有的全部科目，因此新题库包一旦注册就会立刻出现在界面上。见第 13 节「题库扩展」。

#### 语文题型 · Chinese question types
The Chinese subject carries **reading comprehension** and a wide **ancient-poem** bank on top of the usual word
work. Each type is its own template, so the memory curve tracks them separately.
语文科目除了字词基础，还包含**阅读理解**与丰富的**古诗**题库；每种题型都是独立的模板，因此记忆曲线会分别记录。

| 题型 Type | 说明 What it asks |
| --- | --- |
| 📖 阅读理解 comprehension | 12 篇短文，每篇三题：主要内容、细节与词句体会。12 short passages, three questions each: the main idea, a detail and the meaning of a word. |
| 🏮 古诗接龙 poem | 下一句接上句，覆盖 30 首小学必背古诗。The next line of a line, over 30 poems children learn by heart. |
| 🖋️ 补全诗句 poemFill | 诗句里缺一个字，补上它。Fill in the missing character of a line. |
| 🏛️ 诗题 poemTitle | 由诗句猜诗题。Which poem do these lines come from? |
| 🧑‍🏫 作者 poemAuthor | 这首诗是谁写的。Who wrote this poem? |
| 🪶 上一句 poemPrev | 上一句是什么。Which line comes before this one? |
| 💭 诗意 poemMeaning | 这首诗表达了什么。What does the poem express? |
| 🔗 诗句配对 poemMatch | **配对题**：把四个诗句和它们的诗题连起来。A matching question: four lines and their poems. |
| 📅 节气排序 solarTerms | **排序题**：把四个二十四节气按一年中的顺序排好。An ordering question: four solar terms in the order of the year. |

Every poem question carries an explanation, so a wrong answer teaches the title, the poet and the dynasty.
每道古诗题都带解析，答错时会告诉孩子诗题、作者与朝代。

#### 答题形式 · The shapes of a question

A question is not always four buttons. The contract carries the shape of the question, and the exam renders
whatever shape it finds — so a new kind of question needs no new screen.
题目不总是四个按钮。题目数据里带着它的「形状」，考试界面按形状渲染，因此新增一种题型不需要新界面。

| 形状 Shape | 数据 Data | 玩法 How it is answered |
| --- | --- | --- |
| 四选一 Multiple choice | `options` + `answer`（下标） | 点一个选项就作答。Tap an option to answer. |
| 填空 Filled in | `input: 'number' \| 'text'` + `answer` | 把答案写出来再确认；数字按数值比对，文字忽略大小写与空格。Type the answer; a number is compared by value, a word without its case or spaces. |
| 配对 Matching | `pairs`（左右两栏） | 先点左边一项，再点右边配对的那一项；可以重来。Pick a left item, then its partner on the right. |
| 排序 Ordering | `items`（正确顺序） | 按顺序点出每一项，可以撤销，最后确认。Tap the items in the right order, undo if you like. |

The new kinds in the built-in banks: 数学 `mul-input` 与 `fraction-input`（算式填空）、英文 `spelling-input`（拼写填空）、
语文 `poemMatch` 与 `solarTerms`、逻辑 `trueFalse`（判断对错）。
内置题库新增的题型：数学的算式填空、英语的拼写填空、语文的诗句配对与节气排序、逻辑的判断对错。

A filled-in answer cannot be guessed from the options, a matching question trains the recall of a whole set and an
ordering question trains the order of a sequence — three different ways to remember the same thing.
填空题没有选项可以蒙，配对题练的是整组回忆，排序题练的是顺序关系 —— 同一份知识有三种记法。

#### 记忆曲线 · Memory curve

A paper is not a flat random draw. Every question carries a memory level from **0** (unfamiliar) to **5**
(mastered), and each candidate is weighted by that level before the draw.
出卷不是等概率随机抽取。每道题都带一个 **0**（生疏）到 **5**（熟练）的记忆等级，抽取前先按等级换算成权重。

| 记忆等级 Level | 0 | 1 | 2 | 3 | 4 | 5 |
| --- | --- | --- | --- | --- | --- | --- |
| 抽中权重 Weight | 1.00 | 0.55 | 0.30 | 0.17 | 0.09 | 0.05 |

- A correct answer raises the level by **1**; a wrong answer lowers it by **2**, so a question that slips becomes up
  to about four times as likely to come back.
  答对等级 **+1**，答错等级 **−2**，所以一时答错的题会立刻变得最多约四倍更容易再出现。
- **20 hours** without seeing a question costs one level, at most two levels per pass — the forgetting curve applied
  across sessions, not only inside one paper.
  一道题 **20 小时**没见到就掉一级，每次最多掉两级——这把遗忘曲线应用到了跨场次，而不只是单张试卷内。
- Weights never reach zero, so a mastered question still resurfaces for revision.
  权重永远不会归零，因此熟练题仍会偶尔出现用于复习。
- Declarative questions are tracked one by one (`<mod>:<itemId>`); generated templates are tracked per template
  (`<mod>#<kind>`), so a maths template cannot be memorised through its numbers.
  声明式题目逐题记录（`<mod>:<itemId>`），程序生成的题按模板记录（`<mod>#<kind>`），因此数学题不会靠记住数字就算「掌握」。
- The exam setup shows how many questions have been recorded and how many are mastered.
  考试设置页会显示已记录多少题、其中多少题已掌握。

#### 考试结算 · The settlement of a paper

`rewardFor()` prices a single correct answer; the **settlement** of the whole paper decides what it is really
worth. A wrong answer never costs anything: it simply pays nothing and breaks the streak.
`rewardFor()` 给一道答对的题定价；整张卷子的**结算**决定它到底值多少。答错从不扣钱：只是这一题没有金币，连击会断。

| 加成 Bonus | 数值 Value | 说明 Note |
| --- | --- | --- |
| 🔥 连击 Streak | ×1.0 → ×1.5 | 连续答对越多倍率越高（每连对 +10%，最多 5 步）。The longer the run, the more it pays. |
| 🌟 全对 Perfect | ×1.5 | 整张卷子一题不差。Not a single mistake. |
| 📜 长卷 Long paper | ×1.1 | 一次做 12 题。A paper of twelve questions. |
| 🎯 及格 Pass | +20% | 答对题数达到一半。Half of the paper is right. |
| 🙋 答错 Wrong | 0 | 不扣钱，只是这一题没有金币、连击归零。Nothing is deducted. |

#### 做题得到的道具 · The gear a paper drops

Answering questions now yields gear, not only money.
做题现在不只换钱，也换道具。

| 来源 Source | 掉落 Drop |
| --- | --- |
| 每答对一题 Correct answer | 30% 掉 🌾 军粮 ×1 |
| 连对 5 题 Five in a row | 必掉 🌾 军粮 ×2 |
| 某一科全对 A subject perfected | 数学 → 🌾 ×2；语文 / 百科 → 🎟️ 集市券 ×1；逻辑 → 📜 征兵令 ×1（免费招 2 名民兵） |
| 整卷全对 A perfect paper | 🐎 战马 ×1 |

The **market voucher** pays for one purchase without gold, and the **recruit order** hires two militia for free.
**集市券**可以免费换一次物资，**征兵令**可以免费招 2 名民兵。

#### 里程碑道具 · Milestone gear

The lifetime count of correct answers unlocks permanent gear.
累计答对的题数会解锁永久道具。

| 答对题数 Correct answers | 道具 Gear | 效果 Effect |
| --- | --- | --- |
| 300 | 🚩 军旗 War banner | 全军攻击 +5% |
| 500 | 🏅 徽章 Badge | 每场战斗后 +10 金币 |
| 800 | 💊 药箱 Medicine chest | 伤兵恢复 +50% |
| 1200 | 🐎 驿马 Post horse | 主角移动速度 +10% |

#### 掌握度地图与复习卷 · The mastery map and the revision papers

The exam setup carries a **mastery map**: one bar per subject with the number of mastered questions and how many
are due for a revision. Two revision papers build on it.
考试设置页有一张**掌握度地图**：每一科一条进度条，写着已掌握多少题、还有多少题该复习。基于它有两种复习卷。

| 试卷 Paper | 内容 Content |
| --- | --- |
| 📖 标准考试 Standard | 按年级、科目与题量出的一张普通卷子。An ordinary paper. |
| 🔁 只考错题 Mistakes | 只出答错过的题，答对一次就把它从错题本里划掉。Only the questions that were answered wrongly. |
| ⏰ 复习队列 Review | 只出很久没复习、还没掌握的题。The questions that are due. |

#### 考试就是经验 · An exam is experience

A paper that reaches the pass line teaches: every correct answer is **one experience point**, and **50 points**
buy one attribute point, which the child spends himself.
及格的卷子会教东西：每答对一题 **1 点经验**，**50 点**换 1 点属性点，由孩子自己分配。

| 属性 Attribute | 每点效果 Per point | 说明 Note |
| --- | --- | --- |
| 👑 统御 Leadership | 队伍上限 +2、全军攻击 +1% | 带得动更大的队伍。 |
| 🩺 医术 Surgery | 伤兵恢复 +10% | 伤兵回来得更快。 |
| ⚙️ 工程 Engineering | 围城准备 −0.5 天、设施造价 −5% | 围城更快，城镇更便宜。 |
| 🧠 谋略 Tactics | 全军攻击 +5%、战前显示敌方构成 | 开打前就看清对面是什么兵。 |

The points are spent in the **👤 角色详情** panel, which also shows the experience bar, the mastery map and the
milestone progress.
属性点在**👤 角色详情**面板里分配，面板里还有经验条、掌握度地图与里程碑进度。

### 4.6 战斗 · Battle

A hostile party that reaches within **1.3 tiles** of the player stops the world and starts a **meeting**, not a
battle. The meeting card shows the enemy leader, his warband and the two armies' sizes; only 「⚔️ 开战」 enters the
arena, while 「🏃 逃跑」 and 「🗣️ 喊话」 let the child walk away or talk back. The whole flow is described in 4.18.
当敌对部队进入到玩家 **1.3 格**范围内时，世界会停下并进入一场**遭遇对话**，而不是直接开战。遭遇卡片会显示敌将、他的队伍与双方兵力对比；只有点「⚔️ 开战」才进入战场，「🏃 逃跑」与「🗣️ 喊话」让孩子可以直接走开或回话。完整流程见 4.18。

The arena is a **1400 × 960** field (about twice the ground of the old 1000 × 680 map, with 35 × 24 terrain
cells), and the two armies start **784 px** apart, so there is room and time to form up before the lines meet.
Every troop group you bring — one family at one rank — is an independent **squad** with its own order, formation
and density, so you can send the spearmen forward, hold the archers back and scatter the cavalry, all in the same
fight.
战场是一片 **1400 × 960** 的场地（面积约为旧 1000 × 680 地图的两倍，35 × 24 个地形格），两军相距 **784 px**，因此接战之前既有地方也有时间排兵布阵。你带来的每个兵种档位（同一个家族 + 同一个档位）都是一支独立的**小队**，各自拥有命令、队形与密度，因此可以同时做到：长枪兵压上、弓箭手原地待命、骑兵散开包抄。

#### 开局对峙与下令 · The opening standoff

A fight does **not** start with both lines running at each other. When the arena opens, every squad on both sides
holds its ground: the lord reads the field first, and the enemy spends the opening seconds dressing its ranks. After
about **5 seconds** the enemy changes formation — ranged squads spread into a firing line, melee squads tighten into a
wedge — and about **2.4 seconds** later it attacks. A lord who attacks first (or lands the first blow) cuts that wait
short: the enemy answers within a second.
战斗**不是**从两排人对着冲开始的。战场刚打开时，双方每一支小队都原地驻守：主角先看清战场，敌军用开局这几秒整理队形。大约 **5 秒**后敌军变阵（远程换成一线射阵、近战收成楔形），再过约 **2.4 秒**才发起进攻。如果主角先下令攻击（或者先打中敌人），这段等待会立刻缩短：敌军在一秒内就会应战。

| 阶段 Phase | 发生什么 What happens |
| --- | --- |
| ⏳ 对峙 Standoff | 双方都按兵不动，底部提示「敌军 N 秒后进攻」，并给出「⚔️ 全军出击」。Both sides hold, the command bar counts the seconds down and offers 「⚔️ 全军出击」. |
| 🚩 变阵 Dressing | 敌军换阵型，几秒后冲锋。The enemy changes formation and charges a moment later. |
| ⚔️ 交战 Contact | 谁先动手都一样：剩下的就是阵型、克制与命令的较量。Whoever moved first no longer matters: formations, counters and orders decide it. |

The lord's orders are what start his own advance: pick a squad chip and give ⚔️ 攻击 / 🏇 跟随 / 🎯 移动, or press
「⚔️ 全军出击」 to send every squad at once. A squad told to hold still fights back on its own — a defending squad
strikes anything that comes within reach, and a ranged squad shoots from where it stands.
主角自己的推进由命令决定：先点小队按钮，再下 ⚔️ 攻击 / 🏇 跟随 / 🎯 移动，或者直接按「⚔️ 全军出击」让所有部队一起出动。奉命驻守的小队也会自己还手 —— 防守中的士兵会打任何进入攻击范围的敌人，远程单位则站在原地射击。

A squad that loses soldiers closes its ranks: the survivors take the front slots, so a thinned squad keeps facing the
foe instead of standing in the gaps left by the fallen. That is also what keeps a long fight from stalling with one
soldier on each side just out of reach.
小队减员后会收拢队形：幸存者补上前排的位置，因此人少了也仍然面朝敌人，而不是站在阵亡者留下的空位里。这也是长时间的战斗不会停在「双方各剩一人、刚好都够不着」的原因。

#### 战场地形 · Battlefield terrain

The field is not a flat lawn: it is divided into cells, and every cell carries a piece of terrain that changes how
a soldier fights there. **Every battle is fought on a newly drawn field**: the river's course, the spot and size of
the lake and the mountain and the patches of forest and sand all come from a fresh battle seed, so no two fights
share a map. The same seed still rebuilds the same field, which is what a replay needs.
战场不是一块平地：它被分成若干格子，每格有一种地形，会改变站在那里的士兵的战斗表现。**每一场战斗都会重新生成一张地图**：河流的走向、湖泊与山地的大小和位置、森林与沙地都来自一个新的战斗种子，因此没有两场仗共用一张地图；同一个种子仍然会生成同一张地图，重放战斗时需要的正是这一点。

| 地形 Terrain | 效果 Effect |
| --- | --- |
| 🌳 森林 Forest | 树木掩体：防御 +15%，移动 −20%。Cover: defence +15%, movement −20%. |
| 🏜️ 沙地 Desert | 体力消耗：攻击 −10%，移动 −10%。The heat tires the troops: attack −10%, movement −10%. |
| 🌊 河流 River | 涉水而行：移动 −30%，防御 −5%。Wading is slow: movement −30%, defence −5%. |
| 💧 湖泊 Lake | 深水：无法通行，士兵会绕着走。Deep water: impassable, the soldiers walk around it. |
| ⛰️ 山地 Mountain | 居高临下：攻击 +10%，防御 −10%。The high ground: attack +10%, defence −10%. |

The ground under the fighters is read in `strike()`: the attacker's cell adds to its attack and the defender's
cell adds to its defence, so a fight that happens in a forest is a different fight from one on the plain.
攻击者脚下的格子会加攻击，防守者脚下的格子会加防御，因此森林里的一场和平原上的一场是两场不同的仗。

The lake is the only impassable ground. It is always placed inside the field and clear of the two deployment bands,
so it can never cut the field in two or drop a soldier into deep water. When the direct line to a slot or
to the enemy crosses water, the soldier follows a smoothed A* route around the shore; the whole squad also takes a
group route, so the formation walks around the lake together instead of each soldier picking a different way.
Melee blows cannot cross deep water, so two soldiers on opposite shores cannot hit each other through the lake.
湖泊是唯一不可通行的地面。它总是落在战场内部、避开两侧的列阵区，因此不会把战场分成两半，也不会让士兵一开始就站在深水里。当通往队形位置或敌人的直线穿过水面时，士兵会沿着
平滑后的 A* 路线绕岸而行；整支小队还会走一条集体路线，因此队形是一起绕过湖泊，而不是每个士兵各走各的。
近战攻击也不能越过深水，因此站在湖两岸的两名士兵不会隔着湖互相砍中。

#### 战斗速度 · Battle speed

The ⚙ button in the corner of the battle screen opens the battle tools: the **speed** and the **terrain legend**.
The speed is **slow by default**, so a child can read the field and give orders before the next clash happens.
战斗界面角落的 ⚙ 按钮打开「战斗工具」面板：里面是**速度**与**地形说明**。速度**默认是慢速**，这样孩子来得及看清战场、赶在下一次交手前下达命令。

| 速度 Speed | 倍率 Multiplier | 说明 Note |
| --- | --- | --- |
| 🐢 慢速 Slow | ×0.6 | 默认。战斗慢半拍，方便看清每一个动作。The default: the fight crawls, so every move can be read. |
| 🚶 正常 Normal | ×1 | 游戏原本的速度。The speed the game always had. |
| 🐇 快速 Fast | ×1.8 | 战局推进很快，适合熟练之后。For a player who knows the ropes. |

#### 战场动画 · Battle animations

Every soldier is drawn with small movements, so the fight reads at a glance: a walking soldier hops and kicks up
dust, a standing one breathes, a hit flashes white with a red ring and a shake, a strike leans into the blow and a
badly wounded soldier keeps a slow red pulse at its feet. A fallen soldier tips over, drops and fades out over
nine tenths of a second instead of blinking away; a training dummy does the same and then stands back up.
每名士兵都带着细小的动作绘制，战斗因此一眼就能看懂：行军的士兵会一颠一颠地跳、脚下扬起尘土，站定的士兵会呼吸，挨打时白光一闪、红圈扩散并左右晃动，出手时身体向目标倾一下，重伤的士兵脚边一直有缓慢的红色脉冲。倒下的士兵会向侧面倒下、下沉并在 0.9 秒里淡出，而不是瞬间消失；练兵木桩也一样倒下，然后再站起来。

These are **render-only** effects: `src/game/battleAnim.js` turns speed, `hitFlash`, `swing` and elapsed time into
the hop, shake, lunge and fall, and `BattleMap.vue` draws them. The fight's numbers and outcome are untouched, and
smooth fractional placement keeps a walking soldier gliding instead of stepping a whole pixel at a time.
这些**只影响绘制**：`src/game/battleAnim.js` 把速度、`hitFlash`、`swing` 与经过的时间换算成跳动、晃动、前倾与倒下，再由 `BattleMap.vue` 画出来。战斗的数值与胜负完全不变；小数坐标让行军的士兵平滑滑动，而不是一次跳一整个像素。

#### 大战场性能 · Big-battle performance

A 400 v 400 quick battle — 800 soldiers on the field — holds a steady 60 frames in desktop Chrome (p50 16.7 ms,
p95 16.8 ms), with the frame-rate chip and the troop counts still updating; before the change the same scene ran at
8 FPS. Three things made the difference. Finding a foe no longer scans the whole field: the nearest enemy is looked
up ring by ring in a coarse 90 px grid rebuilt every 0.12 s, and every soldier keeps its target for 0.18 s with the
refreshes staggered, so one search compares a dozen soldiers instead of all 800. Line of sight is only checked once
the foe is already within reach, and the push between neighbours compares squared distances. The field itself is no
longer reactive data: the simulation and the painter read the raw battle, while a counter that moves ten times a
second drives the command bar.
400 v 400 的快速战斗（场上 800 名士兵）在桌面 Chrome 里稳定 60 帧（p50 16.7 ms、p95 16.8 ms），帧率芯片与双方兵力照常刷新；改动前同一场景只有 8 帧。三处改动解决了问题。找敌人不再扫描全场：最近的敌人改在 90 px 的粗网格里按圈搜索（网格每 0.12 秒重建），每名士兵把目标记住 0.18 秒并按士兵错开刷新，因此一次搜索只比较十几个人而不是全部 800 人。视线检查只在敌人已经进入攻击距离时才做，士兵之间的推挤改用平方距离比较。战场本身也不再是响应式数据：模拟与绘制直接读原始数据，命令栏由一个每秒更新十次的计数器驱动。

The measured numbers come from `tools/verify-perf-browser.mjs`, which runs the real browser check after the armies
have met, so the standoff is not mistaken for the load. The same guard fails the suite when a change drops the big
battle below 30 frames.
上面的数字来自 `tools/verify-perf-browser.mjs`：它等两军接战之后才开始采样，避免把开局对峙当成负载；以后若有改动让大战场跌破 30 帧，这套检查会直接失败。

#### 镜头 · Camera

The camera zooms with the armies: when they are far apart the whole field is seen from a distance, and when they
meet it zooms in. On a phone the zoom floor is lower (**0.42** instead of 0.7), so at the opening both armies fit on
a 390 px-wide screen instead of the camera sitting on the empty ground between them. The field pans with the left
mouse button or a finger, which stops the auto-follow, and the 🎯 button brings the camera back to the fighting. A
drag may go **140 px past the edge** of the field — on all four sides — so the surrounding ground shows and a
soldier standing at the border is not pinned to the screen edge; the camera rests there until 🎯 is tapped. A move
counts as a drag only after 4 px, so a tap still moves the commander; a second finger cannot throw the camera, and
a drag never plants a rally flag.
镜头会随两军距离缩放：双方拉开时看全景，交手后自动拉近。手机上缩放下限更低（**0.42**，桌面为 0.7），因此开局在 390 px 宽的手机屏上两支军队都能入镜，而不是把镜头停在双方之间的空地上。用鼠标左键或手指拖动战场可以自由查看，并会停止自动跟随；点 🎯 按钮让镜头重新回到战斗。镜头可以拖出战场边缘 **140 px**（四个方向都可以），看到周围的空地，站在最边上的士兵不再被钉在屏幕边上；松手后镜头停在缓冲位置，点 🎯 才回到战斗。移动超过 4 px 才算拖动，因此轻点仍然是移动指挥官；多出来的手指不会把镜头甩走，拖动也不会误插旗。

Tap a squad chip at the bottom (or 全军 for all of them), then give the order:
点底部的小队按钮选择部队（或选「全军」），然后下达命令：

| 命令 Order | 行为 Behaviour | 数值 Modifier |
| --- | --- | --- |
| ⚔️ 攻击 Attack | 全军压向最近的敌人，**保持队形**推进，远程单位贴近时整队后撤；退路被墙或湖挡住时沿墙滑开、必要时绕过敌人侧翼，不会钻进角落对射。Charge the nearest enemy **without breaking the formation**; ranged squads step back as one block, slide along a wall or lake that blocks the way back and round the enemy's flank when they must, instead of backing into a corner to trade shots. | 攻击 ×1.08，防御 ×0.94 |
| 🛡️ 防守 Defend | 原地结阵，守住当前位置，远程单位站着对射。Hold the current spot and trade blows. | 攻击 ×0.96，防御 ×1.25 |
| 🏇 跟随 Follow | 贴身跟随指挥官移动，沿途交战。Escort the commander and engage whatever is close. | 攻击 ×1，防御 ×1.05 |
| 🎯 移动 Move | 整队走到点击处后原地待命。March to the tapped point and wait there. | 攻击 ×0.94，防御 ×1 |

Each squad also has a **formation** and a **density**, changed from the folded 「▦ 队形」 panel and applied
immediately. Formations decide how the soldiers of a squad are laid out; densities decide how tightly packed they are.
每支小队还有**队形**与**密度**，在收起的「▦ 队形」面板里切换，改动立即生效。队形决定这一小队怎么排，密度决定人和人之间的间隔。

#### 反击与队形 · Counterattack and formation

Two rules make the fight read like a battle of armies rather than a crowd:

- **Everyone answers an attack.** A soldier that is hit remembers who hit it and turns to answer that one, even
  when it was holding its position or walking somewhere else. Only the front of the line can reach a foe with a
  spear, but every soldier shoots back the moment it is in reach.
  **被打了就会还手。** 士兵会记住是谁打了它，转身去还手 —— 哪怕它本来在防守或者在赶路。拿长枪的只有前排能
  碰到敌人，但每个士兵只要够得着就会回击。
- **An attack keeps the formation.** The squad turns so that its front rank faces the foe, its anchor goes onto the
  enemy and every soldier holds its own slot around it. The ranks do not mob the enemy, and a ranged squad that is
  too close steps back as one block instead of every soldier running on its own.
  **攻击不乱队形。** 小队会转向敌人，前排压上去，每个士兵守住自己那个位置；队列不会一拥而上，远程小队嫌近了
  也是整队一起后撤，不是各自乱跑。
- **A corner does not end the kiting.** Backing straight away from the enemy would put a skirmisher's back to the
  wall, so the retreat first measures how much open ground each way leads into (up to 150 px, stopping at the wall
  or deep water), how far it keeps from the foe and how fast the ground is. A squad with the edge behind it slides
  along the wall, and if the only open way is round the enemy's flank it takes that way. The direction it chose last
  frame carries a little weight, so a squad in a corner does not dither between two equally open walls.
  **墙角不是风筝的终点。** 直线后退会把远程士兵的背贴到墙上，因此后撤前会先量每个方向还有多少空地（最远
  150 px，撞墙或深水即止）、离敌人能拉开多远、脚下地皮跑得多快。背后是边缘时就贴着墙滑开，只有绕过敌人
  侧翼才有空地时就走那一边。上一帧选的方向也有少量权重，因此角落里的队伍不会在两堵同样空旷的墙之间来回犹豫。

| 队形 Formation | 效果 Effect |
| --- | --- |
| ▦ 方队 Square | 排成方块。Block. 防御 +6% |
| ▬ 一行 Single rank | 横排一线，正面最宽。Widest front. 攻击 +6% |
| ▤ 两行 Two ranks | 两排纵深。Two deep. 防御 +3% |
| ▥ 三行 Three ranks | 三排厚阵。Three deep. 防御 +8%，移动 −5% |
| ▲ 尖形 Wedge | 楔形突击。Shock wedge. 攻击 +12%，防御 −5% |
| ⁘ 随机 Scatter | 散兵散布，没有加成；**每个士兵自己扑向敌人**，最难被围住。Scattered, no bonuses; **every soldier closes on the foe on its own**, hardest to surround. |

| 密度 Density | 效果 Effect |
| --- | --- |
| ⋯ 松散 Loose | 间隔 38，远程受伤 −22%，防御 −6%，移动 +6% |
| ≡ 紧凑 Tight | 间隔 22，防御 +14%，移动 −8% |

Tapping the battlefield normally moves your commander marker; when the selected squad is on 移动, the same tap
plants its yellow rally flag instead.
点击战场通常是移动指挥官标记；当选中的小队处于「移动」时，同一次点击会改为插下它的黄色目标十字。

#### 冲锋、疲劳与齐射减速 · Charge, fatigue and the volley slow

A melee soldier whose foe is more than **90 px** away breaks into a sprint (**+30% speed**). The sprint is latched:
once it starts it carries the soldier through the last stretch to contact instead of dying out a few pixels short.
It burns **2.5 s** of stamina; when the stamina is gone the soldier is winded for **2.5 s** at **−10% speed**, then
recovers and can charge again. A soldier whose target is a ranged unit leaves its formation slot inside 90 px and
closes on it directly, so a squad can no longer hold its front rank just outside spear reach.
近战士兵的目标超过 **90 px** 时会冲刺（**+30% 速度**）。冲刺是「锁住」的：一旦开始就会一直持续到接战，而不是在差几像素时断掉。它消耗 **2.5 秒**体力；体力耗尽后疲劳 **2.5 秒**（**−10% 速度**），喘匀后可以再次冲锋。目标为远程兵的士兵在 90 px 内会离开阵位直接扑上去，因此小队的前排不会再被阵型槽位挡在长枪够不到的地方。

An archer is slowed after every arrow (**0.9 s at 0.72 speed**), cannot draw its bow at under **32 px**, and can
only back away at **0.85 times** its speed while a foe is in its face. Kiting a melee squad therefore gets harder
the longer it goes on, which is what makes being caught dangerous; a large melee push can drag an archer line into
hand-to-hand, while a small archer party can still keep its distance and shoot it to pieces.
弓箭手每射出一箭都会短暂降速（**0.9 秒 × 0.72 速度**），距离小于 **32 px** 时无法开弓，被贴住时只能以 **0.85 倍**速度后撤。因此连续风筝越久越难，被咬住才真正危险；大规模近战能把弓箭手阵线拖进肉搏，而小股弓箭手仍然能保持距离把人射散。

Damage is `max(1, round(atk × 攻击加成 × 克制系数 × 脚下地形攻击 × 目标防御 × 脚下地形防御 × 0.5 + 随机值))`; melee units swing every 1.0 s and
ranged units fire a projectile every 1.6 s. Melee units engage inside 26 px; archers shoot at 150 px and every rank
beyond 初级 adds 10%.
伤害为 `max(1, round(攻击 × 攻击加成 × 克制系数 × 脚下地形攻击 × 目标防御 × 脚下地形防御 × 0.5 + 随机值))`；近战单位每 1.0 秒攻击一次，远程单位每 1.6 秒射出一支箭。近战单位在 26 px 内接战；弓箭手射程 150 px，每升一档 +10%。

The three families form a rock-paper-scissors cycle — **长枪兵克制骑兵、骑兵克制弓箭手、弓箭手克制长枪兵** —
worth **+40% attack when countering and −25% when countered**. The charge and the volley slow do not remove that
cycle: equal archers still beat equal spearmen on a small field (5 v 5 and 8 v 8 lose four times out of five), and
a 20 v 20 spear push only wins by surviving the arrows and finishing with seven to eleven men. Militia still lose to
equal archers, while cavalry still ride archers down in six or seven seconds.
三个主力兵种形成循环克制 —— **长枪兵克制骑兵、骑兵克制弓箭手、弓箭手克制长枪兵** —— **克制方攻击 +40%，被克制方 −25%**。冲锋与齐射减速并没有取消这个循环：同数量的弓箭手在小规模下仍然压制长矛兵（5 v 5 与 8 v 8 里长矛兵五局只赢一局），20 v 20 的长矛兵要撑过箭雨、最后只剩七到十一人才险胜；民兵仍打不过同数量弓箭手，而骑兵依旧能在六七秒内冲垮弓箭手。

**After the battle, your warband is exactly the soldiers who survived it.**
**战斗结束后，你的队伍就是战场上真正的幸存者。**

If every soldier falls, the warband is empty; there is no free replacement troop.
如果全军覆没，队伍就真的是空的，不会凭空补兵。

#### 主将与亲兵 · The generals and their bodyguard

Both sides now bring a **general**: you bring the lord (👑, drawn with the lord sprite) and the enemy brings the
commander of its faction (🗡, drawn with the faction's own commander art — the grey bandit, the purple wolf or the
amber eagle). A general is **not** a squad: he has his own hit points (**120**), he stands outside the formation
system, and he swings at anything that comes within reach of his arm without anyone giving him an order.
双方现在都会带来一位**主将**：你带来领主（👑，用领主的立绘），敌人带来所属势力的大将（🗡，用该势力的将领立绘——
灰袍强盗、紫色苍狼或琥珀赤鹰）。主将**不是**小队：他有自己的一条生命值（**120**），不参与队形系统，
也不需要任何命令 —— 谁走进他的攻击范围，他就自己挥刀。

| 项目 Item | 规则 Rule |
| --- | --- |
| 生命值 Hit points | 双方主将各 **120** 点，两条血条显示在战场顶部的双方兵力下面。Both generals carry **120** points, shown as two bars under the army counts at the top of the field. |
| 亲兵 Bodyguard | 开战前每方从自己的**近战**士兵里抽出 **4 名**围住主将（最多抽走一半，至少留下一个小队）。亲兵没死光之前，主将**一下都挨不到**：所有飞向他的刀剑都由亲兵接下。Before the fight each side pulls **4 melee soldiers** out of its own warband to stand around its general (at most half the army, always leaving one squad). Until every guard is dead the general **cannot be hit at all** — every blow and arrow meant for him lands on a guard. |
| 亲自出手 Swinging | 主将走到敌人身边会自动出手（每 **1.1 秒**一下，基础攻击 16 / 14）。A general strikes whatever is in reach every **1.1 seconds** (16 attack for the lord, 14 for the hostile one). |
| 敌方主将 The hostile general | 他跟着自己军队的后方走，不会一个人冲进你的阵列。He walks behind his own line instead of charging your army alone. |
| 把敌将打倒 Beating him | 敌方主将生命归零＝**这场战斗立刻结束**：结算之后双方都退到世界地图上、刚刚的战场周围。他的队伍还在（只是少了阵亡的人），所以你可以**马上追上去再打一场**，也可以带队伍走开（标记在 `generalDowns` 里）。**战斗要赢，仍然得把敌人士兵全部消灭。** A hostile general at zero hit points **ends the battle on the spot**: once it is settled both sides fall back onto the world map around the field they just fought over. His warband survives (minus the fallen), so you may **go after him again at once** or walk away (the fall is counted in `generalDowns`). **A battle is still only won once every enemy soldier is gone.** |
| 士兵打光 Last stand | 一方士兵全部倒下、主将还站着时，战斗**不会立刻结束**：主将独自撑 **8 秒**（攻击 ×1.3、出手间隔 ×0.75），撑完就退场 —— 你退场＝判负（不再扣第二批士兵），敌将退场＝你赢。**你只剩主将时面板上会出现「🏳 撤退」**，不用等那 8 秒。When a side has no soldiers left but its general still stands, the battle **does not end at once**: the general holds out for **8 seconds** on his own (attack ×1.3, a swing every 0.75 of the usual gap) and then leaves the field — your general leaving is a defeat (nothing else is taken from you), theirs leaving is a win. **While you are the last man standing a「🏳 撤退」button appears**, so you need not wait out those 8 seconds. |
| 你倒下 You going down | 领主生命归零＝**这场战斗立刻失败**，结算后回到世界地图、落在战场周围，见下面的「倒下之后」。The lord at zero hit points means **the battle is lost on the spot**; it is settled and he is put back on the world map around the field — see「倒下之后」below. |

The bars at the top of the battle screen show it at a glance: 👑 is your own health, 🗡 is the enemy general's, and
the 🛡 number after each bar is how many bodyguards still stand in front of that general.
战场顶部的两条血条一眼就能看清：👑 是你自己的血量，🗡 是敌将的血量，每条后面 🛡 的数字是那位主将身前还剩几名亲兵。

##### 倒下之后 · What going down means

| 谁 Who | 发生什么 What happens |
| --- | --- |
| 你 You | 战斗立刻判负并结算。接下来：**损失一半士兵**（每组只留下体力最好的那一半）、被亲兵抬回**刚刚那片战场周围**的一处空地（3–7 格，不点对点、不瞬移到别的城镇、也不会恰好落在城里）、生命值恢复到**一半**（60 点）。Land lost at once and settled. Then: **half your soldiers are scattered** (each group keeps its healthiest half), your bodyguard carries you to open ground **around the field you just fought on** (3–7 tiles away — no teleporting across the world, no town you never walked to), and your health comes back at **half** (60 points). |
| 敌人 The enemy | 他的队伍还站在原地，只是少了阵亡的士兵；他从战场离开，下一次交手会重新带兵。他的队伍在几秒后就能再次咬住你 —— **所以主角也可以逃跑**（遇敌面板上的「逃跑」）。His warband stays where it stood, minus its fallen; he leaves the field and brings a fresh bodyguard next time. That warband can be on you again within seconds — **which is why the lord may run** (the 逃跑 button on the meeting panel). |
| 士兵全灭 The warband is wiped out | 最后一名士兵倒下时战斗还没结束：主将独自撑 8 秒。撑不住或你按「撤退」＝判负并结算，**不会再损失第二批士兵**（只有医院的救回判定可能抬回几名 1 点血的伤兵），他带着**当前**的生命值退回战场周围，敌人几秒后就能追上来。The battle does not end when the last soldier falls: the lord holds out for 8 seconds. When those run out — or you press 撤退 — it is settled as a defeat with **no second army to lose** (only the hospital rescue roll may bring back a few one-hit-point wounded); he falls back around the field **with the health he still had**, and the enemy can follow within seconds. |
| 敌将独自撑到最后 The hostile general holds alone | 他的士兵全部倒下后同样撑 8 秒；时间一到他就只身逃走，**这场战斗算你赢**（战利品、占领结算照常），结算面板会写明「敌将只身逃走」。When his soldiers are all gone he holds for 8 seconds too; when the clock runs out he flees alone and **the battle counts as a win** (loot and captures as usual), with 「敌将只身逃走」written on the result screen. |
| 敌将倒下 The enemy general falls | 同样**立刻结算**并回到地图战场周围：你的队伍一个兵都不会少，敌方队伍也还在，追不追由你决定。The same: **settled at once** and both sides fall back around the field. Not one of your soldiers is lost, the enemy warband survives, and whether to chase it is your choice. |

The battlefield is simply the tile the lord was standing on when the fight broke out, so a defeat in a far corner
of the map leaves him in that same corner: the enemy warband is still there, the two sides are 3–7 tiles apart, and the
next few seconds decide whether this ends in a chase or in a clean getaway.
战场就是他开打时站着的那一格，所以在天涯海角战败也只是回到同一片地方：敌人的队伍还在，双方相隔 3–7 格，
接下来的几秒决定这是一场追击还是一次脱身。

After a defeat the lord's health closes **slowly over time** and only while the world is moving (marching, camping
or resting in a town): **0.5 points a second** on the road, **1.6 a second** inside any settlement, **×1.6 again in
a town of your own**, and **×(1 + 0.2 × 医院等级)** with a hospital. The wound is saved with the game, so a reload
does not heal him. The world map shows it as a ❤️ chip in the top bar (it turns warm while he is hurt) and the
👤 角色详情 panel shows the bar and the number.
战败之后，领主的生命值会**随时间慢慢恢复**，而且只在世界「动起来」的时候恢复（行军、扎营或在据点休整）：
路上每秒 **0.5** 点，任何据点里每秒 **1.6** 点，**自己的城镇再 ×1.6**，有医院再 **×(1 + 0.2 × 医院等级)**。
伤口跟着存档走，刷新页面不会自动痊愈。世界地图顶部用一个 ❤️ 芯片显示他的血量（受伤时变成暖色），
👤 角色详情 面板里有血条和具体数字。

### 4.7 物资 · Supplies

Each battle consumes **3 food**; fighting with an empty larder weakens the army's attack by 25%.
每场战斗消耗 **3 份军粮**；粮草不足时全军攻击力下降 25%。

Each horse in the baggage train adds **+1% attack** to the whole army, capped at **+10%**.
每匹随军战马为全军提供 **+1% 攻击**，最多 **+10%**。

### 4.8 角色信息面板 · Lord info panel

The world map top bar carries a tappable **👤 角色详情** chip that opens a read-only popup summarising the
current character: troops, treasury and supplies in one place.
世界地图顶部状态栏有一个可点击的 **👤 角色详情** 芯片，打开后会弹出只读的角色面板，把兵力、资金和物资集中展示。

| 区块 Block | 内容 Contents |
| --- | --- |
| 头部 Header | 领主名字、第几天、所在地形与时钟状态（停滞 / 流逝 / 扎营）。Lord name, day counter, the terrain you are standing on and the clock state (frozen / flowing / camping). |
| 主将状态 Lord health | 领主自己的血条与数字，并说明「被打到 0 点即判负、散一半兵、被抬回战场旁」的规则。The lord's own health bar and number, with the rule written out: zero hit points loses the battle, scatters half the warband and carries him back beside the field. |
| 资金与物资 Treasury and supplies | 金币、军粮、战马，并附消耗说明。Gold, food, horses and what they do. |
| 部队 Warband | 每个兵种一行：等级 T、数量、攻 / 防 / 血、该兵种日薪小计；末行汇总每日军饷支出。One row per unit type: tier, count, atk/def/hp and its daily wage subtotal, plus a total wage row. |
| 战绩 Record | 战斗胜 / 总、胜率、参加考试次数、累计答对题数。Wins / battles, win rate, exams taken and total correct answers. |

The panel reads from the player store and the world store, so it always matches what the battle and exam screens
see; it is purely informational and never changes state.
面板数据直接读自 player store 和 world store，因此与战斗、考试界面看到的数据始终一致；它只展示信息，不会改变任何状态。

### 4.9 存档 · Saving

Progress is written to `localStorage` automatically (every 6 s on the world map) and on every settlement action.
进度会自动写入 `localStorage`（在世界地图上每 6 秒一次），并在每次据点操作后保存。

Each player name gets its own save slot, so several people can share one browser.
每个玩家名字有独立的存档位，因此多个人可以共用同一个浏览器。

### 4.10 受伤与恢复 · Wounds and recovery

A soldier does not simply vanish when it goes down. In a fight a soldier that reaches **0 HP** is defeated: it
either **dies for good** or — with a little luck, and a lot more luck with a hospital — it survives as a
**wounded soldier** at 1 HP.
士兵不会在倒下时凭空消失。战斗中生命值归零的士兵算「被打败」：要么**彻底阵亡**，要么——靠一点运气，医院会大幅提高概率——以 1 点生命的**伤兵**活下来。

A soldier group is stored as `{ type, tier, count, hp }`, and `hp` holds one value per soldier, so the warband
remembers who is hurt. A wounded soldier enters the next battle with the health it still has.
士兵组以 `{ type, tier, count, hp }` 存储，`hp` 与士兵一一对应，队伍因此记得谁受了伤；伤兵带着剩余生命进入下一场战斗。

| 情况 Situation | 每点恢复 Healing per day | 说明 Notes |
| --- | --- | --- |
| 行军 / 扎营 Marching or camping | **6** | 慢，但一直在恢复。Slow, but never stops. |
| 在据点休整 Resting in a settlement | **24** | 在城镇里恢复快得多。Much faster inside a town. |
| 自己的城镇 Own town | **24 + 6 × (等级 − 1)** | 自己的城镇恢复最快，等级越高越快。Fastest in your own town, and the level counts. |
| 医院加成 Hospital | **×(1 + 0.5 × 等级)** | 每一级医院把恢复速度再乘一次。Every hospital level multiplies the rate again. |

The lord himself heals on a different clock from his soldiers, because the map runs two clocks of its own:
**0.5 points a second while marching or camping**, **1.6 inside a settlement**, **×1.6 in a town of his own** and
**×(1 + 0.2 × hospital level)** on top. See 4.6 for what a fallen lord costs.
领主自己的恢复和士兵不同步，因为地图本来就有两种时钟：**行军或扎营时每秒 0.5 点**、**据点里每秒 1.6 点**、
**自己的城镇再 ×1.6**，有医院再 **×(1 + 0.2 × 医院等级)**。主将倒下要付什么代价见 4.6。

The **战果 · battle result** screen reports the three numbers that matter: 阵亡 (dead), 受伤 (wounded) and 救回
(saved by the hospital). The **👤 角色详情** panel shows how many soldiers are hurt and the average health of
the warband.
战果界面会报告三个关键数字：阵亡、受伤与救回；**👤 角色详情** 面板会显示队伍里有多少伤兵与平均体力。

A soldier that is promoted to a higher rank comes back **at full health**: new gear, new soldier.
升档后的士兵会以**满血**归队：换了装备，就是新兵。

### 4.11 据点归属、驻军与围城 · Ownership, garrisons and sieges

Every settlement belongs to exactly one holder, and the holder decides what the lord may do with it.
每个据点都只有一个归属，归属决定主角能对它做什么。

| 归属 Owner | 城镇 Town | 村庄 Village | 说明 Notes |
| --- | --- | --- | --- |
| 无主 Neutral | 可进入，可**占领** | 可进入 | 谁都可以进；无主的城镇如果没人防守，插旗就能拿下，有人守军就要先打下来。Open to everybody; an unclaimed town nobody defends is taken by raising the flag, one that holds soldiers has to be stormed. |
| 苍狼 / 赤鹰 A kingdom | 可进入，也可**攻打** | 可进入 | 可以先进去考试与招募，也可以打下来据为己有。You may walk in and trade, or take it by force. |
| 强盗 Bandits | **永远不占城镇** | 不可进入，可攻打 | 强盗只能控制村庄。Bandits never hold a town. |
| 你的 Your own | 可进入 | 可进入 | 自己的城镇没有占领与围城按钮，只有「进入」。Your own town has no claim and no siege button — just the door. |

- The map draws an **ownership ring** in the colour of the holder around every settlement, and the troop badge
  in the corner shows the **garrison** that defends it.
  地图上每个据点都有一圈**归属光环**，颜色就是归属方的颜色；右上角的兵力角标是它的**驻军**。
- An **unclaimed town** belongs to nobody. When it holds **no soldiers** the bottom bar offers **🚩 占领** and
  the lord simply raises his flag; the town becomes his without a fight and starts over as a poor hamlet.
  When it still **holds a garrison** the button becomes **⚔️ 攻城** with the number of defenders — the flag has
  to be planted the hard way, so the garrison has to be beaten first. Winning hands the town over; losing leaves
  it to its defenders, and the lord may try again.
  **无主的城镇**谁都可以进。**没有守军**时底部是 **🚩 占领**，插旗就能拿下，城镇从零开始发展；**还有守军**时按钮变成
  **⚔️ 攻城**（并显示守军人数），必须先把守军打下来才能占领。打赢了城镇归你，打输了城镇仍归原样，可以再来一次。
- A **bandit village** cannot be entered. The bottom bar offers **⚔️ 赶走强盗** instead, which starts a fight
  against the bandits in the village. Win and the village becomes unclaimed and can be entered.
  **强盗村庄**进不去，底部按钮变成 **⚔️ 赶走强盗**，直接与村中的强盗士兵开战；打下来之后村庄变成无主，可以进入。
- A **kingdom town** can be entered without conquering it — the lord may examine and recruit there — and the
  bottom bar also offers **🏰 准备围城**: the siege needs **2 天** of preparation, and **the clock keeps
  running while you prepare** — the town uses the time too.
  **王国城镇**可以直接进去（考试、招募都行），也可以打下来：底部还有 **🏰 准备围城**，围城需要 **2 天**准备，
  而且**准备期间时间照常流逝**——城镇也会利用这段时间。
- While the siege is prepared the garrison **keeps growing** (up to four extra soldiers) and the owner
  **sends a relief warband** that marches to the town and turns on the attacker on the way.
  准备期间驻军会**继续增加**（最多多出四名），归属方还会**派出援军**奔向城镇，并在路上反击进攻者。
- When the preparation is over the button becomes **⚔️ 攻打**. The garrison fights for the town, and if the lord
  wins the town is **his**: no garrison, level 1, and a fresh start.
  准备结束后按钮变成 **⚔️ 攻打**，驻军为城镇而战；主角打下来，城镇就归他所有：驻军清空、等级回到 1、重新开始。
- A siege can always be **called off**: while it is prepared the bottom bar shows the countdown and a
  **🚫 取消围城** button, and the same button is there once the preparation is over. Calling it off stops the
  clock as well, so the world freezes again.
  围城随时可以**中断**：准备期间底部会显示倒计时和 **🚫 取消围城** 按钮，准备结束后同样有这个按钮；中断后时钟也会停下，世界重新冻结。
- A **failed assault breaks the siege**: the lord has to gather his troops and **prepare the siege again**
  before he may attack a second time.
  **攻打失败会中断围城**：主角必须重新集结部队、**重新准备围城**，才能再次发起进攻。

### 4.12 城镇发展与设施 · Town development and facilities

A captured town is a project. It develops through exams, and its level decides how good it gets.
夺下来的城镇是一项长期工程：靠考试发展，等级决定它能有多好。

```
考试 exam ──▶ 主角的钱袋 lord's purse ──▶ 注入资金 inject ──▶ 城镇金库 town funds ──▶ 设施 facilities
   │                                                                        │
   └──▶ 发展 development ──▶ 繁荣度 prosperity ──▶ 等级 level ◀────────────┘
```

- **考试 → 资金与发展.** The exam always pays the **lord personally** — even in a town he owns, so he is never
  short of money. In a town he owns, every correct answer additionally adds **+2 开发** to that town.
  **考试 → 资金与发展。** 考试收入**永远进主角的钱袋**——即使在自己的城镇里也不会缺钱；
  而在自己城镇里，每答对一题还会额外给城镇 **+2 开发**。
- **注入资金 · Inject funds.** The 「🏛️ 城镇」 panel has an **注入资金** button: it moves **100** gold from the
  lord's purse into the town treasury, which is where the money for the facilities comes from.
  **注入资金。** 「🏛️ 城镇」页签里的「注入资金」按钮会从主角钱袋里拿出 **100** 金币放进城镇金库，
  建造设施用的就是这笔钱。
- **发展 → 繁荣度.** Every day a town gains or loses prosperity: above **40** development it climbs
  (`(发展 − 40) × 0.15` per day), below 40 it slides back. A town also earns **繁荣度 × 0.15** gold a day.
  **发展 → 繁荣度。** 每天城镇的繁荣度随发展变化：高于 **40** 时按 `(发展 − 40) × 0.15` 上涨，低于 40 时下滑；
  城镇每天还有 `繁荣度 × 0.15` 的收入。
- **投入发展.** Surplus town money can also be turned into development: **60 城镇资金 → +6 开发**.
  **投入发展。** 城镇里多余的钱也可以换成发展：**60 城镇资金 → +6 开发**。
- **繁荣度 → 等级.** Prosperity reaching the next threshold promotes the town: **40 → Lv.2 小镇**,
  **70 → Lv.3 城镇**, **90 → Lv.4 大城**. The level is shown in the **top left corner of the town screen** and
  on the map name plate.
  **繁荣度 → 等级。** 繁荣度达到阈值就升级：**40 → 二级 小镇**、**70 → 三级 城镇**、**90 → 四级 大城**；
  等级显示在**城镇界面左上角**，地图上的名字牌也会带 `Lv.N`。
- A higher level means **better recruits** (the weight of the higher ranks rises with every level), **faster
  recovery in your own town** and a **larger garrison**.
  等级越高，**兵源越好**（高阶权重随等级上升）、**自己的城镇恢复更快**、**驻军也更多**。

Two facilities can be built with the town's money, and both can be upgraded three times.
两种设施可以用城镇资金建造，都能升到三级。

| 设施 Facility | 造价 Cost | 效果 Effect |
| --- | --- | --- |
| 🏥 医院 Hospital | 120 / 210 / 300 | 恢复速度 ×(1 + 0.5 × 等级)，战败存活率 +10% / 级。Recovery ×(1 + 0.5 × level) and +10% survival per level. |
| 🏚️ 军营 Barracks | 150 / 250 / 350 | 全军攻击与防御 +6% / 级。+6% attack and defence for the whole army per level. |

Resting inside a settlement also keeps the town developing: the clock runs, the wounded heal and the town gains
prosperity — while the warbands on the map hold their ground.
在据点里休整时城镇照常发展：时间流逝、伤兵恢复、城镇繁荣度照涨，而地图上的敌军原地不动。

### 4.13 势力会变强 · The factions grow

The world does not stay as it was found. Every day the factions reinforce their warbands, and new bands of
bandits wander onto the map.
世界不会一直停在最初的样子：每天各势力都在补充兵员，新的强盗也会随机出现在地图上。

- **强盗上限 50 支.** A new bandit warband appears every second day until the map holds **50** of them; the
  rest keep roaming and keep growing.
  **强盗上限 50 支。** 每隔一天出现一伙新的强盗，直到地图上有 **50** 支为止；它们会继续游荡、继续变强。
- **势力的兵力上限跟着你的繁荣度走.** The total number of soldiers a faction may field is
  `20 + 0.6 × (所有已占领城镇的繁荣度之和)`. A rich empire makes the rivals stronger — that is the point of
  taking towns.
  **势力的兵力上限跟着你的繁荣度走。** 每个势力在地图上的兵力上限是
  `20 + 0.6 ×（所有已占领城镇的繁荣度之和）`。你的领地越富，敌人越强 —— 这正是打城镇的意义。
- **每天补一名士兵.** A faction below its cap reinforces its strongest warband by one soldier a day, and
  sometimes a rank-2 veteran instead of a raw recruit.
  **每天补一名士兵。** 势力没到上限时，每天给它最强的一支部队补一名士兵，偶尔补的是二级老兵而不是新兵。

### 4.14 版本号与更新内容 · Version and changelog

The version of the build lives in `src/game/versions/`: `index.js` exports `VERSION` and `CHANGELOG`, one file per
release (`v0.0.1.js`, …) holds the batches that release shipped, and `batches.js` is generated from `progress.md`.
版本号集中在 `src/game/versions/`：`index.js` 导出 `VERSION` 与 `CHANGELOG`，每个发布版本一个文件（`v0.0.1.js` …）写着这次发布包含的批次，而 `batches.js` 是从 `progress.md` 生成的。

- **The number is `major.minor.patch`, and only the patch moves.** The game is still in its early stage, so every
  release bumps the last digit only: `v0.0.1` → `v0.0.2` → `v0.0.3` → `v0.0.4`; the major and minor numbers stay at zero.
  **版本号是 `主版本.次版本.修订号`，目前只更新修订号。** 游戏还处于早期阶段，每次发布只加最后一位：
  `v0.0.1` → `v0.0.2` → `v0.0.3` → `v0.0.4`，主版本与次版本一直是 0。
- **The home screen shows it in one place.** The title carries a single `版本 v0.0.4` badge, and that badge opens the
  dialog with the update notes of the current release: a short summary and every batch it shipped. There is no second
  version button at the bottom of the page any more.
  **首页只显示一处。** 标题下面有一个「版本 v0.0.4」徽章，点它就弹出本次发布的更新内容：一段摘要加上这次发布包含的
  每个批次。页面底部不再有第二个版本按钮。
- **The notes come from `progress.md`.** `node tools/build-versions.mjs` parses the 「已完成功能」 section of the
  progress file and writes it into `src/game/versions/batches.js`, so the progress file stays the one source of truth.
  **更新内容来自 `progress.md`。** `node tools/build-versions.mjs` 解析进度文件的「已完成功能」一节，写进
  `src/game/versions/batches.js`，因此进度文件是唯一的事实来源。
- **Only game features reach the dialog.** Every bullet of that section starts with either `▶` (a change a player
  can see or feel) or `🔧` (an internal note). The generator keeps the `▶` bullets and drops the `🔧` ones, so the
  dialog never shows file names, scripts or test counts — and a batch with nothing player-facing (a batch of pure
  documentation, say) does not appear at all.
  **对话框里只有游戏功能。** 「已完成功能」一节的每条内容都以 `▶`（玩家看得见的变化）或 `🔧`（开发层面的改动）开头；
  生成脚本只保留 `▶`，因此对话框里不会出现文件名、脚本名或检查项数量 —— 一条功能都没有的批次（比如纯文档批次）干脆不显示。
- **Helpers.** `versionLabel('0.0.1')` renders `v0.0.1`, `nextPatchVersion('0.0.1')` gives `0.0.2` and
  `changelogOf(version)` filters the notes of one version.
  **辅助函数。** `versionLabel('0.0.1')` 输出 `v0.0.1`，`nextPatchVersion('0.0.1')` 得到 `0.0.2`，
  `changelogOf(version)` 取出某一个版本的更新内容。

### 4.15 练兵 · Training

While the camp is pitched, the world map offers a **🎯 练兵** button that opens the battle field as a drill ground.
扎营时，世界地图上会出现「🎯 练兵」按钮，点它就把战场变成一块训练场。

- **No enemy at all.** The field holds the lord's own soldiers and eight **wooden dummies** standing on the far
  side; the dummies never fight back, they only take blows.
  **完全没有敌人。** 场上只有主角自己的士兵和对面的八个**训练木桩**，木桩只挨打，绝不还手。
- **Nothing can be lost.** A training session has no outcome at all: it does not end, no soldier can die, and the
  warband, the purse, the food store and the record are left exactly as they were.
  **练兵不会损失任何东西。** 训练场没有胜负，不会结束，士兵不会阵亡，队伍、金币、军粮与战绩都原样不动。
- **The dummies stand back up.** A dummy that is knocked down is on its feet again two seconds later, so a drill
  never runs out of targets.
  **木桩会自己立起来。** 木桩被打倒后两秒重新立起，训练永远有靶子。
- **Everything still works.** The whole command bar is live: pick a squad, give it an order (攻击 / 防守 / 跟随 / 移动),
  change its formation and density, drag the camera and plant rally flags.
  **照常操练。** 命令栏一切照旧：选小队、下命令（攻击 / 防守 / 跟随 / 移动）、换队形与密度、拖动镜头、插下目标十字。
- **Leaving is one tap.** The 🏕 结束练兵 button at the bottom of the command bar returns to the world map, and the
  camp is still pitched.
  **一键退出。** 命令栏上的「🏕 结束练兵」回到世界地图，营地还保持着。

### 4.16 快速战斗 · Quick battle

The home screen carries a **⚡ 快速战斗** entry: it opens a simulator that answers "who would win?" without a
campaign. Pick the battlefield, the two sides and the size of the armies, and the simulation fights the fight many
times over and counts the results.
首页有一个「⚡ 快速战斗」入口：它打开一个模拟器，不用打战役就能回答「谁打得过谁」。选好战场、敌我势力与兵力规模，
模拟器会一遍遍地把这场仗打完并统计结果。

- **The battlefield can be picked.** `ARENA_MAPS` in `src/game/arena.js` holds six presets — 混战 (mixed), 平原
  (plain), 密林 (forest), 山地 (mountain), 大河 (river) and 湖泽 (lake) — and `generateArenaTerrain()` lays the
  ground out after the preset. The same presets work in a real battle: `createBattle()` takes an `arenaMap`.
  **战场可以选。** `src/game/arena.js` 的 `ARENA_MAPS` 有六种预设 —— 混战 / 平原 / 密林 / 山地 / 大河 / 湖泽 ——
  `generateArenaTerrain()` 按预设摆地形；真实战斗也用同一套预设（`createBattle()` 有 `arenaMap` 参数）。
- **The numbers are yours to set.** Every side lists the four kinds (民兵 / 长枪兵 / 弓箭手 / 骑兵) with a stepper
  and a **quick slider**; each kind holds **0–100** soldiers, and dragging the slider sets a large count in one go.
  The four sizes (小队 8×8 / 中队 16×16 / 大队 32×32 / 大军 64×64) are only a shortcut that spreads the current mix
  over the wanted size.
  **兵力随便填。** 两边都列出四个兵种（民兵 / 长枪兵 / 弓箭手 / 骑兵），每个兵种都有加减键和**快速滑杆**；
  **每种最多 100 名**，拖动滑杆即可一次设好较大的数量。四档规模只是把当前的配比铺到想要的总数。
- **Both sides can be picked.** One tap gives the lord a whole band of one kind (at the middle rank) and the enemy
  the mix of its faction (强盗 / 苍狼王国 / 赤鹰王国) — and every number stays editable afterwards.
  **敌我势力可以选。** 一键让己方变成整队一个兵种（中级档），敌方变成该势力的配比（强盗 / 苍狼王国 / 赤鹰王国），
  之后每个数字仍然可以改。
- **The fight is a real one.** 「⚡ 进入战场」 opens the ordinary battle screen with the two chosen armies on the
  chosen field: the same squads, the same orders, the same formations, the same camera.
  **打完是真打一场。** 「⚡ 进入战场」 打开的就是平常那个战斗界面，两支选好的队伍站在选好的战场上：小队、命令、
  队形与镜头全都一样。
- **The campaign is not touched.** A quick battle is a drill: no loot, no record, and not one soldier of the lord's
  own warband is lost. The result panel says so and takes you back to the setup.
  **战役不受影响。** 快速战斗只是练习：没有战利品、不记战绩，主角自己的队伍一个士兵都不会少；结算面板会说明这一点，
  并把你带回设置页。
- **It can be left at any moment.** A 「← 返回」 button sits in the corner of the fight and returns straight to the
  setup, without waiting for one side to break. A campaign battle has no such button: there the fight has to be
  decided.
  **随时可以退出。** 战斗界面右上角有「← 返回」按钮，直接回到设置页，不必等一方被打垮；战役里的战斗没有这个按钮，
  必须分出胜负。
- **Or look at the odds first.** 「📊 先看看胜率」 runs the same two armies through 20 fights and reports the win
  rate, the wins, losses and draws, the average survivors and fallen on both sides and the average length of a
  fight. It reuses `createBattle()` and `stepBattle()` from `src/game/battle.js`, only with the largest step,
  because nobody watches it.
  **也可以先看胜率。** 「📊 先看看胜率」 用同样的两支队伍跑 20 场，给出胜率、胜 / 负 / 平、双方平均剩余与阵亡与
  平均时长。它复用 `src/game/battle.js` 的 `createBattle()` 与 `stepBattle()`，只是把步长开到最大（没人观看）。

### 4.17 题库检索 · The question bank

The home screen carries a **🔎 题库检索** entry that opens the whole question bank: every question of the
declarative packs (the encyclopedia and the external mods) and one sample of every generated template.
首页有一个 **🔎 题库检索** 入口，打开整个题库：声明式题包（百科知识与外部 mod）的每一道题，以及每一个生成题型的一道样题。

| 能做的事 What it does | 说明 Note |
| --- | --- |
| 🔍 搜索 Search | 按题干里的字搜索，也匹配科目名与题型名。Search the prompt, the subject and the kind. |
| 🎚 过滤 Filter | 按年级（全部 / 三年级 / 四年级）与科目筛选。Filter by grade and by subject. |
| 📖 查看 View | 点一行展开：完整题干、答案、解析与题目的 key。Open a row for the prompt, the answer, the explanation and the key. |
| 🔁 换一题 Another sample | 生成题可以再抽一道同题型的样题。A generated question can draw another sample. |
| 📊 掌握度 Mastery | 有存档时，每一行标着「生疏 / 眼熟 / 已掌握」。With a save, every row shows how well it is known. |

It is a browsing and previewing tool: it never changes the campaign, and it is the fastest way for a parent or a
teacher to see what the bank really holds.
它是浏览与预览工具，不会改动战役，却是家长或老师看清题库里到底有什么的最快方式。

### 4.18 遇敌对话与逃跑 · Meeting a hostile warband

When a hostile party reaches the lord, the world stops and a **meeting card** opens instead of the battle map.
The card carries the enemy leader's portrait — his faction commander sprite in a faction-coloured frame — the
faction name, what kind of party he leads, the two armies' sizes, and the enemy warband listed troop by troop.
当敌对部队追到主角身边时，世界会停下并弹出**遭遇对话框**，而不是直接进入战场。卡片上有敌将头像（势力将领像素图 + 势力色边框）、
势力名、对方是哪一种队伍、双方兵力对比，以及按兵种列出的敌军名册。

| 选项 Choice | 结果 Result |
| --- | --- |
| ⚔️ 开战 Fight | 进入战斗地图，敌人就是刚才拦路的那支队伍。The battle map opens with the very party that blocked the road. |
| 🏃 逃跑 Run | 主角随机退开 **3–6 格**（只会落在走得到、站得住的格子），那支敌军 **30 秒游戏时间**内不会再次拦住你；不损失士兵，也不花金币。The lord dashes a random **3–6 tiles** (only reachable, walkable ground) and that party cannot catch him again for **30 game seconds**; no soldier and no coin is lost. |
| 🗣️ 喊话 Talk back | 敌将再回一句，循环可以听完这个势力的所有台词；不改变任何数值。The leader answers, and every line of the faction can be heard in turn; nothing changes. |

The meeting explicitly freezes the game: while the card is open the day counter, the clock and every party on the
map hold still, and a camp is broken as the two sides stop. The escape cooldown is counted in **game time**, so a
frozen clock pauses it too — the enemy cannot be "waited out" by standing still.
遭遇期间游戏完全暂停：卡片打开时天数、时钟与地图上所有部队都不动，扎营也会被打断。逃跑冷却按**游戏时间**计算，
因此时钟冻结时冷却也停住——站着不动不能把敌人「等掉」。

Each hostile faction speaks with its own voice: the bandits want the supplies, the wolf patrol demands the lord
identify himself, and the eagle cavalry counts to three. The lines live in `src/game/encounter.js`, so adding a
faction means adding one record there.
每个敌对势力都有自己的口气：强盗想要干粮，苍狼巡逻队要主角报上名来，赤鹰铁骑则数到三。所有台词集中在
`src/game/encounter.js`，新增势力只需要在那里加一条记录。

---

### 4.19 城镇、居民与随从 · Towns, townsfolk and companions

据点不再只是一张菜单。走到城门口点「进入」，主角就站进了这座城镇自己的地图：一条主街、一个广场、几排房屋，
市集、兵营、学堂、医馆、铁匠铺、酒馆都在街边，村民在自家门口走动。地图用和世界地图一样的点击寻路——
点地面走过去，点房子就走过去推门，点人就走过去说话。
A settlement is no longer a menu. Tapping 「进入」 at the gate puts the lord inside the town's own map: a main
street, a square, rows of houses, and the market, barracks, school, hospital, smithy and tavern along the street,
with the townsfolk drifting about their doorways. It moves exactly like the world map — tap the ground to walk,
tap a house to walk up to its door, tap a person to walk over and talk.

| 建筑 Building | 城镇 Town | 村庄 Village | 推门后 What the door opens |
| --- | --- | --- | --- |
| 🏛️ 议事厅 Hall | ✅ | — | 城镇管理：繁荣度、发展、资金、设施与驻军 · the town books, facilities and garrison |
| 🛒 集市 Market | ✅ | ✅（谷仓 Barn） | 买卖军粮、战马、集市券 · supplies and horses |
| 🛡️ 兵营 Barracks | ✅ | — | 招募与升级兵种 · recruit and upgrade soldiers |
| 🏥 医馆 Hospital | ✅ | — | 恢复速度、伤兵与领主生命 · how fast the town heals |
| 📜 学堂 School | ✅ | — | 城镇考试 · the exam |
| ⚒️ 铁匠铺 Smithy | ✅ | — | 兵种升级 · the upgrade tree |
| 🍺 酒馆 Tavern | ✅ | — | 镇上的所有人，可以逐个搭话 · everybody in town, one by one |
| 🏠 民居 Houses | ✅ | ✅ | 一句闲话 + 居民名单 · a line of small talk and who lives here |
| 🌾 磨坊 Mill / 水井 Well | — | ✅ | 同上 · the same |

镇上的每个人都有自己的名字、职业与性格：卫兵、猎人、书生、铁匠、医师、吟游诗人、商人、农夫。
他们在自家门口一两格内慢慢走动，头顶挂着一个记号：**「?」表示有委托还没接，「!」表示已经接下，「✓」表示做完了**。
Every townsperson has a name, a trade and a few lines of their own: guard, hunter, scholar, smith, healer, bard,
merchant, farmer. They wander a step or two around their own doorstep and carry a mark overhead: **「?」 for a job
nobody has taken, 「!」 for one in progress, 「✓」 for one that is done**.

**委托 Quest.** 和居民说话会看到他想请你做的事，例如「答对 16 道考题」「赢下 3 场战斗」「招募 10 名士兵」。
点「📜 接受委托」才算接下：接下这一刻会把当前统计（答对题数 / 胜场 / 招募人数）记成起点，之后你为他做的事才计入，
所以之前攒下的战绩不会白送你一份委托。想反悔就点「放弃委托」，进度作废、可以重新接。
Talking to somebody shows the job they would like done — answer 16 questions, win 3 fights, hire 10 soldiers.
Pressing 「📜 接受委托」 is what actually takes it on: the counter (correct answers / wins / recruits) is recorded at
that moment, and only what the lord does afterwards counts, so an old record never hands out a free quest.
「放弃委托」 drops it again and it can be taken up anew.

**委托日志 Quest log.** 接下的委托可以在两个地方查看：城镇底部工具栏的「📜 委托」和世界地图顶部的「📜 委托」芯片，
后者在骑马走天下时也能打开。日志按「进行中 N / 已完成 M」分组，每条写着谁托付的、在哪座城镇、还差多少，
做完的那条会变成绿色的「✅ 已完成 —— 回去找他就能招募」，并给一个「去找他」按钮直接跳回那座城镇。
The accepted jobs live in two places: the 「📜 委托」 button in the town bar and the 「📜 委托」 chip on the world map,
so they can be read while riding across the country. The log lists open and finished jobs, each with who asked, in
which town, what is still missing, and a green 「✅ 已完成 —— 回去找他就能招募」 line with a button that walks the
lord straight back to that town.

**招募与随从 Recruiting a companion.** 委托做完之后再找他说话，「🤝 招募为随从」按钮才会亮起，价格按职业不同
（吟游诗人 110 金、卫兵 140 金、医师 200 金）。花掉金币，他就成了你的随从，**但身边还没有兵**——
士兵得从你自己的队伍里拨给他：打开「👥 随从」面板，左边是你的部队，右边是他的旗子，点「给他」把一名士兵交过去，
点「收回」把人要回来。每位随从能带的兵有限（4–6 名，按职业），士兵连同伤口一起转手，不会凭空治好。
Once the job is done the 「🤝 招募为随从」 button lights up and the price depends on the trade (bard 110, guard 140,
healer 200). Paying it makes him a companion — **with an empty banner**: his soldiers come out of the lord's own
warband. In the 「👥 随从」 panel the warband sits on the left, his banner on the right, 「给他」 hands a soldier over
and 「收回」 takes one back. A banner holds four to six soldiers depending on the trade, and a soldier carries his
wounds across the transfer.

**路上同行的队伍 The party on the road.** 招募之后，随从会跟着主角在世界地图上走：走在前面时他们排在身后，
两人一排、越靠后越拉开，走起来轻轻起伏，站定时就在身后站定，夜里和主角一起待在提灯的光圈里。
小地图上主角的白点周围会多出一圈小点（每位随从一颗），详细全图里则是他们自己的像素小人——右上角带着兵力徽章，
和领主、敌将一样（小一号，没有分到兵的随从不挂）。世界地图顶部的
「👥 随从 N」芯片可以随时打开随从面板分配士兵，不必特意跑回城里。
Once hired, a companion rides with the lord on the world map: a small train behind him, two abreast with the pairs
opening out further back, bobbing as it walks, standing behind him when he stops and staying inside his lantern light
at night. The minimap grows a ring of dots around the lord's dot (one per companion) and the detailed atlas draws
their own sprites — each with his troop badge in the top-right corner, the same one the lord and the commanders wear
(one size smaller, and none at all for a companion with no soldiers). The 「👥 随从 N」 chip on the world map opens
the companion panel at any time, so handing out soldiers never means riding back to town.

**随从参战 Companions in battle.** 带着兵的随从会跟你上战场：他的士兵在战场后排排成自己的小队，队名就是他的名字
（例如「李守信·民兵」），能单独下令、单独换队形。伤亡分开结算——他的兵死了是他的旗子少了人，你的队伍不会替他背损失，
他本人也不会阵亡。此外每种职业还给全军一点小加成（卫兵 +2% 防御、猎人 +2% 攻击、医师 +15% 伤兵恢复……）。
A companion with soldiers marches into battle as squads of his own in the rear, named after him
(「李守信·民兵」), and can be ordered and re-formed like any other squad. Casualties are settled separately: his
losses thin his banner, never the lord's roster, and he himself is never killed. Each trade also adds a small
army-wide bonus (guard +2% defence, hunter +2% attack, healer +15% recovery …).

**素材与代码 Art and code.** 城镇场景的 39 张 32×32 素材（地面 6 张、建筑与设施 15 张、街道道具 10 张、
居民 8 张）由 `tools/pixel-assets/generate-town.mjs` 通过 Pixelorama 桥接生成，与地图素材共用 `pixkit.mjs`
里的光栅器与调色板。场景布局在 `src/game/town.js`（确定性地块、道路、广场与建筑摆放），人物与委托规则在
`src/game/npc.js`，界面是 `src/views/TownView.vue` + `src/components/TownMap.vue`、`NpcDialog.vue`、
`CompanionPanel.vue`、`QuestPanel.vue`。
The 39 sprites of a town scene (six ground tiles, fifteen buildings and facilities, ten street props and eight
townsfolk) are drawn by `tools/pixel-assets/generate-town.mjs` through the Pixelorama bridge, sharing the rasterizer
and palette of the map art in `pixkit.mjs`. The layout lives in `src/game/town.js`, the people and their jobs in
`src/game/npc.js`, and the screens are `src/views/TownView.vue` with `TownMap.vue`, `NpcDialog.vue`,
`CompanionPanel.vue` and `QuestPanel.vue`.

---

## 5. 势力与兵种 · Factions and Units

### 5.1 势力 · Factions

| 势力 Faction | 颜色 Colour | 敌对 Hostile | 说明 Notes |
| --- | --- | --- | --- |
| 你的部队 Your Warband | `#4aa3ff` | 否 No | 玩家自己。The player. |
| 强盗 Bandits | `#9aa2ab` | 是 Yes | 特殊势力，始终敌对并主动追击玩家；灰色是它没有王国身份的标志。The special faction: always hostile and actively hunts the player; grey is what marks it as the one faction with no kingdom behind it. |
| 苍狼王国 Wolf Kingdom | `#7a5cc0` | 是 Yes | 按势力聚集，围绕锚点活动。Clusters around faction anchors. |
| 赤鹰王国 Eagle Kingdom | `#c98a2b` | 是 Yes | 同上。Same as above. |

Each non-player faction spawns its parties in clusters around 2–3 anchors, bandits roam further and hunt within
9 tiles, and every party wanders around its home point.
每个非玩家势力会在 2–3 个锚点附近成团生成部队；强盗游荡范围更大，并在 9 格内主动追击；所有部队都会围绕本据点游荡。

On the world map every party is drawn as its **commander** — one 32 px figure per faction whose cloth carries the
faction colour: a grey hooded, masked bandit with a sword, a purple caped captain with a wolf-marked shield, and an
amber knight on horseback. The lord and every commander show a **troop badge** (the army's total strength) in the
top-right corner of the icon. `color` in `src/game/factions.js` is the single source of truth: the art generator
imports that table, and the legend swatch and the minimap dot read it too.
世界地图上每支部队都画成它的**将领**——每个势力一个 32 px 人物，衣服就是势力色：灰色连帽蒙面持剑的强盗、紫色披风并持狼纹盾的队长、骑马的琥珀色骑士。主角与每位将领的图标右上角都有**兵力角标**（该部队总兵力）。`src/game/factions.js` 里的 `color` 是唯一数据源：素材生成脚本会 import 这张表，图例色块与小地图圆点也都读它。

### 5.2 兵种 · Unit roster

Every family is stored as `{ type, tier, count }`; a tier-1 row is what a town or village sells, the higher tiers
are what you promote into. Range only matters for ranged units, and the counter column is the family each one beats.
每个家族都以 `{ type, tier, count }` 存储；一级档是村庄 / 城镇直接卖的，更高档只能靠升级。射程只对远程有意义，「克制」列是它打得过的家族。

| 兵种 Unit | 档位 Tier | 攻 Atk | 防 Def | 血 HP | 射程 Range | 招募价 Cost | 日薪 Wage | 克制 Counters | 特性 Trait |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 民兵 Militia | 1 | 4 | 3 | 30 | — | 12 | 1 | — | 村庄基础兵种，可升级为三个家族。Village basic troop; upgrades into all three families. |
| 初级长枪兵 Spearman | 1 | 9 | 10 | 56 | — | 30 | 2 | 骑兵 | 防御最高，顶住冲锋。Highest defence; stops a charge. |
| 中级长枪兵 Spearman | 2 | 12 | 13 | 73 | — | 57 | 3 | 骑兵 | 同上。/ Same. |
| 高级长枪兵 Spearman | 3 | 15 | 17 | 92 | — | 93 | 4 | 骑兵 | 同上。/ Same. |
| 精英长枪兵 Spearman | 4 | 18 | 21 | 115 | — | 141 | 5 | 骑兵 | 同上。/ Same. |
| 初级弓箭手 Archer | 1 | 8 | 3 | 34 | 150 | 34 | 2 | 长枪兵 | 隔空输出，需要前排保护。Ranged; needs a front line. |
| 中级弓箭手 Archer | 2 | 10 | 4 | 44 | 165 | 65 | 3 | 长枪兵 | 同上。/ Same. |
| 高级弓箭手 Archer | 3 | 13 | 5 | 56 | 180 | 105 | 4 | 长枪兵 | 同上。/ Same. |
| 精英弓箭手 Archer | 4 | 16 | 6 | 70 | 195 | 160 | 5 | 长枪兵 | 同上。/ Same. |
| 初级骑兵 Cavalry | 1 | 12 | 6 | 58 | — | 46 | 3 | 弓箭手 | 速度 1.8，绕后切远程。Speed 1.8; flanks the enemy shooters. |
| 中级骑兵 Cavalry | 2 | 16 | 8 | 75 | — | 87 | 5 | 弓箭手 | 同上。/ Same. |
| 高级骑兵 Cavalry | 3 | 20 | 10 | 96 | — | 143 | 6 | 弓箭手 | 同上。/ Same. |
| 精英骑兵 Cavalry | 4 | 25 | 12 | 119 | — | 216 | 8 | 弓箭手 | 同上。/ Same. |

A rank costs `×1 / 1.9 / 3.1 / 4.7` of the family's basic price, so the elite is dear — that is the point of the
promotion ladder.
档位价格是家族基础价的 `×1 / 1.9 / 3.1 / 4.7`，所以精英很贵——这正是升级阶梯存在的意义。

Your commander is a separate marker on the battlefield (120 HP, speed 150) used as the anchor for the 防守 and
跟随 orders.
你的指挥官在战场上是一个独立的标记（120 血、速度 150），是「防守」和「跟随」命令的参照点。

---

## 6. 游戏界面 · Game Screens

| 界面 Screen | 路由 Route | 内容 Contents |
| --- | --- | --- |
| 首页 Home | `#/` | 输入领主名字、开始新游戏 / 继续进度 / 快速战斗（三者同级，主按钮独占一行）、难度选择、最近玩过的名字、玩法小贴士、**题库检索**与分享入口；标题下只有**一个版本徽章**，点它**弹出更新内容对话框**。Name entry, new / continue / quick battle (the three on the same level, the main button on a row of its own), the difficulty picker, recent names, the tips, the **question bank** and the share link; below the title there is **one version badge** and tapping it **opens the update notes in a dialog**. |
| 题库检索 Question bank | `#/bank` | 整个题库的列表：**搜索框**、年级与科目过滤、点开看答案与解析、生成题可「换一题」、每行的掌握度标记。The whole bank in one list: a **search box**, the grade and subject filters, the answer and the explanation of every row, another sample for a generated question and the mastery of each row. |
| 快速战斗 Quick battle | `#/quick` | 战场地图（六种预设）、四档规模、敌我势力与**每个兵种的加减键和快速滑杆（每种 0–100）**；「⚡ 进入战场」真的上战场打一场，「📊 先看看胜率」用同样的队伍跑 20 场给出胜率与平均阵亡。The battlefield (six presets), the four sizes, the two sides and **a stepper plus a quick slider (0–100) for every kind of soldier**; 「⚡ 进入战场」 puts the lord on the field to fight it out, and 「📊 先看看胜率」 runs the same armies through 20 fights for the win rate and the average casualties. |
| 游戏介绍 Guide | `#/guide` | 目标、地图、据点、考试、科目（含百科知识与已加载的 Mod 科目）、记忆曲线、兵种克制循环与**兵种升级图**（逐档属性与升级价）、战术 / 队形 / 密度说明，以及题库扩展方式。Goals, map, settlements, exams, the subject list (encyclopedia plus any loaded mod subjects), the memory curve, the RPS cycle and the generated **unit upgrade diagram**, plus the tactics / formation / density tables and how to extend the question bank. |
| 世界地图 World map | `#/world` | 全屏 canvas 地图、右上角小地图与图例（图标 + 势力色块）、📖 详细地图浮层（拖动平移、回到主角）、顶部状态栏（含 👤 角色详情 芯片、📅 天数时钟芯片（天数 + 时刻 + 当天进度条）与 🎚 难度芯片）、点难度芯片弹出的难度设置面板、底部按钮（进入 / ⛺ 扎营 / ⚔️ 赶走强盗 / 🏰 准备围城 / ⏳ 围城倒计时 / 🚫 取消围城 / ⚔️ 攻打 / 🚩 占领 / ⚔️ 攻城）与四个功能按钮、提示条、扎营时的帐篷与篝火、据点上的归属光环与驻军角标、**遇敌时弹出的遭遇对话框（敌将头像 / 兵力对比 / 名册 / 开战 · 逃跑 · 喊话）**、存档提示浮层。Full-screen canvas map, the corner minimap with its sprite legend, the 📖 detailed atlas overlay (drag to pan, recentre on the lord), status chips (including the 👤 lord info chip, the 📜 quest chip and the 👥 companion chip, the 📅 day clock chip with the day, the hour and a day-progress bar, and the 🎚 difficulty chip), the difficulty sheet behind that chip, the bottom buttons (enter / ⛺ camp / ⚔️ drive off bandits / 🏰 prepare a siege / ⏳ siege countdown / 🚫 cancel the siege / ⚔️ storm / 🚩 claim / ⚔️ assault) plus four action buttons, hint bar, a tent and campfire while camping, the ownership ring and garrison badge on every settlement, **the meeting card that opens when an enemy catches the lord (portrait / army sizes / roster / fight · run · talk back)**, and toasts. |
| 城镇 Town | `#/town?id=…` | 可以走动的城镇 / 村庄场景：像素地面与建筑、广场喷泉、居民的「?」「!」「✓」委托记号；底部是「💬 和人说话 / 🚪 进入某处」「👥 随从」「📜 委托」「🏛 镇务」；推门打开的是同一套市场 / 招募 / 升级 / 城镇 / 考试面板，医馆是恢复读数，酒馆与民居列出全镇居民。The walkable town / village scene: pixel ground and buildings, a fountain in the square and the 「?」「!」「✓」 job marks over the townsfolk; the bar carries the talk / enter button, 「👥 随从」, 「📜 委托」 and 「🏛 镇务」, and a door opens the very same market / recruit / upgrade / town / exam panels, with the hospital showing the healing numbers and the tavern or a house listing everybody in town. |
| 据点 Settlement | `#/settlement?id=…` | 据点标题栏（左上角显示城镇等级，中间是 📅 天数时钟芯片，右侧有「🏘 走进城里」按钮与归属、金币 / 兵力）、招募 / 升级 / 市场 / 城镇 / 考试 五个页签。Header (town level in the top-left corner, the 📅 day clock chip in the middle, a 「🏘 走进城里」 button plus owner, gold and troops on the right) plus Recruit / Upgrade / Market / Town / Exam tabs. |
| 战斗 Battle | `#/battle` | 战场 canvas（带地形，鼠标左键或手指都能拖动镜头）、顶部双方兵力、右上角的帧率芯片（最近半秒平均帧率）、⚙ 战斗工具（速度 🐢/🚶/🐇 与地形说明）、🎯 回中按钮与快速战斗专属的「← 返回」、小队选择条（每档一个按钮）、攻击 / 防守 / 跟随 / 移动 四个命令、可折叠的队形与密度面板、提示行、战斗结果面板；战斗中左缘滑动返回会被拦下并提示；**练兵模式**下顶部写着「🎯 练兵」、对面是训练木桩，底部多出「🏕 结束练兵」。Arena canvas (with terrain, panned by the left mouse button or a finger), both sides' strength, a frame-rate chip in the corner (the average of the last half second), the ⚙ battle tools (speed 🐢/🚶/🐇 and the terrain legend), the 🎯 recentre button and a 「← 返回」 button in a quick battle, a squad chip bar, the four orders, a collapsible formation / density sheet, a hint line and the result panel; an edge swipe back is refused with a note while the fight is on; in **training mode** the bar reads 「🎯 练兵」, the other side is the wooden dummies and a 🏕 结束练兵 button sits under the command bar. |

A first-run intro modal shows the guide before the campaign starts, so new players always see the rules.
首次开始游戏会先弹出介绍弹窗，保证新玩家一定看到规则。

---

## 7. 游戏操作 · Controls

- **查看时间 See the time** — 世界地图顶部的 📅 芯片显示第几天、几点几分（地图上一天 24 秒，1 秒 = 游戏里的 1 小时；据点里放慢到 1 秒 = 1 分钟）和当天的进度条；据点界面与角色信息面板里也有同样的时钟。The 📅 chip in the world-map status bar shows the day, the hour of that day (a day is 24 seconds on the map, one second is one in-game hour; inside a settlement it slows to one second per in-game minute) and a bar for the day's progress; the settlement screen and the lord panel carry the same clock.
- **昼夜 Day and night** — 每天的最后五分之一（19:12 起）是夜晚：地图变暗、主角与所有部队都变慢 25%，主角身边有一圈灯光。The last fifth of every day (from 19:12) is night: the map darkens, the lord and every warband slow down by 25%, and the lord keeps a lantern light around him.
- **移动 Move** — 点击世界地图任意位置；游戏时间只在移动时流逝。Tap anywhere on the world map; game time advances only while the lord walks.
- **扎营 Camp** — 点底部「⛺ 扎营」原地扎营，时间与敌军照常流转；点「🔥 拔营」或点地图移动即结束。Tap 「⛺ 扎营」 to rest in place while time keeps running; 「🔥 拔营」 or a map tap breaks camp.
- **练兵 Drill** — 扎营时底部多出「🎯 练兵」按钮，点它进入训练场：场上只有自己的士兵和训练木桩，没有敌人，不会死人，练习完点「🏕 结束练兵」回到世界地图。While the camp is pitched the bottom bar grows a 「🎯 练兵」 button: it opens a drill ground with the lord's own soldiers and wooden dummies, no enemy and no losses, and 「🏕 结束练兵」 takes you back to the world map.
- **快速战斗 Quick battle** — 首页的「⚡ 快速战斗」进入快速战斗：选战场、选敌我势力，用加减键或滑杆定好每个兵种的数量（每种 0–100），点「⚡ 进入战场」就在战场上亲自指挥一场；点「📊 先看看胜率」则用同样的队伍跑 20 场给出胜率。The 「⚡ 快速战斗」 entry on the home screen opens the quick battle: pick a battlefield, the two sides and the count of every kind of soldier (0–100 each) with the stepper or the slider, then 「⚡ 进入战场」 puts you on the field to command the fight yourself; 「📊 先看看胜率」 runs the same armies through 20 fights instead.
- **走进城镇 Walk into town** — 靠近据点后点底部的「进入」，人就站进了城镇地图：点地面走路，点房子走到门口推门，点人走过去说话；手机上一根手指就够。Tap 「进入」 near a settlement to stand inside its map: tap the ground to walk, tap a house to walk to its door, tap a person to walk over and talk — one finger is enough on a phone.
- **接受委托 Accept a job** — 和居民说话，看完他的请求后点「📜 接受委托」；接下这一刻才开始计数，点「放弃委托」可以退回。Talk to a townsperson, read the job and press 「📜 接受委托」 — the counting starts at that moment, and 「放弃委托」 gives it back.
- **看委托 Log of jobs** — 城镇底部「📜 委托」或世界地图顶部「📜 委托」芯片都能打开；里面写着谁托付的、在哪座城、还差多少，做完的可以直接点「去找他」。Open the log from 「📜 委托」 in a town or from the world-map chip: who asked, which town, what is left, and a button that walks straight back to him once it is done.
- **随从跟着走 The train on the road** — 招募来的随从会在世界地图上跟在主角身后（两人一排的小队），小地图与全图也能看到；点顶部「👥 随从」芯片随时分配士兵。A recruited companion follows the lord on the world map (a small train two abreast), shows on the minimap and the atlas, and the 「👥 随从」 chip hands out soldiers at any time.
- **随从 Companions** — 「👥 随从」面板里把士兵「给他」或「收回」，他的旗子装满就不再收人；「解散」把人和兵一起放回你的队伍。In the 「👥 随从」 panel hand soldiers over with 「给他」 or take them back with 「收回」; a full banner takes no more, and 「解散」 returns both the companion and his soldiers to the warband.
- **赶走强盗 Drive off bandits** — 强盗村庄不能进入，底部按钮是「⚔️ 赶走强盗」，打一场就能进。Tap 「⚔️ 赶走强盗」 at a bandit village and win the fight to open it up.
- **占领无主城镇 Claim an unclaimed town** — 无主的城镇如果没人防守，底部按钮「🚩 占领」直接拿下；如果还有守军，按钮变成「⚔️ 攻城」，必须打赢守军才能占领。An unclaimed town nobody defends is taken with 「🚩 占领」; one that still holds soldiers offers 「⚔️ 攻城」 and has to be stormed.
- **准备围城 / 攻打 / 取消围城 Prepare a siege / storm / cancel** — 想把别人的城镇据为己有：先「🏰 准备围城」等 2 天（时间会流逝），再「⚔️ 攻打」；只是进去办事就不用打。围城期间随时可以点「🚫 取消围城」中断，准备的进度全部作废；攻打失败后也要重新准备围城。To take someone else's town: 「🏰 准备围城」 (two days, the clock runs) and then 「⚔️ 攻打」; walking in to trade needs no fight. Tap 「🚫 取消围城」 at any time to call the siege off, and a failed assault means the siege has to be prepared all over again.
- **难度 Difficulty** — 首页开局时选择难度，世界地图上点 🎚 芯片可随时更改；难度决定考试收入、招募价与军粮消耗，也决定敌军有多强，芯片还会显示随胜场上升的威胁。Pick the difficulty on the home screen and change it any time with the 🎚 chip on the world map; it decides the exam pay, the recruit price and the food cost, and how strong the factions are — the chip also shows the threat that rises with every win.
- **城镇管理 Town management** — 据点里的「🏛️ 城镇」页签：繁荣度、发展、资金、设施与驻军；「注入资金」把自己钱袋里的钱放进城镇金库；在自己占领的城镇里还能点「➕ 驻守 / ➖ 撤回」，把自己的部队留在城里守城、或随时带回来（驻军随城镇逐日恢复，地图上的兵力角标跟着变化）。The 「🏛️ 城镇」 tab inside a settlement: prosperity, development, funds, facilities and the garrison; 「注入资金」 moves the lord's own gold into the town treasury, and in a town he owns the 「➕ 驻守 / ➖ 撤回」 buttons leave his soldiers behind to defend it or bring them back (the garrison heals with the town and the map badge follows it).
- **遇敌对话 Meeting an enemy** — 敌军追上来时先弹出遭遇对话框：上方是敌将头像、势力、双方兵力与敌方兵种名册，下面三个选项。「⚔️ 开战」进入战场，「🏃 逃跑」随机退开 3–6 格并让敌人冷却 30 秒，「🗣️ 喊话」再听敌将回一句；对话期间世界暂停。A hostile party opens a meeting card instead of a battle: the leader's portrait, his faction, both army sizes and the enemy roster sit above three choices. 「⚔️ 开战」 opens the arena, 「🏃 逃跑」 dashes 3–6 tiles away and cools the enemy down for 30 seconds, and 「🗣️ 喊话」 makes the leader answer; the world is frozen while the card is open.
- **开战 Start a fight** — 遇敌后点「⚔️ 开战」才进入战斗地图；敌人就是对话框里那支队伍。Tap 「⚔️ 开战」 on the meeting card to enter the battle map with the party from the dialog.
- **战术 Orders** — 战斗中先点小队按钮选部队（或「全军」），再切 ⚔️ 攻击 / 🛡️ 防守 / 🏇 跟随 / 🎯 移动。Pick a squad chip (or 全军) first, then switch ⚔️ attack / 🛡️ defend / 🏇 follow / 🎯 move.
- **开局对峙 Opening standoff** — 刚进战场时双方都不动，敌军约 5 秒后变阵、再约 2.4 秒后冲锋；点「⚔️ 全军出击」一次让所有部队出击，或者先选一支队伍单独下令。Both armies hold when the arena opens; the enemy dresses its ranks for about five seconds, then charges a couple of seconds later. Press 「⚔️ 全军出击」 to send everyone at once, or pick one squad and order just that one.
- **队形与密度 Formation and density** — 展开战斗底部的「▦ 队形」面板，给选中的小队换队形（方队 / 一行 / 两行 / 三行 / 尖形 / 随机）和密度（松散 / 紧凑）。Open the 「▦ 队形」 sheet to change the selected squad's formation (square / single rank / two ranks / three ranks / wedge / scatter) and density (loose / tight).
- **战斗速度与地形 Battle speed and terrain** — 战斗界面右上角 ⚙ 打开工具面板：切换 🐢 慢速 / 🚶 正常 / 🐇 快速（默认慢速），并查看五种战场地形的效果。Tap the ⚙ button in the corner of the battle screen for the tools panel: the speed (🐢 slow by default, 🚶 normal, 🐇 fast) and the effect of every kind of battlefield terrain.
- **镜头 Camera** — 用手指拖动战场可以自由查看，点 🎯 让镜头回到战斗。Drag the field with a finger to look around, and tap 🎯 to bring the camera back to the fighting.
- **查看角色信息 View lord info** — 点击世界地图顶部的 👤 角色详情 芯片，查看士兵、资金、物资与战绩。Tap the 👤 lord info chip on the world map to review troops, treasury, supplies and record.
- **看全图 Open the atlas** — 点右上角小地图打开 📖 详细地图；在图上按住拖动查看不同区域，点「🎯 回到主角」拉回视野，点 ✕ 或按 Esc 关闭。Tap the minimap in the top-right corner to open the detailed atlas; press and drag on it to look at another region, 「🎯 回到主角」 recentres on the lord, and ✕ or Esc closes it.
- **指挥 Commander** — 点击战场移动指挥官标记；若选中部队处于「移动」，同一次点击改为插下目标十字。Tap the field to move the commander marker; when the selected squad is on 移动 the tap plants its rally flag instead.
- **保存 Save** — 世界地图上的 💾 保存按钮，另有自动保存。The 💾 button on the world map, plus autosave.
- **退出 Exit** — 世界地图上的 🏠 退出按钮回到首页。The 🏠 button returns to the home screen.

---

## 8. 游戏分享 · Sharing

Tap 📤 分享 on the home screen or the world map to open a popup that renders the game URL as a QR code.
在首页或世界地图点击 📤 分享，会弹出把游戏网址渲染成二维码的窗口。

The QR is encoded locally with `qrcode-generator`, so the popup works on an offline LAN; the 复制链接 button
falls back to a legacy `execCommand` copy when the browser has no clipboard API (plain HTTP pages).
二维码用 `qrcode-generator` 本地编码，因此离线局域网也能用；在没有剪贴板 API 的页面（纯 HTTP）下，「复制链接」会自动回退到 `execCommand` 复制。

Friends must be on the same network (WiFi) to open the shared link.
好友需要连在同一个网络（WiFi）下才能打开分享的链接。

---

## 9. 奖励与惩罚 · Rewards and Penalties

| 项目 Item | 数值 Value |
| --- | --- |
| 答对奖励（三年级）Reward, grade 3 | 5 金币（简单，整卷封顶 ×2）／19（普通）／14（困难） 5 gold on easy (paper capped at ×2) / 19 normal / 14 hard |
| 答对奖励（四年级）Reward, grade 4 | 5 金币（简单）／25（普通）／19（困难） 5 gold easy / 25 normal / 19 hard |
| 逻辑推理加成 Logic bonus | +6 金币（普通与困难） +6 gold on normal and hard |
| 百科知识加成 Encyclopedia bonus | +4 金币（普通与困难） +4 gold on normal and hard |
| 结算加成 Settlement bonuses | 连击 ×1.0–×1.5、全对 ×1.5、长卷 ×1.1、及格 +20%；简单档整卷最多拿到基础价 ×2（见 4.5） |
| 答对掉道具 Gear from answers | 军粮 / 战马 / 集市券 / 征兵令（见 4.5） |
| 经验与属性 Experience and attributes | 及格卷每答对一题 +1 经验，50 经验换 1 点属性（见 4.5） |
| 初始资金 Starting gold | 150（简单）／120（普通）／90（困难） 150 easy / 120 normal / 90 hard |
| 初始军粮 Starting food | 8（简单）／5（普通）／3（困难） 8 easy / 5 normal / 3 hard |
| 初始兵力 Starting troops | 8 名民兵 8 militia |
| 胜利战利品 Victory loot | 按敌方部队价值的 35% 结算 35% of the defeated warband's value |
| 收编俘虏 Prisoners | 60% 概率，最多 +4 民兵 60% chance, up to +4 militia |
| 战败结果 On defeat | 队伍只保留幸存者，并被推离敌人 3 格 Your warband keeps only its survivors and is pushed 3 tiles clear |
| 士兵全部倒下 The warband is wiped out | 不立刻结束：主将独自撑 8 秒，撑完或按「撤退」＝判负，**不再损失第二批士兵**，带着当前生命退回战场周围。Not over at once: the lord holds out for 8 seconds, then (or when 撤退 is pressed) the battle is lost with **no second army to lose**, and he steps back to the field with the health he still has. |
| 敌将独自撑到最后 The hostile general holds alone | 他撑满 8 秒就只身逃走，**这场战斗算你赢**，结算写明「敌将只身逃走」。He holds for 8 seconds and then flees alone: **the battle counts as a win**, and the result says he ran. |
| 主将倒下 The lord goes down | 立刻判负：**损失一半士兵**、退到世界地图上**刚刚战场周围**（3–7 格）、生命值恢复到一半（之后慢慢恢复）；敌人还在附近。The battle is lost at once: **half the warband is scattered**, the lord falls back to the world map **around the field he fought on** (3–7 tiles) at half health, which then closes slowly — and the enemy is still nearby. |

The difficulty changes three things: the exam pay, what the army costs (recruit price and food) and how strong the
factions are. It never changes the questions, and a wrong answer never costs gold.
难度改三件事：考试收入、养兵成本（招募价与军粮）和敌军强度；它不改题目，答错也从不扣钱。

A defeated enemy party is removed from the map and stops hunting you for 45 s, and after you lose a battle the
same party cannot engage again for 60 s.
被击败的敌方部队会从地图移除，并停止追击 45 秒；你战败后，同一支部队 60 秒内不会再次接战。

If your warband is empty, hostile parties stop attacking you until you recruit again.
如果你的队伍为空，敌对部队会停止攻击你，直到你重新招募。

---

## 10. 游戏数据 · Game Data

All state lives in `localStorage`; there is no server.
所有状态都存在 `localStorage` 里，没有后端。

| 键 Key | 内容 Contents |
| --- | --- |
| `kids-war-game:users` | 玩过的领主名字列表。The list of player names used on this browser. |
| `kids-war-game:save:<name>` | 单个存档：世界种子、地形（压缩为地形 id 数组）、据点、部队、玩家坐标、天数、金币、兵员、物资、统计。One save slot: world seed, terrain (stored as a compact terrain-id array), settlements, parties, player position, day, gold, troops, supplies and stats. |

Saved fields · 存档字段：`seed` `gridIds` `settlements` `parties` `playerPos` `day` `gold` `troops` `supplies` `stats` `questionStats` `difficulty` `experience` `attributes` `lordHp` `lordMaxHp` `companions` `quests`.

`experience` and `attributes` are what the child learned: the experience the papers gave and the attribute points it
was spent on. A save without them starts at zero.
`experience` 与 `attributes` 记的是孩子学到的东西：考试给的经验与花在属性上的点数；旧存档没有这两个字段时按零处理。

`lordHp` / `lordMaxHp` carry the lord's own wounds: a save without them restores a whole lord.
`lordHp` / `lordMaxHp` 保存领主自己的伤：没有这两个字段的旧存档会把他当作满血。

`difficulty` carries the difficulty of the campaign; a save without it is an easy game. The threat is not saved: it
is derived from `stats.wins` and the towns the lord holds, so a reload keeps the same pressure.
`difficulty` 保存本局的难度；没有这个字段的旧存档按「简单」处理。威胁不单独存档：它由 `stats.wins` 与领主占领的
城镇数量推导，因此读档后压力与原来一致。

`day` carries the campaign clock across a reload; the in-flight clock accumulator and the camp flag are not
saved, so a resumed game always starts standing still with the clock frozen.
`day` 让战役天数跨刷新保留；尚未走完的时钟进度与扎营标记不写入存档，因此读档后总是原地站立、时钟冻结。

A warband entry is `{ type, tier, count, hp }` (family, 1–4 rank, soldiers and one hit-point value per soldier).
Loading rewrites the pre-standard keys (`infantry` / `veteran` / `marksman` / `knight`) through `normalizeTroops()`,
so an old save keeps its strength, and a save that predates the wounds starts every soldier at full health.
队伍每一项是 `{ type, tier, count, hp }`（家族、1–4 档位、人数，以及每人当前生命值）。
读档时会用 `normalizeTroops()` 改写旧版 key（`infantry` / `veteran` / `marksman` / `knight`），因此旧存档的兵力不会丢；
早于「受伤」系统的存档则让每名士兵以满血归队。

A settlement carries `owner` (`neutral` / `player` / `bandit` / `wolf` / `eagle`), `level`, `prosperity`,
`development`, `funds`, `facilities` (`hospital` / `barracks`), `garrison` and `siege`. A save that predates the
ownership system gets a deterministic owner per settlement, so the world still has hostile towns to take.
每个据点保存 `owner`（`neutral` / `player` / `bandit` / `wolf` / `eagle`）、`level`、`prosperity`、`development`、
`funds`、`facilities`（`hospital` / `barracks`）、`garrison` 与 `siege`；早于归属系统的存档会按据点 id 稳定地
补一个归属，因此世界里仍有可以攻打的城市。

`stats` 记录 `days` `battles` `wins` `exams` `correct` `recruited`（累计招募的士兵数，委托会用到）。
`stats` tracks `days` `battles` `wins` `exams` `correct` and `recruited` (how many soldiers were hired, which a quest can ask for).

`companions` 是随从列表：`{ id, name, role, sprite, townId, soldiers }`，`soldiers` 与队伍同构
（`{ type, tier, count, hp }`）；`quests` 是委托记录，按 NPC id 存 `{ npcId, name, title, townId, townName, kind, target, base, accepted, done }`，
其中 `base` 是接取当天对应计数（答对题数 / 胜场 / 招募人数）的值。两者都是后加的字段，旧存档没有时按「没有随从、没有委托」处理。
`companions` is the list of followers (`{ id, name, role, sprite, townId, soldiers }`, with `soldiers` in the same
`{ type, tier, count, hp }` shape as the warband) and `quests` holds one record per NPC —
`{ npcId, name, title, townId, townName, kind, target, base, accepted, done }` — where `base` is the value of the
counter (answers, wins, recruits) on the day the job was accepted. Both are newer fields: a save without them loads
with nobody following and no job taken.

`questionStats` holds the memory curve, keyed per question — `{ "<mod>:<itemId>" | "<mod>#<kind>": { level, right, wrong, lastSeen } }` — pruned to the 1200 most recently seen records on save; a save without the field simply starts with an empty curve.
`questionStats` 保存记忆曲线，按题目为键 —— `{ "<mod>:<itemId>" | "<mod>#<kind>": { level, right, wrong, lastSeen } }` —— 存档时只保留最近见到的 1200 条记录；旧存档没有该字段时按「全部生疏」处理。

Deleting a save is as simple as removing those keys, or calling `deleteGame(name)` from `src/game/save.js`.
删除存档只需移除这些键，或调用 `src/game/save.js` 里的 `deleteGame(name)`。

---

## 11. 手机端支持 · Mobile Support

The game is designed for phones first: the layout uses a `max-width: 560px` breakpoint that stacks the world
HUD, collapses the legend, shrinks the minimap, wraps list rows and turns exam answers into a single column.
游戏以手机优先设计：`max-width: 560px` 断点会把世界地图 HUD 改为竖排、默认收起图例、缩小小地图、把列表行折行、并把考试选项改成单列。

Touch targets are at least 40–44 px, the world map uses a `click` handler (works for taps, mice and automation),
and rubber-band scrolling plus the grey tap highlight are disabled.
触控目标最小 40–44 px；世界地图使用 `click` 事件（触摸、鼠标、自动化都能触发）；橡皮筋滚动与点击灰块已关闭。

The app fills the dynamic viewport (`100dvh`) so the mobile URL bar does not clip the bottom buttons, and the HUD
respects `env(safe-area-inset-*)` on notched devices.
应用使用动态视口高度（`100dvh`），因此手机地址栏不会裁掉底部按钮；HUD 也通过 `env(safe-area-inset-*)` 适配刘海屏。

The canvas caps device pixel ratio at 2 and caches its vignette gradient per resize, keeping the redraw cheap.
画布的 device pixel ratio 上限为 2，并且暗角渐变只在尺寸变化时生成一次，让每帧重绘足够轻量。

The detailed atlas is panned with **pointer events** and `touch-action: none`, so a finger drag scrolls the map
instead of the page, and `setPointerCapture` keeps the drag alive when the finger leaves the canvas.
详细地图用 **pointer 事件**加 `touch-action: none` 拖动，因此手指拖动的是地图而不是页面；`setPointerCapture` 保证手指移出画布后拖动仍然连续。

The **battle field** is designed the same way: it is bigger than a phone screen, so the camera follows the fighting
and a drag pans the field (the battle canvas uses the same pointer-event scheme, and a drag never plants a rally
flag). It takes the primary pointer only — the left button of a mouse, one finger — and calls a move a drag after
4 px of travel, so a tap still moves the commander on both inputs; a tap is decided on `pointerup`, not on the click
that a touch may or may not synthesise. The battle tools sit in the top-right corner instead of the command bar, so
the field stays as tall as possible on a phone.
**战场**也是同样的思路：它比手机屏幕大，因此镜头跟着战斗走，拖动可以平移战场（战斗 canvas 用同一套 pointer 事件，
拖动时不会误插旗）。它只认主指针（鼠标左键或一根手指），移动累计超过 4 px 才算拖动，因此在两种输入下轻点都仍然是
移动指挥官；轻点在 `pointerup` 上判定，不依赖触摸时可能根本不生成的 click。战斗工具放在右上角而不是底部命令栏，
这样手机上的战场能留到最大。

The command bar at the bottom is **clear**: the squad chips, the order buttons, the formation toggle and the hint
each carry their own panel, so the field is visible in the gaps instead of sitting under a dark sheet. The hint has a
text shadow to stay readable on the grass, and the buttons still take the full 44 px touch target.
底部的**命令栏是透明的**：小队按钮、命令按钮、队形开关与提示行各自带面板，战场在按钮之间的空隙里依然看得见，
不再被一层黑色渐变罩住。提示行加了文字阴影，在草地上也读得清；按钮本身仍然保持 44 px 的触控高度。

The battle screen also refuses a **browser back step** while the fight is on: a phone's edge swipe is exactly that,
and it would otherwise throw the fight away. The refusal is a route guard rather than a swallowed touch, so it holds
for the Android back key too, and the screen says why; the on-screen button sets the flag that lets the leave
through.
战斗界面还会在战斗进行中**拒绝浏览器的后退**：手机左缘的滑动返回就是一次后退，否则会把整场战斗甩掉。拦截放在路由
守卫里而不是吞掉触摸事件，因此安卓的返回键同样被拦住，画面上也会说明原因；界面上的返回按钮会先放行再离开。

The battle runs **slow by default**, so a child can read the field and give orders before the next clash — the fast
speed is one tap away in the ⚙ panel.
战斗**默认慢速**，孩子来得及看清战场、赶在下一次交手前下令；想加速，点 ⚙ 面板即可。

---

## 12. 游戏部署 · Deployment

```bash
npm install
npm run dev        # 开发 · dev, http://<lan-ip>:5180
npm run build      # 生产构建 · production build into dist/
npm run preview    # 预览构建产物 · preview the build, http://<lan-ip>:4180
npm run serve      # 同上，显式指定 4180 端口 · same, explicit port 4180
```

Both dev and preview bind to `0.0.0.0`, so any device on the LAN can open `http://<lan-ip>:5180`.
开发和预览都绑定 `0.0.0.0`，因此局域网内任何设备都能访问 `http://<局域网IP>:5180`。

Because the app uses hash routing, the built `dist/` folder also works when opened directly from a static file
host, a USB stick or even `file://`.
由于使用 hash 路由，构建出的 `dist/` 目录即使放在静态文件服务器、U 盘甚至用 `file://` 直接打开也能运行。

---

## 13. 游戏维护 · Maintenance

### 新增兵种 · Add a unit

Add a family to `UNIT_TYPES` in `src/game/units.js` with its base (rank-1) statistics, `recruitCost`, `wage` and
the family it counters; ranks, prices and battle stats are all derived from the shared `TIER_RANKS` multipliers, so
you never write a per-rank table. To make it recruitable, add its 初级 row to `TOWN_POOL` in `src/game/recruit.js`
and, if it is a militia-style branch, list it in `BRANCHES`.
在 `src/game/units.js` 的 `UNIT_TYPES` 里加一个家族，写好一级（基础）属性、`recruitCost`、`wage` 和它克制的家族；档位、价格与战斗数值全部由共用的 `TIER_RANKS` 乘数推导，不需要写逐档表格。要让它能被招募，就把它的初级档加进 `src/game/recruit.js` 的 `TOWN_POOL`；如果它是像民兵那样的一级分支，还要加进 `BRANCHES`。

`upgradesFor()` builds the promotion edges and `upgradeCost()` prices them from the two recruit prices, so the
upgrade tree and the guide's diagram follow automatically.
`upgradesFor()` 负责生成升级连线，`upgradeCost()` 用两端招募价算出价格，因此升级树和介绍里的升级图都会自动跟着变。

Every definition returned by `unitDef()` carries both `key` and `type`, and the edges reuse those very objects, so
an edge can be handed straight to `player.upgradeTroops()` — `{ type, tier }` is the shape the whole game stores
soldiers in, and it is also what the panel's `v-for` keys and steppers are built from.
`unitDef()` 返回的定义同时带 `key` 与 `type`，算升级边时直接复用这批对象，因此一条边可以原样交给 `player.upgradeTroops()`——全游戏存兵都用 `{ type, tier }` 这个形状，界面的 `v-for` key 与数量步进器也由它构成。

It also needs a sprite named after the family under `public/pixel/unit/` (use `TYPE_SPRITES` in `units.js` to map
ranks 1–2 and 3–4 to different art) and an entry in `SPRITE_CATEGORY`, see 「美术素材」below.
它还需要一张以家族 key 命名的 `public/pixel/unit/` 素材（用 `units.js` 里的 `TYPE_SPRITES` 把 1–2 档和 3–4 档映射到不同素材），并在 `SPRITE_CATEGORY` 里登记，见下文的「美术素材」。

Old saves that still hold pre-standard keys (`infantry`, `veteran`, `marksman`, `knight`) are rewritten by
`normalizeTroops()` in `units.js`; add an entry to `LEGACY_TYPES` there whenever a family is renamed.
仍保存着旧 key（`infantry`、`veteran`、`marksman`、`knight`）的旧存档由 `units.js` 里的 `normalizeTroops()` 改写；以后若再改名，记得往那里的 `LEGACY_TYPES` 补一条。

### 美术素材 · Pixel art assets

Every sprite is a 32x32 PNG under `public/pixel/<category>/`, generated by `tools/pixel-assets/generate.mjs`,
which draws through the Pixelorama bridge registered as the `pixelorama` server in the repository root `.mcp.json`
(Pixelorama must be open and listening on `127.0.0.1:7373`).
所有素材都是 `public/pixel/<分类>/` 下的 32×32 PNG，由 `tools/pixel-assets/generate.mjs` 生成；该脚本通过仓库根目录 `.mcp.json` 里注册的 Pixelorama 桥接作画（需要 Pixelorama 处于打开状态并监听 `127.0.0.1:7373`）。

```bash
node tools/pixel-assets/generate.mjs                    # 全部素材 every asset
node tools/pixel-assets/generate.mjs unit commander     # 只画某些分类 only these categories
node tools/pixel-assets/generate.mjs militia            # 只画一张 a single sprite
```

| 分类 Category | 素材 Sprites |
| --- | --- |
| `unit/` | 四个家族各两档外观加领主：militia、spearman / spearman-elite、archer / marksman、cavalry / knight、lord |
| `settlement/` | town, village |
| `commander/` | 三个势力的地图将领：bandit（灰色蒙面）、wolf（紫袍狼纹盾）、eagle（骑马披风骑士） |
| `terrain/` | 地形装饰与地图标记：forest, mountain, water, desert, camp（扎营的帐篷与篝火） |

Faction commander art takes its cloth colour from `src/game/factions.js`, which the generator imports directly, so
the sprite, the legend swatch and the minimap dot are all one value.
势力将领素材的衣色取自 `src/game/factions.js`（生成脚本直接 import 该文件），因此素材、图例色块与小地图圆点是同一个值。

Unit art is **two looks per family plus rank pips**: ranks 1–2 use the basic sprite, ranks 3–4 the elite one, and
the arena draws 1–4 small pips over each soldier so the exact rank stays readable — `unitSprite(type, tier)` in
`src/game/units.js` is the one place that decides this.
兵种素材是**每家族两档外观 + 档位血点**：1–2 档用普通外观，3–4 档用精英外观，战场上再在每个士兵头顶画 1–4 个小点，保证档位一眼可辨——判断规则集中在 `src/game/units.js` 的 `unitSprite(type, tier)`。

Art is authored on a 32x32 design grid and exported at `scale: 1`, so the file matches the drawn pixels one to one.
素材在 32×32 的设计网格上绘制，并以 `scale: 1` 导出，因此文件与画出的像素一一对应。

The game only ever draws them at integer scales — nearest-neighbour on canvas, `image-rendering: pixelated` in the
DOM — because a fractional scale is what makes pixel art look blurry. `src/game/pixelAssets.js` is the single place
that maps a unit type, settlement kind, faction or terrain key to its file.
游戏只用整数倍缩放绘制 —— canvas 关闭插值，DOM 用 `image-rendering: pixelated` —— 因为小数缩放正是像素画发糊的原因。单位类型、据点类型、势力与地形键到文件的对应关系集中在 `src/game/pixelAssets.js`。

Adding a sprite: add a painter to `buildAssets()` in `generate.mjs`, give it a name, register that name in
`SPRITE_CATEGORY`, then re-run the generator. Keep it one pixel clear of the canvas edge, otherwise the outline
pass clips the silhouette.
新增素材：在 `generate.mjs` 的 `buildAssets()` 里加一个绘制函数并起名，把名字登记到 `SPRITE_CATEGORY`，然后重新运行脚本。素材要与画布边缘留出 1 像素，否则描边会被裁掉。

The generator owns the silhouette outline, the shared body plan of the units and the palette, so a change to one
pawn reads across the whole roster; `UNIT_ART` in `generate.mjs` is the table that gives each sprite its cloth,
helmet and weapon, and `COMMANDERS` does the same for the three map commanders, which layer on that same body plan
(hood + mask, cape + wolf-marked shield, mounted lancer).
生成脚本统一负责描边、各单位共用的身体结构与配色，因此改一处就能让整套兵种保持一致；`generate.mjs` 里的 `UNIT_ART` 就是给每张素材指定衣色、头盔与武器的表，`COMMANDERS` 则用同一套身体结构规定三位地图将领（连帽蒙面、披风加狼纹盾、骑马枪骑）。

### 新增地形 · Add terrain

Add the type to `TERRAIN` in `src/game/terrain.js`, give it a base colour in `drawTile()` inside
`src/components/WorldMap.vue`, and add its sprite name to `TILE_DECO` in the same file when it should carry a
pixel-art decoration.
在 `src/game/terrain.js` 的 `TERRAIN` 里加类型，在 `src/components/WorldMap.vue` 的 `drawTile()` 里给它底色；若还需要装饰，把素材名加进同文件的 `TILE_DECO`。

A marker that should also appear on the minimap and the atlas goes into `src/game/atlas.js` — `drawMiniMap()` draws
the tiny version and `drawAtlas()` the draggable one, both from the same world state.
需要同时出现在小地图与全图上的标记请写进 `src/game/atlas.js`：`drawMiniMap()` 画小图、`drawAtlas()` 画可拖动的全图，两者读同一份世界状态。

Note that `TERRAIN_KEYS` order is the serialisation order used by `gridToIds()`, so append new terrain at the end
or old saves will read the wrong ids.
注意 `TERRAIN_KEYS` 的顺序就是 `gridToIds()` 的序列化顺序，因此新地形请追加到末尾，否则旧存档会读错 id。

### 新增战场地形 · Add battlefield terrain

The terrain of a **battle** is a separate table: `ARENA_TERRAIN` in `src/game/arena.js`. One record is enough —
it carries the colour the field is painted with, the speed, attack and defence modifiers it applies and whether
a soldier may walk on it. `generateArenaTerrain()` places the kinds on the field, `damageOf()` reads the ground
under the fighters and `BattleMap.vue` paints the cells.
**战场**的地形是另一张表：`src/game/arena.js` 里的 `ARENA_TERRAIN`。加一条记录就够——它带着这块地皮的颜色、
它给出的速度 / 攻击 / 防御修正，以及士兵能不能走上去。`generateArenaTerrain()` 负责把这些地形摆到战场上，
`damageOf()` 读取交战双方脚下的地形，`BattleMap.vue` 负责把格子画出来。

```js
myterrain: {
  key: 'myterrain',
  name: '沼泽',
  en: 'Marsh',
  color: '#5c6b3a',
  speedMul: 0.6,   // 移动变慢 movement
  atkMul: 0.9,     // 攻击下降 attack
  defMul: 1.05,    // 防御上升 defence
  walkable: true,
  note: '沼泽：移动 −40%，攻击 −10%，防御 +5%。'
}
```

A kind that is not walkable must never stand where an army deploys: `generateArenaTerrain()` clears the
deployment columns, `arenaPath.js` routes a soldier around the water, and the last-resort sideways nudge in
`stepBattle()` still exists, so a fight can never stall.
不可通行的地形不能出现在军队的出发位置上：`generateArenaTerrain()` 会清空出发区域，`arenaPath.js` 会带士兵
绕开水域，`stepBattle()` 里还保留最后一道侧向推开的保险，因此战斗不会卡住。

### 新增难度 · Add a difficulty

The difficulty table is `DIFFICULTIES` in `src/game/difficulty.js`. A record carries the key, the names, the icon,
the pay (`rewardDelta`, `flatReward`, `payMul`, `paperCap`), the start (`startGold`, `startFood`), the running costs
(`foodPerBattle`, `recruitMul`), the enemy numbers (`foeSize`, `foeGrowth`, `foeCap`, `foeTierStart`, `foeTierMax`,
`banditDays`) and the threat curve (`threatWins`, `threatTowns`, `threatCap`). The reward formula reads the pay
through `rewardFor(question, difficulty)`; the quiz settlement reads the cap; the battle store reads the food; the
recruit list reads the markup; the world store reads the enemy numbers and the threat. A new difficulty therefore
needs no other code change — but it should also be added to the two pickers (the home screen and the world map
sheet) if it is meant to be visible.
难度表是 `src/game/difficulty.js` 里的 `DIFFICULTIES`。一条记录包含 key、名称、图标、收入（`rewardDelta`、
`flatReward`、`payMul`、`paperCap`）、开局（`startGold`、`startFood`）、运行成本（`foodPerBattle`、
`recruitMul`）、敌军参数（`foeSize`、`foeGrowth`、`foeCap`、`foeTierStart`、`foeTierMax`、`banditDays`）以及
威胁曲线（`threatWins`、`threatTowns`、`threatCap`）。奖励公式通过 `rewardFor(question, difficulty)` 读收入，
试卷结算读封顶，战斗 store 读军粮，招募列表读加价，世界 store 读敌军与威胁。因此新增难度不需要改其他代码——
但若要让人看到它，还需要把它加进两个选择器（首页与世界地图的难度面板）。

### 版本与更新内容 · Version and changelog

The version and the update notes live in `src/game/versions/`: `index.js` exports `VERSION`, `VERSIONS` / `CHANGELOG`
and the helpers, one file per release (`v0.0.1.js`, …) holds the batches of that release, and `batches.js` is the
generated list of every shipped batch.
版本号与更新内容都写在 `src/game/versions/`：`index.js` 导出 `VERSION`、`VERSIONS` / `CHANGELOG` 与辅助函数，
每个发布版本一个文件（`v0.0.1.js` …）写着这次发布的批次，而 `batches.js` 是所有已发布批次的生成结果。

Releasing a new build is three edits:
发布一个新版本只要动三处：

1. raise `VERSION` to the next patch number — `nextPatchVersion(VERSION)` gives it, and only the last digit moves;
   把 `VERSION` 改成下一个修订号（`nextPatchVersion(VERSION)` 可以算出来，目前只加最后一位）；
2. add a release file `v0.0.2.js` (with its `version`, `date`, `title`, `summary` and `batches`) and list it in
   `VERSIONS`;
   新增一个发布文件 `v0.0.2.js`（写上 `version`、`date`、`title`、`summary` 与 `batches`），并把它加进 `VERSIONS`；
3. write the shipped work down in `progress.md` and run `node tools/build-versions.mjs` to regenerate
   `src/game/versions/batches.js`, then note the release in `README.md`.
   把这次的工作写进 `progress.md`，运行 `node tools/build-versions.mjs` 重新生成 `src/game/versions/batches.js`，
   再在 `README.md` 里记一笔。

Nothing else has to change: the home screen reads the module, so the badge and the update notes follow the number
on their own.
其它地方都不用动：首页读的就是这个模块，版本号与更新内容会自己跟着变。

### 题库扩展 · Question mods

Every subject is a **mod**, the five built-ins included, and both paths use the same contract — so adding a
subject never touches `ExamModal.vue`, the reward formula or the save format.
每个科目都是一个 **mod**（五个内置科目也一样），两条扩展路径共用同一套契约——因此新增科目不需要改 `ExamModal.vue`、奖励公式或存档格式。

A mod is one object (JavaScript) or one JSON file:
一个 mod 可以是一个 JS 对象，也可以是一个 JSON 文件：

| 字段 Field | 必填 Required | 说明 Meaning |
| --- | --- | --- |
| `key` | 是 Yes | 唯一 id，正则 `[a-z0-9-]`，同时作为题目的 `type` 与存档 key 前缀。Unique id (`[a-z0-9-]`), also the question `type` and the save-key prefix. |
| `name` | 否 No | 中文界面名。Chinese label. 缺省用 `key`。 |
| `en` | 否 No | 英文名。English label. |
| `icon` | 否 No | 一个 emoji，考试界面的科目按钮用。One emoji for the subject button. |
| `grades` | 否 No | 适用年级，默认 `[3, 4]`。Supported grades, `[3, 4]` by default. |
| `items` / `questions` | 否 No | 声明式题列表（两个字段名等价）。Declarative question list (the two names are aliases). |
| `kinds` | 否 No | 生成器函数 `(grade) => [{ kind, make(rng, grade) }]`，只能写在 JS 包里。Generator templates, JavaScript packs only. |

At least one valid item or one generator is required, otherwise the pack is rejected.
至少有一条合法题目或一个生成器，否则整个包会被拒绝。

Each declarative item is:
每条声明式题目包含：

| 字段 Field | 必填 Required | 说明 Meaning |
| --- | --- | --- |
| `id` | 是 Yes | 包内唯一且**永不变更**：它就是记忆曲线的 key。Unique in the pack and **never renamed** — it is the memory-curve key. |
| `grade` | 否 No | `3` 或 `4`，缺省取 `grades[0]`。`3` or `4`, defaults to `grades[0]`. |
| `prompt` | 是 Yes | 题干。Question text. |
| `options` | 四选一时是 Yes for a multiple choice | 至少 2 个互不重复的非空选项；超过 4 个时只取正确答案加 3 个干扰项。At least 2 unique non-empty options; extras beyond four are dropped. |
| `answer` | 四选一时是 Yes for a multiple choice | 正确选项的下标（从 0 开始）。Zero-based index of the correct option. |
| `explain` | 否 No | 答错时显示的解析。Shown under a wrong answer. |

A question can also have another **shape**, in which case the fields above change:
题目也可以是别的**形状**，这时上面的字段会换掉：

| 形状 Shape | 字段 Fields | 说明 Meaning |
| --- | --- | --- |
| 填空 Filled in | `input`（`number` 或 `text`）+ `answer`（字符串或字符串数组） | 孩子把答案写出来；数字按数值比对，文字忽略大小写与空格。The child types the answer; a number is compared by value, a word without its case or spaces. |
| 配对 Matching | `pairs`（`[[左, 右], …]`，至少两组） | 把左右两栏连起来；右栏每次出现都会打乱。Connect the two columns; the right column is shuffled every time. |
| 排序 Ordering | `items`（按正确顺序给出，界面会打乱） | 把项目按顺序点出来。Tap the items in the right order. |

```json
{
  "key": "safety",
  "name": "安全常识",
  "en": "Safety",
  "icon": "🚦",
  "grades": [3, 4],
  "questions": [
    {
      "id": "electric-shock",
      "grade": 3,
      "prompt": "发现有人触电，首先应该怎么做？",
      "options": ["直接用手去拉他", "先切断电源", "站在原地大声呼喊", "用水泼向他"],
      "answer": 1,
      "explain": "先断电再施救，否则自己也会被电到。"
    }
  ]
}
```

**External pack · 外部题库包** — drop the file into `public/mods/`, then list it in `public/mods/index.json`:
将文件放进 `public/mods/`，再在 `public/mods/index.json` 里登记：

```json
{ "mods": ["safety.json"] }
```

`main.js` calls `ensureModsLoaded()` at boot and the exam awaits the same promise before drawing a paper, so a
large pack cannot produce a short paper; each file may hold one mod or `{ "mods": [ … ] }`.
`main.js` 在启动时调用 `ensureModsLoaded()`，考试出卷前会等待同一个 Promise，因此大题库包不会导致卷子题目不足；每个文件可以是一个 mod，也可以是 `{ "mods": [ … ] }`。

Registration is first-wins: a duplicate `key` is rejected, a file that fails to parse is skipped, and the built-ins
are always registered before any external pack. To try a pack without writing a file, paste it in the console:
注册是先到先得：重复 `key` 会被拒绝，解析失败的文件会跳过，内置科目永远先于外部包注册。想不落盘就试一个包，可在控制台执行：

```js
kidsWarGame.loadModsFromText('{"key":"my-pack","name":"我的题","grades":[3],"items":[{"id":"a1","prompt":"1 + 1 = ?","options":["1","2"],"answer":1}]}')
```

**Built-in generators · 内置生成器** — `english.js`、`math.js`、`logic.js`、`chinese.js` export a type table
(`ENGLISH_TYPES` etc.); add a function there and it becomes a `kind` of that subject automatically. The kind is the
name the generator gives its questions — the `kind` field in the question it returns — so it stays the same in every
build and it is the memory key: renaming a generator resets its curve. `encyclopedia.js` is declarative and
demonstrates the item path.
`english.js`、`math.js`、`logic.js`、`chinese.js` 各导出一张题型表（`ENGLISH_TYPES` 等），往里加一个函数就会自动成为该科目的一个 `kind`。kind 取的是生成器写在题目里的那个 `kind` 名字，因此任何构建里都稳定，它同时就是记忆 key——重命名生成器会让这条曲线归零。`encyclopedia.js` 是声明式写法，可作为题目路径的范例。

> The kind used to be the name of the function, which a production build could shorten — that changed the memory
> curve of every question. The generator table now reads the kind from the question itself, so the curve survives a
> release. `src/game/quiz/mods.js` is the one place that decides this.
> kind 过去取自函数名，而生产构建会压缩函数名 —— 那会改掉每道题的记忆曲线。现在生成器表改从题目自身读 kind，因此曲线能跨版本保留；决定这件事的地方只有 `src/game/quiz/mods.js` 一处。

Every generator must return the `choice()` shape (`prompt`, `options`, `answer` index, `explain` optional),
because the exam UI and the reward formula read only those fields; `choice()` keeps at most three distractors, so
every question has 2–4 options.
每个生成函数必须返回 `choice()` 的形状（`prompt`、`options`、答案下标 `answer`，`explain` 可选），因为考试界面和奖励计算只读这些字段；`choice()` 最多保留 3 个干扰项，因此每道题都是 2–4 个选项。

The Chinese bank shows the two shapes a bigger subject needs. `POEM_BANK` holds one record per poem (title,
author, dynasty, theme and the lines), and every poem question is generated from it, so a new poem only means a
new record. `PASSAGES` holds the reading passages, each with its own questions; the passage text is prepended to
the prompt, and the exam styles the question box with `white-space: pre-wrap` so the passage keeps its breaks.
语文题库展示了大型科目需要的两种写法。`POEM_BANK` 每首诗一条记录（诗题、作者、朝代、主题与诗句），
所有古诗题都由它生成，加一首诗就是加一条记录；`PASSAGES` 存放阅读短文与各自的题目，
短文会被拼进题干，考试界面的题目框用 `white-space: pre-wrap` 保留换行。

A generator needs a **bank of at least four items**, otherwise a paper would repeat the same prompt; the
`tools/verify-chinese.mjs` check enforces that.
每个生成函数的题库**至少要有四条**，否则一份卷子会重复出题；`tools/verify-chinese.mjs` 会守住这条线。

### 新增势力 · Add a faction

Add it to `FACTIONS` and `NPC_FACTIONS` in `src/game/factions.js`; `buildParties()` will then spawn its warbands
clustered around anchors automatically.
在 `src/game/factions.js` 的 `FACTIONS` 和 `NPC_FACTIONS` 里加一项，`buildParties()` 就会自动围绕锚点成团生成它的部队。

A hostile faction also needs a voice at the meeting and a face on the card: add an `ENCOUNTER_TALK` record in
`src/game/encounter.js`, register its commander sprite in `SPRITE_CATEGORY` (`src/game/pixelAssets.js`) and draw the
32×32 PNG with `tools/pixel-assets/generate.mjs`. Without them the meeting falls back to the bandit lines and shows
no portrait.
敌对势力还需要在遭遇对话框里说话、有张脸：在 `src/game/encounter.js` 的 `ENCOUNTER_TALK` 里加一条台词记录，
把它的将领素材登记到 `SPRITE_CATEGORY`（`src/game/pixelAssets.js`），并用 `tools/pixel-assets/generate.mjs`
画出那张 32×32 的 PNG。缺了这些，对话框会退回强盗台词，头像也不会显示。

### 新增设施 · Add a facility

Facilities live in `FACILITIES` in `src/game/settlement.js`. One entry is enough: the town panel renders the list
from that table, `facilityCost()` prices the next level, and the effect is read by the systems that care about it
(the hospital by `healRate()` and `survivalChance()`, the barracks by `armyBonusOf()`).
设施写在 `src/game/settlement.js` 的 `FACILITIES` 表里。一条记录就够：城镇面板按这张表渲染，
`facilityCost()` 负责算下一级的价钱，效果则由关心它的系统读取（医院给 `healRate()` 与 `survivalChance()`，
军营给 `armyBonusOf()`）。

A new facility therefore needs three things: the table entry, a line in the effect table above, and the place
that reads it — for example `battle.start()` already adds `world.armyBonus` to the attack and defence of the army.
因此新增一种设施需要三件事：表里加一条、上面那张效果表加一行，以及真正读取它的地方 ——
例如 `battle.start()` 已经把 `world.armyBonus` 加到全军的攻击与防御上。

### 存档兼容 · Save compatibility

Anything added to the world state must also be written in `persistGame()` (`src/composables/gameState.js`) and
read back in `loadGame()` (`src/game/save.js`), otherwise it will be lost on reload.
任何加进世界状态的数据，都必须在 `persistGame()`（`src/composables/gameState.js`）里写出，并在 `loadGame()`（`src/game/save.js`）里读回，否则刷新后就会丢失。

### 自检脚本 · Self-check scripts

The game has a set of dependency-free checks under `tools/`, all runnable with plain `node`
(they bundle the Vue sources with the esbuild that already ships with Vite, so no test framework is needed).
游戏在 `tools/` 下有一组零依赖的自检脚本，直接用 `node` 跑即可（它们用 Vite 自带的 esbuild 打包 Vue 源码，不需要测试框架）。

| 命令 Command | 作用 What it does |
| --- | --- |
| `node tools/verify-upgrade.mjs` | 99 项检查：每条升级边的 `type` / `tier` / 价格、民兵 → 三个家族、家族内升档、非法边被拒、钱不够不动兵，以及界面那条「把边的 `type`/`tier` 原样喂回 store」的路径。99 checks: every edge's `type` / `tier` / price, militia into the three families, rank climbs inside a family, illegal edges refused, a broke lord keeping his soldiers, and the exact panel path that feeds an edge's `type` / `tier` back into the store. |
| `node tools/verify-chinese.mjs` | 32 项检查：语文题型齐全（阅读理解 + 6 种古诗题）、年级内题型名唯一（它们是记忆曲线的 key）、上千道采样题全部合法（2–4 个选项、答案在选项里、题干不重复）、短文带着全文且长度适合手机。32 checks: the Chinese types are complete (reading comprehension plus six poem types), the type names are unique per grade (they are the memory-curve keys), a thousand sampled questions are all well formed (2–4 options, the answer among them, no repeated prompt) and the passages carry their text at a phone-friendly length. |
| `node tools/verify-settlements.mjs` | 131 项检查：据点归属（强盗不占城镇）、驻军、`{ type, tier, count, hp }` 形状与旧档迁移、恢复速率、战败存活判定、围城（天数 / 时钟 / 援军 / 占领）、强盗村庄、城镇经济（考试 → 资金 + 发展 → 繁荣度 → 等级）、设施与更高等级的兵源，以及城镇慢钟（60 秒 = 1 游戏小时）。131 checks: settlement ownership (no bandit town), garrisons, the `{ type, tier, count, hp }` shape and its migration, the recovery rates, the survival roll, sieges (days / clock / relief / capture), the bandit village, the town economy (exam → funds + development → prosperity → level), the facilities and the richer recruit list. |
| `node tools/verify-upgrade-head.mjs` | 同一套升级检查跑在修复前的源码上（`291eddaa81d`），用来复现旧缺陷：升级后会写入一个没有 `type` 的兵员，界面回退显示成民兵，并且只扣 8 金币保底价。The same upgrade suite against the pre-fix sources (`291eddaa81d`), reproducing the old defect: a soldier with no `type` is written, the panel falls back to militia, and only the 8-gold floor is charged. |
| `node tools/verify-upgrade-browser.mjs` | 真实 Chrome（headless + CDP）走一遍界面：预置一份站在村庄旁的存档，进村、打开「升级」页签、真的点「升级」按钮，再读回 DOM 与金币。Real Chrome (headless over CDP) walks the interface: a save with the lord next to a village, into the village, the 升级 tab, a real click on 升级, and the DOM and treasury read back. |
| `node tools/verify-settlements-browser.mjs` | 真实 Chrome 走一遍据点玩法：地图上的归属光环、角色面板里的伤兵、赶走强盗、准备围城并攻打城镇，以及城镇面板（等级 / 繁荣度 / 资金 / 建医院 / 注入资金 / 投入发展）。Real Chrome walks the settlement features: the ownership ring on the map, the wounded in the lord panel, driving off bandits, preparing a siege and storming the town, and the town panel (level / prosperity / funds / building a hospital / injecting money / investing). |
| `node tools/verify-battle.mjs` | 168 项检查：难度（三种难度的金币、科目加成、开局资源、军粮、招募价、威胁与敌军成长、存档读写）、战斗速度（默认慢速、慢速推进更少）、**开局对峙**（双方先驻守、敌军 5 秒后变阵 / 再 2.4 秒后冲锋、先动手会立刻引来应战、全军出击一次下令、练兵没有对峙）、**每战一张新地图**（12 个种子给出 12 张不同布局、同种子可复现、每张都含五种地形、湖泊不贴边也不进列阵区、六种预设各自仍有该有的地形、没有士兵开局站在深水里）、战场地形（五种地形的生成与效果、湖泊不可通行、森林减速、森林减伤）、**绕湖寻路**（直线被湖挡住、A* 找到干路、路径与平滑后都在陆地上、撤退方向不进水）、**反击与队形**（士兵记住攻击者、转身还手、挨打掉血；攻击时队形保持、各排仍有距离、两边都有伤亡）、**远程不再钻墙角**（角落里的后撤方向不出界、不往墙里退、不穿过敌人、不会来回犹豫，开阔地仍然直线后退；4 名弓箭手被压进角落 2.5 秒内要离开至少 60 px）、十二场战斗都能分出胜负，以及围城（可中断、失败后要重新准备、打赢后占领）；**冲锋与齐射**（战场面积约为旧场的两倍且格子跟随、远处的近战 1 秒走出 100 px 以上并掉体力、停下命令立刻取消冲刺、2.5 秒后疲劳、齐射后的弓箭手 1 秒只走不到正常时的 80%、射击点亮减速计时、20 px 内无法开弓）。168 checks: the difficulty (the gold of the three levels, the subject bonus, the opening resources, the food, the recruit markup, the threat and the enemy growth, the save round trip), the battle speed (slow by default, the slow speed advances less), **the opening standoff** (both armies hold, the enemy dresses its ranks after five seconds and charges 2.4 seconds later, a first strike brings the answer at once, the charge button orders everyone, a drill has no standoff), **a new field for every battle** (twelve seeds give twelve different layouts, the same seed rebuilds the same map, each holds all five kinds of ground, the lake never touches the edge or a deployment band, the six presets keep their own ground and nobody starts in deep water), the battlefield terrain (all five kinds are generated, the lake is impassable, the forest slows a soldier down and takes less damage), **the path around a lake** (the straight line is blocked, A* finds a dry route, the raw and the smoothed path stay on land, the retreat does not back into water), **the counterattack and the formation**, **the cornered skirmisher** (the retreat stays inside the field, does not back into the wall, does not run through the foe and does not dither between two walls, while an open field still falls back straight away; four archers pressed into a corner get at least 60 px clear within 2.5 s), twelve battles that always end, and the sieges; **the charge and the volley** (the field covers about twice the old area with the grid following it, a distant melee soldier covers over 100 px in one second while its stamina falls, a hold order cancels the sprint, the burst is spent after 2.5 s, an archer slowed by a volley covers under 80 percent of its normal ground, a shot lights the slow clock, and a foe 20 px away cannot be shot). |
| `node tools/verify-difficulty.mjs` | 58 项检查：普通档保留原来的 5 / 8 / 12 题收入（239 / 410 / 677），困难约为普通的 74%，简单档整卷封顶（50 / 80 / 120），三档的单价、开局资源、军粮与招募价单调递增；威胁随胜场与城镇上升、按档封顶且永不低于 1；同一种子的世界在困难档敌军更多、简单档更少；城镇招募价与旧档迁移；以及世界每天真的按难度与威胁补兵、封顶生效。58 checks: normal keeps the shipped 5 / 8 / 12 question payouts (239 / 410 / 677), hard pays about 74% of normal, the practice paper is capped (50 / 80 / 120), and the price, the starting resources, the food and the recruit markup rise monotonically; the threat rises with wins and towns, is capped per level and never falls below 1; the same world seed fields more enemies on hard and fewer on easy; the town prices and the old-save migration; and the world really reinforces by the difficulty and the threat, with the ceiling holding. |
| `node tools/verify-battle-mobile-browser.mjs` | 真实 Chrome 用 **390 × 844（dpr 3、触摸）** 的手机视口进一场真实战斗：页面不滚动、画布满屏、顶栏与工具不重叠也不出界、顶栏文字不被截断、两条栏之间留出 **580 px（69%）** 净空、命令栏不超过屏幕三分之一、每个按钮 ≥38 px、开局两支军队全部在画面内（缩放 0.42）、手指拖动平移镜头、左右边缘各留出 **140 px** 外围空地、点 🎯 恢复跟随；换成快速战斗（多一个「← 返回」，工具最宽）后顶栏仍不被工具压住、文字不被截断、返回按钮留在屏幕内；控制台 0 报错（24 项）。Real Chrome enters a real battle with a **390 x 844 (dpr 3, touch)** phone viewport: no page scroll, the canvas fills the screen, the top bar and the tools neither overlap nor leave the screen, the top-bar text is not clipped, **580 px (69 percent)** of clear field sits between the bars, the command bar stays under a third of the screen, every button is at least 38 px, both armies are on screen at the opening (zoom 0.42), a finger drag pans the camera, each side leaves **140 px** of ground past the edge, 🎯 restores the follow, a quick battle (the extra back button makes the tools widest) keeps the top bar clear, unclipped and the back button on screen, and the console stays clean (24 checks). |
| `node tools/verify-battle-browser.mjs` | 真实 Chrome 走一遍新功能：首页的难度选择、世界地图的难度面板与「取消围城」按钮、**战斗开局**（双方驻守 + 「⚔️ 全军出击」提示条，点一下全军出击）、战斗界面的速度按钮与地形说明、帧率芯片、**真的用鼠标拖动和触摸拖动战场**（镜头跟着动、自动跟随停止、指挥官不动）、轻点仍然移动指挥官、点 🎯 恢复跟随、真的执行一次 `history.back()` 确认战斗没有被退出，命令栏透明而按钮各自带面板、控制台 0 报错、敌将倒下后双方退回战场、士兵打光后的孤军奋战与「撤退」按钮（76 项）；点下「⚔️ 全军出击」后还会确认对峙提示条真的从 DOM 里消失。Real Chrome walks the new features: the difficulty picker on the home screen, the difficulty sheet and the 「取消围城」 button on the world map, **the battle opening** (both armies holding with the 「⚔️ 全军出击」 banner, and a real click on it that clears the banner from the DOM), the speed buttons and the terrain legend on the battle screen, the frame-rate chip, **a real mouse drag and a real touch drag** (the camera moves, the auto-follow stops, the commander stays put), a tap that still moves the commander, the 🎯 recentre, a real `history.back()` proving the battle is not left, a clear command bar with panels on its buttons, a clean console, the fall of a hostile general taking both sides back to the field, and a warband wiped to the last man holding a last stand with its 撤退 button (76 checks). |
| `node tools/verify-perf-browser.mjs` | 真实 Chrome 开一场 400 v 400（800 名士兵）的快速战斗，等双方接战后再采样 6 秒 `requestAnimationFrame`：断言至少 30 帧、95% 的帧不超过 50 ms，并确认阵亡让存活数下降、命令栏的 `stamp` 在前进、顶部兵力文字发生变化、画布不是空白、控制台 0 报错（9 项）。Real Chrome opens a 400 v 400 quick battle (800 soldiers), waits for the armies to meet, then samples `requestAnimationFrame` for six seconds: at least 30 frames and 95% of frames under 50 ms, with the alive count falling, the command bar's `stamp` advancing, the strength text changing, the canvas painted and the console clean (9 checks). |
| `node tools/verify-training-browser.mjs` | 真实 Chrome 走一遍新功能：首页显示版本号、点徽章展开更新内容；世界地图上**没扎营时没有「练兵」按钮**、扎营后出现；点进去后战斗界面写着「🎯 练兵」、对面是训练木桩、store 认得出这是训练、没有敌人、**没有胜负**、金币 / 军粮 / 队伍都不变；木桩真的挨打而士兵毫发无伤；点「🏕 结束练兵」回到世界地图，营地还在，控制台 0 报错。Real Chrome walks the new features: the home screen shows the version and the badge opens the update notes; the world map has **no drill button before the camp** and one after it; inside, the battle screen reads 「🎯 练兵」, the other side is the wooden dummies, the store knows it is a drill, there is no enemy, **no outcome**, and the purse, the food and the warband do not move; the dummies really take the blows while the soldiers stay untouched; 「🏕 结束练兵」 returns to the world map with the camp still pitched, and the console stays clean. |
| `node tools/verify-encounter.mjs` | 50 项检查：遇敌时**不直接开战**而是停下世界、对话内容（势力口气 / 敌军名册 / 双方兵力）、三种选项、逃跑只落在**走得到、站得住的 3–6 格**且不损兵不花钱、冷却按游戏时间计（冻结时也不走）、扎营被打断、喊话只换台词，以及「开战」把刚才那支队伍带进战场。50 checks: a meeting **never drops straight into battle** but freezes the world, the card carries the faction voice / the roster / both army sizes, the three choices all resolve, running lands on a **reachable tile 3–6 away** for free, the cooldown runs on game time (and pauses with the frozen clock), camping is broken, talking only swaps lines, and 开战 throws exactly that party into the arena. |
| `node tools/verify-companions-browser.mjs` | 真实 Chrome 验证两项世界地图优化：**详细全图上带兵的随从**在图标右上角画出兵力徽章（和领主、敌将同一枚，小一号；没分到兵的不挂），以及**世界上方每一块控件**——状态栏的芯片与按钮、小地图按钮、图例和图例的「收起 / 展开」——都是同一块黑色透明玻璃、悬停只加深黑色；顺带保存世界地图与全图的截图（14 项）。Real Chrome checks the two world-map optimisations: **a companion with soldiers** carries his troop badge in the top-right corner of his sprite on the detailed atlas (the lord's and the commanders' own badge, one size smaller; a soldier-less companion carries none), and **every control above the map** — the top-bar chips and buttons, the minimap button, the legend and its toggle — is the same translucent black glass with a hover that only deepens the black; it also saves screenshots of the world map and the open atlas (14 checks). |
| `node tools/verify-encounter-browser.mjs` | 真实 Chrome（headless + CDP）走一遍遭遇：预置一支贴着主角的强盗，读回对话框（头像 / 名册 / 三个按钮）且**没有进战斗**；连点两次「喊话」换台词；点「逃跑」后对话框关闭、冷却生效、主角离敌人更远且没损失；再点「开战」真的进战场且敌人就是那支队伍，控制台 0 报错。Real Chrome (headless over CDP) walks a meeting: a bandit party seeded beside the lord brings up the card (portrait / roster / three buttons) with **no battle started**; two 喊话 taps swap the lines; 逃跑 closes the card, arms the cooldown, moves the lord farther away and loses nothing; 开战 really enters the arena with that same party, and the console stays clean. |
| `node tools/verify-chinese-browser.mjs` | 真实 Chrome 考一张只选「语文」的卷子，走完全部题目并读回题干：卷子里要有**阅读理解短文**与**古诗题**，短文保持换行、同一份卷子里没有重复题目、控制台 0 报错。Real Chrome takes a Chinese-only paper, walks every question and reads the prompts back: the paper must carry a **reading passage** and an **ancient-poem question**, the passage keeps its line breaks, no question repeats inside one paper and the console stays clean. |
| `node tools/verify-quick-battle-browser.mjs` | 真实 Chrome 走一遍新功能：首页的「⚡ 快速战斗」与开始 / 继续按钮**同级**；点版本徽章弹出**更新对话框**（写着版本号、列出批次、**没有任何开发细节**）、关闭后消失；快速战斗页有六种战场、四档规模、四个己方整队与三个敌方势力，**八个兵种各有加减键和滑杆**（滑杆上限 100，能加也能清零）；选好后点「⚡ 进入战场」，**真的站上战场** —— 顶栏写着「⚡ 快速战斗」、双方兵力与所选一致、小队可选、命令照常下达；控制台 0 报错。Real Chrome walks the new features: the 「⚡ 快速战斗」 entry sits **on the same level** as the start / continue buttons; tapping the version badge opens the **update dialog** (the version, the batches and **no development details** at all) and it closes again; the quick battle screen offers six battlefields, four sizes, four friendly bands and three enemy factions, and **each of the eight kinds has a stepper and a slider** (the slider tops out at 100 and can also clear the count); after the picks, 「⚡ 进入战场」 **really puts the lord on the field** — the bar reads 「⚡ 快速战斗」, both armies match the choice and the orders work, with a clean console. |
| `node tools/verify-quick-battle.mjs` | 58 项检查：六种战场预设各生成正确的地形、湖泽的深水不可通行；**每个兵种的数量可以任意设置**（清零、加满、缩放时配比不变、每种封顶 100）且每人满血；四个己方整队与三个敌方势力的配比都对；`battle.startQuick()` 用选好的队伍与战场开战，**战斗真的会分出胜负并结算**，而**战役数据纹丝不动**；五场模拟的胜 / 负 / 平相加等于场次、胜率与胜场一致；模拟足够快。58 checks: every battlefield preset lays out the right ground and the deep water of the lake map is impassable; **the count of every kind can be set freely** (cleared, filled, scaled with the mix kept and capped at 100) and every soldier starts healthy; the four friendly bands and the three enemy mixes are right; `battle.startQuick()` opens the fight with the chosen armies on the chosen field, **the fight really ends and settles** and **the campaign data does not move**; the wins, losses and draws of five rounds add up and the win rate follows the wins; and the simulation is quick. |
| `node tools/build-versions.mjs` | 从 `progress.md` 的「## 2. 已完成功能」一节重新生成 `src/game/versions/batches.js`，并打印解析到的每个批次。Regenerates `src/game/versions/batches.js` from the 「## 2. 已完成功能」 section of `progress.md` and prints every batch it found. |
| `node tools/verify-general.mjs` | 150 项检查：亲兵确实是从自己队伍里抽出的 4 名近战士兵（不会凭空多出人、小队伍按比例少抽、至少留下一支小队）；有亲兵的主将**一下都挨不到**，伤害由亲兵接下，亲兵死光后主将才掉血；敌将被打到 0 点**立刻结束战斗**并计入 `generalDowns`，敌人队伍还留在场上；领主被打到 0 点**当场判负**；一场战斗结束后双方都退回地图上**刚刚战场周围**（3–7 格内、可走地面、不会瞬移到别的城镇），敌人的队伍还在、冷却几秒就能再追上来；敌将倒下时一个兵都不散、领主也不回满；主将走到敌人身边会自动出手；亲兵一路跟着自己的主将；主将血量的上下限、半血恢复、按真实时间回血（路上 / 据点 / 自己的城镇 / 医院逐级更快）、存档往返；胜场只是带着伤走出战场；界面确实显示两条主将血条、敌将、敌将倒下的结算与退回战场的说明。150 checks: the bodyguard really is four melee soldiers taken out of that side's own warband (nobody appears out of thin air, a small army yields fewer and always keeps a squad); a guarded general **cannot be hit at all** — the damage lands on a guard — and only bleeds once the guards are gone; a hostile general at zero hit points **ends the battle on the spot**, is counted in `generalDowns`, and leaves his warband standing; the lord at zero **loses the battle on the spot**; after any such battle both sides come back to the map **around the field they fought on** (within 3–7 tiles, on walkable ground, never teleported to another town), the enemy warband is still there and free to chase within seconds; an enemy general going down costs the lord not one soldier and does not restore his health; a general swings at whatever comes in reach; the bodyguard keeps station around its general; the lord health clamps, halves, heals in real time (road / settlement / own town / hospital each faster) and survives a save; a won battle only carries the wound out; and the interface really shows both bars, the hostile general, the fall of a general and the fall back to the field. |
| `node tools/verify-training.mjs` | 62 项检查：版本号格式与更新内容（首个版本是 v0.0.1、只更新修订号、最新条目就是当前版本、更新内容由 `progress.md` 生成）、练兵场（只有自己的士兵与训练木桩、没有敌人、训练不会结束、士兵不会受伤、木桩挨打后会自己立起来）、练兵对战役零影响（金币 / 军粮 / 队伍 / 战绩都不变），以及界面上确实有版本号、练兵按钮与「结束练兵」按钮。62 checks: the version format and the update notes (the first release is v0.0.1, only the patch moves, the newest entry is the current version, the notes are generated from `progress.md`), the drill ground (only the lord's own soldiers and the wooden dummies, no enemy, the session never ends, nobody is hurt, the dummies stand back up), that a drill changes nothing in the campaign (purse / food / warband / record), and that the interface really carries the version, the drill button and the end-of-drill button. |
| `node tools/verify-quiz.mjs` | 135 项检查：试卷结算（基础价、连击倍率、全对 ×1.5、长卷 ×1.1、及格加成、**答错不扣钱**）、道具掉落（答对掉军粮、连对 5 题必掉、整科全对掉集市券或征兵令、全对掉战马）、掌握度地图（按科目按年级统计、错题本与复习队列）、复习卷只出指定的题、经验与属性点（及格才给经验、点数可分配、属性效果接进恢复 / 造价 / 围城 / 全军攻击）、里程碑（四个道具按答对数解锁）、以及存档与旧档兼容。135 checks: the paper settlement (the base price, the streak multiplier, ×1.5 for a perfect paper, ×1.1 for a long paper, the pass bonus, **a wrong answer never costs gold**), the gear a paper drops (food for a correct answer, two rations for five in a row, a voucher or a recruit order for a perfect subject, a horse for a perfect paper), the mastery map (per subject and per grade, the mistake book and the review queue), a revision paper that only asks for the wanted questions, the experience and the attribute points (only a passed paper teaches, the points can be spent, the effects reach the recovery, the prices, the siege and the attack of the army), the milestones (the four gears unlock by the number of correct answers) and the save round trip with an old save. |
| `node tools/verify-quiz-browser.mjs` | 真实 Chrome（headless + CDP，1200 × 900）走一遍学习主线：考试设置页有**掌握度地图**与三种卷子（标准 / 只考错题 / 复习队列）；只考错题真的只出错过的题；把一整张卷子全部答对后，结算页出现**连击、全部答对、及格线、掉落道具与经验**，钱袋、经验与背包都真的变了；世界地图上出现**属性点芯片**；角色详情面板列出四个属性、掌握度地图与里程碑，并能真的加一点；市场用**集市券**免费换物资，招募页用**征兵令**免费招两名民兵；控制台 0 报错。Real Chrome (headless over CDP at 1200x900) walks the exam spine: the setup carries the **mastery map** and the three kinds of paper (standard, mistakes, review); a paper of mistakes really holds the mistakes; after a paper answered without a mistake the result page shows the **streak, the perfect bonus, the pass line, the dropped gear and the experience**, and the purse, the experience and the baggage really change; the world map grows an **attribute points chip**; the lord panel lists the four attributes, the mastery map and the milestones, and a point can really be spent; the market pays for one purchase with a **voucher** and the recruits hire two militia with a **recruit order**; the console stays clean. |

The skill `.agents/skills/kids-war-game-testing/` runs all of them in one command:
`node .agents/skills/kids-war-game-testing/scripts/run-checks.mjs --browser`.
技能 `.agents/skills/kids-war-game-testing/` 可以一条命令跑完全部：
`node .agents/skills/kids-war-game-testing/scripts/run-checks.mjs --browser`。

---

## 14. 项目结构 · Project Structure

```
kids-war-game/
├── index.html                  # 入口 HTML，含手机 viewport 设置
├── package.json                # 脚本与依赖
├── vite.config.js              # dev 5180 / preview 4180，@ → src 别名
├── README.md                   # 本文件：游戏介绍与维护指南
├── progress.md                 # 开发进度、已知限制与路线图
├── public/pixel/               # 生成的 32x32 素材：unit / settlement / commander / terrain / ground / town / prop / npc + index.json
├── public/mods/                # 外部题库包：index.json 清单 + 每个科目一个 JSON
├── tools/pixel-assets/
│   ├── pixkit.mjs              # 共用像素工具：桥接、光栅器、调色板与清单合并
│   ├── generate.mjs            # 世界地图素材生成脚本（士兵 / 据点 / 将领 / 地形），经 Pixelorama 桥接作画
│   └── generate-town.mjs       # 城镇场景素材生成脚本（地面 / 建筑 / 道具 / 居民，39 张）
├── tools/verify-chinese.mjs    # 语文题库自检（无头，32 项检查）
├── tools/verify-chinese-browser.mjs # 真实 Chrome 考一张语文卷，读回短文与古诗题
├── tools/verify-chinese.entry.mjs # 语文题库检查的用例
├── tools/make-chinese-save.entry.mjs # 生成「主角站在自己城镇旁」的存档，供语文走查使用
├── tools/verify-upgrade.mjs    # 升级路径自检（无头，99 项检查）
├── tools/verify-settlements.mjs # 据点 / 围城 / 城镇经济 / 城镇慢钟自检（无头，131 项检查）
├── tools/verify-upgrade-head.mjs # 同一套检查跑在修复前的源码上，复现旧缺陷
├── tools/verify-upgrade-browser.mjs # 真实 Chrome 走一遍「升级」界面
├── tools/verify-settlements-browser.mjs # 真实 Chrome 走一遍据点、围城与城镇面板
├── tools/verify-battle.mjs    # 难度 / 战斗速度 / 开局对峙 / 每战一张新地图 / 战场地形 / 绕湖寻路 / 远程后撤 / 冲锋与齐射 / 反击与队形 / 围城中断自检（无头，168 项检查）
├── tools/verify-general.mjs   # 主将与亲兵自检：主将挨打、亲兵挡刀、敌将倒下即结束战斗、士兵打光后的孤军奋战与撤退、领主判负与退回战场、回血速率（无头，150 项检查）
├── tools/verify-general.entry.mjs # 主将与亲兵检查的用例
├── tools/verify-difficulty.mjs # 难度数值、开局、军粮、招募价、威胁与敌军成长自检（无头，58 项检查）
├── tools/verify-battle-browser.mjs # 真实 Chrome 走一遍难度、开局对峙、速度、地形与围城中断
├── tools/verify-battle-mobile-browser.mjs # 真实 Chrome 用 390 × 844 手机视口走一遍战斗 / 快速战斗布局与拖动缓冲（24 项）
├── tools/verify-perf-browser.mjs # 真实 Chrome 采样 800 人战场帧率（≥30 FPS）
├── tools/verify-training.mjs  # 版本号与练兵自检（无头，62 项检查）
├── tools/verify-training-browser.mjs # 真实 Chrome 走一遍版本号与练兵
├── tools/verify-training.entry.mjs # 版本号与练兵检查的用例
├── tools/verify-encounter.mjs # 遇敌对话与逃跑自检（无头，50 项检查）
├── tools/verify-encounter.entry.mjs # 遇敌对话与逃跑检查的用例
├── tools/verify-encounter-browser.mjs # 真实 Chrome 走一遍遭遇对话框（喊话 / 逃跑 / 开战）
├── tools/verify-quick-battle.mjs # 快速战斗模拟器自检（无头，58 项检查）
├── tools/verify-quick-battle.entry.mjs # 快速战斗检查的用例
├── tools/verify-quick-battle-browser.mjs # 真实 Chrome 走一遍更新对话框与快速战斗
├── tools/verify-quiz.mjs    # 学习主线自检：结算、道具、掌握度、经验与里程碑（无头，135 项检查）
├── tools/verify-quiz.entry.mjs # 学习主线检查的用例
├── tools/verify-quiz-browser.mjs # 真实 Chrome 走一遍考试结算、掌握度地图与属性点
├── tools/make-quiz-save.entry.mjs # 生成带记忆曲线与道具的学习主线存档
├── tools/build-versions.mjs   # 从 progress.md 的「已完成功能」一节生成更新内容
├── tools/rewrite-progress-features.mjs # 把「已完成功能」一节改写成「▶ 功能 / 🔧 技术」两类条目
├── tools/verify-upgrade.entry.mjs # 升级检查的用例
├── tools/verify-settlements.entry.mjs # 据点检查的用例
├── tools/verify-battle.entry.mjs # 难度 / 战斗 / 围城检查的用例
├── tools/verify-difficulty.entry.mjs # 难度数值、威胁与敌军成长检查的用例
├── tools/make-save.entry.mjs   # 生成「主角站在村庄旁」的存档，供界面自检使用
├── tools/make-settlement-save.entry.mjs # 生成强盗村庄 / 敌城 / 自有城镇三种存档
├── tools/verify-town.mjs       # 城镇 / 居民 / 委托 / 随从自检（无头，108 项检查）
├── tools/verify-town.entry.mjs # 城镇检查的用例
├── tools/verify-town-browser.mjs # 真实 Chrome 走进城镇、点房屋、点居民、接受委托、招募与分配士兵（29 项）
├── tools/verify-companions-browser.mjs # 真实 Chrome 验证全图随从兵力角标与世界上方统一黑玻璃（14 项）
├── tools/town-scene.entry.mjs  # 把城镇场景在 node 里重建出来，供浏览器检查定位像素
├── tools/reporter.mjs          # 自检脚本共用的输出器
└── src/
    ├── main.js                 # 应用入口：Pinia + Router，预加载像素素材并启动题库 Mod 加载
    ├── App.vue                 # 根容器，承载全局分享弹窗
    ├── router/index.js         # hash 路由：home / world / town / settlement / battle / quick / bank / guide
    ├── styles/global.css       # 主题变量、按钮、面板、手机断点
    ├── composables/
    │   ├── gameState.js        # 新游戏 / 继续 / 持久化
    │   └── share.js            # 分享弹窗的全局开关
    ├── game/
    │   ├── rng.js              # 种子随机 + 值噪声
    │   ├── terrain.js          # 地形定义与序列化映射
    │   ├── difficulty.js       # 难度设置：收入 / 军费 / 敌军三条轴与战役威胁
    │   ├── versions/             # 版本号（只更新修订号）与更新内容：一个发布一个文件，批次由 progress.md 生成
    │   │   ├── index.js          #   VERSION / VERSIONS / CHANGELOG 与辅助函数
    │   │   ├── v0.0.1.js         #   首个版本的更新内容
    │   │   └── batches.js        #   由 tools/build-versions.mjs 从 progress.md 生成
    │   ├── daynight.js         # 昼夜：夜晚占一天的五分之一，黑度与减速系数
    │   ├── encounter.js        # 遇敌对话：三势力台词、敌军名册、逃生点计算与冷却
    │   ├── arena.js            # 战场地形：五种地形、生成、效果与不可通行
    │   ├── arenaPath.js        # 战场寻路：A*、路径平滑、视线与绕湖撤退方向
    │   ├── factions.js         # 势力定义
    │   ├── units.js            # 兵种家族、档位、升级树与升级价格、克制、伤兵与旧存档改写
    │   ├── settlement.js       # 据点归属、驻军、围城常量、城镇经济（繁荣度 / 发展 / 等级）与设施
    │   ├── pixelAssets.js      # 素材清单、预加载与 canvas 绘制助手
    │   ├── recruit.js          # 村庄 / 城镇兵源生成
    │   ├── town.js             # 城镇场景：确定性地块、道路、广场、建筑摆放、可行走判定与场景寻路
    │   ├── followers.js        # 随从在地图上的队形槽位、追赶拖尾与走路起伏
    │   ├── npc.js              # 居民与随从：职业、名字、委托类型与文本、随从带兵上限与转移
    │   ├── atlas.js            # 小地图与详细地图：地形缓存、兵力角标、两个整图画法
    │   ├── worldgen.js         # 世界生成（地形 + 最大连通陆地 + 据点 + 部队）
    │   ├── pathfinding.js      # A* + 二叉堆 + 尽力靠近回退
    │   ├── battle.js           # 战斗模拟（小队、命令、队形、密度、克制、远程风筝、地形、速度档、练兵木桩、双方主将与亲兵）
    │   ├── lord.js             # 主将：血量、亲兵数量、敌方主将数值、半血与随时间恢复的速率
    │   ├── quickBattle.js      # 快速战斗模拟器：战场 / 敌我势力 / 兵力规模 / 场次与战报
    │   ├── save.js             # localStorage 存档槽
    │   ├── skills.js           # 经验与属性：统御 / 医术 / 工程 / 谋略及其效果
    │   ├── milestones.js       # 里程碑道具：军旗 / 徽章 / 药箱 / 驿马
    │   └── quiz/
    │       ├── index.js        # 出卷、奖励、科目与年级定义
    │       ├── registry.js     # Mod 契约：校验、注册与题目条目展开
    │       ├── scheduler.js    # 记忆曲线：等级、权重、遗忘与加权抽取
    │       ├── reward.js       # 试卷结算：连击、满分、长卷、及格与道具掉落
    │       ├── mastery.js      # 掌握度地图、错题本与复习队列
    │       ├── mods.js         # 内置题库包与 public/mods 外部加载
    │       ├── encyclopedia.js # 百科知识题（声明式，64 条）
    │       ├── shared.js       # 选项构造与干扰项工具
    │       ├── english.js      # 英文字库与题型
    │       ├── chinese.js      # 语文题型
    │       ├── math.js         # 数学题型
    │       └── logic.js        # 逻辑推理题型
    ├── stores/
    │   ├── player.js           # 领主：金币、兵员、物资、统计
    │   ├── world.js            # 世界：地形、据点、部队、玩家坐标、拍摄机
    │   └── battle.js           # 战斗：模拟循环与结算
    ├── components/
    │   ├── WorldMap.vue        # 世界地图 canvas 与点击移动
    │   ├── TownMap.vue         # 城镇 canvas：地面 / 建筑 / 道具 / 居民按脚底排序绘制、点击寻路与居民走动
    │   ├── NpcDialog.vue       # 与一位居民说话：台词、委托（接受 / 放弃）、招募为随从
    │   ├── CompanionPanel.vue  # 随从面板：把士兵交给随从的旗子或收回、解散
    │   ├── QuestPanel.vue      # 委托日志：进行中 / 已完成、进度、回城按钮
    │   ├── MiniMap.vue         # 右上角小地图，点击打开全图
    │   ├── WorldAtlas.vue      # 可拖动的详细地图浮层
    │   ├── BattleMap.vue       # 战场 canvas、地形绘制、可拖动镜头与特效
    │   ├── RecruitPanel.vue    # 招募
    │   ├── UpgradePanel.vue    # 升级
    │   ├── TownPanel.vue       # 城镇：繁荣度、发展、资金、设施与驻军
    │   ├── MarketPanel.vue     # 市场
    │   ├── ExamModal.vue       # 考试流程
    │   ├── QuestionBody.vue    # 答题区：四选一 / 填空 / 配对 / 排序四种形状
    │   ├── CharacterPanel.vue  # 角色信息面板（兵力 / 资金 / 物资 / 战绩）
    │   ├── EncounterDialog.vue # 遇敌对话框：敌将头像、兵力对比、名册与开战 / 逃跑 / 喊话
    │   ├── DayClock.vue        # 战役时钟：天数、当天时刻与进度条
    │   ├── ShareModal.vue      # 二维码分享
    │   └── GuideContent.vue    # 复用的游戏介绍内容
    └── views/
        ├── HomeView.vue        # 登录 / 继续 / 首次介绍
        ├── WorldView.vue       # 世界地图屏
        ├── TownView.vue        # 城镇屏：可走动的场景 + 推门打开的各个面板 + 委托 / 随从入口
        ├── SettlementView.vue  # 据点屏（提供「走进城里」入口）
        ├── BattleView.vue      # 战斗屏（练兵时多一个「结束练兵」）
        ├── QuickBattleView.vue # 快速战斗：选战场 / 敌我 / 规模，跑出胜率
        ├── BankView.vue        # 题库检索：搜索、过滤、看答案与掌握度
        └── GuideView.vue       # 介绍页
```

### 关键文件 · Key files

| 文件 File | 作用 Role |
| --- | --- |
| `src/game/worldgen.js` | 世界生成的全部规则。All world-generation rules. |
| `src/game/town.js` | 城镇与村庄场景：确定性的地块 / 道路 / 广场、建筑与门的位置、可行走判定、场景寻路与「站在谁旁边」的判定。The town and village scenes: the deterministic ground, roads, square, buildings and their doors, the walkable rule, the scene path and the "who is the lord standing next to" lookups. |
| `src/game/followers.js` | 随从在世界地图上的站位：按行进方向排出的「身后两人一排」槽位、指数追赶的拖尾与走路起伏；小地图与全图共用同一套槽位。Where a companion stands on the world map: the "two abreast behind the lord" slots from the direction of travel, the exponential catch-up lag and the walking bob — the minimap and the atlas read the same slots. |
| `src/game/npc.js` | 居民与随从：八个职业（名字 / 台词 / 招募价 / 带兵上限 / 全军加成）、三类委托、随从转移士兵的规则。The townsfolk and companions: eight trades (name, lines, hiring price, banner size, army bonus), the three kinds of job and the rule that moves soldiers in and out of a banner. |
| `src/game/units.js` | 兵种家族、档位、升级树 / 价格与克制关系；介绍里的升级图也从这里生成。Unit families, ranks, the upgrade tree and prices, the counter cycle and the guide's upgrade diagram. |
| `src/game/settlement.js` | 据点归属、驻军、围城规则、城镇经济（繁荣度 / 发展 / 等级）与设施效果。Settlement ownership, garrisons, the siege rules, the town economy (prosperity / development / level) and the facility effects. |
| `src/game/battle.js` | 战斗模拟：小队命令、队形 / 密度、克制伤害、远程风筝、地形效果、速度档、开局对峙（双方先驻守、敌军变阵后冲锋）与胜负判定。Battle simulation: squad orders, formations / densities, counter damage, ranged kiting, the terrain effects, the speed settings, the opening standoff (both sides hold, the enemy dresses its ranks and then charges) and win/lose logic. |
| `src/game/arena.js` | 战场地形：五种地形的定义与效果、**按战斗种子重新生成整张战场**（河流走向、湖泊 / 山地 / 森林 / 沙地的位置与大小）、不可通行规则。Battlefield terrain: the five kinds and their effects, **a whole new field drawn from the battle seed** (the river's course, the place and size of the lake, mountain, forests and sand) and the impassable rule. |
| `src/game/arenaPath.js` | 战场寻路：25 × 17 格上的 A*、二叉堆、路径平滑、直线视线，以及按「每个方向还剩多少空地」挑选的撤退方向（避开墙、湖与敌人，必要时沿墙或绕侧翼）。Arena navigation: A* and its min-heap on the 25 × 17 grid, path smoothing, line of sight, and the retreat direction that weighs the open room in every way out (off the wall, the lake and the foe, sliding along a wall or round the flank when it must). |
| `src/game/difficulty.js` | 难度设置：收入 / 军费 / 敌军三条轴、开局资源与随胜场上升的战役威胁。The difficulty setting: the pay, cost and enemy axes, the opening resources and the campaign threat that rises with every win. |
| `src/game/daynight.js` | 昼夜规则：夜晚占一天的五分之一、黑度曲线与夜晚的减速系数。The day and night rules: the night share of the day, the darkness curve and the night slowdown. |
| `src/game/encounter.js` | 遇敌对话：三个势力的台词库、敌军名册、逃生点（3–6 格、可站立、走得到）与 30 秒冷却。The meeting: the three factions' line banks, the enemy roster, the escape tiles (3–6 tiles, walkable and reachable) and the 30-second cooldown. |
| `src/stores/battle.js` | 战斗状态：模拟循环、速度档、镜头、小队命令（含一键「全军出击」）、战后结算（幸存者、战利品、敌方同步）。Battle state: the simulation loop, the speed setting, the camera, the squad orders (including the one-tap 「全军出击」) and the post-battle settlement. |
| `src/stores/world.js` | 每帧的世界推进：移动、游戏时钟门控与扎营、部队 AI、遭遇判定与冻结、逃跑，以及战役时钟读数。Per-frame world tick: movement, the clock gate and camping, party AI, encounter detection and its freeze, fleeing, and the campaign clock readout. |
| `src/game/quiz/index.js` | 出卷入口与奖励公式。Exam entry point and reward formula. |
| `src/game/quiz/reward.js` | 试卷结算：连击、满分、长卷、及格加成与道具掉落。The paper settlement: the streak, the perfect paper, the long paper, the pass bonus and the gear a paper drops. |
| `src/game/quiz/mastery.js` | 掌握度地图、错题本与复习队列，全部由记忆曲线派生。The mastery map, the mistake book and the review queue, all derived from the memory curve. |
| `src/game/skills.js` | 经验与四个属性，以及它们对队伍上限、恢复、造价、围城与攻击的影响。The experience, the four attributes and what they change. |
| `src/game/milestones.js` | 里程碑道具：按累计答对数解锁的军旗、徽章、药箱与驿马。The milestone gear: the banner, the badge, the medicine chest and the post horse. |
| `src/game/quiz/registry.js` | Mod 契约、校验与题目条目展开，改题目结构只动这一处。The mod contract, validation and entry expansion. |
| `src/game/quiz/scheduler.js` | 记忆曲线的全部常数、权重、遗忘与加权抽取。Every memory-curve constant, weight, forgetting step and weighted pick. |
| `src/components/WorldMap.vue` | 地图绘制与输入。Map rendering and input. |
| `src/components/EncounterDialog.vue` | 遭遇对话框：敌将头像、双方兵力、敌军名册与开战 / 逃跑 / 喊话三个选项。The meeting card: the enemy portrait, both army sizes, the roster and the fight / run / talk choices. |
| `src/game/atlas.js` | 小地图与详细地图的共用画法：1 像素 1 格的地形缓存、兵力角标、据点 / 将领 / 主角标记。The two whole-world painters: the 1-px-per-tile terrain cache, the troop badge, and the settlement / commander / lord markers both maps share. |
| `src/game/pixelAssets.js` | 素材清单与绘制助手，改素材路径只动这一处。Sprite manifest and canvas drawing helper; the one place asset paths live. |
| `tools/pixel-assets/generate.mjs` | 全部 32x32 素材的绘制脚本。The painter for every 32x32 asset. |
| `tools/verify-upgrade*.mjs` | 升级路径的三支自检脚本：无头用例、修复前源码复现、真实 Chrome 界面验证。The three upgrade self-checks: the headless suite, the pre-fix reproduction and the real-browser pass. |

---

## 15. 常见问题 · Troubleshooting

**地图点不动 / The character does not move.**
目标可能落在水域或孤岛上；此时会走到最近的可达位置。若完全没反应，请确认点击落在 canvas 上（顶部状态栏和图例会挡住地图）。
The target may be water or an island; the character then walks as close as possible. If nothing happens at all,
check that the click landed on the canvas rather than on the status chips, the minimap or the legend.
目标可能落在水域或孤岛上；此时会走到最近的可达位置。若完全没反应，请确认点击落在 canvas 上（顶部状态栏、小地图与图例会挡住地图）。

**天数不动、敌人也不动 / The day counter and the enemies are frozen.**
这是设计如此：游戏时间只在主角移动或扎营时流逝，站着不动会冻结世界。想让时间前进，点地图移动，或点「⛺ 扎营」。
By design: game time only advances while the lord walks or camps, so standing still freezes the world. Move by
tapping the map, or tap 「⛺ 扎营」 to let time pass in place.

**据点页签是空的 / A settlement tab looks empty.**
升级 / 考试 页签若整块空白，通常是某个面板组件在渲染时报错并中断了整个页面的更新（历史上就是 `UpgradePanel.vue` 漏了 `unitSprite` 导入）。打开浏览器控制台看 `[Vue warn] Unhandled error during execution of render function` 定位到具体组件即可。
A blank 升级 / 考试 tab usually means a panel component threw during render and aborted the whole page update — historically `UpgradePanel.vue` calling `unitSprite` without importing it. Open the browser console and look for `[Vue warn] Unhandled error during execution of render function` to find the component.

**升级后兵种没变，还是原来的兵种 / A promoted soldier keeps its old type.**
升级连线必须自带目标兵种：`upgradesFor()` 返回的每条边都要有 `type`（目标家族）与 `tier`（目标档位），因为界面和 `player.upgradeTroops()` 都只按这两个字段匹配。历史上边里只有家族记录的 `key` 而没有 `type`，于是「全部是民兵」时点任一分支（长枪兵 / 弓箭手 / 骑兵）实际写入的是一个 `type` 为空的兵员，界面按未知兵种回退成民兵显示，价格也退化成 8 金币保底价。`unitDef()` 现在会补上 `type: base.key`，可在控制台执行 `upgradesFor('militia', 1)` 确认三条边都写明了目标家族。
An upgrade edge has to name its target family: every entry returned by `upgradesFor()` needs a `type` (target family) and a `tier` (target rank), because the panel and `player.upgradeTroops()` match on exactly those two fields. Historically the edge carried only the family record's `key` and no `type`, so with an all-militia warband tapping any branch (spearman / archer / cavalry) stored a soldier with an empty type that the UI fell back to militia for, at the 8-gold floor price. `unitDef()` now supplies `type: base.key`; run `upgradesFor('militia', 1)` in the console to confirm all three edges name their target family.

**进不去城镇 / Cannot enter a town.**
需要走到据点约 1.4 格以内，底部才会出现「进入」按钮。
You must be within about 1.4 tiles of the settlement before the "enter" button appears.

**强盗的村庄进不去 / A bandit village cannot be entered.**
这是设计如此：强盗控制的村庄禁止进入，底部按钮会变成「⚔️ 赶走强盗」，打赢驻军之后村庄就变成无主，可以进入。别的势力的城镇可以直接进去（考试、招募都行），想据为己有才需要「🏰 准备围城」等 2 天再「⚔️ 攻打」；无主的城镇如果没人防守就「🚩 占领」，有人守军则要「⚔️ 攻城」打下来。
That is by design: a bandit village is closed to the lord, so the bottom button becomes 「⚔️ 赶走强盗」 — win against the garrison and the village turns unclaimed and open. A town held by a kingdom can be entered without a fight, and only has to be stormed if the lord wants to own it: prepare a siege for two days, then storm it. An unclaimed town nobody defends is claimed with 「🚩 占领」; one that still holds soldiers has to be taken with 「⚔️ 攻城」.

**无主的城镇为什么不能直接占领 / Why can I not claim an unclaimed town right away.**
因为城里还有守军。按钮会变成「⚔️ 攻城」并显示守军人数，把守军打下来城镇才归你；打输了城镇还是原样，可以再来一次。地图上那些没有守军角标的无主城镇才能直接「🚩 占领」。
Because the town still holds soldiers. The button becomes 「⚔️ 攻城」 with the number of defenders, and the town is yours only once they are beaten; a lost assault leaves the town as it was and you may try again. An unclaimed town without a garrison badge on the map can be claimed with 「🚩 占领」 right away.

**围城一直没准备好 / The siege never becomes ready.**
围城准备需要 2 天，而时间只在移动、扎营、城镇休整或**准备围城**时流逝——准备期间时钟会自己走，所以站在原地等也是有效的。
The preparation takes two days, and the clock only runs while the lord marches, camps, rests in a settlement or **prepares a siege** — so standing still is enough, the siege keeps the clock alive.

**想中断围城 / I want to call off a siege.**
准备期间（以及准备完成之后）底部都有「🚫 取消围城」按钮，点它即可中断：准备进度作废，时钟也停下来。
While the siege is prepared — and after the preparation is over — the bottom bar carries a 「🚫 取消围城」 button; tapping it calls the siege off, the preparation is lost and the clock stops again.

**攻打失败后还能再打吗 / Can I storm the town again after losing?**
不可以。攻打失败会中断这次围城，必须重新「🏰 准备围城」等满 2 天才能再次进攻——这样失败是有代价的。
No. A failed assault breaks the siege: the lord has to prepare it again (two more days) before he may attack a second time, so a defeat costs something.

**战斗太快看不清 / The battle is too fast to follow.**
战斗默认是慢速（🐢）。想更快就把战斗界面右上角 ⚙ 打开，切到 🚶 正常或 🐇 快速；想慢下来同理。
The battle runs slow by default (🐢). Open the ⚙ tools in the corner of the battle screen to switch to 🚶 normal or 🐇 fast, and back again whenever you like.

**战场只看得到一小块 / The battlefield does not fit on the screen.**
战场比手机屏幕大，镜头会跟着战斗走。用手指拖动可以自由查看，点 🎯 让镜头回到战斗；两军靠近时镜头会自动拉近。
The field is bigger than a phone screen, so the camera follows the fighting. Drag it with a finger to look around, tap 🎯 to bring it back, and it zooms in on its own when the armies meet.

**伤兵一直不恢复 / The wounded never heal.**
行军时每点每天只恢复 6 点生命，城镇里是 24 点，自己的城镇更快，医院还会再乘一次。伤兵会带着剩余生命进入下一场战斗。
Marching restores 6 hit points a day, resting in a settlement 24, your own town even more, and a hospital multiplies the rate again. A wounded soldier carries its damage into the next battle.

**队伍空了怎么办 / My warband is empty.**
敌对部队会暂时不再攻击你；走到最近村庄用金币招募民兵即可恢复（金币来自城镇考试）。
Hostile parties stop attacking you; walk to the nearest village and buy militia (gold comes from town exams).

**敌人打不完 / Enemies keep appearing.**
这是设计如此：被击败的部队会从地图移除，其余部队继续游荡，世界不会主动补充新的敌人。
By design: defeated parties are removed, the rest keep roaming, and the world does not spawn replacements.

**新势力的部队图标是空白 / A new faction's party icon is blank.**
在 `factions.js` 里加了势力却忘了重新生成素材：将领素材是按 `COMMANDERS` 和 `factions.js` 的配色画出来的，运行 `node tools/pixel-assets/generate.mjs commander` 即可。
A faction added to `factions.js` without regenerating its art leaves the party icon blank: the commander sprites are painted from `COMMANDERS` and the colours in `factions.js`, so run `node tools/pixel-assets/generate.mjs commander`.

**新增的题库不出现 / A new question mod does not show up.**
检查 `public/mods/index.json` 是否列出了文件名、`key` 是否与已有科目重复（重复会被丢弃），以及每条题目是否都有唯一的 `id`、非空 `prompt`、至少两个互不相同的选项和合法的 `answer` 下标——不合法的题会被静默丢弃。也可以在控制台用 `kidsWarGame.loadModsFromText(json)` 直接验证一段 JSON。
Check that `public/mods/index.json` lists the file, that the `key` is not already taken (duplicates are dropped), and that every item has a unique `id`, a non-empty `prompt`, at least two distinct options and a valid `answer` index — invalid items are dropped silently. You can also validate a JSON blob directly with `kidsWarGame.loadModsFromText(json)` in the console.

**分享的二维码打不开 / The shared QR does not open.**
确认对方和你在同一个 WiFi 局域网，并且打开的是本机的局域网 IP 而不是 `localhost`。
Make sure the other device is on the same WiFi LAN and that you shared a LAN IP, not `localhost`.

**进度丢了 / Progress is gone.**
存档按领主名字隔离；用同一个名字在同一个浏览器上「继续上次进度」即可。
Saves are keyed by player name; pick the same name in the same browser and use "continue".

---

## 16. 战团玩法对照 · Comparison with Mount & Blade

《骑马与砍杀 II：战团》（Mount & Blade II: Bannerlord）是本类型的标杆，本作的世界地图 + 实时小队战斗就是它的 2D 简化版，但两条主线不同：战团要经营领主与政治，本作要**让学习直接变强**。
Mount & Blade II: Bannerlord is the benchmark of the genre, and the world map plus the real-time squad battle of this game is its two-dimensional simplification — but the two have different spines: Bannerlord is about running a lord and playing politics, while here **studying has to make the lord stronger**.

下面这张表是逐项对照后的结论：**已有 / 部分 / 没有** 三档，再给出建议的优先级。完整对照（每项的特性、缺口、儿童向改造建议与改动文件）在 `progress.md` 第 6 节。
The table below is the outcome of the item-by-item comparison in three grades — **have it / partly / missing** — plus a suggested priority. The full comparison (every feature, its gap, the kid-friendly adaptation and the files it touches) is in section 6 of `progress.md`.

| 战团特性 Bannerlord feature | 本作现状 Here | 建议 Suggestion |
| --- | --- | --- |
| 小队命令、队形与密度 Squad orders, formations, spacing | ✅ 已有 Have | — |
| 兵种相克、战场地形 Troop counters, battlefield terrain | ✅ 已有 Have | — |
| 围城、城镇发展与设施 Sieges, town growth and facilities | ✅ 已有 Have | — |
| 竞技场与练兵 Arena and drill | ✅ 已有 Have（快速战斗 / 练兵） | — |
| **士气与溃逃 Morale and routing** | ❌ 没有 Missing | P0：给士兵加士气，战斗变成胜 / 负 / 溃逃三种结果。Add morale and give a fight a third outcome: win, lose or rout. |
| **声望 Renown** | ❌ 没有 Missing | P0：战斗 / 军令 / 比武产出声望，解锁城镇爵位与兵源。Renown earned in battle, orders and tournaments. |
| **任务（军令）Orders** | ❌ 没有 Missing | P1：城镇发布限时任务，用战役时钟倒计时。Timed orders posted by the towns and counted down with the campaign clock. |
| **比武大会 Tournament** | ❌ 没有 Missing | P1：复用现成战斗打三轮淘汰，名次给声望与金币。A three-round ladder on the existing battle system. |
| **属性与技能（考试 = 经验）Attributes and skills** | ✅ 已有 Have（v0.0.2） | 答对题目累积统御 / 医术 / 工程 / 谋略。Every correct answer earns an attribute point. |
| **侧翼包围 Flanking** | ❌ 没有 Missing | P2：侧后受击给伤害加成，让包围真的有价值。A flank and rear bonus, so encircling pays. |
| **新兵种 New families** | ⚠️ 部分 Partly（民兵 + 三家族） | P2：弩手、弓骑兵、长戟兵。Crossbow, mounted archer, polearm. |
| **俘虏与赎金 Prisoners and ransom** | ⚠️ 部分 Partly（打赢 +4 民兵） | P2：战后俘虏可赎金或招入。Captives can be ransomed or recruited. |
| **势力关系 Faction relations** | ❌ 没有 Missing | P2：势力之间交战 / 结盟，世界不再只是刷兵。War, peace and alliance between the factions. |
| **攻城三阶段 Siege phases** | ⚠️ 部分 Partly（准备 2 天 + 一战） | P3：围城 → 破墙 → 巷战。Surround, breach, streets. |
| **商队与工坊 Caravan and workshops** | ⚠️ 部分 Partly（市场只卖军粮战马） | P3：商品与物价波动，工坊按城镇等级生产。Goods with drifting prices and town workshops. |
| **迷雾 / 四季 / 战前部署 Fog, seasons, deployment** | ❌ 没有 Missing | P3：视野半径、四季对地形的影响、开战前拖部署线。A sight radius, four seasons, a deployment line. |
| 3D 第一人称、联机、继承 3D first-person, multiplayer, inheritance | — | 🚫 不做 Not planned：与 8–12 岁的定位不符。Out of place for this age group. |

The single most important difference from Bannerlord is kept on purpose: **the gold comes only from correct answers**, so every new system above is designed to pay out in a way that learning feeds — an exam is experience, a mission is a timed task, a tournament is a ladder you climb with your own soldiers.
与战团最重要的差别是刻意保留的：**金币只能靠答对题目获得**，所以上面每个新系统都设计成「学习能喂饱它」——考试就是经验，任务有倒计时，比武靠自己的兵打上去。

---

## 17. 学习主线的改进 · Improving the exam spine

> **已完成 · Done.** 这一节的四层改进已在 **v0.0.2** 落地：结算层、道具掉落、里程碑、掌握度地图、两种复习卷、经验与四个属性都已进游戏。下面保留「之前断在哪里」与「做了什么」的对照。
> The four layers below shipped in **v0.0.2**: the settlement, the gear a paper drops, the milestones, the mastery map, the two revision papers and the experience with its four attributes are all in the game. The table of what used to break is kept for reference.

本作的核心是**做题换道具和资金**，所以这条链的每一环都要经得起推敲：入口 → 出卷 → 记忆曲线 → 奖励 → 花钱 → 变强。
The core of this game is **answering questions for gear and money**, so every link of that chain has to hold up: entry → paper → memory curve → reward → spending → getting stronger.

### 17.1 这条链原本断在哪里 · Where the chain used to break

| 环节 Link | 原本 Today | 断点 The break | 现在 Now |
| --- | --- | --- | --- |
| 入口 | 只有城镇能考试 | 村庄与野外都没有，孩子得先走到城镇 | 未变 Still the same |
| 奖励 | 每答对一题同一个价（20 / 26 金币 + 科目加成） | 做得多、做得快没有区别 | ✅ 结算层：连击 ×1.0–×1.5、全对 ×1.5、长卷 ×1.1、及格 +20% |
| 答错 | — | — | ✅ **不扣钱**：只是这一题没有金币、连击归零 |
| 道具 | 军粮与战马只能**用金币买** | 「做题得道具」这一半是空的 | ✅ 答对掉军粮，整科全对掉集市券 / 征兵令，全对掉战马 |
| 长期目标 | 只有金币一个数字 | 没有可见的进度 | ✅ 里程碑：军旗 / 徽章 / 药箱 / 驿马 |
| 可见性 | 只有「已记录 N 题 / 掌握 M 题」 | 哪一科弱看不出来 | ✅ 掌握度地图（科目 × 年级）+ 角色详情里的进度条 |
| 通过与否 | 只改标题「🏅 通过 / 📄 结束」 | 及格没有任何后果 | ✅ 及格给经验，经验换属性点 |
| 错题 | 沉在记忆曲线里 | 错题不能重考 | ✅ 只考错题 / 复习队列两种复习卷 |
| 学习 → 战斗 | 只有金币这条单线 | 学得越多，打仗并不更强 | ✅ 统御 / 医术 / 工程 / 谋略四个属性 |

The reward is flat, the gear can only be bought, the progress is invisible, the pass line means nothing and nothing that the child learns makes the army stronger — all five are fixed now.
奖励是平的、道具只能买、进度看不见、及格没有后果、学到的东西不会让军队更强 —— 这五件事现在都改掉了。

### 17.2 四层改进 · The four layers

| 层 Layer | 内容 Content | 关键改动 Key change |
| --- | --- | --- |
| **A 让一次考试更有戏** | 连击倍率 ×1.0 → ×1.5、全对 ×1.5、12 题长卷 ×1.1、及格 +20%；**答错不扣钱** | 新增 `src/game/quiz/reward.js`（结算层，`rewardFor()` 保持不变） |
| **B 让题目变成道具** | 答对掉军粮；某一科全对掉集市券 / 征兵令；整卷满分掉战马；累计答对 300 / 500 / 800 / 1200 解锁军旗 / 徽章 / 药箱 / 驿马 | 新增 `src/game/milestones.js`，`supplies` 增加券与征兵令 |
| **C 让学习看得见** | 掌握度地图（科目 × 年级）、连击、「今天该复习的 N 题」队列、错题本与「只考错题」 | 新增 `src/game/quiz/mastery.js`，由 `questionStats` 派生，**不改存档结构** |
| **D 让学习改变战斗** | **考试 = 经验**：及格卷每答对一题 +1 经验，50 经验换 1 点属性；统御加队伍上限、医术加快恢复、工程缩短围城、谋略给情报与攻击 | 新增 `src/game/skills.js`，接进 `battle.js` 与 `settlement.js` |

还有一条把两条主线缝起来的：**战后复盘卷** —— 打输了给一次针对这次敌人的补考，答对就恢复士气或补回几个兵。
（还没做。）And one that stitches the two spines together: a **post-battle revision paper** — after a loss the game offers a paper drawn against the enemy you just faced. *(Not built yet.)*

批次 21 又加了两件事：**题库检索**（首页入口，搜索 / 过滤 / 看答案）与**更多答题形式**（填空、配对、排序）。
Batch 21 added two more things: the **question bank** (a home entry with the search, the filters and the answers) and **more shapes of a question** (filled in, matching, ordering).

### 17.3 剩下什么 · What is left

| 项目 Item | 状态 Status |
| --- | --- |
| 数字填空题型（算式、拼写已上线） | ✅ 部分 Done（批次 21） |
| 题目难度与知识点标签（自适应出题的前提） | ⏳ 未做 Not yet |
| 每日目标与连击统计（跨天） | ⏳ 未做 Not yet |
| 老师工具：布置作业 + 学习报告导出 | ⏳ 未做 Not yet |
| 战后复盘卷 | ⏳ 未做 Not yet |

完整的缺口清单、数值表、数据形状与「不建议做的部分」写在 `progress.md` 第 7 节。
The full gap list, the number tables, the data shapes and the "what not to do" list live in section 7 of `progress.md`.