KairoCustomCommandRegistry

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

The class accessed via ev.customCommandRegistry. Used inside the router.beforeEvents.startup event to register Minecraft custom commands.

Methods

• registerCommand
• registerEnum

registerCommand

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

Registers a Minecraft custom command through kairo-router.

Use this wrapper instead of calling Minecraft's native customCommandRegistry.registerCommand() directly. Native Minecraft command registration rejects duplicate command ids. Kairo-router keeps your command declaration even when the native duplicate registration is skipped, then routes execution to the currently active addon version. This preserves command compatibility when multiple versions of the same addon are installed and the world switches between them.

Parameters

• customCommand: CustomCommand

  The command definition.

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

  Handler invoked when the command is executed.

• options: { runWhenInactive?: boolean }

  Optional settings. runWhenInactive lets infrastructure commands run even while the addon is inactive. Most addon commands should omit this.

Returns: void

Compatibility rules

Treat a released command id and its ordered parameter types as a stable ABI.

• Do not change the ordered parameter types for an existing command id.
• Do not insert a new required parameter before existing parameters.
• Renaming a parameter is compatible. For example, target: string can become player: string because the type sequence is unchanged.
• Changing a parameter type, such as string to entity, is incompatible.

If you need an incompatible signature, release a major version and clearly warn users that older addon versions with the previous command signature must be uninstalled. A safer alternative is to publish a new command id and keep the old one for existing worlds.

---

registerEnum

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

Registers an enum for use in command arguments. Can be referenced in a CustomCommand argument definition.

Parameters

• name: string

  The name of the enum.

• values: string[]

  The allowed enum values.

Returns: void

Examples

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 }
    },
  )
})