Connection Packets & Flow

This section details the packets exchanged during the initial connection handshake and the state transitions required to enter the PLAY state.

Connection State Machine

enum class ConnectionState {
    CONNECTING,      // QUIC handshake in progress
    HANDSHAKING,     // Protocol handshake pending
    AUTHENTICATING,  // Waiting for auth tokens
    PLAY,            // Fully authenticated
    DISCONNECTING,   // Graceful disconnect
    DISCONNECTED     // Connection closed
};

Complete Handshake Sequence

The following diagram illustrates the interaction between the Client, the AlloyServer, and Hytale Services.

Packet Definitions

Connect (ID 0)

Initiates the protocol connection.

Offset	Size	Field	Description
0	1	nullBits	Optional field flags
1	64	protocolHash	Protocol version (fixed ASCII)
65	1	clientType	Game or Editor
66	16	uuid	Player UUID
82	4	languageOffset	Offset to language string
86	4	identityTokenOffset	Offset to identity token
90	4	usernameOffset	Offset to username

AuthGrant (ID 11)

Sent by the server to provide the authorization grant.

Fields:

• authorizationGrant: String (max 4096)
• serverIdentityToken: String (max 8192)

AuthToken (ID 12)

Sent by the client to finalize the token exchange.

Fields:

• accessToken: String (max 8192)
• serverAuthorizationGrant: String (max 4096)

Password Authentication (Fallback)

If no identity token is provided in the Connect packet, the server falls back to password authentication.

Certificate Handling

The server uses an ECDSA P-256 certificate.

• Environment Variable: ALLOY_CERT_THUMBPRINT=<40-char hex SHA1>
• Fingerprint Usage: The SHA-256 fingerprint (base64url) is sent in the /server-join/auth-token request to bind the session to the specific server instance.

QUIC Configuration

The server expects ALPN: hytale/1 and an idle timeout of 60000ms.