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 native 등록은 같은 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

커맨드 인수에서 사용할 열거형을 등록합니다. 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 }
    },
  )
})