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 の native customCommandRegistry.registerCommand() を直接呼ぶのではなく、このラッパーを使ってください。Minecraft 本来の登録処理は、同じ command id の重複登録を拒否します。kairo-router は native 側で重複登録がスキップされた場合でもコマンド宣言を保持し、実行時に現在 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 を追加し、既存ワールド向けに古い command id を残す方法もあります。

---

registerEnum

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

コマンド引数用の enum 値を登録します。CustomCommand の引数定義で参照できます。

パラメーター

• name: string

  enum の名前。

• values: string[]

  enum の選択肢。

返り値: void

使用例

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

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

  // コマンドの登録
  ev.customCommandRegistry.registerCommand(
    {
      name: 'myaddon:spawn',
      description: 'エンティティをスポーンさせます',
      permissionLevel: CommandPermissionLevel.Any,
      mandatoryParameters: [
        { name: 'type', type: CustomCommandParamType.String },
      ],
    },
    (origin, type) => {
      console.log(`コマンド実行: type=${type}`)
      return { status: CustomCommandStatus.Success }
    },
  )
})