Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TaylorZaneKirk/MMO-Project/llms.txt

Use this file to discover all available pages before exploring further.

These messages handle the authentication and session establishment sequence — from initial login through character load, world entry, reconnect, and logout. All payload field names match the keys defined in protocol-v1.json. The server owns the session lifecycle; the client only sends intent and applies server-confirmed results.

​
login_request C→S

Sent by the client immediately after the WebSocket connection is opened. Declares credentials and the desired protocol version. Optionally opts the session into revisioned delta delivery. 
{
  "type": "login_request",
  "payload": {
    "account_name": "player1",
    "password": "hunter2",
    "protocol_version": "v1",
    "runtime_delta_protocol": 1
  }
}
​
account_name
string
required
The account login name.
​
password
string
required
The account password.
​
protocol_version
string
required
Must be "v1". The server rejects unknown protocol versions and closes the connection.
​
runtime_delta_protocol
integer | null
Send 1 to opt this session into revisioned delta delivery. Clients that omit this field or send null remain in legacy snapshot-refresh mode. See Delta Runtime for details.

​
login_response S→C

Returned by the server after evaluating the login credentials. On failure, the server closes the WebSocket after sending this message. 
{
  "type": "login_response",
  "payload": {
    "login_status": "ok",
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}
​
login_status
string
Outcome of the login attempt. One of:
  • "ok" — credentials valid; session created; session_id and account_id are populated
  • "invalid_credentials" — account name or password did not match
  • "account_inactive" — account exists but is disabled
  • "unsupported_version" — protocol_version did not match the server’s expected value
​
session_id
string | null
UUID of the newly created server session. Populated only when login_status is "ok".
​
account_id
string | null
UUID of the authenticated account. Populated only when login_status is "ok".

​
character_load_response S→C

Sent by the server immediately after a successful login_response. Binds the authenticated session to the account’s owned character. World entry does not proceed if character_id is null. 
{
  "type": "character_load_response",
  "payload": {
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "character_id": "c9d0e1f2-a3b4-5678-cdef-012345678901"
  }
}
​
session_id
string
The active session UUID, echoed from the login response.
​
character_id
string | null
UUID of the account’s character. null if the account has no character, in which case world entry is blocked.

​
enter_world_response S→C

Sent by the server after character_load_response. Delivers the minimum authoritative state needed to place the character into the world. A world_snapshot follows immediately after. 
{
  "type": "enter_world_response",
  "payload": {
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "character_id": "c9d0e1f2-a3b4-5678-cdef-012345678901",
    "map_id": "x1000y992",
    "tile_x": 12,
    "tile_y": 7,
    "facing": "south",
    "presence_source": "character_save"
  }
}
​
session_id
string
The active session UUID.
​
character_id
string
The UUID of the character entering the world.
​
map_id
string
The chunk map identifier the character is entering, for example "x1000y992".
​
tile_x
integer
The character’s authoritative starting tile X coordinate on map_id.
​
tile_y
integer
The character’s authoritative starting tile Y coordinate on map_id.
​
facing
string
The character’s starting facing direction. One of "north", "south", "east", "west".
​
presence_source
string
Indicates how the starting position was determined:
  • "character_save" — position was restored from the database record
  • "default" — no saved position existed; the character spawned at the map default

​
reconnect_request C→S

Sent by the client to restore a previously disconnected session within the reconnect grace window. See Session Flow — Reconnect grace window for eligibility rules. 
{
  "type": "reconnect_request",
  "payload": {
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "character_id": "c9d0e1f2-a3b4-5678-cdef-012345678901"
  }
}
​
session_id
string
required
The UUID of the session to restore, obtained from the original login_response.
​
character_id
string
required
The UUID of the character associated with the session.

​
reconnect_response S→C

Returned by the server after evaluating a reconnect_request. On success, a fresh world_snapshot follows immediately. 
{
  "type": "reconnect_response",
  "payload": {
    "reconnect_status": "restored",
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "character_id": "c9d0e1f2-a3b4-5678-cdef-012345678901",
    "map_id": "x1000y992",
    "tile_x": 12,
    "tile_y": 7,
    "facing": "south"
  }
}
​
reconnect_status
string
Outcome of the reconnect attempt. One of:
  • "restored" — session restored; position fields are populated
  • "session_invalid" — session record not found, already revoked (e.g. after explicit logout), or map presence could not be loaded
  • "reauthentication_required" — session has expired or the reconnect grace window has elapsed
​
session_id
string | null
The restored session UUID. Populated only on "restored".
​
character_id
string | null
The restored character UUID. Populated only on "restored".
​
map_id
string | null
The map the character is being restored to. Populated only on "restored".
​
tile_x
integer | null
The character’s restored tile X coordinate. Populated only on "restored".
​
tile_y
integer | null
The character’s restored tile Y coordinate. Populated only on "restored".
​
facing
string | null
The character’s restored facing direction. Populated only on "restored".

​
logout_request C→S

Sent by the client to end the session explicitly. The server revokes the session, removes live map presence, and closes the WebSocket connection after processing this message. 
{
  "type": "logout_request",
  "payload": {
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "character_id": "c9d0e1f2-a3b4-5678-cdef-012345678901"
  }
}
​
session_id
string
required
The UUID of the session to end.
​
character_id
string
required
The UUID of the character whose presence should be cleared.
There is no logout_response message. The server closes the WebSocket after processing logout_request. Any subsequent reconnect_request for this session will receive "session_invalid" because the session’s revoked_at column is set by the logout operation.

Build docs developers (and LLMs) love

Get started for freeTalk to us