Packets

A packet event hands you one Minecraft protocol packet decoded into a Java record. Packet events fire on the network thread, not the client thread, and the record is a flat snapshot: only what its accessors expose survived the decode.

on<PacketReceiveEvent> { e ->
    val packet = e.packet()
    if (packet !is S2CGameMessagePacket || packet.overlay()) return@on
    if (!packet.content().contains("duel")) return@on

    onClientThread { chat.sendToServer("/next") }
}

#Two threads

Reading the record's accessors off the client thread is safe. interaction, raycast, rotations.apply, inventory and container writes, world.blockEntitiesIn and world.removeEntity throw ScriptThreadException off it; packets.send returns false.

#Receiving

Only packets the client has a decoder for reach a handler; anything else fires nothing, and a decode failure is logged once per packet class. Inside a bundle each sub-packet fires separately.

#Packet, S2CPacket, C2SPacket

nursultan.packet.*, nursultan.packet.c2s.* and nursultan.packet.s2c.* are default imports, so record and enum names need no import line.

#Cancelling

Cancelling a received sub-packet inside a bundle removes it from the bundle. Both events ignore EventOptions — priority and ignoreCancelled alike.

#Sending

packets is game.packets(); a refused send warns once per packet class in the script console. send reuses the record's own sequence field, sendSequenced replaces it. A packet sent from a script goes out through the same connection call, so it fires PacketSendEvent again.

#Fidelity

A vanilla constant with no script twin decodes to null and logs one warning; a script constant with no vanilla twin makes the whole send fail. Full items, components and signatures are reachable only through the world and Inventory and items, never off a packet.

#The reference

Packet records mirror the Minecraft protocol of the client they ship with (1.21.11) — the only part of the API tied to the game version; a Minecraft update can rename or reshape a record. The client rewrites .sdk/ on every launch, so the packets jar follows the client you develop against.