index.adoc

Nimble Protocol

Copyright © 2022 Peter Bjorklund. All rights reserved.

Nimble Protocol

All commands documented below is usually prepended using the Ordered Datagram Protocol. Ordered Datagrams has a U16 sequence number that ensures that out of order and duplicate datagrams are ignored.

Join Game Request

Sent by the client to the server, asking for the included local players to become participants in the game session.

Implemented by nimbleSerializeClientOutGameJoin().

Type	Name	Description
U8	Command	NimbleSerializeCmdJoinGameRequest (0x01)
Version	Nimble Protocol Version	The protocol version described in this document. Currently 0.0.1.
Version	Application Version	Since it is vital that the application is deterministic, you need to verify that everyone is using the exact same version of the application.
U8	Participant Count	The number of participants that follows in the stream.
U8 * Participant Count	Local Player Identifier	The local player identifier for the participant on the client. The client can select any unique identifier between 1-255. 0 is reserved.

Version

The semantic version. Used for the Nimble Protocol and Application version.

Type	Name	Description
U16	Major
U16	Minor
U16	Patch

Join Game Response

Sent by the server to the client, approving or denying the join game request. If participant count is 0, the request was denied.

Implemented in nimbleSerializeServerOutGameJoinResponse().

Type	Name	Description
U8	Command	NimbleSerializeCmdJoinGameResponse (0x09)
U8	Participant Connection Id	Game session unique identifier for the participant connection created when a join game request was approved.
U8	Participant Count	The number of participant infos that follows the stream. If zero, the join request was denied.
Participant Join Result * Participant Count	Join Infos	Assigned participant Ids for each participant in the participant connection. Client should mark Steps with the unique participant ids.

Participant Join Result

Information about the local player identifier and their assigned participant id.

Type	Name	Description
U8	Local Player Identifier	Game session unique identifier for the local player on the client.
U8	Participant Id	Game session assigned unique participant identifier for the local player on the client.

Download Game State Request

Sent from a client to a server to request the most recent game state that the server has knowledge of. The client usually only request it once, after receiving a successful Join Game Response. Usually the complete state is only set on the server each X tick (X is usually around 30-60 ticks).

Type	Name	Description
U8	Command	NimbleSerializeCmdDownloadGameStateRequest (0x03)
U8	ClientRequestId	Increased everytime the client starts a new download game state attempt.

Download Game State Response

Sent from the server to the client in response to a Download Game State Request.

Implemented in nimbleSerializeServerOutGameStateResponse().

Type	Name	Description
U8	Command	NimbleSerializeCmdGameStateResponse (0x0B)
U8	ClientRequestId	The request ID provided by the client in the Download Game State Request
StepId (U32)	StepId	The StepId/TickId when the game state was captured, before input and update was applied to the state.
U32	State Octet Size	The number of octets in the total state.
U32	Blob Stream Channel ID	The game state will be transferred over this blob stream channel.

Game State Chunk

Sent from the server to the client. A blob stream chunk is usually 1024 octets.

Type	Name	Description
U8	Command	NimbleSerializeCmdGameStatePart (0x0A)
U32	Blob Stream Channel ID	The blob stream channel Id that the client is receiving the state on.
BlobStreamOutEntrySend	Blob Stream Out Entry format	See BlobStream documentation for specifics. But essentially it is: U8 Blob Stream Command (0x01) U32 ChunkID that follows U16 Chunk Octet Size. Usually 1024 octets for all chunks except maybe the last one. U8 * Chunk Octet Size. the Blob Stream Chunk.

Game State Chunk Ack

Sent from the client to the server to acknowledge which chunks of the game state that have been received.

Type	Name	Description
U8	Command	NimbleSerializeCmdDownloadGameStateStatus (0x04)
U32	Blob Stream Channel ID	The blob stream channel Id that the client is receiving the state on.
BlobStreamInLogicSend	Blob Stream In Logic format	See BlobStream documentation for specifics. But essentially it is: U8 Blob Stream Command (0x02) U32 ChunkID that the client is waiting for U32 Receive Mask with bits set for each chunk that the client has received.

Game Step Request

Send Steps (Human Player Inputs) from the client to the server. The Steps should be sent with redundancy, include all Steps that hasn’t been acked by the server in Game Step Response.

Implemented by nbsPendingStepsSerializeOutHeader().

Type	Name	Description
U8	Command	NimbleSerializeCmdGameStep (0x02)
U32	Latest authoritative StepId	The StepID received from server without any gaps or missing steps.
U64	StepId Receive Mask	Bit mask with bit set for each stepIds completely received after Latest authoritative StepId
U32	Start StepId	The first stepId in the stream that follows.
Multiple Steps For Participants	Predicted steps	The predicted combined steps for all the local players on the client.

Game Step Response

Sent from the server to the client with the authoritative steps (combined Steps from all participants).

Implemented by nimbleSerializeServerOutStepHeader().

Type	Name	Description
U8	Command	NimbleSerializeCmdGameStepResponse (0x08)
U8	Connection specific buffer count	The number of steps contained at the connection specific incoming predicted steps.
S8	Authoritative StepId delta	The difference between the last predicted stepId received and the current authoritative stepId. Negative values means that the client is behind the server and should increase the rate of predicting steps. A positive value means that the predicted steps are ahead of the assembly of authoritative steps. The higher the number, the higher the perceived latency for the inputs.
U32	Last Received StepId	The last received stepId from the client.
U32	First StepId in range	The first stepId in the range of steps that follows. It contains steps that the client has previously indicated that it is missing (determined from Game Step Request).
U8	Range Count	The number of ranges following.
Authoritative Step Range * Range Count	Authoritative Step Ranges	The authoritative step ranges that the client is probably missing.

Authoritative Step Range

Type	Name	Description
U8	Delta StepId	The difference between the last stepId in the previous range. Or the First StepId in range if this is the first range.
Multiple Steps For Participants	Authoritative Steps	The authoritative steps for all the participants in the game for this step range.

Types

Multiple Steps For Participants

Multiple steps for multiple participants. Used both for predicted steps (includes local participants) and authoritative steps (includes all participants in the game session).

Type	Name	Description
U8	Step Count	The number of step for participants that follows. Allowed to be zero.
Step For Participants * Step Count	Steps

Step For Participants

A single step that includes multiple participants.

Type	Name	Description
U8	Step Octet Count	The number of octets following in the stream (includes Participant Count and Steps for each Participant).
U8	Participant Count	Steps follows for that number of participants
U8	Step for one Participant * Participant Count	Steps follows for that number of participants

Step for one Participant

A single step for the indicated participant ID.

Type	Name	Description
U8	Participant ID	Step for the indicated participant ID.
U8	Step octet size	number of octets that follows.
U8 * Step octet size	Step payload	Application specific step payload. It is recommended that first octet in the payload can be a zero to indicate that the step is "unknown", no input is pressed.