SpacetimeDB Defold SDK

SpacetimeDB 2.x client SDK for Defold, in Lua.

SpacetimeDB is a database that runs your game's server logic as transactional reducers inside it and streams row changes straight to subscribed clients, so there's no REST layer and no separate game server to run and scale yourself. This SDK is the Defold side of that. It opens the websocket connection, subscribes queries, calls reducers, and mirrors the rows they touch into a local cache your game reads and reacts to.

A SpacetimeDB module defines tables on the server, and a client subscribes to SQL queries against them. Whatever a query selects becomes a live cache on the device, and this SDK keeps that cache in sync as the server commits. Rows arrive already decoded against the module's schema, so a column typed as Identity shows up as a plain hex string and one typed as Timestamp shows up as microseconds, rather than the raw wire values SpacetimeDB actually sends.

Requirements

• A SpacetimeDB 2.x module to talk to
• Defold 1.12.4 or newer, with extension-websocket 4.2.4 as this SDK's only dependency. 1.12.4 is where zlib.inflate learned to read a gzip wrapper, which is what decodes the compressed frames the server sends above 1KiB; CI runs 1.13.0

The SDK itself is pure Lua and runs on both native and HTML5 targets.

Install

Add both of these to your game.project dependencies.

https://git.nokopia.com/yuris/spacetimedb-defold/archive/v4.0.2.zip
https://github.com/defold/extension-websocket/archive/refs/tags/4.2.4.zip

Then Project ▸ Fetch Libraries.

extension-websocket is not optional and not automatic. Defold does not resolve dependencies transitively, so a project listing only this SDK compiles fine and then fails at connect. Nothing further is needed for an HTML5 build; 4.2.4 sends the subprotocol on that target too. Installation has the details.

Getting started

The Quickstart takes you from an unpublished module to a connected game that replicates row changes between clients. It covers writing and publishing the module, generating the Lua schema, connecting, subscribing, row callbacks, reducer calls, and the coroutine form of each one-shot call.

Features

How this SDK compares with the official SpacetimeDB 2.x clients (Rust, C#, TypeScript and Unreal), whose capabilities are described in the SDK API Overview and Connecting to SpacetimeDB. ✅ shipped, ❌ absent, ➖ not applicable.

Feature	This SDK	Official SDKs
Callback context (ctx first argument)	✅	✅
Connection builder	✅	✅
Subscribe to SQL queries	✅	✅
Subscription builder and handle	✅	✅
Applied and error callbacks	✅	✅
Unsubscribe at runtime	✅	✅
Typed query builder	✅	✅
Local row cache	✅	✅
Lookup by primary key or unique column	✅	✅
Iterate and count cached rows	✅	✅
Row callbacks	✅	✅
Reducer calls	✅	✅
Procedure calls with a return value	✅	✅
Await-style calls beside the callbacks	✅	✅
Views	✅	✅
Event tables	✅	✅
Schema generation	✅	✅
Disconnect	✅	✅
BSATN wire	✅	✅
Identity persistence	✅	❌
Automatic reconnection	✅	❌
Connection state	✅	❌
Round-trip latency	✅	❌
Frame-budgeted apply	✅	➖
Compressed frames (gzip)	✅	✅

Documentation

The wiki documents installation, a quickstart, the usage guide, the API reference and the notes for working on the SDK itself.

Repository layout

• stdb/ is the SDK, and the only directory Defold exposes
• dev/ is everything else, excluded from the consumer archive via .gitattributes

A dependency archive therefore carries stdb/, LICENSE, README.md and game.project. dev/ is the test and conformance harness, and it reaches only someone who clones the repository.

Disclaimer

An independent project, not affiliated with or endorsed by Clockwork Labs. The official SpacetimeDB client SDKs are Rust, C#, TypeScript and Unreal; this one is not among them.

The MIT licence below covers this SDK only. SpacetimeDB itself is separately licensed, BSL 1.1 at the version pinned here, so check its terms before you ship a server.

License

MIT © 2026 Yuris Cakranegara