mirror of
https://github.com/motajs/template.git
synced 2026-10-22 23:40:20 +08:00
docs(10-11): 按 D-48 重做实操（其他组）
- events.md：设置 Flag / 勇士回血 两个示例改写为六步实操，删除 import 并补复制说明；删去约 100 个 / 发布前 数量类信息（保留内置事件集已完整的视角） - data-plugins.md：注册插件片段删除 import 并补复制说明，包来源改为直接说明；生命周期讲解与占位示例保留 - 10-11-READER-REVIEW.md：追加用户循环 batch 6（D-48 实操·其他）记录
This commit is contained in:
parent
454325052f
commit
66a75b08ad
@ -415,3 +415,30 @@
|
||||
- 构建门禁：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` → **green**，输出 `build complete`，dead link = 0。
|
||||
- 边界：仅改 `docs/intermediate/*.md`（`combat-overview` 无实操、不改）；未改 `config.ts` 与任何生产代码；未新增文件；未引入指向 `docs/advanced/` 的真实链接（D-47 预留仍为代码 span + HTML 注释）；未引入 `dev.md` 引擎开发约定，未写发布前/数量类信息。
|
||||
|
||||
---
|
||||
|
||||
## 用户循环 · batch 6 记录（D-48 实操·其他）
|
||||
|
||||
**范围：** 用户修订循环第 1 轮 batch 6（D-48 实操写法）——「其他」组 3 篇（`events`、`replay-commands`、`data-plugins`）。沿用 batch 4/5 的口径：**保留系统/原理讲解**，只重做「实操/示例」部分，使其可分步照抄（目标 → 改哪里 → 复制什么 → 改什么 → 怎么验证 → 注意）；片段一律去掉 `import`，并显式给出「顶部通常已有、不要重复粘，报缺再补」的说明（统一指向 `code-basics.md` 的「照抄教程里的代码时，怎么处理 import」）。既有的 U-20 / U-21 / B-10 / B-12 等修正全部保留。
|
||||
|
||||
### 逐条处置
|
||||
|
||||
| 文档 | 处置 |
|
||||
| --- | --- |
|
||||
| `events.md` | ①两个示例（「设置 Flag」「勇士回血」）各改写为六步实操，片段删去 `import { BuiltInFunction } from '@motajs/anon-tokyo'` 与 `import { IBlockEventEnv } from '@user/data-system'`，补复制说明；包来源在「注意」中保留一句并回指 `src-tour`「包从哪来」（B-01 修正保留）。②按 D-48 删去「发布前会提供约 100 个」「内置事件总数约 100 个」「（发布前合计约 100 个）」三处**数量 / 发布前**信息，「内置事件集已完整 / 相当完整」的 U-20 视角保留（不再以具体数字表述）。③`BuiltInFunction`、`IBlockEventEnv`、参数接口、注册入口、内置导读、编辑器识别等系统讲解原样保留。 |
|
||||
| `replay-commands.md` | 本篇按 D-43 **本就不给示例**，全文无代码片段、无 `import`；「新增自定义录像指令」三步为分步文字指令，无需改动。U-21 的高级教程说明与 D-47 预留标记（代码 span `高级教程 · 录像指令` + `<!-- TODO(advanced): 录像指令 -->`）保留。本批不改。 |
|
||||
| `data-plugins.md` | ①「注册插件」片段删去 `import { IDataPluginDefine } from '@user/data-state'` 与 `import { DataShopPlugin } from './shop'`，补复制说明；把原「示例里的 `@user/*` 是包名」改为直接说明 `IDataPluginDefine` 来自 `@user/data-state`（指回 `src-tour`「包从哪来」）。②「插件定义」「时机次序」（含 B-12 的 `dependencies` 两义区分）、「可存档内容」、D-47 预留、`示例` 占位（N-4）原样保留——示例仍为占位，待用户提供较简单插件（D-44）。 |
|
||||
|
||||
### 共用复制说明（各篇统一）
|
||||
|
||||
> 复制说明：片段已省略 `import`；文件顶部通常已有，不要再粘。若编辑器提示缺少某个名字，再在顶部补对应的 `import`（详见 `code-basics.md` 的「照抄教程里的代码时，怎么处理 import」）。
|
||||
|
||||
### 校验
|
||||
|
||||
- 结构门禁：本批所涉 3 篇（含未改的 `replay-commands`）复核为 CRLF、单 H1（`STRUCT-OK`）。
|
||||
- 格式门禁：`node node_modules/prettier/bin/prettier.cjs --write docs/intermediate/*.md`（D-45）已跑，全部 `unchanged`（内容本就符合 prettier）。
|
||||
- 构建门禁：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` → **green**，输出 `build complete`，dead link = 0。
|
||||
- 边界：仅改 `docs/intermediate/*.md`（`replay-commands` 按 D-43 无示例、不改）；未改 `config.ts` 与任何生产代码；未新增文件；未引入指向 `docs/advanced/` 的真实链接（D-47 预留仍为代码 span + HTML 注释）；未引入 `dev.md` 引擎开发约定，未写发布前/数量类信息。
|
||||
- 备注：D-48 明确不写「发布前/数量类无关信息」，与 batch 3 U-20 曾写入的「发布前约 100 个」冲突；本批按 D-48 删去该数字表述，仅保留「内置事件集已完整」的视角。
|
||||
- 结论：中级教程 24 篇的 D-48 实操改写（概念 / 基础 / 战斗 / 其他四组）至此全部覆盖。
|
||||
|
||||
|
||||
@ -34,16 +34,15 @@ awake（装配）→ initialize（加载前）→ afterLoad（加载后）
|
||||
|
||||
## 注册插件
|
||||
|
||||
插件在 `src/data/plugin/list.ts` 的 `dataPlugins` 数组中登记（示例里的 `@user/*` 是包名，含义见 [src 导览](./src-tour.md) 的「包从哪来」）：
|
||||
插件在 `src/data/plugin/list.ts` 的 `dataPlugins` 数组中登记；`IDataPluginDefine` 来自 `@user/data-state`（包名含义见 [src 导览](./src-tour.md) 的「包从哪来」）：
|
||||
|
||||
```ts
|
||||
import { IDataPluginDefine } from '@user/data-state';
|
||||
import { DataShopPlugin } from './shop';
|
||||
|
||||
/** 数据端插件列表 */
|
||||
export const dataPlugins: IDataPluginDefine[] = [new DataShopPlugin()];
|
||||
```
|
||||
|
||||
> 复制说明：片段已省略 `import`；文件顶部通常已有，不要再粘。若编辑器提示缺少某个名字，再在顶部补对应的 `import`（详见 [代码基础](./code-basics.md) 的「照抄教程里的代码时，怎么处理 import」）。
|
||||
|
||||
数据端启动时按这个列表加装插件。把你自己写的插件 `new` 出来加进数组即可（插件目录见[源码导览](./src-tour.md)）。
|
||||
|
||||
## 可存档内容
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# 自定义事件
|
||||
|
||||
在地图事件里，你能调用一批内建动作——设置图块、移动勇士、往事件里再插一段……这些都是引擎内置的**事件函数**。内置事件集已经相当完整（发布前会提供约 100 个，覆盖地图、玩家、事件、流程控制等常用动作）；当你需要其中没有的额外动作时，也能照着同样的方式加一个自己的事件函数，让事件语句调用到它。
|
||||
在地图事件里，你能调用一批内建动作——设置图块、移动勇士、往事件里再插一段……这些都是引擎内置的**事件函数**。内置事件集已经相当完整（覆盖地图、玩家、事件、流程控制等常用动作）；当你需要其中没有的额外动作时，也能照着同样的方式加一个自己的事件函数，让事件语句调用到它。
|
||||
|
||||
本篇只讲「如何自定义新的事件函数」，不展开事件系统的原理。事件环境里会用到数据端主对象 `state`，它的获取方式与含义见[数据端总览](./data-state-overview.md)。
|
||||
|
||||
@ -58,7 +58,7 @@ interface ISetBlockEventParam {
|
||||
|
||||
## 注册事件
|
||||
|
||||
光写内建函数还不够，还要把它注册进事件系统。注册入口是 `src/data/event/registrations.ts` 的 `createEventRegistrations()`，它返回一个 `BuiltInFunction[]`。下面是它的**节选**（内置事件总数约 100 个，这里只列几个作示例）：
|
||||
光写内建函数还不够，还要把它注册进事件系统。注册入口是 `src/data/event/registrations.ts` 的 `createEventRegistrations()`，它返回一个 `BuiltInFunction[]`。下面是它的**节选**（这里只列几个作示例）：
|
||||
|
||||
```ts
|
||||
export function createEventRegistrations(): BuiltInFunction[] {
|
||||
@ -76,7 +76,7 @@ export function createEventRegistrations(): BuiltInFunction[] {
|
||||
new EventInsertEvents(),
|
||||
new EventInsertEvent()
|
||||
|
||||
// ...其余内置事件（发布前合计约 100 个）
|
||||
// ...其余内置事件
|
||||
];
|
||||
}
|
||||
```
|
||||
@ -95,12 +95,13 @@ export function createEventRegistrations(): BuiltInFunction[] {
|
||||
|
||||
## 示例：设置 Flag
|
||||
|
||||
下面这个事件函数把参数里的 Flag 名与值写进 Flag 系统。示例为了紧凑，把参数接口 `ISetFlagEventParam` 直接写在同一个代码块里；实际编写时按上文「参数接口」一节，把它放进 `src/data/event/types.ts`，只把事件函数类放到 `src/data/event/` 下（示例里的 `@motajs/*`、`@user/*` 是包名，含义见 [src 导览](./src-tour.md) 的「包从哪来」）：
|
||||
**目标**：让事件语句能调用一个 `setFlag` 动作，把指定的 Flag 字段设为指定值。
|
||||
|
||||
**改哪里**：事件函数**类**放进 `src/data/event/` 下的文件（可新建，也可并入与该功能相关的现有文件，例如图块相关的放进 `map.ts`）；下面的参数接口 `ISetFlagEventParam` 放进 `src/data/event/types.ts`；再注册进 `src/data/event/registrations.ts` 的 `createEventRegistrations()`。
|
||||
|
||||
**复制什么**：
|
||||
|
||||
```ts
|
||||
import { BuiltInFunction } from '@motajs/anon-tokyo';
|
||||
import { IBlockEventEnv } from '@user/data-system';
|
||||
|
||||
interface ISetFlagEventParam {
|
||||
/** Flag 名 */
|
||||
readonly field: string;
|
||||
@ -120,7 +121,9 @@ export class EventSetFlag implements BuiltInFunction<
|
||||
}
|
||||
```
|
||||
|
||||
写好后加进 `createEventRegistrations()`：
|
||||
> 复制说明：片段已省略 `import`；文件顶部通常已有，不要再粘。若编辑器提示缺少某个名字，再在顶部补对应的 `import`（详见 [代码基础](./code-basics.md) 的「照抄教程里的代码时，怎么处理 import」）。
|
||||
|
||||
再把新类加进注册数组：
|
||||
|
||||
```ts
|
||||
export function createEventRegistrations(): BuiltInFunction[] {
|
||||
@ -131,16 +134,21 @@ export function createEventRegistrations(): BuiltInFunction[] {
|
||||
}
|
||||
```
|
||||
|
||||
Flag 的读写接口见 [Flag 变量](./flags.md)。
|
||||
**改什么**：把 `'setFlag'` 换成你的事件名（需全局唯一）；把 `setFieldValue(...)` 那一行换成你要执行的动作。
|
||||
|
||||
**怎么验证**：在事件语句里写一句 `setFlag(...)` 调用它，运行后读对应 Flag，应能看到写入的值（Flag 的读写见 [Flag 变量](./flags.md)）。
|
||||
|
||||
**注意**：`BuiltInFunction` 来自 `@motajs/anon-tokyo`、`IBlockEventEnv` 来自 `@user/data-system`（包名含义见 [src 导览](./src-tour.md) 的「包从哪来」），顶部缺哪个再补哪个；参数接口建议放进 `src/data/event/types.ts`，与内置参数放在一起。
|
||||
|
||||
## 示例：勇士回血
|
||||
|
||||
再写一个让勇士回复生命值的事件函数。它读取参数里的回复量，通过可修改属性接口加到勇士的 `hp` 上（参数接口同样应放入 `src/data/event/types.ts`，这里为紧凑仍内联书写）：
|
||||
**目标**：让事件语句能调用一个 `healHero` 动作，按给定数值回复勇士生命值。
|
||||
|
||||
**改哪里**：事件函数类放进 `src/data/event/` 下；参数接口 `IHealHeroEventParam` 放进 `src/data/event/types.ts`；再注册进 `createEventRegistrations()`（方式同上例）。
|
||||
|
||||
**复制什么**：
|
||||
|
||||
```ts
|
||||
import { BuiltInFunction } from '@motajs/anon-tokyo';
|
||||
import { IBlockEventEnv } from '@user/data-system';
|
||||
|
||||
interface IHealHeroEventParam {
|
||||
/** 回复的生命值 */
|
||||
readonly hp: number;
|
||||
@ -158,7 +166,13 @@ export class EventHealHero implements BuiltInFunction<
|
||||
}
|
||||
```
|
||||
|
||||
勇士属性的读写方式见[勇士属性](./hero-attribute.md)。
|
||||
> 复制说明：片段已省略 `import`；文件顶部通常已有，不要再粘。若编辑器提示缺少某个名字，再在顶部补对应的 `import`（详见 [代码基础](./code-basics.md) 的「照抄教程里的代码时，怎么处理 import」）。
|
||||
|
||||
**改什么**：把 `'healHero'` 换成你的事件名；把 `add('hp', param.hp)` 换成你要调整的属性与数值。
|
||||
|
||||
**怎么验证**：在事件里调用 `healHero(...)`，勇士生命值应增加对应数值（勇士属性的读写见 [勇士属性](./hero-attribute.md)）。
|
||||
|
||||
**注意**：回复生命走可修改属性接口的 `add('hp', ...)`，不要直接改 `state.hero.attribute`；事件名需全局唯一，与内置事件重名会冲突。
|
||||
|
||||
## 编辑器识别
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user