# CoreState 组装与初始化

新增一个子系统时，最先遇到的问题通常不是「类写在哪」，而是「它应该拿谁、由谁创建、什么时候创建」。`CoreState` 是数据端的组合根：它先把跨系统共用的对象按依赖顺序建好，再让插件在这套对象上继续装配。装配顺序错了，代码不一定立刻报错，但会在第一次访问某个字段时拿到 `undefined`。

本篇只讲四层为什么存在、每层放什么、构造器实际按什么顺序建对象，以及 `MainDataPlugin` 在插件阶段补了哪些默认装配。加载如何推进见[加载系统](./loading-system.md)，可存档对象与执行器见[可存档内容](../i/saveable-content.md)，插件排序与阶段推进见[插件内部机制](./plugin-internals.md)。

## 系统模型

| 层          | 职责                                                 |
| ----------- | ---------------------------------------------------- |
| L0 公共数据 | 工具、仓库与跨系统共用的运行期对象，不依赖其它子系统 |
| L1 状态基座 | 保存需要进存档的运行时状态，并允许系统层操作这些状态 |
| L2 系统层   | 在状态之上执行游戏逻辑，自身不作为存档内容           |
| L3 顶层     | 面向启动流程，把前面的对象接成加载入口               |

```mermaid
flowchart TD
    L3[L3 顶层<br/>loadManager / loader] --> L2[L2 系统层<br/>enemyContext / combat / eventSystem / pathfinding]
    L2 --> L1[L1 状态基座<br/>flags / maps / hero / enemyManager]
    L1 --> L0[L0 公共数据<br/>stores / face / replay]
```

箭头表示依赖：L3 依赖 L2，L2 依赖 L1，L1 依赖 L0。构造顺序则相反，从 L0 开始逐层向上。`CoreState` 同时实现四层叠加后的接口，所以运行时是同一个对象；但每个子系统只接收它需要的那一层接口。

## 层不是目录

L0–L3 是构造依赖的分组，不是源码目录。一个包可以同时包含 L0 的仓库与 L1 的状态类；一个文件也可以定义多个层的接口。判断一个对象属于哪一层，看它「构造时依赖谁、是否进存档、是否只服务启动」，而不是看它放在哪个文件夹。

这也意味着不能用 import 路径推断分层：`data-base` 里有 L1 的地图与勇士，也有 L0 的图块与朝向工具；`data-system` 整体偏 L2，但它的接口仍然只依赖 L1。真正决定依赖方向的是构造参数与类型，而不是包名。

新增子系统时，默认通过插件实现，不先问「它属于哪一层」。只有必须改变引擎默认能力的极少数情况，才需要判断它落在 L0、L1 还是 L2：看它构造时依赖谁、是否进存档、是否只服务启动。插件与渲染端不需要挤进四层。

## 一条依赖链在运行时怎么走

以「勇士走一步」为例，四层在同一条链上各做一件事，但没有一层反向持有更高层：

1. 输入层让勇士位置对象的移动器排一步。移动器属于 L1 的 `hero`，它只管理坐标、朝向与步骤队列。
2. 移动器把这一步交给 `DefaultHeroMoveTopImpl`。顶层实现由插件安装，不属于 CoreState 的四层构造；它持有 L1 的地图、L2 的事件执行器与一个依赖 L0/L1 的通行谓词。
3. 谓词读取 L0 的 `faceManager` 与 L1 地图上的图块通行位，回答「能不能进、会不会撞」。
4. 每一步进入结算阶段时，移动器都会调用事件系统；坐标改变时是旧格到新格，失败步则是同一格的前后两次。L2 的事件系统从 L1 的地图收集候选，从 L0 的 `eventStore` 取事件，再由解释器执行脚本；脚本可以写 L1 的 Flag、勇士或地图。
5. 寻路是另一条链：L2 的 `pathfinding` 读取 L1 的图层，反复调用同一个谓词构图与搜索，最后把方向步骤交回 L1 的移动器。

这条链说明分层不是「调用顺序从上到下」，而是「每一层只依赖更低的接口」。顶层实现、谓词与插件可以同时接触多层，但它们是把能力注入低层，而不是让低层反过来 import 高层。

## L0：公共数据

| 对象           | 负责什么                         | 为什么在 L0                    | 依赖        |
| -------------- | -------------------------------- | ------------------------------ | ----------- |
| `roleFace`     | 图块数字到朝向图的绑定           | 只处理图块标识，不认识游戏进度 | 无          |
| `faceManager`  | 按组与字符串 id 注册方向处理器   | 移动、构图、图块转换共用       | 无          |
| `tileStore`    | 图块原始定义：通行位、事件、类型 | 只读定义，所有层都可能查询     | 无          |
| `itemStore`    | 道具原始定义                     | 只读定义，不依赖地图或勇士     | `tileStore` |
| `mapStore`     | 地图原始数据                     | 只读定义，供地图状态按需创建   | 无          |
| `eventStore`   | 事件 id 到事件对象的映射         | 事件对象不依赖地图状态         | 无          |
| `enemyStore`   | 怪物原始定义                     | 只读定义，供敌人管理器创建实例 | `tileStore` |
| `replaySystem` | 录像数组、指令注册表与播放沙箱   | 每个系统都可能用到它           | 无          |

L0 的共同点是「构造时不需要 L1/L2/L3」。录像系统放在 L0 的唯一理由是每个系统都可能用到它；可存档与否不是分层依据，关键是它不依赖更高层。

`tileStore` 必须早于 `itemStore` 与 `enemyStore`，因为后两者在构造时就要拿图块定义。`faceManager` 在 L0 只是建表，真正的 Dir4 / Dir8 处理器由 `MainDataPlugin` 注册；这保证默认玩法策略不写死在对象图里。

L0 的仓库大多是只读定义：`tileStore`、`itemStore`、`mapStore`、`enemyStore` 保存的是「内容是什么」，不是「这一局进行到哪」。把它们放在 L0，读档时不需要恢复，也不会因为一局的状态变化而改写定义。`roleFace` 与 `faceManager` 是工具性的查找表；`replaySystem` 放在 L0，只因为每个系统都可能用到它。

L0 的边界是「可以被任何层使用，但不主动使用任何层」。如果某个对象需要知道当前楼层、勇士位置或 Flag，它就不属于 L0；如果它只需要图块定义或方向处理器，放在 L0 可以避免在 L1/L2 里重复建一份。

## L1：状态基座

| 对象           | 负责什么                           | 为什么在 L1                          | 依赖                                 |
| -------------- | ---------------------------------- | ------------------------------------ | ------------------------------------ |
| `flags`        | 全局 Flag 字段与值                 | 需要进存档，系统层只读写             | 无                                   |
| `maps`         | 楼层、图层、图块与事件的运行时状态 | 地图改动要进存档，且被寻路与事件读取 | `CoreState`（以 `IDataCommon` 回指） |
| `hero`         | 勇士属性、位置、道具、装备与跟随者 | 勇士状态是存档主体，系统层只操作它   | `CoreState`（以 `IDataCommon` 回指） |
| `enemyManager` | 怪物实例、原始定义与特殊属性       | 敌人状态需要进存档，且依赖图块定义   | `tileStore`                          |

L1 的共同点是「保存游戏进度」。它们可以被 L2 读写，也可以被 L3 的读档流程恢复，但自身不决定战斗、事件或寻路的执行策略。`maps` 与 `hero` 在构造时接收 `CoreState`，但类型是 `IDataCommon`，只看得到 L0；这是向下依赖，不是反向依赖。

L1 的对象可以互相引用，但要通过主对象或公开接口，而不是在构造时抓取彼此的私有字段。`enemyManager` 只拿 `tileStore`，不拿 `maps` 或 `hero`，所以它可以在没有地图的环境里独立创建。

L1 的边界是「保存重建所需的状态，不保存可以重算的中间结果」。战斗中的临时伤害、寻路得到的路径、事件收集出的候选列表都不属于 L1；它们是 L2 在某一刻算出来的派生数据。把派生数据塞进 L1，会让存档体积膨胀，也会在读档后留下与新状态不一致的缓存。

L1 也不负责「什么时候写」。它只提供可读写的状态与存档能力；触发写入的是 L2 的系统或插件。这样同一份状态可以被不同玩法复用，而不必把玩法写进状态对象。

## L2：系统层

| 对象           | 负责什么                                 | 为什么在 L2                              | 依赖                                  |
| -------------- | ---------------------------------------- | ---------------------------------------- | ------------------------------------- |
| `enemyContext` | 怪物上下文：战斗前后的属性修正与特殊逻辑 | 需要读 L1 状态，但自身不保存进度         | `CoreState`（以 `IStateSystem` 回指） |
| `combat`       | 战斗流程：伤害、夹击、死亡与掉落         | 在状态之上执行，读档后可按需重建         | `CoreState`                           |
| `eventSystem`  | 事件仓库、解释器、收集器与执行器         | 需要事件对象与地图状态，但不作为存档内容 | `CoreState`、`config.events`          |
| `pathfinding`  | 构图、搜索与把路径交给移动器             | 需要图层、谓词与移动器，但不保存地图数据 | `CoreState`                           |

L2 的共同点是「执行逻辑」。它们会修改 L1 的状态，但不自己保存一份副本；读档后，L1 被恢复，L2 继续按新状态工作。`eventSystem` 在构造时接收入口提供的内建函数表，并创建解释器；`pathfinding` 只创建求解器与系统对象，谓词、图层与移动器由 `MainDataPlugin` 在 `awake` 中注入。

L2 不能依赖 L3。比如事件系统不应该在构造时读取 `loader`，寻路也不应该依赖加载进度；需要加载结果时，由插件在加载后把值注入 L2，或由 L2 的调用方传入。

L2 的边界是「执行策略，不是内容定义」。事件系统知道怎么收集与执行，但不知道某个事件 id 对应哪段脚本；寻路知道怎么构图与搜索，但不知道当前楼层长什么样；战斗知道怎么结算，但不知道怪物原始定义从哪来。内容定义在 L0，状态在 L1，L2 只把两者接起来。

L2 也不是「所有逻辑都必须放这里」。默认玩法策略（用哪个谓词、给移动器装哪个顶层实现、注册哪些加载钩子）属于插件，不属于 `CoreState` 的构造。把它们放进 L2，会让系统对象在构造时就需要知道具体玩法，失去替换空间。

## L3：顶层

| 对象          | 负责什么                                 | 为什么在 L3                                     | 依赖                   |
| ------------- | ---------------------------------------- | ----------------------------------------------- | ---------------------- |
| `loadManager` | 汇总加载任务、推进任务并累计进度         | 只服务加载流程，不参与日常结算                  | 无                     |
| `loader`      | 按阶段加载核心配置、额外配置与自定义内容 | 需要 `loadManager` 与 starter，且只在启动期使用 | `loadManager`、starter |

L3 的共同点是「启动入口」。它们不持有游戏进度，也不执行战斗或事件；它们把外部资源读进来，供插件在加载后使用。`CoreState` 在构造器里调用 `loader.addCoreConfig('core', config.coreURL)`，把核心配置登记为第一个加载任务；真正的加载由 `state.load()` 推进，不在本篇展开。

L3 是四层里最容易被低层误用的层。低层如果为了拿一个配置而保存 `state.loader`，就把「对象图」和「启动流程」绑死了；正确做法是让插件在加载后读取配置，再把结果注入低层。

L3 的边界是「只在启动期有用」。`loadManager` 与 `loader` 不参与日常战斗、事件或寻路；它们读取外部资源，供插件在加载后创建对象。把运行期逻辑写进 L3，会让「加载完成」与「游戏运行」两条时间线纠缠在一起，读档时也很难判断哪些对象应该重建。

## 构造器的实际顺序

前面按层说明职责；落到代码上，四层由构造器按固定顺序建出来。`CoreState` 的构造器按下面的顺序执行，顺序本身就是依赖声明：

1. L0：`roleFace`、`faceManager`、`tileStore`、`itemStore`、`mapStore`、`eventStore`、`enemyStore`、`replaySystem`。`itemStore` 与 `enemyStore` 在 `tileStore` 之后。
2. L1：`flags`、`maps`、`hero`、`enemyManager`。`maps` 与 `hero` 接收主对象，`enemyManager` 接收 `tileStore`。
3. L2：`enemyContext`、`combat`、`eventSystem`、`pathfinding`。它们都接收主对象；`eventSystem` 还接收 `config.events`。
4. L3：`loadManager`，再用它和 `config.loadStarter` 创建 `loader`；随后登记核心配置。
5. 插件表：遍历 `config.dataPlugins`，按 `id` 建表；重复 id 告警 78 并保留第一个。
6. 依赖表：把每个插件的 `dataDeps` 交给 `orderPlugins`，在构造期计算一次拓扑序。
7. `awake()`：按拓扑序对处于 `NotAwakened` 的插件执行同步装配。

第 5 到第 7 步发生在四层全部构造完成之后。原因是 `awake` 可能访问任意一层：主插件要注册朝向、注入寻路谓词、给勇士移动器装顶层实现、注册加载钩子与可存档内容。任何一层还没建好，插件拿到的就是 `undefined`。

`config.dataPlugins` 里 `MainDataPlugin` 排在最前，只是入口的列表顺序；真正的执行顺序仍由 `dataDeps` 决定。它没有隐式前置地位，依赖它注册的默认装配或存档 id 时，必须在 `dataDeps` 中显式写 `'main-data-plugin'`。

## MainDataPlugin 实际装配

`CoreState` 只负责建对象与排序，默认玩法策略放在 `MainDataPlugin.awake`。它按下面的顺序补装配：

1. 创建 `Dir4FaceHandler` 与 `Dir8FaceHandler`，按 `FaceGroup` 和字符串 id 注册到 `faceManager`。之后移动与构图才能取到方向处理器。
2. 创建 `DefaultPassPredicateImpl`，注入 `pathfinding.finder`；把图层先设为 `null`，因为此时勇士还不在任何楼层；把勇士的移动器绑定给寻路系统。
3. 创建 `DefaultHeroMoveTopImpl`，装到 `state.hero.location.mover`。它负责边界、通行谓词与 `enter` / `leave` / `hit` 的事件派发。
4. 给加载器注册默认加载钩子，让加载阶段能按核心配置追加内容。
5. 初始化敌人、录像指令与钩子；这些初始化需要主对象与已注册的仓库。
6. 注册默认可存档对象：勇士、Flag、地图、敌人管理器与录像。注册决定存档里出现哪些 key；不要用注册顺序推断读档先后。
7. 保存敌人初始化返回的弱引用处理器，供后续战斗逻辑使用。

这些动作不放进 `CoreState` 构造器，是因为它们属于「默认玩法」而不是「对象图」：换一套玩法可以替换插件，而不需要改四层构造。`MainDataPlugin` 仍然只是一个普通插件，它的 `awake` 与其它插件共享同一套拓扑序与状态机。

`new CoreState(config)` 返回时，四层对象与插件的 `awake` 都已完成，但这不等于「游戏可以开始」：`faceManager` 已注册 Dir4 / Dir8，L0 的仓库可用；L1 的对象存在但还没有被内容填充；寻路已拿到谓词与移动器，图层仍是 `null`；`loader` 已登记核心配置但还没有开始读取；`initialize` 与 `afterLoad` 还没有执行。这个状态适合写单元测试，不适合直接开始游戏。

入口只做三件事：`createCoreStateConfig(starter)` 汇总加载 starter、核心配置路径、插件列表与内建函数表；`createCoreState(starter)` 用这份配置构造实例并返回尚未异步加载的主对象；`MainDataPlugin` 在插件阶段完成上面的默认装配。`src/data.ts` 只 re-export `createCoreState`，不承担装配逻辑。`ICoreStateConfig` 只有这四个字段，业务参数通过插件构造器或配置字段传入，不要扩 `CoreState` 的构造签名。构造器也不发起网络或文件读取，`loadStarter` 只保存引用，I/O 留给加载阶段。

## 新增子系统放哪一层（插件优先）

新增子系统默认全部通过插件实现：在 `awake` 里创建管理器并挂到插件实例上，在 `afterLoad` 里读取加载内容。不要因为「写起来更直接」就往 `CoreState` 的四层里加字段。只有必须改变引擎默认能力、且要被所有项目共享的极少数情况，才动 L0 / L1 / L2。

| 改动类型                       | 落点                     | 原因                                     |
| ------------------------------ | ------------------------ | ---------------------------------------- |
| 新增业务子系统                 | 插件                     | 默认做法，不改变 `CoreState` 的对象图    |
| 新的可存档进度                 | 插件自己持有的可存档对象 | 由插件注册，读档时恢复                   |
| 新的执行逻辑                   | 插件自己的管理器         | 读写 L1，但不作为存档内容                |
| 新的默认玩法装配               | 插件的 `awake`           | 需要主对象与已构造的四层，但不改对象图   |
| 依赖加载内容的初始化           | 插件的 `afterLoad`       | 配置与地图在加载后才可读                 |
| 纯展示、输入或动画             | 渲染端，不在数据端四层   | 数据端只维护状态，不持有画面             |
| 必须改变引擎默认能力（极少数） | 对应的 L0 / L1 / L2      | 插件无法表达、且需要所有项目共享时才考虑 |

新增图块、道具、怪物或地图定义不属于新增子系统，仍然由 L0 的对应 Store 承载；它们是内容，不是运行时逻辑。以任务系统为例：任务进度可存档，任务逻辑是执行逻辑，合适做法是写一个插件，在 `awake` 里创建任务管理器并注册为可存档对象，在 `afterLoad` 里读取任务配置，而不是往 L1 里硬加一个 `quests` 字段。只有任务系统要成为引擎级能力、被所有项目共享时，才考虑放进 L1 / L2，并同时承担构造顺序与接口成本。

再以「新的通行规则」为例：规则是执行策略，不是内容定义。它应该实现为谓词，由插件注入寻路与移动器，而不是写进 `tileStore` 的静态通行位。静态通行位描述「图块本身能不能走」，谓词描述「这一局按什么规则判断」；两者混在一起，换规则就要改内容。

## 边界与注意

四层顺序错了，很少在构造器里立刻抛错，常见的是第一次使用时拿到错误结果：低层保存了高层引用，第一次调用才拿到 `undefined`；朝向处理器还没注册，默认谓词直接返回不通行；进入楼层前 `finder` 的图层是 `null`，`find` 得到 `InvalidInput`；事件内建函数缺失，会在编译阶段抛错；插件依赖写错，被阻断的插件停在 `NotAwakened`，下游看到的是「对象缺失」。

- **依赖只能向下**：L0 不得引用 L1/L2/L3，L1 不得引用 L2/L3，L2 不得引用 L3；跨层能力由上层注入。
- **四层装配顺序固定**：L0 → L1 → L2 → L3，同层内部也按依赖先后；重排会让构造参数拿到未初始化的对象。
- **插件在四层之后**：注册、去重、排序与 `awake` 都发生在子系统装配完成之后，`awake` 可以看到整个数据端。
- **构造不等于加载**：`createCoreState` 只返回实例，异步加载由加载系统推进；两者的时间线不要混在一起。
- **系统层不进存档**：L2 只修改 L1 的状态，读档后继续按新状态工作；可存档对象的注册与执行器见[可存档内容](../i/saveable-content.md)。
- **默认子系统用插件**：需要新能力时新增插件，由主对象注入已有依赖，避免绕过初始化顺序；不要手动构造内部子系统，也不要往四层里加字段。
- **依赖主插件要显式声明**：用到 `main-data-plugin` 注册的默认装配或初始化结果时，在 `dataDeps` 里写 `'main-data-plugin'`。

返回[高级 III 导览](./index.md)。