# 游戏事件钩子 API 文档

本文档由 `DeepSeek R1` 模型生成并微调。

---

## GameLoading 加载进度钩子

### 核心事件说明

| 事件名             | 触发时机                   | 参数 |
| ------------------ | -------------------------- | ---- |
| `coreLoaded`       | 核心脚本加载完成时         | 无   |
| `autotileLoaded`   | 所有自动元件资源加载完成时 | 无   |
| `coreInit`         | 核心类初始化完成时         | 无   |
| `loaded`           | 所有启动必要资源加载完成时 | 无   |
| `registered`       | 客户端和数据端都完成挂载时 | 无   |
| `dataRegistered`   | 数据端服务挂载完成时       | 无   |
| `clientRegistered` | 渲染端挂载完成时           | 无   |

---

### 使用示例

```typescript
import { loading } from '@user/data-base';

// 监听核心初始化事件
loading.on('coreInit', () => {
    console.log('核心系统已就绪');
    initializeCustomModules();
});

// 监听完整加载事件
loading.once('loaded', () => {
    showMainMenu();
    preloadOptionalAssets();
});
```

---

## GameEvent 游戏运行时钩子

### 核心事件说明

| 事件名             | 触发时机                             | 参数                                                                            |
| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------- |
| `reset`            | 游戏初始化时，例如读档后、进入游戏后 | 无                                                                              |
| `mounted`          | 游戏 DOM 挂载完成后                  | 无                                                                              |
| `statusBarUpdate`  | 状态栏更新时                         | 无                                                                              |
| `renderLoaded`     | 渲染端加载完成时                     | 无                                                                              |
| `afterGetItem`     | 拾取道具后                           | `[itemId: 道具ID, x: 坐标X, y: 坐标Y, isGentleClick: 是否轻击]`                 |
| `afterOpenDoor`    | 成功开门后                           | `[doorId: 门动画ID, x: 坐标X, y: 坐标Y]`                                        |
| `afterChangeFloor` | 楼层切换完成后                       | `[floorId: 新楼层ID]`                                                           |
| `moveOneStep`      | 玩家移动一步后                       | `[x: 新坐标X, y: 新坐标Y, floorId: 当前楼层ID]`                                 |
| `afterBattle`      | 战斗结算完成后                       | `[enemy: 敌人数据对象, x?: 战斗坐标X, y?: 战斗坐标Y]`                           |
| `changingFloor`    | 楼层切换过程中（动画播放时）         | `[floorId: 目标楼层ID, heroLoc: 玩家位置对象]`                                  |
| `setBlock`         | 地图图块被修改时                     | `[x: 坐标X, y: 坐标Y, floorId: 楼层ID, newBlock: 新图块值, oldBlock: 旧图块值]` |
| `enemyExtract`     | 解析敌人数据时                       | `[col: 敌人集合对象]`                                                           |
| `restart`          | 从游戏返回标题界面时                 | 无                                                                              |
| `setBgFgBlock`     | 设置背景/前景图块时                  | `[name: 图层名称, number: 图块值, x: 坐标X, y: 坐标Y, floorId: 楼层ID]`         |
| `replayStatus`     | 录像播放状态切换时                   | `[replaying: 是否正在回放]`                                                     |
| `loadData`         | 加载存档时                           | 无                                                                              |

---

### 使用示例

```typescript
// 监听玩家移动事件
hook.on('moveOneStep', (x, y, floorId) => {
    console.log(x, y, floorId);
});

// 监听战斗结束事件
hook.on('afterBattle', (enemy, x, y) => {
    console.log(enemy, x, y);
});

// 监听存档加载事件
hook.once('loadData', () => {
    console.log('读档成功！');
});
```

---

## 弃用说明

```typescript
/**
 * @deprecated 自 v2.B 起废弃的 GameListener
 * 计划在 v2.C 移除，请使用新的 UI 交互系统代替
 */
export const gameListener = new GameListener();
```