docs: rewrite the README as an SDK introduction #99

Merged

yuris merged 1 commit from docs/readme-intro into main

2026-08-21 18:33:40 +00:00

yuris commented

2026-08-21 18:33:33 +00:00

Owner

Restructures the README so it reads top to bottom for someone meeting the SDK for the first time.

Order

Was: intro, code sample, feature list, Install, Layout, Documentation. The sample appeared sixty lines before the two dependencies it needs, and the feature list answered "what else can it do" before the reader had it working.

Now: intro, Requirements, Install, Quickstart, Features, Documentation, Repository layout, Disclaimer, Licence.

Content

The opening explains SpacetimeDB and what this client does, so a reader meets modules, subscriptions and the row cache before the SDK's own vocabulary.
Quickstart is built around subscribing. It keeps the Subscription handle and shows on_applied and on_error. It cannot use the older whole-set subscribe, which is v1-only and asserts on the default v2 wire (stdb/connection.lua:447-450) because v2's own Subscribe is already the query-set form.
The feature list is now a comparison table against the official 2.x clients, sourced from the SDK API Overview and Connecting to SpacetimeDB. It records two gaps (no typed query builder, no compressed frames) alongside two places this SDK does more than upstream (automatic reconnection replaying every live query set, and frame_budget).
Requirements is new, collecting facts that were scattered between the tagline and the install prose.
The wiki section is one sentence, since the wiki carries its own index.
The disclaimer now names Unreal among the official SDKs.

Verification

The quickstart snippet's exact call sequence was replayed against the pure core (subscribe_query -> on_applied -> count -> on_insert -> unsubscribe), asserting each step: applied=1 insert=yuris hello ended=true. Unit suite green, 11 passed, 0 failed.

Docs only, no source change.

Note, unrelated to this PR

stdb/bsatn.lua has an uncommitted local edit in the working tree that replaces the array-count bounds check in Reader:len() with if false then, disabling length validation on incoming wire data. It is left out of this branch. Worth a look before it reaches a commit.

Restructures the README so it reads top to bottom for someone meeting the SDK for the first time. ## Order Was: intro, code sample, feature list, Install, Layout, Documentation. The sample appeared sixty lines before the two dependencies it needs, and the feature list answered "what else can it do" before the reader had it working. Now: intro, Requirements, Install, Quickstart, Features, Documentation, Repository layout, Disclaimer, Licence. ## Content - The opening explains SpacetimeDB and what this client does, so a reader meets modules, subscriptions and the row cache before the SDK's own vocabulary. - **Quickstart is built around subscribing.** It keeps the `Subscription` handle and shows `on_applied` and `on_error`. It cannot use the older whole-set `subscribe`, which is v1-only and asserts on the default v2 wire (`stdb/connection.lua:447-450`) because v2's own `Subscribe` is already the query-set form. - **The feature list is now a comparison table** against the official 2.x clients, sourced from the [SDK API Overview](https://spacetimedb.com/docs/clients/api) and [Connecting to SpacetimeDB](https://spacetimedb.com/docs/clients/connection). It records two gaps (no typed query builder, no compressed frames) alongside two places this SDK does more than upstream (automatic reconnection replaying every live query set, and `frame_budget`). - `Requirements` is new, collecting facts that were scattered between the tagline and the install prose. - The wiki section is one sentence, since the wiki carries its own index. - The disclaimer now names Unreal among the official SDKs. ## Verification The quickstart snippet's exact call sequence was replayed against the pure core (`subscribe_query` -> `on_applied` -> `count` -> `on_insert` -> `unsubscribe`), asserting each step: `applied=1 insert=yuris hello ended=true`. Unit suite green, 11 passed, 0 failed. Docs only, no source change. ## Note, unrelated to this PR `stdb/bsatn.lua` has an uncommitted local edit in the working tree that replaces the array-count bounds check in `Reader:len()` with `if false then`, disabling length validation on incoming wire data. It is left out of this branch. Worth a look before it reaches a commit.

yuris added 1 commit

2026-08-21 18:33:33 +00:00

docs: rewrite the README as an SDK introduction

ci / ci (pull_request) Successful in 20s

Details

3f51cedd7d

Restructure the README so it reads top to bottom for someone meeting the
SDK for the first time: what SpacetimeDB is and what this client does,
then requirements, install, quickstart, features, and the wiki.

- Open with SpacetimeDB itself rather than the cache internals, so the
  reader learns what a module, a subscription and a row cache are before
  the SDK's own vocabulary arrives.
- Move Install ahead of the code sample. The sample used to appear sixty
  lines before the two dependencies it needs.
- Centre the quickstart on subscribing, keeping the Subscription handle
  and showing on_applied and on_error. The older whole-set subscribe is
  v1-only and raises on the default wire, so it cannot be the example.
- Replace the flat feature list with a table comparing this SDK against
  the official 2.x clients, including the two gaps (no typed query
  builder, no compressed frames) and the places it does more
  (auto-reconnect with query-set replay, frame_budget).
- Add Requirements, collecting facts that were scattered between the
  tagline and the install prose.
- Trim the wiki section to one sentence, since the wiki carries its own
  index.
- Note Unreal among the official SDKs, which the disclaimer had missed.

yuris merged commit f29d4dab7f into main

2026-08-21 18:33:40 +00:00

yuris deleted branch docs/readme-intro

2026-08-21 18:33:40 +00:00

yuris referenced this pull request from a commit

2026-08-21 18:33:41 +00:00

docs: rewrite the README as an SDK introduction (#99)

yuris referenced this pull request

2026-08-21 18:38:31 +00:00

docs: title the README "SpacetimeDB Defold SDK" #100

yuris referenced this pull request

2026-08-21 19:52:36 +00:00