List of Events¶

原文：List of Events

这里是 KubeJS 的所有事件列表，按触发时机分为三大类：

🚀 启动时（Startup）：脚本放 /kubejs/startup_scripts/，游戏启动时执行一次，客户端和服务端都会运行。用于注册/修改内容（自定义方块、物品、流体等）。
🖥️ 客户端（Client）：脚本放 /kubejs/client_scripts/，按 F3+T 重载。用于针对单个客户端的修改（渲染、提示文本、GUI 等）。
🌐 服务端（Server）：脚本放 /kubejs/server_scripts/，按 /reload 重载。用于游戏运行期间对世界的修改（配方、方块、实体、玩家等）。

可取消 = 事件回调返回 event.cancel() 可以阻止该行为发生。

🚀 启动时事件（Startup）¶

事件	作用	可取消
`StartupEvents.init`	游戏启动初始化时触发，适合注册事件监听、预加载内容	❌
`StartupEvents.postInit`	所有启动注册完成后触发，适合对已注册内容做关联调整	❌
`StartupEvents.registry(fluid)`	注册自定义流体	❌
`StartupEvents.registry(block)`	注册自定义方块	❌
`StartupEvents.registry(item)`	注册自定义物品	❌
`StartupEvents.registry(enchantment)`	注册自定义附魔	❌
`StartupEvents.registry(mob_effect)`	注册自定义状态效果（药水效果）	❌
`StartupEvents.registry(sound_event)`	注册自定义音效	❌
`StartupEvents.registry(block_entity_type)`	注册自定义方块实体类型	❌
`StartupEvents.registry(potion)`	注册自定义药水	❌
`StartupEvents.registry(particle_type)`	注册自定义粒子类型	❌
`StartupEvents.registry(painting_variant)`	注册自定义画作变体	❌
`StartupEvents.registry(custom_stat)`	注册自定义统计项（统计信息）	❌
`StartupEvents.registry(point_of_interest_type)`	注册兴趣点类型（村民工作站绑定）	❌
`StartupEvents.registry(villager_type)`	注册村民类型	❌
`StartupEvents.registry(villager_profession)`	注册村民职业	❌
`WorldgenEvents.add`	向世界生成添加地物（如矿石、树木、建筑）	❌
`WorldgenEvents.remove`	从世界生成移除地物	❌
`ItemEvents.modification`	修改已有物品的属性（堆叠上限、耐久、属性等）	❌
`ItemEvents.toolTierRegistry`	注册自定义工具等级（挖掘速度/伤害/耐久）	❌
`ItemEvents.armorTierRegistry`	注册自定义盔甲等级	❌
`ItemEvents.modelProperties`	注册物品模型属性（决定物品显示哪个模型/变体）	❌
`BlockEvents.modification`	修改已有方块的属性（硬度、爆炸抗性、音效、行为等）	❌

🖥️ 客户端事件（Client）¶

事件	作用	可取消
`ClientEvents.highPriorityAssets`	以最高优先级加载资源（覆盖贴图/模型，常用于自定义资源包）	❌
`ClientEvents.init`	客户端初始化完成时触发一次	❌
`ClientEvents.loggedIn`	玩家进入（登录）客户端世界时触发	❌
`ClientEvents.loggedOut`	玩家退出客户端世界时触发	❌
`ClientEvents.tick`	客户端每 tick（每帧）触发，用于持续更新	❌
`ClientEvents.painterUpdated`	Painter 绘制工具内容更新时触发	❌
`ClientEvents.leftDebugInfo`	往 F3 调试界面左侧添加文本	❌
`ClientEvents.rightDebugInfo`	往 F3 调试界面右侧添加文本	❌
`ClientEvents.paintScreen`	屏幕渲染时触发，用于自定义 GUI/覆盖层绘制	❌
`ItemEvents.tooltip`	修改物品的提示文本（tooltip）	❌
`ItemEvents.clientRightClicked`	客户端侧右键点击物品（本地即时反应，不经过服务器）	❌
`ItemEvents.clientLeftClicked`	客户端侧左键点击物品	❌
`NetworkEvents.fromServer`	客户端收到服务端数据包时触发	✅

🌐 服务端事件（Server）¶

服务器/世界生命周期¶

事件	作用	可取消
`ServerEvents.lowPriorityData`	低优先级数据包加载时触发（数据包加载早期）	❌
`ServerEvents.highPriorityData`	高优先级数据包加载时触发（数据包加载后期）	❌
`ServerEvents.loaded`	服务端加载完成时触发（适合初始化服务端数据）	❌
`ServerEvents.unloaded`	服务端卸载时触发（适合清理数据）	❌
`ServerEvents.tick`	服务端每 tick 触发，适合全局定时逻辑	❌
`LevelEvents.loaded`	某个维度（世界）加载时触发	❌
`LevelEvents.unloaded`	某个维度（世界）卸载时触发	❌
`LevelEvents.tick`	每个维度每 tick 触发	❌
`LevelEvents.beforeExplosion`	爆炸发生前触发，可取消爆炸	✅
`LevelEvents.afterExplosion`	爆炸发生后触发	❌

配方与数据¶

事件	作用	可取消
`ServerEvents.recipes`	添加/移除/修改配方（最常用的配方事件）	❌
`ServerEvents.afterRecipes`	所有配方处理完成后触发，适合最后兜底修改	❌
`ServerEvents.specialRecipeSerializers`	注册特殊配方序列化器	❌
`ServerEvents.compostableRecipes`	修改堆肥配方（什么能进堆肥桶、产多少）	❌
`ServerEvents.recipeTypeRegistry`	注册自定义配方类型	❌
`ServerEvents.tags`	增删物品/方块/流体等标签（tag）	❌
`ServerEvents.genericLootTables`	修改通用战利品表	❌
`ServerEvents.blockLootTables`	修改方块战利品表（挖掘掉落）	❌
`ServerEvents.entityLootTables`	修改实体战利品表（击杀掉落）	❌
`ServerEvents.giftLootTables`	修改村民赠礼战利品表	❌
`ServerEvents.fishingLootTables`	修改钓鱼战利品表	❌
`ServerEvents.chestLootTables`	修改箱子战利品表（生成战利品）	❌

命令与网络¶

事件	作用	可取消
`ServerEvents.commandRegistry`	注册自定义命令	❌
`ServerEvents.command`	玩家执行命令时触发，可拦截/修改	✅
`ServerEvents.customCommand`	执行自定义命令时触发	✅
`NetworkEvents.fromClient`	服务端收到客户端数据包时触发	✅

物品¶

事件	作用	可取消
`ItemEvents.rightClicked`	玩家右键使用物品时触发（如吃东西、扔鸡蛋）	✅
`ItemEvents.firstRightClicked`	按住右键开始时触发（持续使用的起点）	❌
`ItemEvents.firstLeftClicked`	按住左键开始时触发	❌
`ItemEvents.canPickUp`	判断物品能否被拾取时触发	✅
`ItemEvents.pickedUp`	物品被拾取时触发	❌
`ItemEvents.dropped`	物品被丢弃时触发	✅
`ItemEvents.entityInteracted`	用物品与实体交互时触发（如喂动物、给村民东西）	✅
`ItemEvents.crafted`	物品被合成出来时触发	❌
`ItemEvents.smelted`	物品被烧炼出来时触发	❌
`ItemEvents.foodEaten`	食物被食用时触发	✅

方块¶

事件	作用	可取消
`BlockEvents.rightClicked`	玩家右键点击方块时触发（如右键箱子、按钮）	✅
`BlockEvents.leftClicked`	玩家左键点击方块时触发（开始挖掘）	✅
`BlockEvents.placed`	方块被放置时触发	✅
`BlockEvents.broken`	方块被破坏时触发	✅
`BlockEvents.detectorChanged`	KubeJS 方块检测器状态改变时触发	❌
`BlockEvents.detectorPowered`	方块检测器被激活（充能）时触发	❌
`BlockEvents.detectorUnpowered`	方块检测器取消激活时触发	❌
`BlockEvents.farmlandTrampled`	耕地被踩踏时触发	❌

实体¶

事件	作用	可取消
`EntityEvents.death`	实体死亡时触发	✅
`EntityEvents.hurt`	实体受伤时触发，可取消伤害	✅
`EntityEvents.checkSpawn`	检查实体是否允许生成时触发	✅
`EntityEvents.spawned`	实体生成时触发	✅

玩家¶

事件	作用	可取消
`PlayerEvents.loggedIn`	玩家登录服务器时触发	❌
`PlayerEvents.loggedOut`	玩家登出服务器时触发	❌
`PlayerEvents.respawned`	玩家重生时触发	❌
`PlayerEvents.tick`	每个玩家每 tick 触发	❌
`PlayerEvents.chat`	玩家发送聊天消息时触发，可拦截	✅
`PlayerEvents.decorateChat`	修饰聊天消息（加前缀/颜色/样式）时触发	❌
`PlayerEvents.advancement`	玩家获得进度时触发	✅
`PlayerEvents.inventoryOpened`	玩家打开物品栏/容器时触发	❌
`PlayerEvents.inventoryClosed`	玩家关闭物品栏/容器时触发	❌
`PlayerEvents.inventoryChanged`	物品栏内容发生变化时触发	❌
`PlayerEvents.chestOpened`	玩家打开箱子时触发	❌
`PlayerEvents.chestClosed`	玩家关闭箱子时触发	❌

模组兼容事件¶

提示这些事件在存在对应模组（JEI / REI / GameStages）时才会启用。

Just Enough Items (JEI) —— 客户端¶

事件	作用	可取消
`JEIEvents.subtypes`	注册物品子类型（按 NBT 区分不同变体）	❌
`JEIEvents.hideItems`	从 JEI 隐藏物品	❌
`JEIEvents.hideFluids`	从 JEI 隐藏流体	❌
`JEIEvents.hideCustom`	隐藏自定义内容	❌
`JEIEvents.removeCategories`	移除 JEI 的物品分类（标签页）	❌
`JEIEvents.removeRecipes`	从 JEI 移除配方显示	❌
`JEIEvents.addItems`	向 JEI 添加物品显示	❌
`JEIEvents.addFluids`	向 JEI 添加流体显示	❌
`JEIEvents.information`	为物品添加信息说明（JEI 里的额外文字）	❌

Roughly Enough Items (REI) —— 客户端¶

事件	作用	可取消
`REIEvents.hide`	从 REI 隐藏物品/流体	❌
`REIEvents.add`	向 REI 添加物品/流体显示	❌
`REIEvents.information`	为物品添加信息说明	❌
`REIEvents.removeCategories`	移除 REI 的物品分类	❌
`REIEvents.groupEntries`	对物品条目分组显示	❌

GameStages —— 服务端¶

事件	作用	可取消
`GameStageEvents.stageAdded`	玩家获得某个游戏阶段（GameStage）时触发	❌
`GameStageEvents.stageRemoved`	玩家失去某个游戏阶段时触发	❌