Receivers & Events ​

SwoftLang handles server events through receivers — Capitalized top-level blocks, one per engine subject, whose members are fixed-name methods that fire when something happens to that subject. A Player { } block groups everything that can happen to a player; a Mob { } block groups everything that can happen to a mob; and so on.

Player {
    on_join() {
        broadcast "<yellow>${this.name} joined the game"
    }

    on_chat(message) {
        send "<gray>You said: ${message}" to this
    }
}

Inside every method, this is the subject the block is about — the joining player, the mob that took a hit, the block that was placed. The method's parameters bind the rest of the event's data, positionally, with types fixed by the catalog and names you choose.

The receiver catalog ​

A base receiver is a Capitalized type whose methods fire for every instance of that type. Eleven base receivers cover the engine, plus the special Packet block for raw packets:

A method name is checked against its receiver's table at compile time, and so is its parameter count — a handler that would never fire, or one that binds the wrong data, is a compile error (a misspelled method name gets the nearest match suggested):

Player {
    on_chat() {
        broadcast "hi"
    }
}

ev.sw:2:5: error: Player method 'on_chat' expects 1 parameter (message: String), got 0
    on_chat() {
    ^

Player ​

Every online player. this is the player.

Entity ​

Base for every live entity — players, mobs, projectiles, dropped items. this is the subject entity.

Mob ​

Mob <: Entity — narrows Entity to server-spawned mobs. A lowercase mob "id" { } declaration (Mobs) carries the same method set for one mob type and overrides the base.

Item ​

The item stack involved in an interaction. A lowercase item "id" { } declaration (Items) carries the same method set for one item and overrides the base.

Block ​

The positioned block value. A lowercase block_handler "id" { } declaration (Blocks) carries the same method set for one block id and overrides the base.

Projectile ​

Projectile <: Entity — projectile lifecycle. this is the projectile entity. (The shooter side is reachable via Entity.on_shoot.)

Inventory ​

Open-inventory and GUI interactions.

World ​

The world (Minestom instance). this is the world.

Server ​

The global singleton, plus the pre-login and connection-only events that have no player or entity subject yet. this is the server (Server config).

Npc & Hologram ​

The NPC and hologram receivers reuse the same method set as their lowercase npc "id" { } / hologram "id" { } declarations:

Fan-out — one event, several receivers ​

A single engine event can surface on more than one receiver, so you handle it wherever it reads most naturally. When a player breaks a block, both the block and the player see it; when an entity takes damage, Entity.on_hit fires, and if the entity is a mob, Mob.on_hit fires too.

The most-specific subject fires first — a custom mob "id" before base Mob before base Entity. A cancel in any handler vetoes the shared underlying event; later handlers still run and can observe or undo the decision.

Overriding a base receiver ​

A lowercase custom declaration (mob "id" { }, item "id" { }, block_handler "id" { }) carries the same method set as its base receiver, and most-specific wins: when a custom method and the base method both exist, the custom one replaces the base for that id. To keep the base behavior, call default() (or the equivalent super.<method>(...)) from inside the overriding method:

Mob {
    on_click(player) {
        send "<gray>You poke a ${this.type}." to player
    }
}

mob "ghoul" {
    type: "ZOMBIE"
    name: "<dark_green>Ghoul"
    health: 40

    on_click(player) {
        send "<green>You poke the ghoul." to player
        default()                       // also run base Mob.on_click
    }

    on_target(target) {
        super.on_target(target)
    }
}

default() and super.<method>(...) are only legal inside an overriding method — calling default() from a base receiver or a method that overrides nothing is a compile error.

Cancelling ​

cancel event vetoes the underlying server event — a cancelled chat message is never broadcast. It is legal only inside a method the engine marks cancellable (the Cancellable column above), and only before the handler goes async. Anywhere else it is a compile error:

Player {
    on_join() {
        cancel event
    }
}

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

Async methods ​

A method runs on the tick thread by default. Mark its body async where slow work must not block a tick, following the usual async coloring rules. Cancellation is sync-only, so decide and cancel synchronously, then hand slow work to an async method or a spawned task:

Player {
    on_chat(message) {
        if message contains "spoiler" {
            cancel event
            spawn warn_later(this)
        }
    }
}

async function warn_later(p: Player) {
    wait 1 seconds
    send "<red>No spoilers in chat!" to p
}

The Packet receiver ​

Packet { } is the raw-packet escape hatch: a listener on inbound Minestom packets keyed by class name, for the rare cases the typed receivers above don't cover. Each on "ClassName" { } handler binds player (the sender) and packet (the raw packet) in scope. See Packets for the full treatment.

Packet {
    on "ClientPlayerActionPacket" {
        broadcast "<gray>${player.name} sent a player-action packet"
    }
}

The typed Player.on_packet_in() / on_packet_out() methods cover the common "a packet arrived" case; reach for Packet { } only when you need a specific packet class by name.

Commands are separate ​

command "..." { } declarations are not events — they define the slash-commands players type, and are unchanged. Receivers handle what happens on the server; commands handle what players ask for.