From 2ea8cb33f5ea70e6e15c42da7f374726ae301913 Mon Sep 17 00:00:00 2001
From: unanmed <1319491857@qq.com>
Date: Sat, 17 Oct 2026 17:48:28 +0800
Subject: [PATCH] docs(10-02): write data-vs-render and src-tour concept docs
- data-vs-render: dual-end split (compute vs draw), src/data vs src/client,
mermaid diagram, replay verification runs data side only
- src-tour: tour src/data, src/client, src/content, src/constant.ts plus a
should-you-edit table
---
docs/intermediate/data-vs-render.md | 55 +++++++++++++++++++++++++++
docs/intermediate/src-tour.md | 59 +++++++++++++++++++++++++++++
2 files changed, 114 insertions(+)
create mode 100644 docs/intermediate/data-vs-render.md
create mode 100644 docs/intermediate/src-tour.md
diff --git a/docs/intermediate/data-vs-render.md b/docs/intermediate/data-vs-render.md
new file mode 100644
index 0000000..039c29a
--- /dev/null
+++ b/docs/intermediate/data-vs-render.md
@@ -0,0 +1,55 @@
+# 数据端与渲染端
+
+样板把整个游戏拆成了**数据端**与**渲染端**两部分，两者各自独立、职责分明。理解这个分工，是读懂后面所有内容的前提。
+
+## 各司其职：算与画
+
+数据端负责「算」，渲染端负责「画」。
+
+- **数据端**处理一切与游戏逻辑和结果有关的运算：勇士移动、怪物战斗、道具使用、地图事件、存档与录像……它决定游戏里「发生了什么」。
+- **渲染端**只负责把当前的状态画到屏幕上，并把玩家的操作转达给数据端：它决定游戏「看起来是什么样」。
+
+可以拿一盘棋来类比：
+
+- 数据端像一本**账本**——记录棋子的位置、每一步的走法与胜负判定，真正「下棋」的是它；
+- 渲染端像**棋盘**与**摄像机**——把账本上的棋局摆出来给观众看，并接收观众挪动棋子的手。
+
+```mermaid
+graph LR
+ D[数据端 src/data
算：逻辑与结果]
+ C[渲染端 src/client
画：画面与交互]
+ D -->|产生游戏状态| C
+ C -->|转达玩家操作| D
+```
+
+## 代码分处两地
+
+两端的代码分别放在两个目录：
+
+- 数据端代码在 `src/data`；
+- 渲染端代码在 `src/client`。
+
+一个功能通常只在其中一端实现。想要改变游戏的**规则与数值**，去 `src/data`；想要改变游戏的**画面与交互**，去 `src/client`。两端的目录构成详见 [src 导览](./src-tour.md)。
+
+## 好处：录像验证只跑数据端
+
+双端分离带来的最大好处，是**数据端可以脱离浏览器单独运行**。
+
+数据端不依赖任何渲染（画面、动画、DOM）逻辑，因此可以在 `node` 环境中独立跑通一整局游戏。所谓**录像验证**，就是回放一局录好的操作，只在这条「数据端」路径上重算一遍，据此判定这局游戏的成绩是否与录制时一致。
+
+这意味着：
+
+- 验证一局成绩，不需要打开浏览器、不需要渲染画面，速度快且结果稳定；
+- 只要录像里记录的操作一致，无论在哪台机器、哪种渲染环境下重放，得到的游戏结果都应完全一致。
+
+:::info
+正因为数据端要能独立运行，数据端代码里不能依赖任何渲染端内容。确需调用渲染端时，必须用 `Mota.r(() => {})` 包裹，且除非必要不建议这样做。
+:::
+
+## 小结
+
+- 数据端 = 算，在 `src/data`；渲染端 = 画，在 `src/client`。
+- 数据端可脱离浏览器单独运行，**录像验证只跑数据端**。
+- 改变规则与数值看数据端，改变画面与交互看渲染端。
+
+想了解两端内部各有哪些内容、哪些需要改，见 [src 导览](./src-tour.md)；想在数据端的关键动作上挂接自己的处理，见 [钩子](./hooks.md)。
diff --git a/docs/intermediate/src-tour.md b/docs/intermediate/src-tour.md
new file mode 100644
index 0000000..0d88cb7
--- /dev/null
+++ b/docs/intermediate/src-tour.md
@@ -0,0 +1,59 @@
+# src 导览
+
+`src` 是游戏的入口代码，也是中级教程涉及最多的地方。本篇带你认识它的主要目录，并说明哪些地方通常需要改、哪些通常不用动。两端的分工见 [数据端与渲染端](./data-vs-render.md)。
+
+## src/data：数据端
+
+数据端代码。游戏的逻辑与结果都在这里定义，是本教程后续的重点。常见子目录：
+
+- `src/data/enemy/`：怪物相关逻辑，如特殊属性（`special.ts`）、光环（`aura.ts`）、伤害计算（`calculator.ts`）等；
+- `src/data/event/`：地图事件的内建函数；
+- `src/data/hero/`：勇士移动、通行性等实现；
+- `src/data/hook/`：数据端内置钩子的实现与注册（见 [钩子](./hooks.md)）；
+- `src/data/loader/`、`src/data/plugin/`、`src/data/replay/`：加载、数据端插件、录像指令等。
+
+数据端的入口是 `entry.ts`，它负责装配并创建数据端主对象 `state`；`initialize.ts` 中的 `MainDataPlugin` 则承担主要的初始化工作。
+
+## src/client：渲染端
+
+渲染端代码，负责画面与交互。其构成与数据端一一对应：
+
+- `src/client/entry.ts`：渲染端入口，创建渲染端主对象；
+- `src/client/initialize.ts`：渲染端主插件；
+- `src/client/plugin/`：渲染端插件；
+- `src/client/ui/`：界面相关代码。
+
+## src/content：内容层
+
+游戏内容数据，与代码逻辑分开存放，大多以 `.jsonc` 形式存在：
+
+- `core.jsonc`：核心配置，如勇士初始属性与初始位置；
+- `enemy.jsonc`、`item.jsonc`、`tile.jsonc`：怪物、道具、图块定义；
+- `maps/`：游戏地图；
+- `item.ts`：道具效果的代码实现——内容层可以写少量代码，用来描述「使用某个道具会发生什么」。
+
+## src/constant.ts：常量
+
+游戏的底层核心常量，例如数据端核心配置 `CORE_URL`、勇士默认朝向组 `HERO_FACE`、渲染画布 `RENDER_CANVAS`、渲染宽高 `RENDER_WIDTH` 与 `RENDER_HEIGHT` 等。文件内已注明「不懂的话千万不要动」，一般不需要修改。
+
+## 其余文件（通常不用改）
+
+- `src/data.ts`：数据端入口，仅在录像验证时运行；
+- `src/bootstrap.ts`：启动入口，创建渲染端主对象并打开加载界面；
+- `src/package.json`：入口包的依赖声明；
+- `src/styles.less`：全局样式。
+
+## 该不该改
+
+| 路径 | 用途 | 是否通常需要改动 |
+| --- | --- | --- |
+| `src/data/` | 数据端逻辑与结果 | 是，本教程重点 |
+| `src/client/` | 渲染端画面与交互 | 视需求，交互类需求会改 |
+| `src/content/` | 游戏内容数据 | 是，配置与内容 |
+| `src/constant.ts` | 底层核心常量 | 否，一般不动 |
+| `src/data.ts` | 数据端入口 | 否，一般不动 |
+| `src/bootstrap.ts` | 启动入口 | 否，一般不动 |
+| `src/package.json` | 入口包依赖声明 | 否，一般不动 |
+| `src/styles.less` | 全局样式 | 否，一般不动 |
+
+想先补齐读写这些文件所需的语法与类型知识，见 [代码基础](./code-basics.md)。