Client networking
Call host.disconnect(reason) through ClientHost to leave the joined server or world at the end of the frame, outside hooks. Pass Some(Text) to show a disconnect reason or None for the normal leave flow. The disconnect screen renders the reason in the player's language, like other translatable text: a translatable component shows its translated text and a plain-text reason is unchanged. The call returns Result<(), DisconnectError>: Unavailable means no world is joined, it is closing, or a save is pending, and Text reports an invalid reason (a malformed or too-deep component is refused by that name and nothing changes). A pending request belongs to its current world epoch and cannot leave a later world. Server code continues to use the separate player disconnect operation.
Typed payloads
A typed payload sends a value of your own type on a registered channel. Its body is the value's
PayloadCodec encoding (vanilla's network encoding), with nothing around it, so a peer reads it
as an ordinary registered payload.
Derive PayloadCodec for the value, register it in Hooks::register, and keep the token the
registrar returns:
use mod_api::*;
use std::sync::OnceLock;
#[derive(PayloadCodec)]
struct Counter {
counter: VarInt,
}
static REPLY: OnceLock<ToClient<Counter>> = OnceLock::new();
fn register(r: &mut dyn Registrar) {
let mut payloads = r.payload_handlers();
let mut view = payloads.registrar("1");
// The server answers each counter with the next one.
view.play_to_server_typed::<Counter>(PayloadId("example:count".into()), |value, cx| {
let counter = value.counter.0.checked_add(1).ok_or("counter is too large")?;
let next = Counter { counter: VarInt(counter) };
REPLY.get().unwrap().reply(cx, &next).map(drop).map_err(|e| format!("{e:?}"))
});
let reply = view.play_to_client_typed::<Counter>(
PayloadId("example:count_reply".into()),
|value, _| Ok(log::info!("server counted {}", value.counter.0)),
);
let _ = REPLY.set(reply);
}
- Registration.
play_to_server_typed,play_to_client_typedandplay_bidirectional_typed, and theirconfiguration_*andcommon_*forms, sit beside the raw methods on the same registrar and take its version,optional()andexecutes_on(...). The handler receives the decoded value and the connection'sIPayloadContext. A typed id has one declaration: the same id in another protocol refuses load. - Tokens. Registration returns a
ToServer<T>(client to server) orToClient<T>(server to client), both for a bidirectional one. Keep it and send with it; it has a Wire form, so a wasm mod keeps it the same way. A token grants nothing on its own: each send checks it. - Sending and replying.
ToServer::send(host, &value)sends from the client (ClientHost::send_payload_to_server),ToClient::send(host, player, &value)from the server (PlayerRef::send_payload), andreply(cx, &value)on either answers on the connection a handler received on. They return the raw sends' results:Queuedmeans accepted locally. Sending the wrong direction does not compile. - Schema negotiation. The derive gives the value type a schema fingerprint (field types in
order, variant positions; not names), and it is part of the negotiated version. A peer whose
type has another shape is refused at join when the payload is required; when both sides
declared it
optional(), it is absent and a send returnsUnsupportedPeer. - Named errors.
PayloadSendError::StaleTokenfor a token the registrar did not hand out as it claims (forged, from another load, read as another type, or its mod off);EncodeFailedfor a value the peer could not decode (a bound or the allocation budget), before anything is queued;WrongProtocolfor a send in a phase the id is not declared in. A received body that is not one value of the type closes the session, naming the mod, and the handler does not run. A handler that panics is disabled: its transaction rolls back, nothing it staged is sent, the session closes, and it is not called again.