Add some developer docs #349

kazimuth · 2025-07-15T20:42:13Z

Description of Changes

Add some developer docs.

API

This is an API breaking change to the SDK

Requires SpacetimeDB PRs

Testsuite

SpacetimeDB branch name: master

Testing

N/A

Some API updates

More API updates

…w updates and reducer events

API callback improvements

Add sslEnabled option to Connect function

* Fix compilation issue with master * Initial push for SATS (still WIP) * Small build fix * Small update * Updates from meeting with Tyler * Fixed issues with LayoutExplicit and added some missing functions * AlgebraicValue cleanup * Copied changes from BitCraftMini * Removed TypeDef --------- Co-authored-by: Clockwork Labs <[email protected]> Co-authored-by: Tyler Cloutier <[email protected]> Co-authored-by: John Detter <[email protected]>

* Upload script to help deploying to our partners * You have to specify hosts individually * Small fix * Another small fix - tested + working --------- Co-authored-by: John Detter <[email protected]>

* Serialize byte arrays as hex * Fix namespace * Small fix --------- Co-authored-by: John Detter <[email protected]>

* First pass * Committing meta file * Removed option type - unneeded * Implementing new some converter * Some converter updates * Tons of fixes here * Cleaned up the some/enum serialization implementation --------- Co-authored-by: John Detter <[email protected]>

Co-authored-by: John <[email protected]>

Co-authored-by: John Detter <[email protected]>

* Several updates to the way ClientCache + processing updates works * Client cache changes working * Removed log statements --------- Co-authored-by: John Detter <[email protected]>

* Copied changes from BitCraft * Applied state diff changes * State diffs complete * Compilation fix * Fix build issues --------- Co-authored-by: John Detter <[email protected]>

* Pulled SpacetimeUnitySDK from the BitCraft project * Removed unused logs * Removed primary key functionality * Fix compilation issues with older version of C# * Primary key client implementation * Another row update fix --------- Co-authored-by: John <[email protected]>

* Pulled SpacetimeUnitySDK from the BitCraft project * Removed unused logs * Removed primary key functionality * Fix compilation issues with older version of C# --------- Co-authored-by: John <[email protected]>

* Adding event parameter to table callbacks * Reverted a namespace change --------- Co-authored-by: Steve <[email protected]> Co-authored-by: John Detter <[email protected]>

Co-authored-by: Derek Brinkmann <[email protected]>

* Add onSubscriptionUpdate callback * Remove unnecesary onTransactionComplete --------- Co-authored-by: Derek Brinkmann <[email protected]>

…ed from callbacks (#20) Co-authored-by: Steve <[email protected]>

* Deserializing reducer args before table updates so they can be accessed from callbacks * Reducer arguments in table events * Removed redundant onSubscriptionUpdate --------- Co-authored-by: Steve <[email protected]> Co-authored-by: John Detter <[email protected]> Co-authored-by: John Detter <[email protected]>

Co-authored-by: Steve <[email protected]>

Co-authored-by: John Detter <[email protected]>

* Deserializing reducer args before table updates so they can be accessed from callbacks * Reducer arguments in table events * Adding OnBeforeDelete event to tables * Renaming ReducerCallInfo to ReducerEvent * Removed extra onSubscriptionUpdate --------- Co-authored-by: Steve <[email protected]> Co-authored-by: John Detter <[email protected]>

* Deserializing reducer args before table updates so they can be accessed from callbacks * Reducer arguments in table events * Adding OnBeforeDelete event to tables --------- Co-authored-by: Steve <[email protected]> Co-authored-by: John Detter <[email protected]>

## Description of Changes Update DLLs to the 1.1.2 versions that have been pushed to NuGet. The SpacetimeDB tag that they were built from is `v1.1.2-csharp-release`. ## API - [ ] This is an API breaking change to the SDK *If the API is breaking, please state below what will break* ## Requires SpacetimeDB PRs None, because we're updating the DLLs to essentially include SpacetimeDB PRs. ## Testsuite SpacetimeDB branch name: master ## Testing CI I guess? Co-authored-by: Zeke Foppa <[email protected]>

## Description of Changes Bump versions to 1.2.0, as well as update the DLLs from SpacetimeDB (commit `fc8f7dcc8`). They don't have any changes, but the versions needed bumping. ## API This itself is not a breaking changes. ## Requires SpacetimeDB PRs clockworklabs/SpacetimeDB#2837 ## Testsuite SpacetimeDB branch name: release/v1.2.0 ## Testing CI only --------- Co-authored-by: Zeke Foppa <[email protected]>

## Description of Changes *Describe what has been changed, any new features or bug fixes* ## API - [ ] This is an API breaking change to the SDK *If the API is breaking, please state below what will break* ## Requires SpacetimeDB PRs *List any PRs here that are required for this SDK change to work* ## Testsuite *If you would like to run the your SDK changes in this PR against a specific SpacetimeDB branch, specify that here. This can be a branch name or a link to a PR.* SpacetimeDB branch name: master ## Testing *Write instructions for a test that you performed for this PR* - [ ] Describe a test for this PR that you have completed --------- Co-authored-by: Alessandro Asoni <[email protected]> Co-authored-by: James Gilles <[email protected]>

## Description of Changes `NetworkRequestTracker` previously was keeping all historical reducer request data, and searching through this every frame to get statistics. I've modified it to throw out much more data -- it's much faster now, but only updates every few seconds. ## API Not an API break, but deprecates an argument of one of NetworkRequestTracker's methods to no longer do anything. Adds new APIs. ## Requires SpacetimeDB PRs N/A ## Testsuite SpacetimeDB branch name: master ## Testing - [x] Tested Bitcraft. **Their F9 debug menu will require an update, since we now only keep one time window of request data, rather than being able to give information about multiple windows.** But it works. - [x] Blackholio CI

## Description of Changes Addresses clockworklabs/SpacetimeDBPrivate#1786 and #329. Marks messages as parsed from the background parsing thread, and then marks them as applied using a separate tracker once they are applied. ## API - [ ] This is an API breaking change to the SDK *If the API is breaking, please state below what will break* ## Requires SpacetimeDB PRs ## Testsuite SpacetimeDB branch name: master ## Testing - [x] Testing against Bitcraft

## Description of Changes Updates the DLLs for clockworklabs/SpacetimeDB#2762, and bumps our version numbers as well. ## API - [ ] This is an API breaking change to the SDK Not a breaking change ## Requires SpacetimeDB PRs None afaik ## Testsuite SpacetimeDB branch name: master ## Testing *Write instructions for a test that you performed for this PR* - [x] Ran through Bitcraft tutorial - [x] Blackholio on CI --------- Co-authored-by: James Gilles <[email protected]> Co-authored-by: Zeke Foppa <[email protected]>

## Description of Changes These version bumps were supposed to happen in #332, but apparently I messed something up while I was switching branches. ## API - [ ] This is an API breaking change to the SDK No breaking changes ## Requires SpacetimeDB PRs None. ## Testsuite SpacetimeDB branch name: master ## Testing CI only Co-authored-by: Zeke Foppa <[email protected]>

## Description of Changes Missed in #333. We should update the 1.2.1 tag and the `release/latest` branch after this. ## API - [ ] This is an API breaking change to the SDK Nope ## Requires SpacetimeDB PRs None ## Testsuite SpacetimeDB branch name: master ## Testing CI only Co-authored-by: Zeke Foppa <[email protected]>

## Description of Changes I'm tired of messing up version updates. I "vibecoded" a script to do it. ## API - [ ] This is an API breaking change to the SDK No. No changes to runtime code. ## Requires SpacetimeDB PRs None ## Testsuite SpacetimeDB branch name: master ## Testing ``` $ python3 tools~/update-version.py 1.1.1 Updated: ./SpacetimeDB.ClientSDK.csproj Updated: ./tests~/tests.csproj Updated: ./examples~/regression-tests/server/StdbModule.csproj Updated: ./examples~/regression-tests/client/client.csproj Updated: ./examples~/quickstart-chat/server/StdbModule.csproj Updated: ./examples~/quickstart-chat/client/client.csproj Updated version in package.json to 1.1.1 $ git diff -U1 diff --git a/SpacetimeDB.ClientSDK.csproj b/SpacetimeDB.ClientSDK.csproj index 5248df6..b3ca7e8 100644 --- a/SpacetimeDB.ClientSDK.csproj +++ b/SpacetimeDB.ClientSDK.csproj @@ -18,4 +18,4 @@ <RepositoryUrl>https://github.com/clockworklabs/com.clockworklabs.spacetimedbsdk</RepositoryUrl> - <AssemblyVersion>1.2.1</AssemblyVersion> - <Version>1.2.1</Version> + <AssemblyVersion>1.1.1</AssemblyVersion> + <Version>1.1.1</Version> <DefaultItemExcludes>$(DefaultItemExcludes);*~/**</DefaultItemExcludes> @@ -27,3 +27,3 @@ <ItemGroup> - <PackageReference Include="SpacetimeDB.BSATN.Runtime" Version="1.2.*" /> + <PackageReference Include="SpacetimeDB.BSATN.Runtime" Version="1.1.*" /> diff --git a/examples~/quickstart-chat/server/StdbModule.csproj b/examples~/quickstart-chat/server/StdbModule.csproj index 0513a81..f290d22 100644 --- a/examples~/quickstart-chat/server/StdbModule.csproj +++ b/examples~/quickstart-chat/server/StdbModule.csproj @@ -16,3 +16,3 @@ <ItemGroup> - <PackageReference Include="SpacetimeDB.Runtime" Version="1.2.*" /> + <PackageReference Include="SpacetimeDB.Runtime" Version="1.1.*" /> </ItemGroup> diff --git a/examples~/regression-tests/server/StdbModule.csproj b/examples~/regression-tests/server/StdbModule.csproj index c6b1cba..3284863 100644 --- a/examples~/regression-tests/server/StdbModule.csproj +++ b/examples~/regression-tests/server/StdbModule.csproj @@ -10,3 +10,3 @@ <ItemGroup> - <PackageReference Include="SpacetimeDB.Runtime" Version="1.2.*" /> + <PackageReference Include="SpacetimeDB.Runtime" Version="1.1.*" /> </ItemGroup> diff --git a/package.json b/package.json index 7839151..a627246 100644 --- a/package.json +++ b/package.json @@ -3,3 +3,3 @@ "displayName": "SpacetimeDB SDK", - "version": "1.2.1", + "version": "1.1.1", "description": "The SpacetimeDB Client SDK is a software development kit (SDK) designed to interact with and manipulate SpacetimeDB modules..", ``` --------- Co-authored-by: Zeke Foppa <[email protected]>

## Description of Changes This is a fix for community bug #340 that was the result of changes to SpacetimeDBClient code that missed changes to the WebGL build. ## API - [ ] This is an API breaking change to the SDK ## Requires SpacetimeDB PRs - None ## Testsuite SpacetimeDB branch name: master ## Testing - [X] Tested changes against Blackholio running under a Unity WebGL build

kazimuth · 2025-07-15T20:43:00Z

See also clockworklabs/SpacetimeDB#2938

gefjon

One suggestion and two responses that don't require action. Thanks for writing this, it's gonna be really helpful!

gefjon · 2025-07-16T13:58:18Z

DEVELOP.md

+
+`DbConnection` in the generated code inherits from `DbConnectionBase<...>` in the SDK code, which lives in [`src/SpacetimeDBClient.cs`](./src/SpacetimeDBClient.cs). This is a general pattern. Similar inheritance patterns are used for tables and indexes: the generated code defines a class that inherits most of its behavior from a class in the SDK.
+
+We require that **a DbConnection is only accessed from a single thread**, which should call the `DbConnection.FrameTick()` method frequently. See [threading model](#threading-model), below.


We do? Ew...

gefjon · 2025-07-16T14:00:16Z

DEVELOP.md

+
+The C# SDK, unlike the [Rust SDK](https://github.com/clockworklabs/SpacetimeDB/tree/master/crates/sdk), **assumes a DbConnection is only accessed from a single thread**. This thread is referred to as the "main thread". The "main thread" is:
+- Whichever thread is repeatedly calling `DbConnection.FrameTick()` in a loop.
+It is **only safe to call `FrameTick()` from a single thread**. It is **only safe to access the DbConnection from this thread**. 


Is this solvable/fixable with a lock?

Would require locking on all accesses of conn.Db. I don't think there's a nice way to do this without an API break. The type system is just much less expressive RE: sharing.

Even if you, say, require conn.Db to be accessed from a callback that has a lock on the database, the user can still just store the Db you passed outside the callback. In the end I think the only way to do it would be to have the user manage the lock.

We could think about doing something MVCC-y, where each conn.Db you see is actually immutable, and you're just getting new copies of the Db on changes, but I would be worried about the perf implications there.

That might allow more work to be done in the background threads, but it would naively involve a lot more allocations since you'd be creating a new copy of the indices each frame. It might work to just have pools of Dictionary<...> lying around that we reuse. Alternatively, we find some sort of haskelly immutable dictionary that can share state between copies.

DEVELOP.md

Thanks Phoebe Co-authored-by: Phoebe Goldman <[email protected]>

bfops · 2025-08-08T17:52:28Z

Migrated to clockworklabs/SpacetimeDB#3140, as we are merging this repo into that one.

# Description of Changes Migrating clockworklabs/com.clockworklabs.spacetimedbsdk#349 since we are merging that repo into this one. > Add some developer docs. # API and ABI breaking changes None # Expected complexity level and risk 1 # Testing None. Docs only. --------- Co-authored-by: James Gilles <[email protected]> Co-authored-by: Phoebe Goldman <[email protected]> Co-authored-by: Zeke Foppa <[email protected]>

jdetter and others added 30 commits November 2, 2022 12:01

Merge pull request #1 from clockworklabs/jdetter/some-api-updates

583b612

Some API updates

Merge pull request #2 from clockworklabs/jdetter/some-api-updates2

a9f8bef

More API updates

Improved names

7832181

.gitignore change

b37b468

Several fixes to sending when the websocket is closed.

fe3a8ad

Give SDK users access to the token key

355b9e9

Changes to the Unity SDK to support callbacks for individual table ro…

842cb00

…w updates and reducer events

Merge pull request #3 from clockworklabs/Derek-Callback-Improvements

40b19b7

API callback improvements

Add sslEnabled option to Connect function

ab12cef

Merge pull request #4 from clockworklabs/derek-add-SSL-option

3364cd7

Add sslEnabled option to Connect function

SDK Upload Script (#7)

7fc5463

* Upload script to help deploying to our partners * You have to specify hosts individually * Small fix * Another small fix - tested + working --------- Co-authored-by: John Detter <[email protected]>

Json Byte Arrays Serialized as Hex (#8)

28897a3

* Serialize byte arrays as hex * Fix namespace * Small fix --------- Co-authored-by: John Detter <[email protected]>

C# Enum Generation (#9)

9286779

* First pass * Committing meta file * Removed option type - unneeded * Implementing new some converter * Some converter updates * Tons of fixes here * Cleaned up the some/enum serialization implementation --------- Co-authored-by: John Detter <[email protected]>

Fix compilation issue (#11)

ca5eefe

Co-authored-by: John <[email protected]>

Automatically find Unity on macOS (#12)

6151939

Co-authored-by: John Detter <[email protected]>

GetEntries now returns both AlgebraicValue and object as a tuple (#15)

cddda19

Co-authored-by: John Detter <[email protected]>

Use Network Thread for Processing DB Rows (#14)

9f9e549

* Several updates to the way ClientCache + processing updates works * Client cache changes working * Removed log statements --------- Co-authored-by: John Detter <[email protected]>

State Diffs (#16)

51086a2

* Copied changes from BitCraft * Applied state diff changes * State diffs complete * Compilation fix * Fix build issues --------- Co-authored-by: John Detter <[email protected]>

SpacetimeDB SDK Version 0.4.1 (#17)

aad6c4b

* Pulled SpacetimeUnitySDK from the BitCraft project * Removed unused logs * Removed primary key functionality * Fix compilation issues with older version of C# --------- Co-authored-by: John <[email protected]>

Adding event parameter to table callbacks (#19)

11801d4

* Adding event parameter to table callbacks * Reverted a namespace change --------- Co-authored-by: Steve <[email protected]> Co-authored-by: John Detter <[email protected]>

Fix compile error in sdk (#22)

bc6ed3e

Co-authored-by: Derek Brinkmann <[email protected]>

Add onSubscriptionUpdate callback (#21)

c15c54e

* Add onSubscriptionUpdate callback * Remove unnecesary onTransactionComplete --------- Co-authored-by: Derek Brinkmann <[email protected]>

Deserializing reducer args before table updates so they can be access…

fb72396

…ed from callbacks (#20) Co-authored-by: Steve <[email protected]>

Changed guid (#25)

30f4347

Co-authored-by: Steve <[email protected]>

Fixed API (#26)

cf771d3

Co-authored-by: John Detter <[email protected]>

bfops and others added 11 commits May 22, 2025 15:40

Add some developer docs

92a0831

kazimuth requested review from joshua-spacetime and rekhoff July 15, 2025 20:42

github-actions bot changed the base branch from release/latest to master July 15, 2025 20:42

Merge branch 'master' into jgilles/docs/developer-docs

3c3d1c5

kazimuth requested a review from gefjon July 15, 2025 20:43

kazimuth added 3 commits July 15, 2025 16:49

More runtime docs

480c9f3

Typos

90ece03

Typo 2

4dbdc1b

gefjon approved these changes Jul 16, 2025

View reviewed changes

Update DEVELOP.md

a37b68d

Thanks Phoebe Co-authored-by: Phoebe Goldman <[email protected]>

rekhoff approved these changes Jul 16, 2025

View reviewed changes

Add doc comments

0993282

bfops force-pushed the master branch from aecb141 to a916977 Compare August 5, 2025 21:13

bfops mentioned this pull request Aug 8, 2025

C#/Unity SDK - Add some developer docs clockworklabs/SpacetimeDB#3140

Merged

bfops closed this Aug 8, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add some developer docs #349

Add some developer docs #349

Uh oh!

kazimuth commented Jul 15, 2025

Uh oh!

kazimuth commented Jul 15, 2025

Uh oh!

gefjon left a comment

Uh oh!

gefjon Jul 16, 2025

Uh oh!

gefjon Jul 16, 2025

Uh oh!

kazimuth Jul 16, 2025 •

edited

Loading

Uh oh!

kazimuth Jul 16, 2025

Uh oh!

kazimuth Jul 16, 2025 •

edited

Loading

Uh oh!

Uh oh!

bfops commented Aug 8, 2025

Uh oh!

Uh oh!


		`DbConnection` in the generated code inherits from `DbConnectionBase<...>` in the SDK code, which lives in [`src/SpacetimeDBClient.cs`](./src/SpacetimeDBClient.cs). This is a general pattern. Similar inheritance patterns are used for tables and indexes: the generated code defines a class that inherits most of its behavior from a class in the SDK.

		We require that a DbConnection is only accessed from a single thread, which should call the `DbConnection.FrameTick()` method frequently. See [threading model](#threading-model), below.

Add some developer docs #349

Add some developer docs #349

Uh oh!

Conversation

kazimuth commented Jul 15, 2025

Description of Changes

API

Requires SpacetimeDB PRs

Testsuite

Testing

Uh oh!

kazimuth commented Jul 15, 2025

Uh oh!

gefjon left a comment

Choose a reason for hiding this comment

Uh oh!

gefjon Jul 16, 2025

Choose a reason for hiding this comment

Uh oh!

gefjon Jul 16, 2025

Choose a reason for hiding this comment

Uh oh!

kazimuth Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kazimuth Jul 16, 2025

Choose a reason for hiding this comment

Uh oh!

kazimuth Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bfops commented Aug 8, 2025

Uh oh!

Uh oh!

kazimuth Jul 16, 2025 •

edited

Loading

kazimuth Jul 16, 2025 •

edited

Loading