From Database to Game Server: Simplifying Real-Time Multiplayer with SpacetimeDB

clockworklabs/SpacetimeDB

SpacetimeDB is essentially a real-time, distributed, and persistent data platform designed specifically for building multiplayer games and applications. Think of it as a blend of a database, a game server, and a state synchronization engine all in one.

SpacetimeDB lets you focus on writing your core game logic in Rust (the Modules) and defining your data structure, while it handles the immense complexity of networking, synchronization, persistence, and concurrency for a massive number of simultaneous players. It drastically simplifies the server-side development of multiplayer apps.

Adopting SpacetimeDB usually follows these high-level steps

You'll need the SpacetimeDB command-line tools (CLI) and the Rust toolchain to develop the server-side logic (Modules).

Install Rust
Make sure you have the standard Rust development environment set up.

Install SpacetimeDB CLI
You'd typically use a command like this (depending on the actual instructions)

cargo install spacetimedb-cli

You define the "Tables" and "Columns" that represent your game state. This is often done using a dedicated definition file.

Concept
If you're building a simple RPG, you might define a Player table and an Item table.

-- Conceptual Schema Definition (often in a .sdb file)
CREATE TABLE Player (
    id UUID PRIMARY KEY,
    name TEXT NOT NULL,
    x REAL NOT NULL,
    y REAL NOT NULL,
    health INTEGER NOT NULL
);

This is where you write the core logic that modifies the database. These are functions that clients can call.

Concept
A function to move a player.

// Conceptual Rust Module (Server-Side Logic)
use spacetimedb_sdk::{*, spacetimedb::Table}; // Example imports

#[spacetimedb_module]
pub fn move_player(ctx: &Context, new_x: f32, new_y: f32) {
    // 1. Get the player row for the current user (using ctx.sender)
    // 2. Check if the move is valid (e.g., not through a wall)
    // 3. Update the database table
    
    Player::update_by_id(
        ctx.sender, 
        PlayerUpdate { 
            x: Some(new_x), 
            y: Some(new_y),
            ..Default::default()
        }
    );
    // SpacetimeDB automatically broadcasts this change to all subscribed clients!
}

On the client side (e.g., a Unity/C# or React/TypeScript application), you use a SpacetimeDB SDK to connect and "subscribe" to the data you need.

Concept
A client connects and says, "Give me all the players in the current game area."

// Conceptual C# Client Code (e.g., in a Unity game)
using SpacetimeDB.Client; // Example using

// 1. Connect to the SpacetimeDB instance
Client.Connect("ws://my-server-url:3000");

// 2. Subscribe to the data needed
// This tells the server to stream all changes to the 'Player' table
Client.Subscribe(Subscription.table("Player"));

// 3. Listen for changes
Player.OnInsert += (row) => {
    // A new player just joined! Instantiate a game object.
};

Player.OnUpdate += (old_row, new_row) => {
    // A player moved! Update their position in the game world.
    UpdatePlayerPosition(new_row.x, new_row.y);
};

When a player performs an action, the client calls the Module you wrote in Rust.

Concept
The player presses the 'W' key.

// Conceptual C# Client Code to call the server function
// The name of the call matches the Rust function name.
SpacetimeDB.Client.Call("move_player", new_x, new_y);

// The client waits for the database update (via subscription) to confirm the move.
// This is the "network loop" handled automatically!

Let's look at the flow for a basic Player Movement interaction.

This code is executed securely on the SpacetimeDB server.

// File: modules/player_actions.rs

use spacetimedb_sdk::spacetimedb::{Context, Table};
use crate::Player; // Assume Player table is defined and imported

// Function called by the client to move the player
#[spacetimedb_module]
pub fn move_player_to(ctx: &Context, target_x: f32, target_y: f32) {
    // Get the ID of the user who sent the request (the current player)
    let player_id = ctx.sender;
    
    // 1. **Authorization Check (Security)**
    // Ensure the player exists and they are allowed to move.
    if Player::filter_by_id(&player_id).is_none() {
        // Log an error, but no state change occurs.
        log::error!("Unauthorized move attempt by non-existent player: {:?}", player_id);
        return;
    }

    // 2. **Game Logic Check (Validation)**
    // For simplicity, let's just ensure the move is not too far.
    // In a real game, you'd check collision, movement speed, etc.
    // NOTE: SpacetimeDB makes sure this check is consistent across all clients.
    // ... (logic to check distance) ...

    // 3. **State Change (Database Update)**
    // If all checks pass, update the row in the Player table.
    // The player_id is the primary key.
    Player::update_by_id(
        player_id, 
        PlayerUpdate { 
            x: Some(target_x), 
            y: Some(target_y),
            ..Default::default()
        }
    );
    
    // ** The magic: SpacetimeDB automatically sends the change 
    // to ALL connected clients subscribed to the 'Player' table.**
}

This code runs on the user's device (e.g., their PC, phone, or browser).

// File: Client/GameManager.cs

using SpacetimeDB.Client;
// Assume Player class is generated from the SpacetimeDB schema

public class GameManager : MonoBehaviour {

    // A dictionary to keep track of the game objects for each player ID
    private Dictionary<Guid, GameObject> playerGameObjects = new();

    void Start() {
        // ... Connection and Authentication setup ...

        // Subscribe to all changes on the Player table
        Client.Subscribe(Subscription.table("Player"));
        
        // Setup Event Handlers for Database Changes
        Player.OnInsert += OnPlayerJoined;
        Player.OnUpdate += OnPlayerStateUpdated;
        Player.OnDelete += OnPlayerLeft;
    }

    // When a player moves (update event received from server)
    void OnPlayerStateUpdated(Player oldState, Player newState) {
        if (playerGameObjects.TryGetValue(newState.id, out GameObject playerObj)) {
            // Smoothly move the visual representation to the new position
            // This is the result of the server's successful "move_player_to" call!
            playerObj.transform.position = new Vector3(newState.x, 0, newState.y); 
        }
    }
    
    // Client User Input Handler
    public void HandleMovementInput(float newX, float newY) {
        // 1. **Optimistic UI Update (Optional but common)**
        // Move the player locally for instant feedback, then...
        
        // 2. **Call the Server Module**
        // This sends a request to the server to execute the secure Rust logic.
        Client.Call("move_player_to", newX, newY);
        
        // 3. **Reconciliation**
        // If the server accepts the move, the OnPlayerStateUpdated event 
        // will fire with the *true* state, correcting any local drift 
        // or rejecting the move if the server's logic invalidated it.
    }
}