HumanBreak/docs/api/user-data-base/钩子.md

游戏事件钩子 API 文档

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

---

GameLoading 加载进度钩子

核心事件说明

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

---

使用示例

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	加载存档时	无

---

使用示例

// 监听玩家移动事件
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('读档成功！');
});

---

弃用说明

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