Byte Engine Docs

Transport protocol

Look up the BETP packet formats, the reliable and unreliable delivery rules, the connection handshake and timeouts, and the limits of the UDP and in-process transports.

The Byte Engine Transport Protocol (BETP) carries application payloads between a client and an authoritative server over UDP. The protocol performs no I/O of its own: the engine's network module supplies a UDP transport and an in-process channel transport for deterministic tests. This page specifies the wire format, the delivery rules, the connection lifecycle, and the transports' limits.

Packets

Every packet starts with a 5-byte header: the ASCII bytes BETP, then one type byte. Every multi-byte field is little-endian. There is no version field.

TypePacketSize in bytesFields after the header, in order
0ReservedNever valid.
1Connection request13Client salt (8).
2Challenge21Client salt (8), server salt (8).
3Challenge response13Connection ID (8).
4Data19 to 1,045Connection ID (8), acknowledgement (2 + 4), unreliable payload.
5Disconnect13Connection ID (8).
6Keep-alive19Connection ID (8), acknowledgement (2 + 4).
7Message21 to 1,045Connection ID (8), sequence (2), acknowledgement (2 + 4), reliable payload.

A payload holds up to 1,024 bytes and fills the rest of the datagram. The protocol doesn't fragment: an application splits larger data across payloads. A datagram is at most 1,045 bytes, and the engine rejects a longer one before decoding it.

An acknowledgement is the newest sequence received, as a 16-bit number, and a 32-bit field whose bit i is set when sequence ack - i arrived; bit 0 stands for the newest sequence itself, so a zero field acknowledges nothing. Every packet on an established connection carries one.

The connection ID is the client salt XOR the server salt, computed by both sides. Salts aren't a security boundary.

Decoding rejects a packet whose header is short, whose protocol bytes differ, whose type byte is unknown or reserved, or whose length is outside its type's range.

Delivery

Each direction of a connection has one stream with two delivery classes:

ClassPacketSequenceResentDelivered
ReliableMessage16-bit, per direction, from 0Every 100 ms until acknowledged, without limitOnce, in sequence order
UnreliableDataNoneNeverAs it arrives, possibly reordered
RuleValue
Window32 reliable messages unacknowledged at once. Later messages wait their turn.
Out-of-order arrivalA reliable message ahead of a gap is held until the gap fills.
Dropped on arrivalA reliable message already delivered, or 32 or more ahead of the next expected one. It's still acknowledged.
Packets per payloadOne. Payloads are never combined into one packet.
Keep-aliveSent after 250 ms without sending anything, or when an acknowledgement is due and nothing else is. It also stands in for a standalone acknowledgement.

Connection lifecycle

StepSenderPacketEffect
1ClientConnection request with its saltResent on every update until a challenge arrives.
2ServerChallenge with both saltsThe server computes the connection ID.
3ClientChallenge response with the connection IDThe client computes the same ID. A challenge with a foreign client salt is an error.
4ServerAny packet carrying the connection ID, usually a keep-aliveAccepts the connection. A response with a wrong ID is dropped.
5ClientAny packet carrying the ID confirms the connection; that packet's payload and acknowledgements aren't lost.

Client states: initial, initiating connection, connecting, connected, disconnecting. Server states: initial, connected, disconnecting. A session that reaches disconnecting is finished; reconnect with a new session.

TimeoutValue
Connecting without confirmationMore than 5 s ends the attempt.
Connected without a packet carrying the connection IDMore than 5 s ends the connection. Keep-alives count.
Disconnect packetEnds the connection at once.

A connected client treats a packet with another connection ID as an error and stops processing that batch. A connected server ignores such packets. Payloads queued before the connection exists are sent once it's established.

Transports

UDP transportValue
Client socketBound to the wildcard address and an ephemeral port of the server's address family, connected to the server, nonblocking.
Server socketBound to the address given, nonblocking. Port 0 picks a free port.
PeersAt most 64, counting handshakes in progress. Datagrams from further addresses are ignored.
New peerIts first datagram must be a connection request.
Handshake timeoutA peer that hasn't connected 5 s after its first datagram is dropped.
Timed-out or disconnected peerSent a best-effort disconnect and reported as a client disconnected event.
SendsBest effort. A failed send isn't an error; reliable messages are resent.
Socket errorsConnection refused, connection reset, and interrupted are skipped. Any other receive error is returned from the update.
Dropping a client or serverSends a disconnect to each connected peer.

The server tags each received payload with the sender's connection ID and sends to all connected peers or to one by ID. Dropped datagrams are logged at debug level and never returned as errors: too large, undecodable, unexpected for the session's state, before the session exists, or carrying a mismatched ID.

The in-process channel transport connects a server to clients it creates, in the same process, without encoding. It reports only connected events, has no peer limit, and never disconnects a client.

ErrorCause
ClientCreateErrorBinding, connecting, or configuring the client socket failed.
ServerCreateErrorBinding or configuring the server socket failed.
PayloadTooLargeA payload longer than 1,024 bytes.
BadSalt, BadConnectionIdA client received a challenge with a foreign salt, or a packet for another connection.

Constants

ConstantValue
Payload1,024 bytes
Datagram1,045 bytes
Window32 messages
Retry interval100 ms
Keep-alive interval250 ms
Session timeout5 s
Peers per UDP server64
Handshake timeout5 s

What the protocol doesn't define

BETP has no version negotiation, no channels beyond the two delivery classes, no fragmentation, and no timestamps, tick numbers, or clock synchronization on the wire. The engine declares a Replicable contract with an Importance of essential or optional, but no transport reads it: every send takes an explicit reliable flag and a payload. The only identity shared across peers is the connection ID; entity identity, ownership, and authority are the application's to define.

Rust API

On this page