KairoCustomCommandRegistry

import { router } from '@kairo-js/router'

通过 ev.customCommandRegistry 访问的类。在 router.beforeEvents.startup 事件中用于注册 Minecraft 自定义命令。

方法

• registerCommand
• registerEnum

registerCommand

registerCommand(
  customCommand: CustomCommand,
  callback: (origin: KairoCommandOrigin, ...args: any[]) => CustomCommandResult | undefined,
  options?: { runWhenInactive?: boolean },
): void

通过 kairo-router 注册 Minecraft 自定义命令。

请使用此包装器，而不是直接调用 Minecraft 原生的 customCommandRegistry.registerCommand()。Minecraft 原生注册会拒绝重复的 command id。kairo-router 会在原生重复注册被跳过时仍保留命令声明，并在执行时将命令路由到当前 active 的附加包版本。这样同一附加包的多个版本可以共存，并在世界中切换版本时保持命令可用。

参数

• customCommand: CustomCommand

  命令定义。

• callback: (origin: KairoCommandOrigin, ...args: any[]) => CustomCommandResult | undefined

  命令执行时调用的处理器。

• options: { runWhenInactive?: boolean }

  可选设置。runWhenInactive 可让基础设施命令在附加包 inactive 时仍然运行。大多数附加包命令应省略该选项。

返回值： void

兼容性规则

已发布的 command id 和它的参数类型顺序应被视为稳定 ABI。

• 不要改变现有 command id 的参数类型顺序。
• 不要在现有参数之前插入新的必填参数。
• 参数名可以重命名。例如 target: string 改为 player: string 是兼容的，因为类型顺序没有改变。
• 改变参数类型（例如 string 改为 entity）是不兼容的。

如果需要不兼容的签名，请发布 major 版本，并明确提醒用户必须卸载使用旧签名的较低版本。更安全的替代方案是发布新的 command id，并为已有世界保留旧命令。

---

registerEnum

registerEnum(name: string, values: string[]): void

注册一个供命令参数使用的枚举。可在 CustomCommand 的参数定义中引用。

参数

• name: string

  枚举的名称。

• values: string[]

  允许的枚举值。

返回值： void

使用示例

import { CommandPermissionLevel, CustomCommandParamType, CustomCommandStatus } from '@minecraft/server'
import { router } from '@kairo-js/router'

router.beforeEvents.startup.subscribe((ev) => {
  // Register an enum
  ev.customCommandRegistry.registerEnum('myAddon:targetType', ['player', 'entity', 'block'])

  // Register a command
  ev.customCommandRegistry.registerCommand(
    {
      name: 'myaddon:spawn',
      description: 'Spawn an entity',
      permissionLevel: CommandPermissionLevel.Any,
      mandatoryParameters: [
        { name: 'type', type: CustomCommandParamType.String },
      ],
    },
    (origin, type) => {
      console.log(`Command executed: type=${type}`)
      return { status: CustomCommandStatus.Success }
    },
  )
})