lobby

Lobby Plugin

A flexible lobby/party system for Cardinal worlds, handling player grouping and session management. Implemented as a Cardinal plugin.

Quick Start

import (
    "github.com/argus-labs/world-engine/pkg/cardinal"
    "github.com/argus-labs/world-engine/pkg/lobby"
)

func main() {
    world, _ := cardinal.NewWorld(cardinal.WorldOptions{...})

    cardinal.RegisterPlugin(world, lobby.NewPlugin(lobby.Config{
        LobbyWorld: cardinal.OtherWorld{
            Region:       "us-west",
            Organization: "myorg",
            Project:      "myproject",
            ShardID:      "lobby-shard-1",
        },
    }))

    world.StartGame()
}

Overview

• PvE: Lobby acts as a persistent party that plays games together
• PvP: Lobby acts as a temporary session where multiple teams gather

Message Categories

The lobby package uses 4 message categories:

1. Command (Client ↔ Shard)

Client sends a command to the shard. Shard processes it and returns a result to the sender.

All commands include RequestID for request/response correlation (except Heartbeat).

2. Event (Shard → All Clients, broadcast)

Shard broadcasts state changes to all subscribed clients.

3. CrossShardCommand (Shard → Shard)

One shard sends a command to another shard.

4. CrossShardResult (Shard → Shard, response)

Shard sends a response back to the originating shard.

Currently not needed. CrossShardCommands in this package don't require responses.

Data Structures

Lobby

Lobby
- ID string              // Unique identifier
- LeaderID string        // Player who controls the lobby
- Teams []Team           // List of teams
- InviteCode string      // Code for others to join
- GameWorld OtherWorld   // Target game shard address
- Session Session        // Current session state
- CreatedAt int64        // Unix timestamp

Team

Team
- TeamID string          // Unique team identifier
- Name string            // Team display name
- Players []PlayerState  // Players in team
- MaxPlayers int         // Max players (0 = unlimited)

PlayerState

PlayerState
- PlayerID string                 // Player identifier
- IsReady bool                    // Ready status
- PassthroughData map[string]any  // Forwarded to game shard
- JoinedAt int64                  // Unix timestamp when player joined

Session

Session
- State SessionState             // idle | in_session
- PassthroughData map[string]any // Forwarded to game shard

Configuration

Cross-Shard Communication

When StartSessionCommand succeeds, NotifySessionStartCommand is sent to game shard:

type NotifySessionStartCommand struct {
    Lobby      LobbyComponent    // Full lobby data (includes GameWorld)
    LobbyWorld cardinal.OtherWorld // For NotifySessionEndCommand callback
}

Game shard should:

1. Register a system that handles NotifySessionStartCommand
2. Run the game
3. Send NotifySessionEndCommand back to lobby when game ends

// In game shard
func GameSessionSystem(state *GameSessionSystemState) {
    for cmd := range state.SessionStartCmds.Iter() {
        payload := cmd.Payload
        // payload.Lobby contains full lobby data
        // payload.LobbyWorld for sending NotifySessionEndCommand back

        // When game ends:
        payload.LobbyWorld.SendCommand(&state.BaseSystemState, lobby.NotifySessionEndCommand{
            LobbyID: payload.Lobby.ID,
        })
    }
}

Custom Provider

Override invite code generation:

type MyProvider struct {
    lobby.DefaultProvider
}

func (p MyProvider) GenerateInviteCode(l *lobby.Component) string {
    return generateMyCustomCode(8)
}

cardinal.RegisterPlugin(world, lobby.NewPlugin(lobby.Config{
    LobbyWorld: cardinal.OtherWorld{...},
    Provider:   MyProvider{},
}))

Default: Hash(LobbyID + Timestamp) -> 6-char uppercase alphanumeric (excludes confusing chars: 0, O, I, L, 1).

Lifecycle

CreateLobby -> idle -> (players join, ready up) -> StartSession -> in_session -> EndSession -> idle
                                                                                      │
                                                                                      v
                                                                        (players can start again)

Key Behaviors

• Invite code persists on leader transfer/leave (no auto-regeneration)
• Leader-only actions: kick, transfer, start session, regenerate code
• Ready check: All players (including leader) must be ready to start
• Session lock: No join/team-change during in_session (leave is always allowed)
• Auto-reset: After session ends, all players reset to not-ready
• Auto-delete: Lobby deleted when last player leaves
• Per-lobby game shard: Each lobby specifies its target game shard via GameWorld

Heartbeat System

The lobby package includes a heartbeat mechanism to detect and remove disconnected players. It uses a deadline-based (lease) approach where clients must continuously renew their presence.

How It Works

1. Clients send HeartbeatCommand periodically (e.g., every HeartbeatTimeout/3 seconds)
2. Server stores a deadline for each player: deadline = now + HeartbeatTimeout
3. On each heartbeat, the deadline is extended: deadline = now + HeartbeatTimeout
4. Server removes players when now >= deadline (player failed to renew their lease)
5. Events emitted: PlayerTimedOutEvent when a player times out

Deadline Approach

When a player joins or sends a heartbeat:

deadline = currentTime + HeartbeatTimeout

When checking for timeouts (every tick):

if currentTime >= deadline {
    // Player timed out - remove from lobby
}

This approach is simpler than tracking "last heartbeat time" because:

• No subtraction needed at check time (now >= deadline vs now - lastHeartbeat > timeout)
• The deadline is the actual removal time, making debugging easier

Configuration

cardinal.RegisterPlugin(world, lobby.NewPlugin(lobby.Config{
    LobbyWorld:       cardinal.OtherWorld{...},
    HeartbeatTimeout: 30, // Remove player after 30 seconds without heartbeat
}))

Client Implementation

Clients should:

1. Start a heartbeat timer immediately after creating or joining a lobby
2. Send HeartbeatCommand at the configured interval
3. Stop the timer after leaving the lobby

// Client-side pseudocode
ticker := time.NewTicker(10 * time.Second)
go func() {
    for range ticker.C {
        sendCommand(lobby.HeartbeatCommand{})
    }
}()

Important: Start heartbeats immediately after joining. The timeout clock starts the moment a player joins, not when they send their first heartbeat.

Timeout Behavior

When a player joins a lobby, their deadline is set to now + timeout. This means:

• Players must send heartbeats before their deadline expires or they are removed
• This prevents "zombie" players who join but never send heartbeats from occupying slots indefinitely

When a player times out:

• Player is removed from the lobby
• PlayerTimedOutEvent is emitted
• If player was leader, leadership auto-transfers to another player
• If lobby becomes empty, it is deleted