From d882668ba051c15360c4c9f69d8973e2d639479e Mon Sep 17 00:00:00 2001
From: unanmed <1319491857@qq.com>
Date: Sat, 17 Oct 2026 21:16:33 +0800
Subject: [PATCH] =?UTF-8?q?docs(10-09):=20=E5=BC=95=E5=AF=BC=E5=BC=8F?=
 =?UTF-8?q?=E9=87=8D=E5=86=99=20hooks=E3=80=81events?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- hooks 以「某个动作发生时想插一手」引导，保留需求→钩子对照表与 addHook/removeHook
- events 以「内建动作 + 也能自己加」引导，保留 BuiltInFunction、env、注册与两示例
---
 docs/intermediate/events.md |  6 ++++--
 docs/intermediate/hooks.md  | 12 ++++++------
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/docs/intermediate/events.md b/docs/intermediate/events.md
index 041a31b..6e063ea 100644
--- a/docs/intermediate/events.md
+++ b/docs/intermediate/events.md
@@ -1,10 +1,12 @@
 # 自定义事件
 
-事件系统让地图事件可以调用一段代码。引擎内置了一批事件函数，例如设置图块、移动勇士；你也可以按同样的方式**自定义新的事件函数**，让事件语句调用到它。本篇只讲如何自定义，不展开事件系统的原理。
+在地图事件里，你能调用一批内建动作——设置图块、移动勇士、往事件里再插一段……这些都是引擎内置的**事件函数**。当内置的还不够用时，你也能照着同样的方式加一个自己的动作，让事件语句调用到它。
+
+本篇只讲「如何自定义新的事件函数」，不展开事件系统的原理。事件环境里会用到数据端主对象 `state`，它的获取方式与含义见[数据端总览](./data-state-overview.md)。
 
 ## 内建函数（BuiltInFunction）
 
-事件里能调用的每一个动作都是一个**内建函数**，接口为 `BuiltInFunction`：
+事件里能调用的每一个动作都叫**内建函数**，接口为 `BuiltInFunction`：
 
 ```ts
 interface BuiltInFunction<P, E> {
diff --git a/docs/intermediate/hooks.md b/docs/intermediate/hooks.md
index 5e57ae9..595c786 100644
--- a/docs/intermediate/hooks.md
+++ b/docs/intermediate/hooks.md
@@ -1,12 +1,12 @@
 # 钩子
 
-钩子（hook）是本引擎提供的「事件订阅」机制。当游戏里发生某个关键动作时，主对象会通知所有挂在它上面的钩子；你在钩子里写下想做的事，就能在正确的时机介入游戏流程。
+游戏里的某个动作发生时——勇士属性变了、战斗开始了、门被推开了——你希望「顺手做点什么」，但又不想去改引擎本身的代码。钩子（hook）就是为此准备的：它是本引擎提供的「事件订阅」机制。动作发生，主对象会依次通知挂在它上面的钩子；你把想做的事写进钩子方法，就能在正确的时机介入。
 
 ## 钩子是什么
 
-数据端的主对象（如勇士、地图、战斗流程等）在发生关键动作时，会依次调用自己身上每个钩子的对应方法。你只需要写一个钩子对象，把它注册到关心的主对象上，就能在这些动作发生时收到通知。
+在数据端，勇士、地图、战斗流程等主对象在发生关键动作时，会依次调用自己身上每个钩子的对应方法。于是你只需要写一个钩子对象、把它注册到关心的主对象上，就能在这些动作发生时收到通知。
 
-一个钩子对象就是若干个方法的集合，方法名对应「什么时候触发」。例如想在勇士属性变化时做点什么，就实现 `onUpdateAttribute`：
+一个钩子对象就是一组方法的集合，**「什么时候」由方法名决定，「做什么」由方法体决定**。例如想在勇士属性变化时做点什么，就实现 `onUpdateAttribute`：
 
 ```ts
 const hook = {
@@ -39,7 +39,7 @@ const hook = {
 
 ## 需求 → 钩子对照表
 
-下表把常见需求和对应的钩子方法列在一起，照着找即可：
+真要动手时，多半是先有一个需求、再去找它对应哪个钩子。下表把常见需求和对应的钩子方法列在一起，照着找即可：
 
 | 需求 | 对应钩子 |
 | --- | --- |
@@ -62,7 +62,7 @@ const hook = {
 
 ## 注册与移除钩子
 
-用 `addHook` 把钩子对象注册到主对象上，它会返回一个控制器：
+写好了钩子对象，还要挂到目标主对象上。用 `addHook` 完成注册，它会返回一个控制器：
 
 ```ts
 const controller = state.hero.attribute.addHook({
@@ -100,4 +100,4 @@ controller.unload();
 
 钩子由所属主对象触发，但同一个主对象可能对应多个游戏对象（例如场上有多只怪物）。因此钩子被触发时，不一定是针对你关心的那一只；当场上存在多个同类主对象时，需要在回调里根据传入的参数判断是否为你的目标对象。一般情况下不会串。
 
-钩子建立在数据端的主对象之上，两端分工见 [数据端与渲染端](./data-vs-render.md)；编写钩子所需的语法见 [代码基础](./code-basics.md)。
+钩子建立在数据端的主对象之上，两端分工见[数据端与渲染端](./data-vs-render.md)；编写钩子所需的语法见[代码基础](./code-basics.md)。