From 63f185720bf62b4e1003011251f197d454805ee7 Mon Sep 17 00:00:00 2001 From: rain Date: Fri, 19 Jun 2026 08:10:44 -0400 Subject: [PATCH 01/11] docs: fix TypeScript connection builder examples --- .../00600-clients/00300-connection.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/docs/00200-core-concepts/00600-clients/00300-connection.md b/docs/docs/00200-core-concepts/00600-clients/00300-connection.md index 8882aa3c80d..f1ad4c73d42 100644 --- a/docs/docs/00200-core-concepts/00600-clients/00300-connection.md +++ b/docs/docs/00200-core-concepts/00600-clients/00300-connection.md @@ -26,9 +26,10 @@ Create a connection using the `DbConnection` builder pattern: ```typescript import { DbConnection } from './module_bindings'; -const conn = new DbConnection.builder() +const conn = DbConnection.builder() .withUri("https://maincloud.spacetimedb.com") - .withDatabaseName("my_database"); + .withDatabaseName("my_database") + .build(); ``` @@ -80,9 +81,10 @@ To connect to a database hosted on MainCloud: ```typescript -const conn = new DbConnection.builder() +const conn = DbConnection.builder() .withUri("https://maincloud.spacetimedb.com") - .withDatabaseName("my_database"); + .withDatabaseName("my_database") + .build(); ``` @@ -126,10 +128,11 @@ To authenticate with a token (for example, from [SpacetimeAuth](../00500-authent ```typescript -const conn = new DbConnection.builder() +const conn = DbConnection.builder() .withUri("https://maincloud.spacetimedb.com") .withDatabaseName("my_database") - .withToken("your_auth_token_here"); + .withToken("your_auth_token_here") + .build(); ``` From e179d7445560b9ae39cb24242746d0ec9c101845 Mon Sep 17 00:00:00 2001 From: rain Date: Sun, 14 Jun 2026 08:11:24 -0400 Subject: [PATCH 02/11] docs: document reducer context random APIs --- .../00300-reducers/00400-reducer-context.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/docs/00200-core-concepts/00200-functions/00300-reducers/00400-reducer-context.md b/docs/docs/00200-core-concepts/00200-functions/00300-reducers/00400-reducer-context.md index a4d743813d1..06e30fb7b2a 100644 --- a/docs/docs/00200-core-concepts/00200-functions/00300-reducers/00400-reducer-context.md +++ b/docs/docs/00200-core-concepts/00200-functions/00300-reducers/00400-reducer-context.md @@ -272,6 +272,46 @@ The context provides access to a random number generator that is deterministic a Never use external random number generators (like `Random` in C# without using the context). These are non-deterministic and will cause different nodes to produce different results, breaking consensus. ::: +Use the context-provided random API for any reducer logic that needs random values: + + + + +```typescript +const fraction = ctx.random(); // [0.0, 1.0) +const roll = ctx.random.integerInRange(1, 6); // inclusive +const bytes = ctx.random.fill(new Uint8Array(16)); +``` + + + + +```csharp +double fraction = ctx.Rng.NextDouble(); // [0.0, 1.0) +int roll = ctx.Rng.Next(1, 7); // [1, 7) +``` + + + + +```rust +use spacetimedb::rand::Rng; + +let value: u32 = ctx.random(); +let roll: u32 = ctx.rng().gen_range(1..=6); +``` + + + + +```cpp +auto& rng = ctx.rng(); +int32_t roll = rng.gen_range(1, 6); // inclusive +``` + + + + ## Module Identity The context provides access to the module's own identity, which is useful when a reducer needs to refer to the database itself. From 219e88e724963360029ae735041ac12417feea35 Mon Sep 17 00:00:00 2001 From: rain Date: Thu, 18 Jun 2026 08:36:05 -0400 Subject: [PATCH 03/11] docs: align reducer skill determinism guidance --- skills/concepts/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/concepts/SKILL.md b/skills/concepts/SKILL.md index 402a1a8ff18..9c4195fc1bd 100644 --- a/skills/concepts/SKILL.md +++ b/skills/concepts/SKILL.md @@ -20,7 +20,7 @@ SpacetimeDB is a relational database that is also a server. It lets you upload a ## Critical Rules 1. **Reducers are transactional.** They do not return data to callers. Use subscriptions to read data. -2. **Reducers must be deterministic.** No filesystem, network, timers, or random. All state must come from tables. +2. **Reducers must be deterministic.** Do not use filesystem, network, external clocks, or external random sources in reducers. Use `ReducerContext` for SpacetimeDB-provided timestamp and deterministic random values. 3. **Read data via tables/subscriptions**, not reducer return values. Clients get data through subscribed queries. 4. **Auto-increment IDs are not sequential.** Gaps are normal, do not use for ordering. Use timestamps or explicit sequence columns. 5. **`ctx.sender` is the authenticated principal.** Never trust identity passed as arguments. From 505d364fe2247bc7e744afd1befed66a3ac81735 Mon Sep 17 00:00:00 2001 From: rain Date: Sat, 20 Jun 2026 08:15:28 -0400 Subject: [PATCH 04/11] docs: fix TypeScript reducer argument examples --- docs/docs/00200-core-concepts/00600-clients/00200-codegen.md | 4 ++-- .../00600-clients/00700-typescript-reference.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/00200-core-concepts/00600-clients/00200-codegen.md b/docs/docs/00200-core-concepts/00600-clients/00200-codegen.md index f648e17a578..3575377a20a 100644 --- a/docs/docs/00200-core-concepts/00600-clients/00200-codegen.md +++ b/docs/docs/00200-core-concepts/00600-clients/00200-codegen.md @@ -189,10 +189,10 @@ For example, a `create_user` reducer becomes: ```typescript // Call the reducer -conn.reducers.createUser(name, email); +conn.reducers.createUser({ name, email }); // Register a callback to observe reducer invocations -conn.reducers.onCreateUser((ctx, name, email) => { +conn.reducers.onCreateUser((ctx, { name, email }) => { console.log(`User created: ${name}`); }); ``` diff --git a/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md b/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md index 759a0f85f10..66abdda2021 100644 --- a/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md +++ b/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md @@ -1088,7 +1088,7 @@ function MyComponent() { return (

Connected as: {identity?.toHexString()}

-
@@ -1136,7 +1136,7 @@ import { useReducer } from 'spacetimedb/react'; import { reducers } from './module_bindings'; const createPlayer = useReducer(reducers.createPlayer); -createPlayer('Alice'); +createPlayer({ name: 'Alice' }); ``` `useReducer` returns a function that calls the generated reducer. Calls made before the connection is ready are queued and flushed once the connection is established. From 473d1364c1c866a62e1c10f167ce39a18c4be630 Mon Sep 17 00:00:00 2001 From: rain Date: Sun, 21 Jun 2026 08:10:10 -0400 Subject: [PATCH 05/11] docs: fix init reducer tutorial wording --- .../00300-tutorials/00300-unity-tutorial/00400-part-3.md | 4 ++-- .../00300-tutorials/00400-unreal-tutorial/00400-part-3.md | 2 +- .../00300-tutorials/00500-godot-tutorial/00400-part-3.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/00100-intro/00300-tutorials/00300-unity-tutorial/00400-part-3.md b/docs/docs/00100-intro/00300-tutorials/00300-unity-tutorial/00400-part-3.md index ee1161f4774..fc5b6ae572c 100644 --- a/docs/docs/00100-intro/00300-tutorials/00300-unity-tutorial/00400-part-3.md +++ b/docs/docs/00100-intro/00300-tutorials/00300-unity-tutorial/00400-part-3.md @@ -85,7 +85,7 @@ We also added two helper functions so we can get a random range as either a `int -Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `init` reducer. SpacetimeDB calls the `init` reducer automatically when first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportGodot to initialize the state of your database before any clients connect. +Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `init` reducer. SpacetimeDB calls the `init` reducer automatically when you first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportunity to initialize the state of your database before any clients connect. Add this new reducer above our `connect` reducer. @@ -161,7 +161,7 @@ In this reducer, we are using the `world_size` we configured along with the `Red -Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `SPACETIMEDB_INIT` reducer. SpacetimeDB calls the `SPACETIMEDB_INIT` reducer automatically when you first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportGodot to initialize the state of your database before any clients connect. +Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `SPACETIMEDB_INIT` reducer. SpacetimeDB calls the `SPACETIMEDB_INIT` reducer automatically when you first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportunity to initialize the state of your database before any clients connect. Add this new reducer above our `connect` reducer. diff --git a/docs/docs/00100-intro/00300-tutorials/00400-unreal-tutorial/00400-part-3.md b/docs/docs/00100-intro/00300-tutorials/00400-unreal-tutorial/00400-part-3.md index c0c1d3202e3..1b388814d96 100644 --- a/docs/docs/00100-intro/00300-tutorials/00400-unreal-tutorial/00400-part-3.md +++ b/docs/docs/00100-intro/00300-tutorials/00400-unreal-tutorial/00400-part-3.md @@ -85,7 +85,7 @@ We also added two helper functions so we can get a random range as either a `int -Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `init` reducer. SpacetimeDB calls the `init` reducer automatically when first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportunity to initialize the state of your database before any clients connect. +Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `init` reducer. SpacetimeDB calls the `init` reducer automatically when you first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportunity to initialize the state of your database before any clients connect. Add this new reducer above our `connect` reducer. diff --git a/docs/docs/00100-intro/00300-tutorials/00500-godot-tutorial/00400-part-3.md b/docs/docs/00100-intro/00300-tutorials/00500-godot-tutorial/00400-part-3.md index 1ba2cc87936..0a4586a5216 100644 --- a/docs/docs/00100-intro/00300-tutorials/00500-godot-tutorial/00400-part-3.md +++ b/docs/docs/00100-intro/00300-tutorials/00500-godot-tutorial/00400-part-3.md @@ -85,7 +85,7 @@ We also added two helper functions so we can get a random range as either a `int -Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `init` reducer. SpacetimeDB calls the `init` reducer automatically when first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportGodot to initialize the state of your database before any clients connect. +Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `init` reducer. SpacetimeDB calls the `init` reducer automatically when you first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportunity to initialize the state of your database before any clients connect. Add this new reducer above our `connect` reducer. @@ -161,7 +161,7 @@ In this reducer, we are using the `world_size` we configured along with the `Red -Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `SPACETIMEDB_INIT` reducer. SpacetimeDB calls the `SPACETIMEDB_INIT` reducer automatically when you first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportGodot to initialize the state of your database before any clients connect. +Let's start by spawning food into the map. The first thing we need to do is create a new, special reducer called the `SPACETIMEDB_INIT` reducer. SpacetimeDB calls the `SPACETIMEDB_INIT` reducer automatically when you first publish your module, and also after any time you run with `publish --delete-data`. It gives you an opportunity to initialize the state of your database before any clients connect. Add this new reducer above our `connect` reducer. From 8adb5fbd9951a944c721d4079ebdaef7aa17bc4b Mon Sep 17 00:00:00 2001 From: rain Date: Mon, 22 Jun 2026 08:13:11 -0400 Subject: [PATCH 06/11] docs: fix React useSpacetimeDB reference --- .../00600-clients/00700-typescript-reference.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md b/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md index 66abdda2021..f3f84524d97 100644 --- a/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md +++ b/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md @@ -1197,10 +1197,11 @@ function Root() { #### `useSpacetimeDB()` -Returns the current `DbConnection` from the provider context: +Returns the current connection state and a `getConnection()` function for accessing the provider-managed `DbConnection`: ```tsx -const conn = useSpacetimeDB(); +const { isActive, identity, token, getConnection } = useSpacetimeDB(); +const conn = getConnection(); ``` #### `useTable(query, callbacks?)` From b6b329acd2b5b504c64195bf272736846199d563 Mon Sep 17 00:00:00 2001 From: rain Date: Tue, 23 Jun 2026 08:11:15 -0400 Subject: [PATCH 07/11] docs: fix CLI reset and TypeScript codegen examples --- .../00100-databases/00300-spacetime-publish.md | 2 +- .../00200-core-concepts/00100-databases/00500-cheat-sheet.md | 4 ++-- .../00100-databases/00300-spacetime-publish.md | 2 +- .../00200-core-concepts/00100-databases/00500-cheat-sheet.md | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs/00200-core-concepts/00100-databases/00300-spacetime-publish.md b/docs/docs/00200-core-concepts/00100-databases/00300-spacetime-publish.md index 82d079fa75e..21d271fb8eb 100644 --- a/docs/docs/00200-core-concepts/00100-databases/00300-spacetime-publish.md +++ b/docs/docs/00200-core-concepts/00100-databases/00300-spacetime-publish.md @@ -95,7 +95,7 @@ If this publish is a major upgrade from 1.x to 2.0, read [1.x to 2.0 Upgrade Not To completely reset your database and delete all data: ```bash -spacetime publish --delete-data +spacetime publish --delete-data always ``` ⚠️ **Warning:** This permanently deletes all data in your database! diff --git a/docs/docs/00200-core-concepts/00100-databases/00500-cheat-sheet.md b/docs/docs/00200-core-concepts/00100-databases/00500-cheat-sheet.md index 6c959fbc929..e762baab919 100644 --- a/docs/docs/00200-core-concepts/00100-databases/00500-cheat-sheet.md +++ b/docs/docs/00200-core-concepts/00100-databases/00500-cheat-sheet.md @@ -913,7 +913,7 @@ spacetime login # Authenticate # Module management spacetime build # Build module spacetime publish # Publish module -spacetime publish --delete-data # Reset database +spacetime publish --delete-data always # Reset database spacetime delete # Delete database # Database operations @@ -926,7 +926,7 @@ spacetime call reducer arg1 arg2 # Call reducer # Code generation spacetime generate --lang rust # Generate Rust client spacetime generate --lang csharp # Generate C# client -spacetime generate --lang ts # Generate TypeScript client +spacetime generate --lang typescript # Generate TypeScript client ``` ## Common Types diff --git a/docs/versioned_docs/version-1.12.0/00200-core-concepts/00100-databases/00300-spacetime-publish.md b/docs/versioned_docs/version-1.12.0/00200-core-concepts/00100-databases/00300-spacetime-publish.md index fe4bc03f162..ca7d6450cca 100644 --- a/docs/versioned_docs/version-1.12.0/00200-core-concepts/00100-databases/00300-spacetime-publish.md +++ b/docs/versioned_docs/version-1.12.0/00200-core-concepts/00100-databases/00300-spacetime-publish.md @@ -93,7 +93,7 @@ spacetime publish --break-clients To completely reset your database and delete all data: ```bash -spacetime publish --delete-data +spacetime publish --delete-data always ``` ⚠️ **Warning:** This permanently deletes all data in your database! diff --git a/docs/versioned_docs/version-1.12.0/00200-core-concepts/00100-databases/00500-cheat-sheet.md b/docs/versioned_docs/version-1.12.0/00200-core-concepts/00100-databases/00500-cheat-sheet.md index 529e79d6ec4..2da3af5235d 100644 --- a/docs/versioned_docs/version-1.12.0/00200-core-concepts/00100-databases/00500-cheat-sheet.md +++ b/docs/versioned_docs/version-1.12.0/00200-core-concepts/00100-databases/00500-cheat-sheet.md @@ -578,7 +578,7 @@ spacetime login # Authenticate # Module management spacetime build # Build module spacetime publish # Publish module -spacetime publish --delete-data # Reset database +spacetime publish --delete-data always # Reset database spacetime delete # Delete database # Database operations @@ -591,7 +591,7 @@ spacetime call reducer arg1 arg2 # Call reducer # Code generation spacetime generate --lang rust # Generate Rust client spacetime generate --lang csharp # Generate C# client -spacetime generate --lang ts # Generate TypeScript client +spacetime generate --lang typescript # Generate TypeScript client ``` ## Common Types From ed140dee3407a1647b30afca1db3aad3889a4062 Mon Sep 17 00:00:00 2001 From: rain Date: Wed, 24 Jun 2026 08:10:31 -0400 Subject: [PATCH 08/11] docs: fix TypeScript codegen table accessor example --- docs/docs/00200-core-concepts/00600-clients/00200-codegen.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/00200-core-concepts/00600-clients/00200-codegen.md b/docs/docs/00200-core-concepts/00600-clients/00200-codegen.md index 3575377a20a..4da763eba32 100644 --- a/docs/docs/00200-core-concepts/00600-clients/00200-codegen.md +++ b/docs/docs/00200-core-concepts/00600-clients/00200-codegen.md @@ -104,14 +104,14 @@ For example, a `user` table becomes: ```typescript // Generated type -export default __t.object("User", { +export default __t.row({ id: __t.u64(), name: __t.string(), email: __t.string(), }); // Access via DbConnection -conn.db.User +conn.db.user ``` From 408d421046ea586355ff6abc3c39ff6042485c0a Mon Sep 17 00:00:00 2001 From: rain Date: Thu, 25 Jun 2026 08:10:05 -0400 Subject: [PATCH 09/11] docs: fix Unreal FAQ links --- docs/docs/00100-intro/00100-getting-started/00500-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/00100-intro/00100-getting-started/00500-faq.md b/docs/docs/00100-intro/00100-getting-started/00500-faq.md index 9bc23e30bab..abbbc177437 100644 --- a/docs/docs/00100-intro/00100-getting-started/00500-faq.md +++ b/docs/docs/00100-intro/00100-getting-started/00500-faq.md @@ -170,7 +170,7 @@ Yes. SpacetimeDB has a C# client SDK that works with Unity. The SDK maintains a ### Can I use SpacetimeDB with Unreal Engine? -Yes. SpacetimeDB has a C++ client SDK for Unreal Engine with Blueprint support. See the [Unreal quickstart](../00200-quickstarts/00700-cpp.md) for details. +Yes. SpacetimeDB has a C++ client SDK for Unreal Engine with Blueprint support. See the [Unreal tutorial](../00300-tutorials/00400-unreal-tutorial/index.md) and [Unreal SDK reference](../../00200-core-concepts/00600-clients/00800-unreal-reference.md) for details. ### Can I use SpacetimeDB with React / Vue / Angular / Svelte? From 2724c9aea5619aad5f0840b393dba1e4239761a1 Mon Sep 17 00:00:00 2001 From: rain Date: Fri, 26 Jun 2026 08:10:31 -0400 Subject: [PATCH 10/11] docs: fix TypeScript shared table example --- docs/docs/00200-core-concepts/00300-tables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/00200-core-concepts/00300-tables.md b/docs/docs/00200-core-concepts/00300-tables.md index dd8ec6c6b0e..a0b0bb43d95 100644 --- a/docs/docs/00200-core-concepts/00300-tables.md +++ b/docs/docs/00200-core-concepts/00300-tables.md @@ -409,8 +409,8 @@ const playerColumns = { }; // Create two tables with the same schema -const Player = table({ name: 'Player', public: true }, playerColumns); -const LoggedOutPlayer = table({ name: 'LoggedOutPlayer' }, playerColumns); +const player = table({ name: 'player', public: true }, playerColumns); +const loggedOutPlayer = table({ name: 'logged_out_player' }, playerColumns); ``` From b2e12abcf96dd69fba7de880792ac6909194c120 Mon Sep 17 00:00:00 2001 From: rain Date: Sat, 27 Jun 2026 08:09:40 -0400 Subject: [PATCH 11/11] docs: fix Solid reducer call example --- .../00600-clients/00700-typescript-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md b/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md index f3f84524d97..d1252bed5e5 100644 --- a/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md +++ b/docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md @@ -1274,7 +1274,7 @@ const [users, isReady] = useTable( const sendMessage = useReducer(reducers.sendMessage); Loading users...}> - + {user =>
{user.name}
}