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>${player.name} joined the game"
    }

    on_chat {
        send "<gray>You said: ${message}" to player
    }
}

Inside every method the subject is a bare variable named after its type — player, mob, block, and so on. The rest of the event's data is bound alongside it as bare variables, with types fixed by the catalog and the names listed in each receiver's table below.

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 every variable it reaches for — a handler that would never fire, or one that reaches for data the event never binds, is a compile error (a misspelled method name gets the nearest match suggested):

Player {
    on_join {
        send "<red>Under attack!" to attacker
    }
}

ev.sw:3:38: error: variable 'attacker' is never assigned
        send "<red>Under attack!" to attacker
                                     ^

Player ​

Every online player. The subject is bound as player.

Entity ​

Base for every live entity — players, mobs, projectiles, dropped items. The subject is bound as 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. The subject is bound as projectile. (The shooter side is reachable via Entity.on_shoot.)

Inventory ​

Open-inventory and GUI interactions.

World ​

The world (Minestom instance). The subject is bound as world.

Server ​

The global singleton, plus the pre-login and connection-only events that have no player or entity subject yet. The subject is bound as 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, write call original method from inside the overriding method — optionally with with arguments <expr>, ... to forward values to it:

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

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

    on_click {
        send "<green>You poke the ghoul." to player
        call original method            // also run base Mob.on_click
    }

    on_target {
        call original method with arguments target
    }
}

call original method is only legal inside an overriding method — writing it in 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 {
        if message contains "spoiler" {
            cancel event
            spawn warn_later(player)
        }
    }
}

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.