Event Catalog ​

An event <Name> { } handler can name any concrete Minestom event. The catalog on this page is generated at build time from the pinned engine snapshot (Minestom ebaa2bbf64) — every public class under net.minestom.server.event.** that implements Event, plus SwoftLang's own first-class events (fishing, dispensers, mobs, TPS). Name one by its short catalog name or by its simple class name, and the compiler wires a listener for you.

event PlayerStartSprinting {
    execute {
        send "${event.player.name} sprints" to event.player
    }
}

Naming an event ​

Every catalog entry answers to two spellings — the short name (the class name with the trailing Event dropped) and the simple class name itself:

// these two declarations listen to exactly the same class
event PlayerFinishItemUse {
    execute {
        send "reeled in after ${event.use_duration} ticks" to event.player
    }
}

event PlayerFinishItemUseEvent {
    execute {
        send "reeled in after ${event.use_duration} ticks" to event.player
    }
}

A misspelled name is caught at compile time, with the nearest catalog match suggested:

event EntityDamg {
    execute {
        send "hurt" to all
    }
}

ev.sw:1:1: error: unknown event 'EntityDamg'; did you mean 'EntityDamage'?
event EntityDamg {
^

Curated typed events vs. the generated catalog ​

Two kinds of events live in the catalog, and they differ only in how richly their event.* properties are typed.

Curated typed events are the core surface — the ones you reach for constantly. Their properties carry precise SwoftLang types (a Player, a Location, an optional<Item>), and most expose short alias bindings so you can write player and message instead of event.player and event.message.

Generated catalog events — every other class in the tables below — expose their properties as Any. A property is discovered from the class's record components and getX()/isX() getters; it is writable when the class ships a matching setX(..) setter (marked with * in the tables). Any values flow into send, interpolation, and further property reads directly; coerce with the usual forms when you need a concrete type.

event EntityShoot {
    execute {
        // 'power' and 'spread' have setters in the catalog, so they are writable
        set event.power to 1.5
        set event.spread to 0.0
        send "line out: ${event.projectile} towards ${event.to}" to all
    }
}

The curated typed events ​

Typed engine events ​

Between the two extremes sits a third tier: typed engine events. These name plain Minestom events — EntityDamage, PlayerMove, PickupItem — but their event.* properties carry precise SwoftLang types and real setters, hand-authored rather than discovered from getters. So event.damage is a writable Double, event.attacker is an optional<Entity>, event.damage_type is a String — properties the raw catalog never exposes. They have no short aliases; reach everything through event.<prop>.

Naming one of these gets you the typed rows below, not the generated Any rows the tables further down would suggest for the same class. EntityDamage is the one to reach for: attack damage flows through it (the engine's EntityAttack is not cancellable), so it is where you read the victim, scale the hit, inspect the source, and veto lethal damage.

event EntityDamage {
    execute {
        set event.damage to event.damage * 2.0
        send "${event.entity} took ${event.damage} (${event.damage_type})" to all
        if event.attacker exists {
            send "attacker: ${event.attacker}" to all
        }
        if event.damage > 100.0 {
            cancel event
        }
    }
}

Tier 1 — the events most scripts reach for ​

Tier 2 — common, fully typed ​

VanillaUseItem is the vanilla PlayerUseItemEvent under a typed identifier of its own — the short name PlayerUseItem is taken by the custom-items use event.

Writing a settable property does what you'd expect — clamp a fall, redirect a teleport, rewrite a death message:

event PlayerMove {
    execute {
        if event.on_ground {
            set event.new_position to event.player.location
        }
    }
}

event PlayerGameModeChange {
    execute {
        send "${event.player.name} -> ${event.new_game_mode}" to event.player
    }
}

Cancelling ​

cancel event is legal on exactly the events the engine marks cancellable (the Cancellable column below, and cancelled in a curated event's rows). It is a compile error anywhere else:

event FishBite {
    execute {
        cancel event
    }
}

nc.sw:3:9: error: event 'FishBite' is not cancellable
        cancel event
        ^

Cancellable catalog events also carry a settable cancelled property, so set event.cancelled to true and cancel event are two spellings of the same effect.

Priority and async ​

Every handler takes an optional priority: (lower runs first) and an execute body. Handlers run on the tick thread by default; a whole handler can be marked execute async where the work must not block a tick, following the usual async coloring rules.

event PickupItem {
    priority: 1

    execute {
        if event.cancelled {
            send "too slow, the catch is gone" to all
        }
        send "caught ${event.item_stack}" to all
    }
}

The generated catalog ​

* marks a property with a setter (writable). Names are the short catalog names; the simple class name (append Event) always works too. Rows here are what the compiler discovers from a class's getters — an event that also appears in the typed engine events tables above resolves to those richer typed rows instead, so consult those first. Projectile-flight events — EntityShoot, ProjectileCollideWithBlock, ProjectileCollideWithEntity, ProjectileUncollide — live in the entity group.

Player · player (47) ​

Entity & projectile · entity (17) ​

Item · item (7) ​

Inventory · inventory (5) ​

Instance · instance (7) ​

Server · server (3) ​

Book · book (1) ​