Skip to main content

UdpNotification

All game-server messages delivered over the UDP proxy as GraphQL payloads. Subscribe to udpNotifications before or with sending mutations so responses and GenericErrorResponse (correlate via sequenceNumber) are not missed. NOTE: the ActorUpdateResponse and VoxelUpdateResponse members are LEGACY and never emitted (applied updates arrive as your own *Notification self-echo; failures as GenericErrorResponse) — they remain in the union for backward compatibility and will be removed in a future major version.

union UdpNotification = ActorUpdateResponse | ActorUpdateNotification | VoxelUpdateResponse | VoxelUpdateNotification | ClientAudioNotification | ClientVideoNotification | ActorLeftNotification | ClientTextNotification | ClientEventNotification | ServerEventNotification | SingleActorMessageNotification | ChannelMessageNotification | GenericErrorResponse | RealtimeConnectionEvent

Possible types​

UdpNotification.ActorUpdateResponse object​

LEGACY — never emitted. The game server retired the dedicated actor-update response opcode (129); an applied update now arrives as your own ActorUpdateNotification (the sender is included in the chunk fan-out) and failures arrive as GenericErrorResponse. This type remains in the UdpNotification union for backward compatibility only — do not select it in new code; it will be removed in a future major version.

UdpNotification.ActorUpdateNotification object​

Notification received when an actor (player or NPC) state is updated by another client or the server. Received via the udpNotifications subscription.

UdpNotification.VoxelUpdateResponse object​

LEGACY — never emitted. The game server retired the dedicated voxel-update response opcode (132); an applied update now arrives as your own VoxelUpdateNotification (the sender is included in the chunk fan-out) and failures arrive as GenericErrorResponse. This type remains in the UdpNotification union for backward compatibility only — do not select it in new code; it will be removed in a future major version.

UdpNotification.VoxelUpdateNotification object​

Notification received when a voxel (block) is updated by another client or the server. Received via the udpNotifications subscription.

UdpNotification.ClientAudioNotification object​

Notification received when another client sends an audio packet (voice chat). Received via the udpNotifications subscription.

UdpNotification.ClientVideoNotification object​

Notification received when another client sends a webcam video fragment. Received via the udpNotifications subscription. videoData is ONE fragment: a 6-byte header (version, codec, frameId uint16 BE, fragIndex, fragCount) followed by that slice of the encoded frame; reassemble fragments with the same uuid and frameId, and drop an incomplete frame when a newer frameId arrives or after ~500 ms.

UdpNotification.ActorLeftNotification object​

The game server has stopped considering an actor present (Buddy v0.25.0). Emitted ONCE, over the actor's last chunk with the replication rings its own updates used, at the moment its presence record is removed -- roughly five seconds after its last update. Not emitted when the actor merely moved to another server. Treat a later ActorUpdateNotification for the same uuid as a rejoin. Received via the udpNotifications subscription.

UdpNotification.ClientTextNotification object​

Notification received when another client sends a text message (chat). Received via the udpNotifications subscription.

UdpNotification.ClientEventNotification object​

Notification received when another client sends a custom event. Received via the udpNotifications subscription.

UdpNotification.ServerEventNotification object​

Notification received when the server sends a custom event. Received via the udpNotifications subscription.

UdpNotification.SingleActorMessageNotification object​

Notification received when another actor sends you a direct actor-to-actor message (SINGLE_ACTOR_MESSAGE). Delivered only to the targeted actor via the udpNotifications subscription.

UdpNotification.ChannelMessageNotification object​

Notification received when a message is published to a channel you are a member of. Delivered over the udpNotifications subscription to every active channel member.

UdpNotification.GenericErrorResponse object​

Asynchronous error from the UDP game server for a previously sent datagram (e.g. a send* mutation). Delivered as a member of the udpNotifications union, NOT as a GraphQL error on the mutation (which only reports whether the datagram was accepted for sending). Match it to the originating send via sequenceNumber and read errorCode for the reason. Note: not every failure produces one — some auth failures are dropped silently (see UdpErrorCode).

UdpNotification.RealtimeConnectionEvent object​

Realtime lifecycle event delivered on the udpNotifications subscription. It is a control frame — it carries no appId, so it is never dropped by the per-app fan-out filter. Branch on code; use retryable to decide whether retrying can succeed. Most codes report that a session could not be opened or correctly scoped and are TERMINAL: the subscription completes immediately after emitting one, so the client must fix the cause and resubscribe. The exception is SERVER_DRAINING, which arrives mid-stream on a healthy subscription and does NOT end it — see that code below.

Returned By​

udpNotifications subscription