From b451da203de6ac23ddd3968f028a6bd64469cd06 Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Wed, 21 Oct 2026 12:05:23 +0800 Subject: [PATCH] =?UTF-8?q?docs(10-20):=20=E4=BF=AE=E8=AE=A2=E5=A3=B0?= =?UTF-8?q?=E6=98=8E=E5=BC=8F/=E6=8F=92=E4=BB=B6=EF=BC=88=E7=94=A8?= =?UTF-8?q?=E6=88=B7=E7=AC=AC4=E8=BD=AEA=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../10-docs-restructure/10-20-USER-REVIEW.md | 43 ++ docs/advanced/declarative-vs-imperative.md | 100 ++-- docs/advanced/plugin-system.md | 478 ++++++++++-------- 3 files changed, 359 insertions(+), 262 deletions(-) diff --git a/.planning/phases/10-docs-restructure/10-20-USER-REVIEW.md b/.planning/phases/10-docs-restructure/10-20-USER-REVIEW.md index 1b70da8..05a9473 100644 --- a/.planning/phases/10-docs-restructure/10-20-USER-REVIEW.md +++ b/.planning/phases/10-docs-restructure/10-20-USER-REVIEW.md @@ -130,3 +130,46 @@ **构建：** `pnpm exec prettier --write docs/advanced/*.md` 后 `--check` 七篇通过；`pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build` 输出 `build complete`，无 dead link。 **状态：已处理** + +--- + +## 第 4 轮 + +**时间：** 2026-10-20 +**用户意见（13 条）：** + +| # | 意见 | 落点 | +|---|------|------| +| U4-01 | 删除「声明式 vs 命令式」里「怪物特殊属性与光环」的例子——不合适，不可能有作者手写特殊属性对象 | `declarative-vs-imperative.md` | +| U4-02 | 插件系统里数据端与渲染端应**并列**写，不要在「插件接口」一节只写数据端、后面才补「数据端与渲染端」 | `plugin-system.md` | +| U4-03 | 示例插件不要写 `dataDeps[0]?.plugin as IShopPlugin \| undefined`；直接 `dataDeps[0].plugin` 或 `const [{ plugin: dataShop }] = dataDeps;`。依赖已加载完毕，不需要非空判断 | `plugin-system.md` | +| U4-04 | 数据端与渲染端插件是**平等关系**；不能只写注册到 dataPlugin。补全渲染端插件的注册与目录；「注册与目录」应放到文档开头 | `plugin-system.md` | +| U4-05 | 删除「插件 id 稳定性与版本迁移」——对普通作者无用，发布相关信息应放到插件库的说明里 | `plugin-system.md` | +| U4-06 | 接口以 `I` 开头的约定文档也要遵守（作者可不遵守，但文档必须规范）；`getDataPlugin` 的 `PluginA` 应改为 `IPluginA` 形式 | `plugin-system.md` | +| U4-07 | **先写模板，再解释每个方法**；高级教程也需要模板，但与中级不同 | 全部 | +| U4-08 | 插件可以在插件之外调用（如钩子里）；不是只有插件内部才能调用插件 | `plugin-system.md` | +| U4-09 | `saveState` / `loadState` **不保证顺序**（Map 存储一律不保证），删除「保证被引用对象先注册」；跨存档引用只说「存 id，读档或需要时再新建」，该场景极其少见，不必展开；存读档验证不需要复杂告警验证；**不要把 `__test__` 的内容写进文档** | `saveable-content.md`（及全部验证） | +| U4-10 | 明确写明 `@shouldReplay` **仅用于数据端** | `replay-consistency.md` | +| U4-11 | 五个 Store 的 inline-code 密度太高；删掉括号里的 `IInterface` 标识；说明改成文字，只讲这个 Store 能干什么，细节后置 | `data-stores.md` | +| U4-12 | Store 要讲**里面存的数据**，不能只讲 Store 本身；不要单开「逐个看接口」大节，直接把五个 Store 平铺，每个讲「存什么 + 自身接口」 | `data-stores.md` | +| U4-13 | 钩子写成「建议一个对象一个实例」；共享允许但不建议，除非明确了解原理与后果；不展开共享实例 | `hooks-in-depth.md` | + +### 第 4 轮处置（声明式 / 插件系统） + +**修改方式：** 派发子代理执行（内联编辑），仅修改 `docs/advanced/declarative-vs-imperative.md`、`docs/advanced/plugin-system.md` 与本职记录。 + +| # | 处置 | +| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| U4-01 | 删除手写 `special` 对象的示例（`ISpecial23Value` 片段）；保留概念，改为说明特殊属性在 `src/data/enemy/special.ts` 的 `createSpecials` 中统一注册、光环通过 `registerAuraConverter` 注册，怪物数据只写编号与参数。 | +| U4-02 | 合并原「数据端与渲染端」与「插件接口」两节：接口一节先并列给出数据端、渲染端完整模板，再用同一组条目逐项说明，不再先写数据端、后面另起一节补渲染端。 | +| U4-03 | 依赖示例改为直接解构后取 `.plugin`（`const [{ plugin }] = dependencies;`），删除 `dataDeps[0]?.plugin as IShopPlugin \| undefined` 与非空判断；在「逐项说明」和「边界与注意」明确依赖已在插件执行前解析完毕。 | +| U4-04 | 「注册与目录」移到文档开头：并列给出 `src/data/plugin/` 与 `src/client/plugin/` 目录、`dataPlugins` 与 `clientPlugins` 两个列表、两个入口的拼接方式；渲染端插件与数据端按同等篇幅覆盖，并补充 `ClientShopPlugin` 的说明。 | +| U4-05 | 删除「插件 id 稳定性与版本迁移」整节，以及小结里对应的 id 契约条目。 | +| U4-06 | 示例泛型统一使用接口名：`getDataPlugin`、`getDataPlugin`，不再出现 `getDataPlugin`；插件对外接口统一用 `I` 前缀，数据端模板把 `IMyPlugin` 放进 `types.ts`。 | +| U4-07 | 改为先模板后解释：插件系统先列数据端 `types.ts` / `plugin.ts` 与渲染端 `plugin.ts` 模板，再逐项解释 `id` / `dataDeps` / `clientDeps` / `awake` / `initialize` / `afterLoad`；声明式篇的伤害计算器与钩子也改成先给完整示例、再解释时机与原因。 | +| U4-08 | 新增「插件之外也能调用」小节：以钩子为例，通过 `state.getDataPlugin` 取回插件并调用其公开成员，明确调用方不必是插件。 | + +**构建：** `pnpm exec prettier --check docs/advanced/plugin-system.md docs/advanced/declarative-vs-imperative.md` 通过；`pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build` 输出 `build complete`，无 dead link。 + +**状态：处理中** + diff --git a/docs/advanced/declarative-vs-imperative.md b/docs/advanced/declarative-vs-imperative.md index 8109ab9..28a2360 100644 --- a/docs/advanced/declarative-vs-imperative.md +++ b/docs/advanced/declarative-vs-imperative.md @@ -1,6 +1,6 @@ # 声明式 vs 命令式接口 -如果你已经会用中级教程里的接口做效果，可能注意过一件事：同样是「让某只怪物更强」，有的写法是直接改数值，有的写法只是往数据里加一条 `special`。这不是新旧语法的差别，而是两种完全不同的思路。 +如果你已经会用中级教程里的接口做效果，可能注意过一件事：同样是「让勇士打出更高伤害」，有的写法是在事件脚本里直接改攻击力，有的写法只是换一个伤害计算器。这不是新旧语法的差别，而是两种完全不同的思路。 高级教程后续的插件、存档、录像与钩子，都建立在第二种思路上。这一层如果没弄明白，后面每篇都会变成死记接口。本篇把两种思路讲透，并告诉你什么时候该用哪一种。 @@ -39,9 +39,9 @@ function healHero(hero: IHeroState): void { 这种写法的执行时机非常直观：代码走到哪，效果就发生到哪。但它会带来几个后果： - 只在执行到的那一瞬间生效。脚本没被触发，效果就不存在；触发第二次，效果就再来一次。 -- 想重新计算只能重跑。怪物移动、光环范围变化之后，旧数值不会自动更新；再跑一遍脚本，又容易把加成叠加两次。 +- 想重新计算只能重跑。怪物移动、周围条件变化之后，旧数值不会自动更新；再跑一遍脚本，又容易把加成叠加两次。 - 每条路径都要自己同步。存档、读档、录像回放、重新进入楼层，这些路径都可能绕开你写的那段脚本，于是状态对不上。 -- 没法凭空给怪物加特殊属性。直接改 `atk` 只是改了一个数字，不能让怪物「获得一条领域属性」。 +- 没法凭空给怪物加特殊属性。直接改 `atk` 只是改了一个数字，不能让怪物获得一条领域属性；特殊属性本身的写法见[特殊属性](../intermediate/enemy-specials.md)。 这不是说命令式一无是处。玩家点一下、走一步、用一次道具，本来就是「现在立刻发生」的动作，用命令式接口最直接。问题只出在：把持续生效的规则也写成了一次性命令。 @@ -49,28 +49,42 @@ function healHero(hero: IHeroState): void { 新样板把规则与调用时机拆开。下面五组都是当前源码里真实存在的机制，也是后续高级内容的基础。 -### 怪物特殊属性与光环 - -你声明什么：怪物数据上的 `special` 字段。键是特殊属性编号，值是该属性的参数。比如给怪物声明一条光环（编号 `23`），参数类型是 `ISpecial23Value`，定义在 `src/data/enemy/special.ts`： - -```ts -// special 字段里编号 23 的值，类型为 ISpecial23Value -const aura: ISpecial23Value = { - range: 1, // 光环范围，单位为格 - square: false, // true 为矩形范围，false 为十字型范围 - hpBuff: 0, // 三项都是百分比：生命、攻击、防御 - atkBuff: 20, - defBuff: 0 -}; -``` - -引擎在哪个时机执行：构建「计算后怪物」时。`state.enemyContext.buildup()` 会按固定顺序重建每只怪物，把光环、查询与最终效果真正写进属性；`aura.ts` 里的 `CommonAuraConverter` 负责把编号 `23` 转成 `CommonAura` 视图，这个转换器在初始化时通过 `ctx.registerAuraConverter(...)` 注册一次。 - -为什么这比命令式更稳：怪物模板本身没有被改写，每次重建都从模板的原始值出发，所以反复重建不会让加成越叠越多；你改的是数据里的一条声明，所有读取计算后怪物的场景都会自动看到新结果；存档也只需要保存模板。更细的构建流程见[战斗总览](../intermediate/combat-overview.md)，属性本身的写法见[特殊属性](../intermediate/enemy-specials.md)。 - ### 伤害计算器 -你声明什么：一组属性到伤害结果的换算规则。核心是实现 `IDamageCalculator.calculate(handler)`，返回 `{ damage, turn }`；接口还有 `getCriticalLimit(handler, attribute)` 供临界值计算，改公式时按内置实现 `MainDamageCalculator` 的写法保留它即可。内置实现通过 `useCalculator(new ...)` 注册一次。 +你声明什么：一组属性到伤害结果的换算规则。下面是它的完整模板： + +```ts +import { IEnemyAttr, IHeroAttr } from '@user/data-common'; +import { + CriticalableHeroStatus, + IDamageCalculator, + IEnemyDamageInfoBase, + IReadonlyDamageHandler +} from '@user/data-system'; + +// 伤害计算器模板：只读输入，返回这次战斗的伤害与回合数 +export class MyDamageCalculator implements IDamageCalculator< + IEnemyAttr, + IHeroAttr +> { + calculate( + handler: IReadonlyDamageHandler + ): IEnemyDamageInfoBase { + // 按 handler 里的属性算出结果 + return { damage: 0, turn: 0 }; + } + + getCriticalLimit( + handler: IReadonlyDamageHandler, + attribute: CriticalableHeroStatus + ): number { + // 临界计算的上限；多数需求用不到 + return 0; + } +} +``` + +`calculate` 是日常唯一需要关心的成员：它接收 `handler`，返回 `{ damage, turn }`。`getCriticalLimit` 只在临界值计算时用到，改公式时按内置实现 `MainDamageCalculator` 的写法保留即可。内置实现通过 `useCalculator(new ...)` 注册一次。 引擎在哪个时机执行：任何需要伤害数值的地方。显示伤害预览、计算临界值、真正结算战斗，都会调用计算器；同一场战斗里，它可能被反复调用很多次。 @@ -78,6 +92,14 @@ const aura: ISpecial23Value = { 改公式与注册的完整做法见[伤害计算](../intermediate/enemy-calculator.md)。 +### 特殊属性与光环 + +你声明什么：特殊属性本身，而不是某只怪物的属性对象。它们在 `src/data/enemy/special.ts` 的 `createSpecials(state)` 里统一注册：每个编号对应一条定义，说明这个属性能做什么、参数长什么样；光环再把编号映射成一个转换器，在初始化时通过 `ctx.registerAuraConverter(...)` 注册一次。怪物数据里只出现编号与参数，不会出现手写的属性对象。 + +引擎在哪个时机执行：构建「计算后怪物」时。`state.enemyContext.buildup()` 按固定顺序重建每只怪物，把特殊属性、查询与最终效果写进属性。 + +为什么这比命令式更稳：每次重建都从模板的原始值出发，反复重建不会让加成越叠越多；你改的是注册表里的一条定义，所有读取计算后怪物的场景都会自动看到新结果；存档也只需要保存模板。更细的构建流程与特殊属性写法见[战斗总览](../intermediate/combat-overview.md)与[特殊属性](../intermediate/enemy-specials.md)。 + ### 道具效果 你声明什么：道具被使用或拾取时要做的事，即道具数据上的效果对象。要实现效果，实现 `IItemEffect` 的 `useEffect(item, state)`；如果还要判断能不能用，再实现 `canUse(item, state)`。 @@ -96,9 +118,7 @@ const aura: ISpecial23Value = { ### 钩子 -你声明什么：某个动作发生时要做的事。实现对应的钩子族接口，把处理写进方法体。比如「勇士属性变化时做点什么」，就实现 `IHeroAttributeHooks` 的 `onUpdateAttribute`。 - -引擎在哪个时机执行：对应动作发生时。主对象会通过 `forEachHook` 依次通知挂在自己身上的钩子。你只需要注册一次： +你声明什么：某个动作发生时要做的事。实现对应的钩子族接口，把处理写进方法体。比如「勇士属性变化时做点什么」，就实现 `IHeroAttributeHooks` 的 `onUpdateAttribute`，再像下面这样注册一次： ```ts import { ICoreState } from '@user/data-state'; @@ -110,7 +130,7 @@ export function registerHeroAttributeHooks(state: ICoreState): void { } ``` -不需要时可以用 `removeHook` 摘掉。内置钩子已经在初始化时注册好，你自己写的钩子才需要 `addHook`。 +引擎在哪个时机执行：对应动作发生时。主对象会通过 `forEachHook` 依次通知挂在自己身上的钩子。不需要时可以用 `removeHook` 摘掉。内置钩子已经在初始化时注册好，你自己写的钩子才需要 `addHook`。 为什么这比命令式更稳：你不需要去改每一个调用点。动作发生时引擎统一广播，多个钩子可以同时存在、各自处理；不再需要时也能干净地移除。完整用法见[钩子深入](./hooks-in-depth.md)。 @@ -133,10 +153,10 @@ export function registerHeroAttributeHooks(state: ICoreState): void { 把执行时机交给引擎，换来的是下面几件事： -1. 时机集中。所有光环都在重建计算后怪物时执行，所有存档对象都在存档时执行。调用点只有引擎一处，不会出现「这个效果我在 A 处记得调用、在 B 处忘了」。 -2. 从模板重算，避免叠加。每次重建都从模板的原始值出发，算出来的是「当前应该是什么样」，而不是「上次基础上再加一点」。命令式反复执行同一段脚本，很容易越加越多。 -3. 按注册表与优先级组合。转换器、效果、钩子都注册到对应系统里，多个扩展可以同时存在；需要顺序时由优先级决定，而不是靠你调整脚本摆放位置。 -4. 录像只记录玩家入口动作。玩家的移动、使用道具等动作进入录像，光环、伤害这些派生结果在回放时重新计算。如果派生结果依赖某段命令式脚本执行了几次，回放就会和录制时对不上。 +1. 时机集中。所有伤害计算都在需要数值时执行，所有存档对象都在存档时执行。调用点只有引擎一处，不会出现「这个效果我在 A 处记得调用、在 B 处忘了」。 +2. 每次重新计算，避免叠加。计算都从当前输入重新得出结果，算出来的是「现在应该是什么样」，而不是「上次结果上再加一点」。命令式反复执行同一段脚本，很容易越加越多。 +3. 按注册表与优先级组合。计算器、效果、钩子都注册到对应系统里，多个扩展可以同时存在；需要顺序时由优先级决定，而不是靠你调整脚本摆放位置。 +4. 录像只记录玩家入口动作。玩家的移动、使用道具等动作进入录像，伤害、属性变化这些派生结果在回放时重新计算。如果派生结果依赖某段命令式脚本执行了几次，回放就会和录制时对不上。 ## 「副作用」是什么 @@ -200,16 +220,16 @@ export class BadDamageCalculator implements IDamageCalculator< 前面五组机制各自要写什么、注册到哪里、引擎什么时候调用，放在一起看更清楚： -| 扩展点 | 你要实现的东西 | 注册入口 | 引擎调用时机 | -| ---------- | -------------------------------------------- | ---------------------------------------- | ---------------------- | -| 特殊属性 | `createSpecials` 里的一条 `map.set(code, …)` | `initializeEnemy` 统一注册，无需单独调用 | 读取或重建计算后怪物时 | -| 光环 | 一个转换器与一个视图 | `ctx.registerAuraConverter(new …)` | 重建计算后怪物时 | -| 伤害计算器 | `IDamageCalculator.calculate` | `useCalculator(new …)` | 显示、临界、战斗结算时 | -| 道具效果 | `IItemEffect.useEffect` | 写在道具数据里 | 使用或拾取道具时 | -| 可存档对象 | `ISaveableContent.saveState` / `loadState` | `state.addSaveableContent(id, content)` | 存档与读档时 | -| 钩子 | 对应钩子族接口的方法 | `addHook(new …)` | 对应动作发生时 | +| 扩展点 | 你要实现的东西 | 注册入口 | 引擎调用时机 | +| ---------- | ------------------------------------------ | ---------------------------------------- | ---------------------- | +| 特殊属性 | `createSpecials` 里的一条定义 | `initializeEnemy` 统一注册，无需单独调用 | 读取或重建计算后怪物时 | +| 光环 | 一个转换器与一个视图 | `ctx.registerAuraConverter(new …)` | 重建计算后怪物时 | +| 伤害计算器 | `IDamageCalculator.calculate` | `useCalculator(new …)` | 显示、临界、战斗结算时 | +| 道具效果 | `IItemEffect.useEffect` | 写在道具数据里 | 使用或拾取道具时 | +| 可存档对象 | `ISaveableContent.saveState` / `loadState` | `state.addSaveableContent(id, content)` | 存档与读档时 | +| 钩子 | 对应钩子族接口的方法 | `addHook(new …)` | 对应动作发生时 | -这些扩展点的写法都是「实现一个类 + 注册一次」：类里只放引擎会调用的方法，注册放在初始化函数里。示例一律写成 `class` 再 `new`，不要写成 `const obj = { ... }` 这种 plain object。 +这些扩展点大多遵循「实现一个类，再注册一次」：类里只放引擎会调用的方法，注册放在初始化函数里。道具效果写在道具数据上，不需要单独注册。 ## 小结 diff --git a/docs/advanced/plugin-system.md b/docs/advanced/plugin-system.md index e2eaf52..42bb330 100644 --- a/docs/advanced/plugin-system.md +++ b/docs/advanced/plugin-system.md @@ -1,112 +1,40 @@ # 插件系统 -如果你已经用过中级教程里的[数据插件](../intermediate/data-plugins.md)，你会知道插件能把一组功能打包、挂到 `state` 上，并按固定时机初始化。那一篇停在「会用」；这一篇讲怎么自己写一个插件、让插件彼此协作，以及为什么插件的 `id` 不能随便改。 +如果你已经用过中级教程里的[数据插件](../intermediate/data-plugins.md)，你会知道插件能把一组功能打包、挂到 `state` 上，并按固定时机初始化。那一篇停在「会用」；这一篇讲怎么自己写一个插件、让插件彼此协作，以及怎么在插件之外调用它。 + +插件分数据端与渲染端两套，写法、注册方式与生命周期一一对应：数据端插件负责逻辑与状态，渲染端插件负责画面与交互。渲染端插件可以依赖数据端插件，反过来不行。下面两边并列讲，遇到不同的地方单独说明。 插件是高级 I 的核心：后面的可存档内容、录像一致性、钩子深入，实际都挂在某个插件上。 阅读前需要会基础语法：`class`、`new`、`import`、`async` / `await`。不需要懂引擎内部实现；涉及内部机制的地方，会先说清「你能拿它做什么」。 -## 插件解决什么问题 +## 注册与目录 -假设你要加一个任务系统：它有自己的状态、自己的管理器，还要在加载完地图后读一遍任务配置。不做成插件的话，这些代码会散在几个地方——对象在 `src/data/initialize.ts` 里 `new`，存档注册也写在那里，加载后的初始化再塞进某个钩子。功能一多，`initialize.ts` 会变成所有人的公共草稿纸。 +数据端插件放在 `src/data/plugin/`，渲染端插件放在 `src/client/plugin/`，各自在自己的目录里： -插件把这一组东西收进一个独立单元： +| 位置 | 放什么 | +| ----------------------------- | ---------- | +| `src/data/plugin/<插件名>/` | 数据端插件 | +| `src/client/plugin/<插件名>/` | 渲染端插件 | -- 自己的对象在自己的目录里创建； -- 自己的存档内容在自己的 `awake` 里注册； -- 自己的加载后逻辑在自己的 `afterLoad` 里写； -- 启动时只需要在 `dataPlugins` 里 `new` 一次。 +插件目录内部按需要拆文件，常见形状两端一致： -这和[声明式接口](./declarative-vs-imperative.md)是同一个思路：你不去改引擎的初始化流程，只声明「在哪个时机做什么」，时机由引擎统一调用。 +| 文件 | 放什么 | +| --------------------------------------- | ------------------------------------------------------------- | +| `plugin.ts` | 插件类本身，实现 `IDataPluginDefine` 或 `IClientPluginDefine` | +| `types.ts` | 插件对外接口、存档数据结构 | +| `state.ts` / `manager.ts` / `system.ts` | 插件自己的对象，按需创建 | +| `index.ts` | 统一导出 | -## 插件接口 +写好后，把插件实例 `new` 进对应端的列表： -一个数据端插件实现 `IDataPluginDefine`： - -| 成员 | 类型 | 说明 | -| --------------------------------- | ---------------------------------------- | ---------------------------- | -| `id` | `string` | 插件标识符，全局唯一 | -| `dataDeps` | `readonly string[]` | 依赖的其他数据端插件 id | -| `awake(state, dependencies)` | `(state, dependencies) => void` | 同步初始化，主对象构造期调用 | -| `initialize(state, dependencies)` | `(state, dependencies) => Promise` | 异步初始化，加载开始前调用 | -| `afterLoad(state, dependencies)` | `(state, dependencies) => Promise` | 加载完毕后调用 | - -这里最容易混淆的是两处名字： - -- 声明依赖时，属性叫 `dataDeps`，写的是依赖插件的 id 字符串数组； -- 三个时机方法收到时，参数叫 `dependencies`，类型是 `Readonly[]`，元素是解析后的插件包装对象，含 `plugin` 与 `status` 两个字段。 - -所以「声明依赖」写的是 `id`，真正拿到的却是对象。两者不要混着写。 - -## 数据端与渲染端 - -插件分数据端与渲染端两套注册表：数据端插件实现 `IDataPluginDefine`，注册在 `dataPlugins`；渲染端插件实现 `IClientPluginDefine`（来自 `@user/client-modules`），注册在 `clientPlugins`。两套的生命周期时机相同，区别在依赖声明与生命周期参数。 - -| 插件类型 | 依赖声明 | 能依赖 | -| -------- | ------------------------- | ----------------------- | -| 数据端 | `dataDeps` | 数据端插件 | -| 渲染端 | `dataDeps` + `clientDeps` | 数据端插件 + 渲染端插件 | - -依赖方向是单向的：渲染端可以依赖数据端，数据端不能依赖渲染端。数据端不引用任何渲染端内容，才能在没有渲染端的环境里单独加载、存档与回放。 - -### 渲染端插件接口 - -`IClientPluginDefine` 在 `id`、`dataDeps` 之上多了一份 `clientDeps`，生命周期方法也因此多一个依赖参数： - -| 成员 | 说明 | -| ------------------------------- | ---------------------------------------- | -| `id: string` | 插件标识符，全局唯一 | -| `dataDeps: readonly string[]` | 依赖的数据端插件 id | -| `clientDeps: readonly string[]` | 依赖的渲染端插件 id | -| `awake(...)` | 同步初始化，渲染端主对象构造期调用 | -| `initialize(...)` | 异步初始化，加载开始前调用，会被 `await` | -| `afterLoad(...)` | 加载完毕后调用，会被 `await` | - -三个时机方法的第一个参数是渲染端主对象 `IClientCore`，后两个参数依次是数据端依赖 `IDataPlugin[]` 与渲染端依赖 `IClientPlugin[]`。它们直接以 `dataDeps` / `clientDeps` 命名，不再统一叫 `dependencies`，所以不必按顺序猜是哪一类。 - -```ts -import { - IClientCore, - IClientPlugin, - IClientPluginDefine -} from '@user/client-modules'; -import { IDataPlugin } from '@user/data-state'; -import { IShopPlugin } from '../../data/plugin/shop'; -import { IClientShopPlugin } from './client-shop'; - -// 渲染端插件：同时依赖一个数据端插件与一个渲染端插件 -export class MyClientPlugin implements IClientPluginDefine { - readonly id = 'my-client-plugin'; - readonly dataDeps: string[] = ['data-shop-plugin']; - readonly clientDeps: string[] = ['client-shop-plugin']; - - awake( - state: IClientCore, - dataDeps: IDataPlugin[], - clientDeps: IClientPlugin[] - ): void { - // 依赖对象已经按声明解析好，直接取用即可 - const dataShop = dataDeps[0]?.plugin as IShopPlugin | undefined; - const clientShop = clientDeps[0]?.plugin as - | IClientShopPlugin - | undefined; - } - - async initialize(): Promise {} - - async afterLoad(): Promise {} -} -``` - -两个依赖数组都要声明，没有依赖就留空。渲染端插件的注册方式与数据端对应：类写在自己的目录里，追加到 `src/client/plugin/list.ts` 的 `clientPlugins` 数组末尾；入口 `src/client/entry.ts` 同样把主插件放在数组前面。需要取回渲染端插件时用 `state.getClientPlugin(id)`，返回 `Readonly> | null`，判空方式与 `getDataPlugin` 一致。 - -渲染端尚未完工，渲染端对象具体有哪些、插件能拿它们做什么，要等完工后再写。上面这些是当前已经定稿的接口。 - -## 注册到 dataPlugins - -插件写好后，在 `src/data/plugin/list.ts` 的 `dataPlugins` 数组里追加一项，不要清空或替换已有插件： +| 端 | 列表文件 | 数组 | +| ------ | --------------------------- | --------------- | +| 数据端 | `src/data/plugin/list.ts` | `dataPlugins` | +| 渲染端 | `src/client/plugin/list.ts` | `clientPlugins` | ```ts +// src/data/plugin/list.ts import { IDataPluginDefine } from '@user/data-state'; import { DataShopPlugin } from './shop'; // 新建插件文件时，必须补上你自己的 import @@ -120,13 +48,156 @@ export const dataPlugins: IDataPluginDefine[] = [ ]; ``` -新建插件时，`list.ts` 里不会有你的类名，必须自己补一行 `import`，路径指向你的插件目录。只把数组写成 `[new MyPlugin()]` 会把商店插件挤掉。 +```ts +// src/client/plugin/list.ts +import { IClientPluginDefine } from '@user/client-modules'; +import { ClientShopPlugin } from './shop'; +import { MyClientPlugin } from './my-client'; -数据端启动时会遍历这个数组，把插件收进注册表。同一个 `id` 出现两次时，后一个会被忽略，控制台报一条错误（错误码 `78`），所以请保证 `id` 唯一。 +/** 渲染端插件列表 */ +export const clientPlugins: IClientPluginDefine[] = [ + new ClientShopPlugin(), + // 追加到末尾，不要替换上面的已有插件 + new MyClientPlugin() +]; +``` + +新建插件时，`list.ts` 里不会有你的类名，必须自己补一行 `import`，路径指向你的插件目录。只把数组写成 `[new MyPlugin()]` 会把已有插件挤掉。 + +两个入口文件分别把主插件放在数组前面，再展开各自的列表：`src/data/entry.ts` 中是 `[new MainDataPlugin(HERO_FACE), ...dataPlugins]`，`src/client/entry.ts` 中是 `[new MainClientPlugin(), ...clientPlugins]`。日常只需要改两个 `list.ts`，不必动入口。 + +同一端的注册表里，`id` 重复时后一个会被忽略，控制台报一条错误（错误码 `78`），所以请保证 `id` 在各自的注册表里唯一。 + +## 插件解决什么问题 + +假设你要加一个任务系统：它有自己的状态、自己的管理器，还要在加载完地图后读一遍任务配置。不做成插件的话，这些代码会散在几个地方——对象在 `src/data/initialize.ts` 里 `new`，存档注册也写在那里，加载后的初始化再塞进某个钩子。功能一多，`initialize.ts` 会变成所有人的公共草稿纸。 + +插件把这一组东西收进一个独立单元： + +- 自己的对象在自己的目录里创建； +- 自己的存档内容在自己的 `awake` 里注册； +- 自己的加载后逻辑在自己的 `afterLoad` 里写； +- 启动时只需要在对应端的插件列表里 `new` 一次。 + +这和[声明式接口](./declarative-vs-imperative.md)是同一个思路：你不去改引擎的初始化流程，只声明「在哪个时机做什么」，时机由引擎统一调用。 + +## 插件接口 + +数据端插件实现 `IDataPluginDefine`（来自 `@user/data-state`），渲染端插件实现 `IClientPluginDefine`（来自 `@user/client-modules`）。两者都由 `id`、依赖声明与三个时机方法组成；渲染端多一份 `clientDeps`，生命周期方法也多一个依赖参数。 + +先看两边的完整模板，后面逐项解释。 + +### 数据端插件模板 + +```ts +// src/data/plugin/my-plugin/types.ts +import { IDataPluginDefine } from '@user/data-state'; + +/** 插件对外暴露的能力；依赖它的插件按这个接口调用 */ +export interface IMyPlugin extends IDataPluginDefine { + doSomething(): void; +} +``` + +```ts +// src/data/plugin/my-plugin/plugin.ts +import { ICoreState, IDataPlugin } from '@user/data-state'; +import { IMyPlugin } from './types'; + +// 数据端插件模板 +export class MyPlugin implements IMyPlugin { + // 插件标识符：在数据端注册表里唯一 + readonly id = 'my-plugin'; + // 依赖的其他数据端插件 id；没有依赖就留空 + readonly dataDeps: string[] = []; + + awake(state: ICoreState): void { + // 在这里装配插件自己的对象 + // 需要进存档的对象，在这里调用 state.addSaveableContent(...) + } + + doSomething(): void { + // 对外方法：其他插件、钩子等通过插件对象调用 + } + + async initialize( + state: ICoreState, + dependencies: Readonly[] + ): Promise {} + + async afterLoad( + state: ICoreState, + dependencies: Readonly[] + ): Promise {} +} +``` + +### 渲染端插件模板 + +```ts +import { + IClientCore, + IClientPlugin, + IClientPluginDefine +} from '@user/client-modules'; +import { IDataPlugin } from '@user/data-state'; + +// 渲染端插件模板：写在 src/client/plugin/my-client/plugin.ts +export class MyClientPlugin implements IClientPluginDefine { + // 插件标识符：在渲染端注册表里唯一 + readonly id = 'my-client-plugin'; + // 依赖的数据端插件 id；没有依赖就留空 + readonly dataDeps: string[] = []; + // 依赖的渲染端插件 id；没有依赖就留空 + readonly clientDeps: string[] = []; + + awake( + state: IClientCore, + dataDeps: IDataPlugin[], + clientDeps: IClientPlugin[] + ): void { + // 依赖已经解析好，直接取用即可 + } + + async initialize( + state: IClientCore, + dataDeps: IDataPlugin[], + clientDeps: IClientPlugin[] + ): Promise {} + + async afterLoad( + state: IClientCore, + dataDeps: IDataPlugin[], + clientDeps: IClientPlugin[] + ): Promise {} +} +``` + +### 逐项说明 + +**`id`**：两端的插件标识符，在各自的注册表里唯一。其他插件按这个字符串声明依赖，`getDataPlugin` / `getClientPlugin` 也按它取回插件。 + +**`dataDeps`**：依赖的数据端插件 id 数组。数据端插件只能填数据端插件；渲染端插件可以填任何数据端插件。没有依赖就留空数组。 + +**`clientDeps`**：只有渲染端插件有，写依赖的渲染端插件 id。没有依赖同样留空。 + +依赖方向是单向的：渲染端可以依赖数据端，数据端不能依赖渲染端。数据端不引用任何渲染端内容，才能在没有渲染端的环境里单独加载、存档与回放。 + +**依赖参数**：三个时机方法收到的依赖是解析后的插件包装对象，不是 id 字符串，形如 `{ status, plugin }`。数据端插件的参数统一叫 `dependencies`，类型是 `Readonly[]`；渲染端插件分成 `dataDeps` 与 `clientDeps` 两个参数，类型分别是 `IDataPlugin[]` 与 `IClientPlugin[]`，顺序与声明一致。不需要时可以把依赖参数整个省略。 + +依赖在插件执行前已经解析完毕。如果声明在 `dataDeps` / `clientDeps` 里的依赖缺失或成环，插件本身不会被加载，所以拿到依赖后直接取 `.plugin` 用即可，不要判空。 + +**`awake`**：同步初始化，在主对象构造期调用。`awake` 返回 `void`，引擎不会等待它的返回值；需要 `await` 的东西放到 `initialize`。数据端此时地图与配置都还没加载，渲染端此时刚拿到渲染端主对象。 + +**`initialize`**：异步初始化，在加载开始前调用，会被 `await`。它不兑现，后面的插件与加载都不会继续。 + +**`afterLoad`**：加载完毕后调用，同样会被 `await`。适合读取加载内容之后再装配的对象。 + +三个时机的具体位置见下一节。 ## 生命周期 -三个时机在启动流程里的位置是固定的。按 `CoreState` 的实际执行顺序，可以画成这样： +三个时机在启动流程里的位置是固定的。两端一一对应，下面按数据端的执行顺序说明： ```text CoreState 构造 @@ -147,7 +218,7 @@ load() 开始 - 把它们挂到插件对象上，供后续调用； - 调用 `state.addSaveableContent(id, content)` 注册需要进存档的对象。 -需要在 `awake` 里等的东西（读文件、等网络、等加载器），都不属于这里，放到 `initialize`。 +需要在 `awake` 里等的东西（读文件、等网络、等加载器），都不属于这里，放到 `initialize`。渲染端插件同样在渲染端主对象构造期执行 `awake`，只是没有存档注册这一类数据端操作。 ### initialize：加载开始前 @@ -182,142 +253,104 @@ load() 开始 - 缺失依赖：`dataDeps` 里写了一个没有注册的 id，该插件被排除，控制台按「插件 id + 缺失的依赖 id」逐条报错（错误码 `77`）； - 下游阻断：依赖上述插件的插件也会一起被排除，三个时机一个都不执行。 -排查时先看控制台里的错误码与 id，再顺链往上找。依赖尽量少：每多一条依赖，就多一个「对方改名或失败会拖住自己」的机会。渲染端插件也按同样方式处理 `clientDeps`。 +排查时先看控制台里的错误码与 id，再顺链往上找。依赖尽量少：每多一条依赖，就多一个「对方改名或失败会拖住自己」的机会。渲染端插件之间的顺序按 `clientDeps` 同样处理；`dataDeps` 指向的数据端插件在渲染端启动前已经就绪。 -## 插件之间怎么调用 +## 调用插件 -### 用依赖参数直接调用 +插件的能力不只在插件之间使用。其他插件、钩子、事件、命令式脚本、渲染端 UI，只要拿得到对应的主对象，都可以调用插件的公开成员。 -声明了依赖，最直接的方式就是用方法参数里的插件对象。注意它是 `IDataPlugin` 包装对象，你要取 `.plugin`： +### 在插件里用依赖参数 -```ts -// 插件 B 依赖插件 A，并在初始化时调用 A 的方法 -export class PluginB implements IDataPluginDefine { - readonly id = 'plugin-b'; - readonly dataDeps = ['plugin-a']; - - awake(state: ICoreState, dependencies: Readonly[]): void { - // 参数顺序与 dataDeps 数组一致 - const a = dependencies[0]?.plugin as PluginA | undefined; - if (!a) return; - a.doSomething(); - } - - async initialize(): Promise {} - - async afterLoad(): Promise {} -} -``` - -这段按新文件写，顶部需要 `import { ICoreState, IDataPlugin, IDataPluginDefine } from '@user/data-state';` 与 `import { PluginA } from './plugin-a';`（路径按你的目录调整）。`PluginA` 需要有能被外部调用的方法。通常的做法是像 `IShopPlugin` 那样，给自己的插件定一个接口：`interface IMyPlugin extends IDataPluginDefine { ... }`，把要暴露的方法写进去。 - -拿到的是注册表里同一个包装对象，它的 `status` 会随阶段推进更新。所以你在自己 `awake` 里看到的依赖状态是 `Awakened`，在 `afterLoad` 里看到的通常已经是 `Loaded`。 - -### 用 getDataPlugin 取回 - -没有声明依赖、或者在启动之后才按需访问时，用 `state.getDataPlugin(id)`。它返回 `Readonly> | null`。下面这段放在能拿到 `state` 的方法里： - -```ts -import { ICoreState, PluginStatus } from '@user/data-state'; -import { PluginA } from './plugin-a'; - -// 取回插件，先判空，再确认状态 -export function callPluginA(state: ICoreState): void { - const holder = state.getDataPlugin('plugin-a'); - if (holder && holder.status === PluginStatus.Loaded) { - holder.plugin.doSomething(); - } -} -``` - -两个检查都不能省： - -- 返回 `null` 表示没有这个 `id`，可能是没注册，也可能是拼写错了； -- `status` 没到你要的阶段，说明它还没执行到那一步，此时调用它的方法可能读到还没装配好的字段。 - -如果在启动阶段就要用某个插件，优先声明依赖，让引擎保证顺序；`getDataPlugin` 更适合可选的、运行中才发生的调用。 - -## 插件 id 稳定性与版本迁移 - -插件有插件 id，它注册的可存档内容另有存档 id，两者互不相干： - -| 名称 | 例子 | 用在哪 | -| ------- | ------------------ | ------------------------------------------- | -| 插件 id | `data-shop-plugin` | `dataPlugins` 注册表、其他插件的 `dataDeps` | -| 存档 id | `@plugin/shop` | `state.addSaveableContent(id, content)` | - -商店插件就是现成的例子：它的插件 id 是 `data-shop-plugin`，在 `awake` 里注册的存档内容却是 `@plugin/shop`。这两个字符串没有任何推导关系，不要以为改了插件 id 存档 id 会跟着变。 - -插件 id 会被别的插件的 `dataDeps` 引用，所以它是一份对外契约： - -- 不要随意改名。改名后，依赖它的插件会变成「缺失依赖」，整条链被阻断； -- 不要复用旧 id 表示新语义。旧依赖方仍然能找到这个 id，但拿到的是另一套对象，运行时会以「方法不存在」之类的形式炸掉，而且很难从依赖声明上看出来。 - -需要演进时，按改动大小选最小做法： - -1. 行为兼容的升级：保留原 `id`，只改实现。依赖方不需要动。 -2. 语义确实变了：新增一个 id，不要复用旧 id；同时把所有依赖方的 `dataDeps` 一起改掉，不要分几次发布。 -3. 必须过渡：让旧 id 继续注册一个兼容实现（或做转发），等所有依赖方迁完再删。 -4. 存档 id 尽量不动：读档时按存档 id 找内容，改了它，旧存档里的数据就对不上。确实要改时，需要自己写迁移逻辑（读档后从旧 id 取数据写进新对象），不要只改字符串。 - -## 注册与目录 - -插件放在 `src/data/plugin/` 下自己的目录里。现有商店插件的形状可以作为参考： - -| 文件 | 放什么 | -| --------------------------------------- | ------------------------------------ | -| `plugin.ts` | 插件类本身，实现 `IDataPluginDefine` | -| `types.ts` | 插件对外接口、存档数据结构 | -| `state.ts` / `manager.ts` / `system.ts` | 插件自己的对象，按需创建 | -| `index.ts` | 统一导出 | - -然后在 `list.ts` 里 `new` 出来加进 `dataPlugins`。最终传给 `CoreState` 的插件数组在 `src/data/entry.ts` 里拼成：主插件在前，`dataPlugins` 展开在后。日常只需要改 `list.ts`，不必动 `entry.ts`。 - -## 示例：一个完整插件 - -假设要新建一个插件：它要能被启动流程加载，并拥有自己的对象与存档内容。插件放在 `src/data/plugin/` 下自己的目录里，下面这份代码写在新建的 `plugin.ts` 中，顶部的 `import` 要一起保留： +声明了依赖，最直接的方式就是用时机方法参数里的插件对象。注意它是 `{ status, plugin }` 包装对象，你要取 `.plugin`： ```ts import { ICoreState, IDataPlugin, IDataPluginDefine } from '@user/data-state'; +import { IShopPlugin } from '../shop'; -// 插件类：实现 IDataPluginDefine 的五个成员 -export class MyPlugin implements IDataPluginDefine { - // 插件 id：全局唯一，发布后不要改，其他插件可能依赖它 - readonly id = 'my-plugin'; - // 依赖的数据端插件 id；没有依赖就留空 - readonly dataDeps: string[] = []; +// 依赖商店插件，在初始化时调用它的公开成员 +export class ShopConsumerPlugin implements IDataPluginDefine { + readonly id = 'shop-consumer-plugin'; + // 依赖顺序与 dataDeps 数组一致 + readonly dataDeps = ['data-shop-plugin']; - // 插件自己的对象；暂时没有就删掉这一行以及 awake 里对应的装配 - mySystem!: MySystem; - - awake(state: ICoreState): void { - // 装配插件自己的对象；这里不要 await - this.mySystem = new MySystem(state); - // 有需要存档的数据时注册；这里是存档 id，不是插件 id - state.addSaveableContent('@plugin/my-plugin', this.mySystem); + awake(state: ICoreState, dependencies: Readonly[]): void { + // 依赖已经解析好，直接取 .plugin，不需要判空 + const [{ plugin }] = dependencies; + const dataShop = plugin as IShopPlugin; + const shop = dataShop.createShopState('my-shop'); + shop.enable(); } async initialize( state: ICoreState, dependencies: Readonly[] - ): Promise { - // 加载开始前要做的事；可以 await，但会阻塞加载 - } + ): Promise {} async afterLoad( state: ICoreState, dependencies: Readonly[] - ): Promise { - // 需要读取加载内容时写在这里 + ): Promise {} +} +``` + +依赖数组的顺序与 `dataDeps` 一致。元素是注册表里同一个包装对象，它的 `status` 会随阶段推进更新：你在自己 `awake` 里看到的依赖状态是 `Awakened`，在 `afterLoad` 里看到的通常已经是 `Loaded`。 + +要调用插件自己的成员，需要把 `.plugin` 断言成它的对外接口（例如 `IShopPlugin`）。所以写插件时，如果希望别人调用你的方法，就在 `types.ts` 里定一个 `IMyPlugin extends IDataPluginDefine`，把公开成员写进去。渲染端插件的 `dataDeps` / `clientDeps` 参数同理，分别断言成数据端接口与渲染端接口。 + +### 用 getDataPlugin 取回 + +没有声明依赖、或者在启动之后才按需访问时，用 `state.getDataPlugin(id)`。它返回 `Readonly> | null`： + +```ts +import { ICoreState, PluginStatus } from '@user/data-state'; +import { IShopPlugin } from './types'; + +// 按 id 取回插件，确认状态后再调用 +export function enableShop(state: ICoreState): void { + const holder = state.getDataPlugin('data-shop-plugin'); + if (!holder || holder.status !== PluginStatus.Loaded) { + return; + } + holder.plugin.createShopState('my-shop').enable(); +} +``` + +这里和依赖参数相反，两个检查都不能省： + +- 返回 `null` 表示没有这个 `id`，可能是没注册，也可能是拼写错了； +- `status` 没到你要的阶段，说明它还没执行到那一步，此时调用它的方法可能读到还没装配好的字段。 + +渲染端用 `state.getClientPlugin(id)`，返回 `Readonly> | null`，判空方式与 `getDataPlugin` 一致。 + +如果在启动阶段就要用某个插件，优先声明依赖，让引擎保证顺序；`getDataPlugin` 更适合可选的、运行中才发生的调用。 + +### 插件之外也能调用 + +调用方不必是插件。钩子、事件脚本、命令式函数，只要拿得到 `state`，都能按 id 取回插件并调用它的公开成员： + +```ts +import { ICoreState, PluginStatus } from '@user/data-state'; +import { IHeroAttr } from '@user/data-common'; +import { IHeroAttributeHooks } from '@user/data-base'; +import { IMyPlugin } from './types'; + +// 钩子里调用插件：钩子只负责在合适的时机触发 +export class MyAttributeHooks implements IHeroAttributeHooks { + constructor(private readonly state: ICoreState) {} + + onUpdateAttribute( + name: K, + value: IHeroAttr[K] + ): void { + const holder = this.state.getDataPlugin('my-plugin'); + if (holder?.status === PluginStatus.Loaded) { + holder.plugin.doSomething(); + } } } ``` -`MySystem` 是你自己写的类，文档不会替你定义。暂时没有对应对象时，把 `mySystem` 字段、`new MySystem(state)` 以及相关的 `addSaveableContent` 一起删掉，否则编译器会报「找不到名称 MySystem」。 - -写好后，把插件追加到 `src/data/plugin/list.ts` 的 `dataPlugins` 数组末尾，并补上新建文件的 `import`，写法见前面的「注册到 dataPlugins」。 - -需要定制的通常只有三处：类名与 `id`；`dataDeps`（没有依赖就留空，不要填插件对象）；`awake` 里的装配。需要进存档的对象必须实现 `ISaveableContent`（`saveState` / `loadState`），细节见[可存档内容](./saveable-content.md)。 +这里同样要判空与检查状态，因为 `getDataPlugin` 只是查注册表，不保证插件已经加载完成。渲染端插件用 `getClientPlugin`，写法一致。 ## 示例：读一个现有插件 @@ -358,11 +391,13 @@ export class DataShopPlugin implements IShopPlugin { - `id` 是 `data-shop-plugin`，没有依赖，所以它会在 `awake` 的第一批里执行； - `awake` 先保存 `state`，再创建系统与管理器。这两个对象都需要主对象，所以只能在这里 `new`； -- `state.addSaveableContent('@plugin/shop', this.manager)` 把管理器注册为存档内容。注册的是管理器，不是插件本身；存档 id 也另起了一套命名； +- `state.addSaveableContent('@plugin/shop', this.manager)` 把管理器注册为存档内容。注册的是管理器，不是插件本身； - `initialize` 与 `afterLoad` 都是空的：商店不依赖加载内容，装配在 `awake` 就完成了。 `IShopPlugin` 在 `IDataPluginDefine` 之上加了 `shop`、`manager`、`createShopState`，这就是「插件对外暴露能力」的写法。别的插件依赖它时，就能直接调用这些成员。 +渲染端也有形状对应的 `ClientShopPlugin`（`src/client/plugin/shop/plugin.ts`）：它的三个时机都是空的，只把 `Shop` 与 `ShopUI` 作为公开成员暴露出来，供其他渲染端插件使用。两端插件的结构一致，差别只在依赖与生命周期参数。 + ### MainDataPlugin：afterLoad 读取加载后的配置 主插件 `src/data/initialize.ts` 的 `MainDataPlugin` 是 `afterLoad` 的典型用法。它的 `awake` 负责装配朝向、寻路、加载钩子与各系统；创建勇士则放到 `afterLoad`： @@ -414,16 +449,16 @@ export class MainDataPlugin implements IDataMainPlugin { ```ts import { ICoreState, PluginStatus } from '@user/data-state'; -import { MyPlugin } from './my-plugin'; +import { IMyPlugin } from './types'; // 启动完成后取回插件并检查状态 export function checkMyPlugin(state: ICoreState): void { - const holder = state.getDataPlugin('my-plugin'); + const holder = state.getDataPlugin('my-plugin'); console.log(holder?.status === PluginStatus.Loaded, holder?.plugin); } ``` -`PluginStatus` 与 `ICoreState` 从 `@user/data-state` 引入，`MyPlugin` 从你的插件文件引入。`status` 应为 `Loaded`，`plugin` 应是你 `new` 的那个实例。如果是 `null`，先检查 `list.ts` 有没有真的 `new` 并放进数组。 +`PluginStatus` 与 `ICoreState` 从 `@user/data-state` 引入，`IMyPlugin` 是你写在插件 `types.ts` 里的对外接口。`status` 应为 `Loaded`，`plugin` 应是你 `new` 的那个实例。如果是 `null`，先检查 `list.ts` 有没有真的 `new` 并放进数组。 想确认依赖阻断，可以把 `dataDeps` 里的某个 id 改成一个不存在的名字再启动：控制台应报缺失依赖错误（`77`，带插件 id 与缺失的依赖 id），并且你的插件没有任何时机输出。插件注册的存档内容如何验证，见[可存档内容](./saveable-content.md)的「验证」一节。 @@ -431,19 +466,18 @@ export function checkMyPlugin(state: ICoreState): void { - 在 awake 里 await。`awake` 的返回值会被忽略，写 `async awake` 也不会被等待。异步准备放到 `initialize`。 - 把 dataDeps 写成对象。它必须是 id 字符串数组；插件对象是三个时机方法收到的参数，不是声明时写的东西。 +- 对依赖参数判空。依赖在插件执行前已经解析好，写 `dataDeps[0]?.plugin` 只会掩盖声明错误；直接取 `dataDeps[0].plugin`。 - 依赖成环。环上的插件全部被排除，依赖它们的下游也不执行。依赖关系要单向。 - 依赖 id 拼错。插件不会报「找不到类」，而是被当作缺失依赖排除；控制台会给出插件 id 与缺失的 id。 -- 用 getDataPlugin 不判空。它可能返回 `null`，也可能处于你还没等到阶段。 -- 把插件 id 当显示名随意改。别的插件的 `dataDeps` 会立刻失效，存档 id 也不会跟着变。 +- 用 getDataPlugin 不判空。它查的是注册表，可能返回 `null`，也可能还没到你需要的阶段。 - 直接改其他系统的内部字段。插件之间应通过公开方法与接口协作；直接改私有字段会绕开对方维护的一致性逻辑。 ## 小结 -- 插件把一组对象与它们的生命周期收进一个独立单元，启动时在 `dataPlugins` 里 `new` 一次。 -- `dataDeps` 声明的是 id 字符串；三个时机方法收到的是解析后的插件对象。 -- 渲染端插件实现 `IClientPluginDefine`，用 `dataDeps` 与 `clientDeps` 分别声明两类依赖；渲染端可以依赖数据端，数据端不能依赖渲染端。 +- 插件把一组对象与它们的生命周期收进一个独立单元，在对应端的 `list.ts` 里 `new` 一次。 +- 数据端与渲染端的写法一一对应；`dataDeps` 声明数据端依赖，渲染端另有 `clientDeps`；渲染端可以依赖数据端，数据端不能依赖渲染端。 - `awake` 在构造期同步执行，不能等异步；`initialize` 在加载前、`afterLoad` 在加载后，二者都会阻塞。 - 三个阶段都按依赖顺序走；循环依赖、缺失依赖会连同下游一起被阻断。 -- 插件 id 是对外契约，不要随意改名或复用；它与可存档 id 是两套命名。 +- 插件可以被其他插件调用，也可以在钩子、事件或任何拿得到主对象的地方按 id 取回调用。 返回[高级 I 导览](./index.md)。