启动阶段规则 - KubeJS PMMO

这一页回答一个问题：每种 PmmoJS 代码应该放在哪个脚本文件夹？

规则

对于带 KubeJS 的 Forge 1.20.1：

脚本文件夹	用途
`startup_scripts/`	注册和仅限启动的 Forge 钩子
`server_scripts/`	PMMO 运行时逻辑和 ProbeJS 文档生成
`client_scripts/`	只读技能显示辅助和客户端 UI

实操指南

`startup_scripts/`

用于在游戏世界加载之前定义数据的任何内容：

// 谓词
PmmoJS.registerPredicate(event => {
  event.registerActionPredicate(PmmoHelper.id('minecraft:stick'), ReqType.WEAPON,
    (player, stack) => player.experienceLevel >= 5
  )
})

// 直接数据注册
PmmoHelper.registerXpAwardData(ObjectType.ITEM, 'minecraft:bread', EventType.CONSUME, {
  cooking: 2
}, true)

// 原始 Forge 事件
ForgeEvents.onEvent('net.minecraftforge.event.entity.player.PlayerEvent$PlayerLoggedInEvent', event => {
  console.info(`[PmmoJS] ${event.getEntity().getScoreboardName()} 已登录`)
})

`server_scripts/`

用于游戏反应、配置编辑和文档生成：

// 运行时触发器
PmmoJS.trigger(EventType.BLOCK_BREAK, event => {
  if (event.hasPlayer()) {
    event.addXpAward('mining', 5)
  }
})

// 内部钩子
PmmoJS.internal(PMMOInternalType.POTION_BREW, event => {
  if (!event.getContextBoolean('alreadyTracked')) {
    event.addXpAward('alchemy', 10)
  }
})

// ProbeJS 文档生成
ProbeJSEvents.generateDoc(event => {
  event.addSnippet('pmmojs.trigger.type', PmmoHelper.getTriggerTypeIds(), 'PmmoJS 触发器 ID')
})

`client_scripts/`

仅限只读操作。SkillHelper 和 ClientSkillHelper 可用于技能显示查询。PmmoHelper 在客户端不暴露。

常见错误

把 ForgeEvents.onEvent(...) 放在 server_scripts/ 中 —— 在 KubeJS 1.20.1 上，这是启动 API。在服务端脚本中不起作用。
把 ProbeJSEvents.generateDoc(...) 放在 startup_scripts/ 中 —— 这是服务端 API。在启动脚本中不起作用。
把 PmmoJS.registerPerk(...) 放在 server_scripts/ 中 —— 这需要在注册时间运行，而不是在游戏过程中。移到启动脚本中。

重载行为

启动脚本只在模组初始化期间运行一次，不支持热重载。
服务端脚本在每次服务器重载时运行，这是你迭代游戏逻辑的地方。
服务端脚本中的配置事件通过重载路径应用，因此与 PMMO 自身的配置重载兼容。

决策流程

问问自己代码在做什么：

在加载时定义数据或结构？ → startup_scripts/
响应游戏行为或编辑配置？ → server_scripts/
只读取技能数据用于 UI 显示？ → client_scripts/
生成 ProbeJS 类型文档？ → server_scripts/