Items, Entities, and Abilities

Items

item

Handled for you: MiniModes builds `GameItemStack` values with metadata, components, stable interactive definition ids, uses, cooldown hooks, and dispatch through game-scoped item interaction events.

Use it for: Custom weapons, menu items, power-ups, kits, armor, consumables, and objective markers.

val dashFeather = item("feather") {
    name("<aqua><bold>Phase Dash")
    lore("<gray>Right-click to dash forward.")
    customModelData = 1201
    uses(3)
    showUsesInLore = true
    glint()
    meta("ability", "dash")

    rightClick {
        cooldown(1500.milliseconds)
        impulse { forward(1.8) }
        sound("entity.enderman.teleport", pitch = 1.4f)
    }
}

Item fields include amount, name, lore, custom model data, damage, unbreakable, hide flags, enchantments, metadata, arbitrary components, dye color, base material, uses, and vanilla-interaction cancellation.

Interactive hooks include rightClick, leftClick, entity click, player damage, any entity damage, shot { launch {}; hit {} }, and drop.

Interactive item events

You can either put behavior in the item definition or listen centrally:

events.onItemRightClick {
    if (!requireAlive()) return@onItemRightClick
    if (item.meta["ability"] == "dash") {
        consumed = true
    }
}

This is useful when several items share routing logic or when the game needs to inspect current phase/team state before allowing the action.

Projectiles

projectile

Handled for you: Projectiles are launched through the runtime with the current game id. Metadata is stored by the platform projectile service and cleaned when the game is disposed.

Use it for: Custom weapons, tagged arrows, snowball abilities, lasers, thrown objectives, and projectile-triggered block effects.

val projectileId = projectile(player, type = "arrow") {
    speed = 4.2
    gravity = false
    critical = true
    meta("weapon", "laser")
    meta("tier", 2)
}

Read metadata in projectile-related events:

events.onEntityDamageByEntity {
    val projectile = damager as? ProjectileDamager ?: return@onEntityDamageByEntity
    if (projectile.metadata["weapon"] != "laser") return@onEntityDamageByEntity
    suppressDamage()
    removeProjectile()
}

Entities

entity

Handled for you: Spawned entity handles are scoped to the game id. Death handlers and platform entity registries are cleaned when the runtime is disposed.

Use it for: NPC targets, mobs, bosses, hologram-like displays, moving hazards, and game objectives.

val guardian = entity("zombie", at = pos(world, 0.0, 80.0, 0.0)) {
    name = "<red>Guardian"
    glowing = true
    ai = true
    invulnerable = false
    attribute("generic.max_health", 80.0)
    mainHand(item("iron_sword"))

    pathfinding {
        speed = 1.2
        follow(players.first())
    }

    onDeath { info ->
        gamePlayers.send(Chat("<gold>The guardian fell."))
    }
}

After spawning, GameEntity supports remove, teleport, rotate, name, flag, attribute, equipment, and pathing through entity.path.to(pos), entity.path.follow(player), and entity.path.stop().

Vehicles

vehicle and minecart

Handled for you: Vehicle handles are created through the platform vehicle service and cleaned by game id.

Use it for: Races, carts, boats, moving seats, rideable objectives, and scripted transport.

val cart = minecart(at = start) {
    name = "<gold>Race Cart"
    gravity = true
    invulnerable = true
    passenger(player)
}

cart.velocity(Velocity(0.6, 0.0, 0.0))
cart.clearPassengers()

Double jump

doubleJump

Handled for you: The platform adapter detects jump attempts, tracks aerial uses, applies cooldowns, optionally resets on ground, and calls your accepted-jump hook.

Use it for: Mobility kits, arena movement, platform fighters, parkour assists, and dodge mechanics.

private var doubleJumpSession: DoubleJumpSession? = null

override fun start() {
    doubleJumpSession = gameRuntime.platform.doubleJump.create(doubleJump {
        maxAerialJumps = 1
        cooldownMillis = 450L
        enabled = { player -> isAlive(player) && config.doubleJumpEnabled }
        canAttempt = { player -> player.pos.world.slot == gameWorld?.slot }
        onDoubleJump = { player ->
            player.velocity = player.lookDirection.normalize().multiply(0.9).withY(0.75)
            player.playSound("entity.breeze.jump", 0.8f, 1.2f)
        }
    })

    alivePlayers().forEach { doubleJumpSession?.track(it) }
}

override fun end(winner: GamePlayer?) {
    doubleJumpSession?.dispose()
}

Track players when they become eligible, untrack eliminated players, and call reset(player) after forced respawns.