Party messages

client.party() — in the DSL just party — carries small binary messages between the scripts of everyone in your party, laid out by a shape you declare. An event reaches whoever is online at that moment; a state is the last value you published under a topic, and the server hands it to whoever joins later.

val Appearance = shape("appearance") {
    string(1, "hat")
    int(2, "tint", default = 0xFFFFFF)
}

val cosmetics = party.channel("crashsystem:cosmetics")
val worn = mutableMapOf<String, String>()

cosmetics.onState(Appearance) { message ->
    worn[message.sender().login()] = message.string("hat")
}

cosmetics.onStateCleared(Appearance) { message ->
    worn.remove(message.sender().login())
}

onEnable {
    cosmetics.publish(Appearance, "hat" to "halo")
}

#The party

#A member

Positions arrive twice a second, only for the other members and only while they are online; position() interpolates between the last two and stops at the newest instead of running past it, and your own entry returns the live player position. The colour comes from a ten entry palette, distinct per member for as long as the party lives, so two members draw the same person the same way.

#A shape

Every declaration except bytes, uuid, struct and the list forms also takes default = …, used when the sender did not send that field. Ids 1 to 15 cost one byte on the wire. Only the id and the type go on the wire, so writing and reading in different orders is fine and a field the receiver does not declare is skipped by its wire type; reusing or reordering an id makes two versions of a script read each other wrong.

#PartyShape

#PartyShapeBuilder

Every method returns the builder, and every field declaration throws ScriptException when the id is outside 1..2047, the field name is not ASCII or is over 32 characters, the shape already holds 64 fields, or the name or the id is taken.

#PartyField

#PartyFieldType

#PartyWire

#PartyStruct

#A channel

A namespace is author:feature: lowercase ASCII [a-z0-9][a-z0-9._-]* on both sides of the colon, at most 48 characters, no empty half. One loaded script holds a namespace at a time. Handlers run on the client thread, one message at a time, inside the same error handling and CPU budget as any other script handler, and only while the script is loaded and enabled.

#PartyChannel

#PartyShapedWriter

The writer is the receiver of the { set(name, value) } block. The order of set calls does not matter, and a field left unset never goes on the wire, so the receiver reads its declared default.

#Choosing who receives

State is always party-wide: publish and clearState take no target.

#PartyTargetKind

#Filtering who sent it

#The result of a send

#The message

sender().self() is always false on a received message. An onEvent or onState handler receives a PartyShapedMessage, which is this table plus the decoded fields below; an onStateCleared handler receives this table only.

#PartyMessageKind

#Reading fields

A field the sender left out returns its declared default; without a default it throws ScriptException naming the field. Asking for the wrong type throws too, and so does a name the shape does not declare.

#PartyFields

#Packing bytes yourself

A bytes field carries whatever you put in it: party.buffer() hands out the writer, party.reader(data) reads it back, and both are positional, so read order has to match write order. Any write past the limit throws ScriptException.

#PartyPayloadReader

Reading past the end throws ScriptException; the payload is a plain array, so a truncated or reordered read gives garbage rather than an error.

#Limits

Sends beyond the client rate limiter come back RATE_LIMITED; the server keeps its own, stricter budgets and drops what exceeds them without an error. State publishes coalesce per topic, so publishing on every tick costs one packet every few ticks and only the newest value goes out.

#What the server decides

A namespace is a routing name, not an identity: it proves nothing about which script sent a message, only which account did.