---
title: 启动注册
hide_meta: true
---

# 启动注册

启动事件注册 PMMO 在游戏开始之前需要的结构。这些属于 `startup_scripts/`，不是 `server_scripts/`。

## 什么放在哪里

**放在 `startup_scripts/` 中：**
- `PmmoJS.registerPredicate(...)` —— 自定义需求谓词
- `PmmoJS.registerPerk(...)` —— 新 Perk 类型定义
- `PmmoHelper.registerRequirementData(...)` —— 直接 PMMO 数据注册
- `PmmoHelper.registerXpAwardData(...)` —— 直接 XP 奖励注册
- `PmmoHelper.registerTriggerListener(...)` —— 直接触发器监听器注册
- `ForgeEvents.onEvent(...)` —— 原始 Forge 事件监听器

**放在 `server_scripts/` 中：**
- `PmmoJS.trigger(...)`、`PmmoJS.internal(...)` —— 运行时钩子
- 所有配置事件 —— `PmmoJS.skillsConfig(...)`、`PmmoJS.perksConfig(...)` 等
- `PmmoJS.settings(...)` —— 物品/方块/实体数据
- `ProbeJSEvents.generateDoc(...)` —— ProbeJS 文档生成

## `PmmoJS.registerPredicate`

注册 PMMO 在需求检查期间评估的自定义谓词。提供三种方法：

- `registerActionPredicate(resourceId, reqType, predicate)` —— 用于物品操作
- `registerBreakPredicate(resourceId, reqType, predicate)` —— 用于方块破坏
- `registerEntityPredicate(resourceId, reqType, predicate)` —— 用于实体交互

每个谓词接收当前 `Player` 和相关目标对象。

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

## `PmmoJS.registerPerk`

定义新的 PMMO Perk 类型。这是用于创建带生命周期回调的自定义 Perk 的重量级 API。

参见 [Perk 注册](./perks) 获取完整指南。

## 直接 PMMO 注册

`PmmoHelper` 在 `startup_scripts/` 中可用，用于将数据直接注册进 PMMO 的 API。当你希望精确控制注册内容，而不通过 KubeJS 事件系统时，这很有用。

常用辅助方法：

```js
// 注册需求
PmmoHelper.registerRequirementData(
  ObjectType.ITEM, 'minecraft:diamond_pickaxe', ReqType.TOOL,
  { mining: 10, endurance: 4 }, true
)

// 注册 XP 奖励
PmmoHelper.registerXpAwardData(
  ObjectType.ITEM, 'minecraft:diamond_pickaxe', EventType.BLOCK_BREAK,
  { mining: 8 }, true
)

// 注册触发器监听器
PmmoHelper.registerTriggerListener('kubejs:example', EventType.BLOCK_BREAK,
  (forgeEvent, context) => {
    context.putInt('bonus_roll', 1)
    context.putBoolean('is_cancelled', false)
    return context
  }
)
```

对于上面的直接数据注册方法，最后一个参数（`true`）告诉 PMMO 替换已有数据而不是与它合并。

Raw trigger listener 返回的 tag 必须包含 `is_cancelled`；PMMO 会用这个键判断 listener 输出是否有效。普通运行时脚本优先用 `PmmoJS.trigger(...)`。

完整直接注册方法列表：`registerRequirementData`、`registerXpAwardData`、`registerDamageXpAwardData`、`registerBonusData`、`registerPositiveEffects`、`registerNegativeEffects`、`registerSalvageData`、`registerVeinData`、`registerMobModifierData`、`registerTriggerListener`，以及对应的工具提示注册变体。

## 原始 Forge 事件

在 KubeJS 1.20.1 上，`ForgeEvents.onEvent(...)` 是启动脚本 API：

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

注意：`ProbeJSEvents.generateDoc(...)` 是服务端脚本 API，不是启动 API。这两个事件系统尽管看起来相似，但有各自不同的生命周期。

## 相关页面

- [阶段规则](./phases)
- [Perk 注册](./perks)