▸ Agent Skills
17 min read

Version: 2.0.0

On this page

Need help with the tutorial? Join our Discord server!

This progressive tutorial is continued from part 1.

Project Structure

Now that we have our client project setup we can configure the module directory. Regardless of what language you choose, your module will always go into a spacetimedb directory within your client directory like this:

blackholio/                     # This is the directory where your Godot project lives
├── blackholio.csproj
├── module_bindings/            # This directory contains the client logic to communicate with the module
├── ...                         # rest of the Godot files                
└── blackholio-server/
    └── spacetimedb/            # This is where your server module lives

Your module_bindings directory can go wherever you want as long as it is inside of res:// in your Godot project. We’ll configure this in a later step. For now we will create a new module in the blackholio directory which will generate the spacetimedb directory for us.

Create a Server Module

If you have not already installed the spacetime CLI, check out our Getting Started guide for instructions on how to install.

In the same directory that contains your blackholio project, run the following command to initialize the SpacetimeDB server module project with your desired language:

warning

The blackholio directory specified here is the same blackholio directory you created during part 1.

  • C#
  • Rust
  • C++

Run the following command to initialize the SpacetimeDB server module project with C# as the language:

spacetime init --lang csharp --server-only blackholio

Use blackholio-server for the project path and blackholio for the database name.

This command creates a new folder named blackholio-server inside of your Godot project blackholio directory. Inside, there’s a spacetimedb folder that contains the SpacetimeDB server project with C# as the programming language.

Run the following command to initialize the SpacetimeDB server module project with Rust as the language:

spacetime init --lang rust --server-only blackholio

Use blackholio-server for the project path and blackholio for the database name.

This command creates a new folder named blackholio-server inside of your Godot project blackholio directory. Inside, there’s a spacetimedb folder that contains the SpacetimeDB server project with Rust as the programming language.

Run the following command to initialize the SpacetimeDB server module project with C++ as the language:

spacetime init --lang cpp --server-only blackholio

Use blackholio-server for the project path and blackholio for the database name.

This command creates a new folder named blackholio-server inside of your Godot project blackholio directory. Inside, there’s a spacetimedb folder that contains the SpacetimeDB server project with C++ as the programming language.

SpacetimeDB Tables

  • C#
  • Rust
  • C++

In this section we’ll be making some edits to the file blackholio-server/spacetimedb/Lib.cs. We recommend you open up this file in an IDE like VSCode or Rider.

Important: Open the blackholio-server/spacetimedb/Lib.cs file and delete its contents. We will be writing it from scratch here.

In this section we’ll be making some edits to the file blackholio-server/spacetimedb/src/lib.rs. We recommend you open up this file in an IDE like VSCode or RustRover.

Important: Open the blackholio-server/spacetimedb/src/lib.rs file and delete its contents. We will be writing it from scratch here.

In this section we’ll be making some edits to the file blackholio-server/spacetimedb/src/lib.cpp. We recommend you open up this file in an IDE like VSCode or Rider.

Important: Open the blackholio-server/spacetimedb/src/lib.cpp file and delete its contents. We will be writing it from scratch here.

First we need to add some imports at the top of the file. Some will remain unused for now.

  • C#
  • Rust
  • C++

Copy and paste into Lib.cs:

using SpacetimeDB;

public static partial class Module
{

}

Copy and paste into lib.rs:

use std::time::Duration;
use spacetimedb::{rand::Rng, Identity, SpacetimeType, ReducerContext, ScheduleAt, Table, Timestamp};

Copy and paste into lib.cpp:

#include "spacetimedb.h"

using namespace SpacetimeDB;

We are going to start by defining a SpacetimeDB table. A table in SpacetimeDB is a relational database table which stores rows, similar to something you might find in SQL. SpacetimeDB tables differ from normal relational database tables in that they are stored fully in memory, are blazing fast to access, and are defined in your module code, rather than in SQL.

  • C#
  • Rust
  • C++

Each row in a SpacetimeDB table is associated with a struct type in C#.

Let’s start by defining the Config table. This is a simple table which will store some metadata about our game’s state. Add the following code inside the Module class in Lib.cs.

// We're using this table as a singleton, so in this table
// there will only be one element where the `id` is 0.
[Table(Accessor = "config", Public = true)]
public partial struct Config
{
    [PrimaryKey]
    public int id;
    public long world_size;
}

Let’s break down this code. This defines a normal C# struct with two fields: id and world_size. We have added the [Table(Accessor = "config", Public = true)] attribute the struct. This attribute signals to SpacetimeDB that it should create a new SpacetimeDB table with the row type defined by the Config type’s fields.

Although we’re using lower_snake_case for our column names to have consistent column names across languages in this tutorial, you can also use camelCase or PascalCase if you prefer. See #2168 for more information.

The Table attribute takes two parameters, an Accessor which is the name of the table and what you will use to query the table in SQL, and a Public visibility modifier which ensures that the rows of this table are visible to everyone.

The [PrimaryKey] attribute, specifies that the id field should be used as the primary key of the table.

Each row in a SpacetimeDB table is associated with a struct type in Rust.

Let’s start by defining the Config table. This is a simple table which will store some metadata about our game’s state. Add the following code to lib.rs.

// We're using this table as a singleton, so in this table
// there only be one element where the `id` is 0.
#[spacetimedb::table(accessor = config, public)]
pub struct Config {
    #[primary_key]
    pub id: i32,
    pub world_size: i64,
}

Let’s break down this code. This defines a normal Rust struct with two fields: id and world_size. We have decorated the struct with the spacetimedb::table macro. This procedural Rust macro signals to SpacetimeDB that it should create a new SpacetimeDB table with the row type defined by the Config type’s fields.

The spacetimedb::table macro takes two parameters, an accessor which is the name of the table and what you will use to query the table in SQL, and a public visibility modifier which ensures that the rows of this table are visible to everyone.

The #[primary_key] attribute, specifies that the id field should be used as the primary key of the table.

Each row in a SpacetimeDB table is associated with a struct type in C++.

Let’s start by defining the Config table. This is a simple table which will store some metadata about our game’s state. Add the following code to lib.cpp.

// We're using this table as a singleton, so in this table
// there will only be one element where the `id` is 0.
struct Config {
    int32_t id;
    int64_t world_size;
};
SPACETIMEDB_STRUCT(Config, id, world_size);
SPACETIMEDB_TABLE(Config, config, Public);
FIELD_PrimaryKey(config, id);

Let’s break down this code. This defines a normal C++ struct with two fields: id and world_size. We use the SPACETIMEDB_STRUCT macro to register the struct for serialization, listing all field names. Then SPACETIMEDB_TABLE registers it as a table with the name config and Public visibility.

The SPACETIMEDB_TABLE macro takes three parameters: the struct type, the table name (which you’ll use to access the table in code), and a visibility modifier (Public or Private) which determines whether rows are synced to clients.

The FIELD_PrimaryKey macro specifies that the id field should be used as the primary key of the table.

NOTE: The primary key of a row defines the “identity” of the row. A change to a row which doesn’t modify the primary key is considered an update, but if you change the primary key, then you have deleted the old row and inserted a new one.

Learn more about defining tables, including indexes, constraints, and column types, in our Tables documentation.

Creating Entities

  • C#
  • Rust
  • C++

Next, we’re going to define a new SpacetimeType called DbVector2 which we’re going to use to store positions. The difference between a [SpacetimeDB.Type] and a [SpacetimeDB.Table] is that tables actually store data, whereas the deriving SpacetimeType just allows you to create a new column of that type in a SpacetimeDB table. Therefore, DbVector2 is only a type, and does not define a table.

Append to the bottom of Lib.cs:

// This allows us to store 2D points in tables.
[Type]
public partial struct DbVector2
{
    public float x;
    public float y;

    public DbVector2(float x, float y)
    {
        this.x = x;
        this.y = y;
    }
}

Let’s create a few tables to represent entities in our game by adding the following to the end of the Module class.

[Table(Accessor = "entity", Public = true)]
public partial struct Entity
{
    [PrimaryKey, AutoInc]
    public int entity_id;
    public DbVector2 position;
    public int mass;
}

[Table(Accessor = "circle", Public = true)]
public partial struct Circle
{
    [PrimaryKey]
    public int entity_id;
    [SpacetimeDB.Index.BTree]
    public int player_id;
    public DbVector2 direction;
    public float speed;
    public Timestamp last_split_time;
}

[Table(Accessor = "food", Public = true)]
public partial struct Food
{
    [PrimaryKey]
    public int entity_id;
}

Next, we’re going to define a new SpacetimeType called DbVector2 which we’re going to use to store positions. The difference between a #[derive(SpacetimeType)] and a #[spacetimedb(table)] is that tables actually store data, whereas the deriving SpacetimeType just allows you to create a new column of that type in a SpacetimeDB table. Therefore, DbVector2 is only a type, and does not define a table.

Append to the bottom of lib.rs:

// This allows us to store 2D points in tables.
#[derive(SpacetimeType, Clone, Debug)]
pub struct DbVector2 {
    pub x: f32,
    pub y: f32,
}

Let’s create a few tables to represent entities in our game.

#[spacetimedb::table(accessor = entity, public)]
#[derive(Debug, Clone)]
pub struct Entity {
    // The `auto_inc` attribute indicates to SpacetimeDB that
    // this value should be determined by SpacetimeDB on insert.
    #[auto_inc]
    #[primary_key]
    pub entity_id: i32,
    pub position: DbVector2,
    pub mass: i32,
}

#[spacetimedb::table(accessor = circle, public)]
pub struct Circle {
    #[primary_key]
    pub entity_id: i32,
    #[index(btree)]
    pub player_id: i32,
    pub direction: DbVector2,
    pub speed: f32,
    pub last_split_time: Timestamp,
}

#[spacetimedb::table(accessor = food, public)]
pub struct Food {
    #[primary_key]
    pub entity_id: i32,
}

Next, we’re going to define a new SpacetimeType called DbVector2 which we’re going to use to store positions. The difference between a regular struct registered with SPACETIMEDB_STRUCT and one registered with SPACETIMEDB_TABLE is that tables actually store data, whereas registering a struct alone just allows you to use it as a column type in a SpacetimeDB table. Therefore, DbVector2 is only a type, and does not define a table.

Append to the bottom of lib.cpp:

// This allows us to store 2D points in tables.
struct DbVector2 {
    float x;
    float y;
};
SPACETIMEDB_STRUCT(DbVector2, x, y);

Let’s create a few tables to represent entities in our game.

struct Entity {
    // The `FIELD_PrimaryKeyAutoInc` constraint indicates to SpacetimeDB that
    // this value should be determined by SpacetimeDB on insert.
    int32_t entity_id;
    DbVector2 position;
    int32_t mass;
};
SPACETIMEDB_STRUCT(Entity, entity_id, position, mass);
SPACETIMEDB_TABLE(Entity, entity, Public);
FIELD_PrimaryKeyAutoInc(entity, entity_id);

struct Circle {
    int32_t entity_id;
    int32_t player_id;
    DbVector2 direction;
    float speed;
    Timestamp last_split_time;
};
SPACETIMEDB_STRUCT(Circle, entity_id, player_id, direction, speed, last_split_time);
SPACETIMEDB_TABLE(Circle, circle, Public);
FIELD_PrimaryKey(circle, entity_id);
FIELD_Index(circle, player_id);

struct Food {
    int32_t entity_id;
};
SPACETIMEDB_STRUCT(Food, entity_id);
SPACETIMEDB_TABLE(Food, food, Public);
FIELD_PrimaryKey(food, entity_id);

The first table we defined is the entity table. An entity represents an object in our game world. We have decided, for convenience, that all entities in our game should share some common fields, namely position and mass.

We can create different types of entities with additional data by creating new tables with additional fields that have an entity_id which references a row in the entity table.

We’ve created two types of entities in our game world: Food and Circle. Food does not have any additional fields beyond the attributes in the entity table, so the food table simply represents the set of entity_ids that we want to recognize as food.

The Circle table, however, represents an entity that is controlled by a player. We’ve added a few additional fields to a Circle like player_id so that we know which player that circle belongs to.

Representing Players

Next, let’s create a table to store our player data.

  • C#
  • Rust
  • C++
[Table(Accessor = "player", Public = true)]
public partial struct Player
{
    [PrimaryKey]
    public Identity identity;
    [Unique, AutoInc]
    public int player_id;
    public string name;
}

There are a few new concepts we should touch on. First of all, we are using the [Unique] attribute on the player_id field. This attribute adds a constraint to the table that ensures that only one row in the player table has a particular player_id. We are also using the [AutoInc] attribute on the player_id field, which indicates “this field should get automatically assigned an auto-incremented value”.

#[spacetimedb::table(accessor = player, public)]
#[derive(Debug, Clone)]
pub struct Player {
    #[primary_key]
    identity: Identity,
    #[unique]
    #[auto_inc]
    player_id: i32,
    name: String,
}

There’s a few new concepts we should touch on. First of all, we are using the #[unique] attribute on the player_id field. This attribute adds a constraint to the table that ensures that only one row in the player table has a particular player_id.

struct Player {
    Identity identity;
    int32_t player_id;
    std::string name;
};
SPACETIMEDB_STRUCT(Player, identity, player_id, name);
SPACETIMEDB_TABLE(Player, player, Public);
FIELD_PrimaryKey(player, identity);
FIELD_UniqueAutoInc(player, player_id);

There’s a few new concepts we should touch on. First of all, we are using the FIELD_UniqueAutoInc macro on the player_id field. This macro combines two constraints: it ensures that only one row in the player table has a particular player_id, and it indicates that this field should get automatically assigned an auto-incremented value.

We also have an identity field which uses the Identity type. The Identity type is an identifier that SpacetimeDB uses to uniquely assign and authenticate SpacetimeDB users.

Writing a Reducer

Next, we write our very first reducer. A reducer is a module function which can be called by clients. Let’s write a simple debug reducer to see how they work.

  • C#
  • Rust
  • C++

Add this function to the Module class in Lib.cs:

[Reducer]
public static void Debug(ReducerContext ctx)
{
    Log.Info($"This reducer was called by {ctx.Sender}");
}
#[spacetimedb::reducer]
pub fn debug(ctx: &ReducerContext) -> Result<(), String> {
    log::debug!("This reducer was called by {}.", ctx.sender());
    Ok(())
}
SPACETIMEDB_REDUCER(debug, ReducerContext ctx) {
    LOG_INFO("This reducer was called by " + ctx.sender().to_string());
    return Ok();
}

This reducer doesn’t update any tables, it just prints out the Identity of the client that called it.

SpacetimeDB Reducers

“Reducer” is a term coined by Clockwork Labs that refers to a function which when executed “reduces” a set of inserts and deletes into the database state. The term derives from functional programming and is closely related to similarly named concepts in other frameworks like React Redux. Reducers can be called remotely using the CLI, client SDK or can be scheduled to be called at some future time from another reducer call.

All reducers execute transactionally and atomically, meaning that from within the reducer it will appear as though all changes are being applied to the database immediately, however from the outside changes made in a reducer will only be applied to the database once the reducer completes successfully. If you return an error from a reducer or panic within a reducer, all changes made to the database will be rolled back, as if the function had never been called. If you’re unfamiliar with atomic transactions, it may not be obvious yet just how useful and important this feature is, but once you build a somewhat complex application it will become clear just how invaluable this feature is.

Publishing the Module

Now that we have some basic functionality, let’s publish the module to SpacetimeDB and call our debug reducer.

In a new terminal window, run a local version of SpacetimeDB with the command:

spacetime start

This following log output indicates that SpacetimeDB is successfully running on your machine.

Starting SpacetimeDB listening on 127.0.0.1:3000

Now that SpacetimeDB is running we can publish our module to the SpacetimeDB host. In a separate terminal window, navigate to the blackholio-server/spacetimedb directory.

If you are not already logged in to the spacetime CLI, run the spacetime login command to log in to your SpacetimeDB website account. Once you are logged in, run spacetime publish --server local blackholio. This will publish our Blackholio server logic to SpacetimeDB.

If the publish completed successfully, you will see something like the following in the logs:

Build finished successfully.
Uploading to local => http://127.0.0.1:3000
Publishing module...
Created new database with name: blackholio, identity: c200d2c69b4524292b91822afac8ab016c15968ac993c28711f68c6bc40b89d5

If you sign into spacetime login via GitHub, the token you get will be issued by auth.spacetimedb.com. This will also ensure that you can recover your identity in case you lose it. On the other hand, if you do spacetime login --server-issued-login local, you will get an identity which is issued directly by your local server. Do note, however, that --server-issued-login tokens are not recoverable if lost, and are only recognized by the server that issued them.

  • C#
  • Rust
  • C++

Next, use the spacetime command to call our newly defined Debug reducer:

spacetime call --server local blackholio debug

Next, use the spacetime command to call our newly defined debug reducer:

spacetime call --server local blackholio debug

Next, use the spacetime command to call our newly defined debug reducer:

spacetime call --server local blackholio debug

If the call completed successfully, that command will have no output, but we can see the debug logs by running:

spacetime logs --server local blackholio

You should see something like the following output:

2025-01-09T16:08:38.144299Z  INFO: spacetimedb: Creating table `circle`
2025-01-09T16:08:38.144438Z  INFO: spacetimedb: Creating table `config`
2025-01-09T16:08:38.144451Z  INFO: spacetimedb: Creating table `entity`
2025-01-09T16:08:38.144470Z  INFO: spacetimedb: Creating table `food`
2025-01-09T16:08:38.144479Z  INFO: spacetimedb: Creating table `player`
2025-01-09T16:08:38.144841Z  INFO: spacetimedb: Database initialized
2025-01-09T16:08:47.306823Z  INFO: src/lib.rs:68: This reducer was called by c200e1a6494dbeeb0bbf49590b8778abf94fae4ea26faf9769c9a8d69a3ec348.

Connecting our Client

  • C#
  • Rust
  • C++

Next let’s connect our client to our database. Let’s start by modifying our Debug reducer. Rename the reducer to be called Connect and add ReducerKind.ClientConnected in parentheses after Reducer. The end result should look like this:

[Reducer(ReducerKind.ClientConnected)]
public static void Connect(ReducerContext ctx)
{
    Log.Info($"{ctx.Sender} just connected.");
}

The ReducerKind.ClientConnected argument to the SpacetimeDB.Reducer attribute indicates to SpacetimeDB that this is a special reducer. This reducer is only ever called by SpacetimeDB itself when a client connects to your database.

SpacetimeDB gives you the ability to define custom reducers that automatically trigger when certain events occur.

  • ReducerKind.Init - Called the first time you publish your module and anytime you clear the database with spacetime publish --server local \<name\> --delete-data.
  • ReducerKind.ClientConnected - Called when a user connects to the SpacetimeDB database. Their identity can be found in the Sender value of the ReducerContext.
  • ReducerKind.ClientDisconnected - Called when a user disconnects from the SpacetimeDB database.

Next let’s connect our client to our database. Let’s start by modifying our debug reducer. Rename the reducer to be called connect and add client_connected in parentheses after spacetimedb::reducer. The end result should look like this:

#[spacetimedb::reducer(client_connected)]
pub fn connect(ctx: &ReducerContext) -> Result<(), String> {
    log::debug!("{} just connected.", ctx.sender());
    Ok(())
}

The client_connected argument to the spacetimedb::reducer macro indicates to SpacetimeDB that this is a special reducer. This reducer is only ever called by SpacetimeDB itself when a client connects to your database.

SpacetimeDB gives you the ability to define custom reducers that automatically trigger when certain events occur.

  • init - Called the first time you publish your module and anytime you clear the database with spacetime publish --server local \<name\> --delete-data.
  • client_connected - Called when a user connects to the SpacetimeDB database. Their identity can be found in the sender value of the ReducerContext.
  • client_disconnected - Called when a user disconnects from the SpacetimeDB database.

Next let’s connect our client to our database. Let’s start by modifying our debug reducer. Rename the reducer to be called connect and change SPACETIMEDB_REDUCER to SPACETIMEDB_CLIENT_CONNECTED. The end result should look like this:

SPACETIMEDB_CLIENT_CONNECTED(connect, ReducerContext ctx) {
    LOG_INFO(ctx.sender().to_string() + " just connected.");
    return Ok();
}

The SPACETIMEDB_CLIENT_CONNECTED macro indicates to SpacetimeDB that this is a special reducer. This reducer is only ever called by SpacetimeDB itself when a client connects to your database.

SpacetimeDB gives you the ability to define custom reducers that automatically trigger when certain events occur.

  • SPACETIMEDB_INIT - Called the first time you publish your module and anytime you clear the database with spacetime publish --server local \<name\> --delete-data.
  • SPACETIMEDB_CLIENT_CONNECTED - Called when a user connects to the SpacetimeDB database. Their identity can be found in the sender value of the ReducerContext.
  • SPACETIMEDB_CLIENT_DISCONNECTED - Called when a user disconnects from the SpacetimeDB database.

Publish your module again by running:

spacetime publish --server local blackholio

Generating the Client

The spacetime CLI has built in functionality to let us generate C# types that correspond to our tables, types, and reducers that we can use from our Godot client.

Let’s generate our types for our module. In the blackholio-server/spacetimedb directory run the following command:

spacetime generate --lang csharp --out-dir ../../module_bindings

This will generate a set of files in the module_bindings directory (inside your Godot blackholio project directory) which contain the code generated types and reducer functions that are defined in your module, but usable on the client.

├── Reducers
├── Tables
│   ├── Circle.g.cs
│   ├── Config.g.cs
│   ├── Entity.g.cs
│   ├── Food.g.cs
│   └── Player.g.cs
├── Types
│   ├── Circle.g.cs
│   ├── Config.g.cs
│   ├── DbVector2.g.cs
│   ├── Entity.g.cs
│   ├── Food.g.cs
│   └── Player.g.cs
└── SpacetimeDBClient.g.cs

This will also generate a file module_bindings/SpacetimeDBClient.g.cs with a type aware DbConnection class. We will use this class to connect to your database from Godot.

Connecting to the Database

At this point we can connect your Godot client to the server. Replace your imports at the top of the GameManager.cs file with:

using System;
using System.Collections.Generic;
using SpacetimeDB;
using SpacetimeDB.Types;
using Godot;

Replace the implementation of the GameManager class with the following.

public partial class GameManager : Node
{
    public static event Action OnConnected;
    public static event Action OnSubscriptionApplied;
    
    [Export]    
    private string ServerUrl { get; set; } = "http://127.0.0.1:3000";
    
    [Export]
    private string DatabaseName { get; set; } = "blackholio";

    [Export]
    private Color BackgroundColor { get; set; } = Colors.MidnightBlue;

    [Export]
    private float BorderThickness { get; set; } = 5.0f;

    [Export]
    private Color BorderColor { get; set; } = Colors.Goldenrod;

    [Export]
    private string DefaultPlayerName { get; set; } = "3Blave";

    private static GameManager Instance { get; set; }
    public static Identity LocalIdentity { get; private set; }
    public static DbConnection Conn { get; private set; }

    public GameManager()
    {
        var builder = DbConnection.Builder()
            .OnConnect(HandleConnect)
            .OnConnectError(HandleConnectError)
            .OnDisconnect(HandleDisconnect)
            .WithUri(ServerUrl)
            .WithDatabaseName(DatabaseName);

        if (AuthToken.TryGetToken(out var authToken))
        {
            builder = builder.WithToken(authToken);
        }

        Conn = builder.Build();
        STDBUpdateManager.Add(Conn);
    }

    public override void _EnterTree()
    {
        Instance = this;
    }

    public override void _ExitTree()
    {
        Disconnect();

        if (Instance == this)
        {
            Instance = null;
        }
    }

    public static bool IsConnected() => Conn != null && Conn.IsActive;

    private void Disconnect()
    {
        STDBUpdateManager.Remove(Conn, true);
        Conn = null;
    }

    // Called when we connect to SpacetimeDB and receive our client identity
    private void HandleConnect(DbConnection conn, Identity identity, string token)
    {
        GD.Print("Connected.");
        AuthToken.SaveToken(token);
        LocalIdentity = identity;

        OnConnected?.Invoke();

        // Request all tables
        Conn.SubscriptionBuilder()
            .OnApplied(HandleSubscriptionApplied)
            .SubscribeToAllTables();
    }

    private void HandleConnectError(Exception ex)
    {
        GD.PrintErr($"Connection error: {ex}");
    }

    private void HandleDisconnect(DbConnection _conn, Exception ex)
    {
        GD.Print("Disconnected.");
        if (ex != null)
        {
            GD.PrintErr(ex);
        }
    }

    private void HandleSubscriptionApplied(SubscriptionEventContext ctx)
    {
        GD.Print("Subscription applied!");
        OnSubscriptionApplied?.Invoke();
    }
}

Here we configure the connection to the database, by passing it some callbacks in addition to providing the ServerUrl and DatabaseName to the connection. We add the connection to STDBUpdateManager, a simple script that hooks into Godot’s update loop in order to drive the sending and processing of messages between your client and SpacetimeDB.

When the client connects, the SpacetimeDB SDK will call the HandleConnect method, allowing us to start up the game.

In our HandleConnect callback we build a subscription and call Subscribe, subscribing to all data in the database. This causes SpacetimeDB to synchronize the state of all your tables with your Godot client’s SDK client cache.

SDK Client Cache

The “SDK client cache” is a client-side view of the database defined by the supplied queries to the Subscribe function. SpacetimeDB ensures that the results of subscription queries are automatically updated and pushed to the client cache as they change which allows efficient access without unnecessary server queries.

There’s only one thing left to do before being able to connect the client and server. Because our SpacetimeDB C# project lives nested in our Godot’s project directory, we need to force exclude blackholio-server from Godot’s C# .csproj. Open Blackholio.csproj with any text editor and add the following line at the end of the <PropertyGroup>:

<DefaultItemExcludes>$(DefaultItemExcludes);blackholio-server/**</DefaultItemExcludes>

Your Blackholio.csproj should look similar to this one:

<Project Sdk="Godot.NET.Sdk/4.6.2">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <TargetFramework Condition=" '$(GodotTargetPlatform)' == 'android' ">net9.0</TargetFramework>
    <EnableDynamicLoading>true</EnableDynamicLoading>
    <DefaultItemExcludes>$(DefaultItemExcludes);blackholio-server/**</DefaultItemExcludes>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="SpacetimeDB.ClientSDK" Version="2.1.0" />
  </ItemGroup>
</Project>

Now we’re ready. Press the play button in Godot.

If all went well you should see the below output in your Godot logs.

SpacetimeDBClient: Connecting to ws://127.0.0.1:3000 blackholio
Connected.
Subscription applied!

Subscription applied indicates that the SpacetimeDB SDK has evaluated your subscription queries and synchronized your local cache with your database’s tables.

We can also see that the server has logged the connection as well.

spacetime logs --server local blackholio
...
2025-01-10T03:51:02.078700Z DEBUG: src/lib.rs:63: c200fb5be9524bfb8289c351516a1d9ea800f70a17a9a6937f11c0ed3854087d just connected.

Next Steps

You’ve learned how to setup a Godot project with the SpacetimeDB SDK, write a basic SpacetimeDB server module, and how to connect your Godot client to SpacetimeDB. That’s pretty much all there is to the setup. You’re now ready to start building the game.

In the next part, we’ll build out the functionality of the game and you’ll learn how to access your table data and call reducers in Godot.

Last updated Oct 08, 2026