Events, Commands, and Input

Events DSL

EventsScope

Handled for you: MiniModes subscribes through the platform adapter using the current game id and stores each subscription for automatic unsubscription when the runtime is disposed.

Use it for: Reacting to movement, combat, block edits, crafting, inventory opens, projectiles, flight toggles, entity interaction, and interactive item dispatch.

Override configureEvents:

override fun configureEvents(events: EventsScope) {
    events.onPlayerMove {
        if (!requireAlive()) return@onPlayerMove
        if (to.y < 20) {
            eliminateTrackedPlayer(player)
            player.gameMode = GameModes.SPECTATOR
        }
    }

    events.onEntityDamage {
        if (!isRunning || !requireParticipant()) {
            cancel()
        }
    }
}

Common context helpers:

• requireParticipant() filters to players in the match.
• requireAlive() filters to tracked alive players.
• cancel() sets the normalized cancellation flag when the event supports it.
• Event-specific helpers include clearDrops(), noDrops(), suppressDamage(), and removeProjectile().

Supported event families include:

Handler	Use case
onBlockBreak, onBlockPlace	Build/break rules, no-drop arenas, protected regions.
onPlayerMove	Void checks, areas, parkour checkpoints, freeze phases.
onPlayerDeath, onPlayerQuit	Lives, elimination, cleanup, early ending.
onEntityDamage, onEntityDamageByEntity	Combat rules, friendly fire, custom damage, shields.
onPlayerInteract, onEntityInteract	Weapons, abilities, menus, objectives.
onProjectileLaunch, onProjectileHitBlock	Projectile metadata, block effects, hit cleanup.
onCraftPrepare, onCraftItem, onInventoryOpen	Crafting rules and inventory restrictions.
onToggleFlight	Double-jump style mechanics and flight prevention.
onItemRightClick, onItemDrop, etc.	Interactive item definitions from ItemDSL.

Use the generic escape hatch for custom normalized events:

events.on(MyCustomEvent::class) {
    // event is typed as MyCustomEvent
}

Game-local commands

GameCommandsScope

Handled for you: The command DSL validates command names, parses typed arguments, handles missing/extra args, prints usage text, catches command exceptions, and reports failures to the player.

Use it for: Admin/debug controls, leader tools, target selection, testing hooks, and game-specific commands under `/minimodes game`.

override fun configureCommands(commands: GameCommandsScope) {
    commands.command("give-token") {
        description = "Give a player a token."
        argument("target", GameInputTypes.player())
        argument("amount", GameInputTypes.integer(min = 1, max = 64), optional = true, default = 1)

        executes {
            val target = arg<GamePlayer>("target")
            val amount = arg<Int>("amount")
            repeat(amount) {
                target.inventory.add(ItemDSL("emerald") { name = "<green>Token" })
            }
        }
    }
}

Arguments are parsed in order. A greedy text argument must be last.

Input types

Built-in GameInputTypes:

Type	Parses
text(minLength, maxLength)	Greedy free text.
word()	A single no-whitespace token.
integer(min, max)	Whole numbers.
number(min, max)	Doubles.
bool()	true/false, yes/no, enabled/disabled, 1/0.
player()	Online player lookup through the platform adapter.
itemName()	Platform-known or syntactically valid item names.

Prompts

The same input types power chat prompts:

prompt(
    player = player,
    type = GameInputTypes.itemName(),
    message = "<yellow>Type an item id.",
    allowCancel = true,
    cancelWords = setOf("cancel", "stop"),
) { respondent, itemId ->
    respondent.inventory.add(ItemDSL(itemId))
}

Prompt state is per-player and per-game. If lockMovement = true, the runtime blocks movement and reminds the player to answer.