Spacetimedb Rust

CORRECT PATTERNS:

use spacetimedb::{table, reducer, Table, ReducerContext, Identity, Timestamp};
use spacetimedb::SpacetimeType;  // Only for custom types, NOT tables

// CORRECT TABLE — accessor, not name; no SpacetimeType derive!
#[table(accessor = player, public)]
pub struct Player {
    #[primary_key]
    pub id: u64,
    pub name: String,
}

// CORRECT REDUCER — immutable context, sender() is a method
#[reducer]
pub fn create_player(ctx: &ReducerContext, name: String) {
    ctx.db.player().insert(Player { id: 0, name });
}

// CORRECT TABLE ACCESS — methods with parentheses, sender() method
let player = ctx.db.player().id().find(&player_id);
let caller = ctx.sender();

DO NOT:

• Derive SpacetimeType on #[table] structs — the macro handles this
• Use mutable context — &ReducerContext, not &mut ReducerContext
• Forget Table trait import — required for table operations
• Use field access for tables — ctx.db.player() not ctx.db.player
• Use ctx.sender — it's ctx.sender() (method) in 2.0

Common Mistakes Table

Hard Requirements

1. DO NOT derive SpacetimeType on #[table] structs — the macro handles this
2. Import Table trait — required for all table operations
3. Use &ReducerContext — not &mut ReducerContext
4. Tables are methods — ctx.db.table() not ctx.db.table
5. Use ctx.sender() — method call, not field access (2.0)
6. Use accessor = for API handles — name = "..." is optional canonical naming in table/index attributes
7. Reducers must be deterministic — no filesystem, network, timers, or external RNG
8. Use ctx.rng() — not rand crate for random numbers
9. Add public flag — if clients need to subscribe to a table
10. Update only via primary key — use delete+insert for non-PK changes (2.0)

Project Setup

[package]
name = "my-module"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
spacetimedb = { workspace = true }
log = "0.4"

Essential Imports

use spacetimedb::{ReducerContext, Table};
use spacetimedb::{Identity, Timestamp, ConnectionId, ScheduleAt};

Table Definitions

#[spacetimedb::table(accessor = player, public)]
pub struct Player {
    #[primary_key]
    #[auto_inc]
    id: u64,
    name: String,
    score: u32,
}

Table Attributes

Column Attributes

Supported Column Types

Primitives: u8-u256, i8-i256, f32, f64, bool, String

SpacetimeDB Types: Identity, ConnectionId, Timestamp, Uuid, ScheduleAt

Collections: Vec<T>, Option<T>, Result<T, E>

Custom Types: Any struct/enum with #[derive(SpacetimeType)]

Reducers

#[spacetimedb::reducer]
pub fn create_player(ctx: &ReducerContext, name: String) -> Result<(), String> {
    if name.is_empty() {
        return Err("Name cannot be empty".to_string());
    }
    ctx.db.player().insert(Player { id: 0, name, score: 0 });
    Ok(())
}

Reducer Rules

1. First parameter must be &ReducerContext
2. Return (), Result<(), String>, or Result<(), E> where E: Display
3. All changes roll back on panic or Err return
4. Must import Table trait: use spacetimedb::Table;

ReducerContext

ctx.db              // Database access
ctx.sender()        // Identity of the caller (method, not field!)
ctx.connection_id() // Option<ConnectionId> (None for scheduled/system reducers)
ctx.timestamp       // Invocation timestamp
ctx.identity()      // Module's own identity
ctx.rng()            // Deterministic RNG (method, not field!)

Table Operations

Insert

// Insert returns the row with auto_inc values populated
let player = ctx.db.player().insert(Player { id: 0, name: "Alice".into(), score: 100 });