No technical claim changed. This is a pass over how the pages read, not
what they say.
Removed 419 em and en dashes, which were the most consistent tell in the
text, along with mechanical boldface and explanatory mid-sentence colons.
Then the judgement work the humanizer skill asks for: rule-of-three
padding, announced counts, signposting, passive voice with the actor
hidden, verbless noun-phrase lists that should have been sentences, and
filler.
Every measured number, file and line reference, version, quoted error
string and piece of reasoning survives. That specificity is what makes
these pages worth reading, and over-editing would have flattened it.
Two accuracy fixes fell out of the pass, both found by reading closely
enough to rewrite:
* API-Reference misquoted the editor command's failure. The real
message is `stdb: no schema from <url>. Is the server running, and is
curl on PATH?`, with a period, not the em dash the page had.
* Roadmap still listed "an example project you can open and run" under
what is missing. `dev/example-chat` has been exactly that for a
while, with its own `game.project` and a headless variant CI runs.
What is genuinely still absent is a staged tutorial of the kind
upstream ships for Unity, Godot and Unreal, so the entry now says
that instead.
docs: 4.2.4 with no patch, and the quickstart moves here
extension-websocket 4.2.4 fixes defold/extension-websocket#67, so the
HTML5 subprotocol patch is gone. Every page that carried the patching
instructions, a vendored-fork workflow, or a 4.2.3 pin is corrected.
Quickstart is now the SDK's tutorial rather than a section of the
README. It walks an unpublished module through to a connected game that
replicates positions between clients, and it absorbed the parts of the
old page the README version did not carry.
API-Reference and Usage-Guide are brought in line with PR #111:
`schema = gen`, `json` no longer required, `stdb.query` on the facade,
`db:ping` as `(err, seconds)`, `stdb.await`/`await_event` including the
Lua 5.1 limit on yielding across `pcall`, `stdb.builder(opts)`, the full
`on_event` type list with payload keys, and a section for the mistakes
that now raise instead of failing quietly.
Protocol-Notes and Roadmap no longer describe `stdb/protocol.lua` or the
v1 JSON wire in the present tense; both went in 4.0.0.
wiki: one wire — drop the v1 JSON pages and claims for 4.0.0
The SDK deleted the v1 JSON wire in 4.0.0, so the wiki stops offering it.
V1-Opt-Out is deleted outright: it documented an opt-out that no longer
exists. Its nav entry and Home row go with it, and all 11 inbound links
across the Usage Guide are gone.
Every page that named a removed API is corrected rather than trimmed:
the protocol option, light, json on connect, Builder:with_protocol, the
legacy whole-set db:subscribe, subscription_replaced, and
Call:on_out_of_energy. json stays documented on auth.exchange and
schema.fetch, which are HTTP and still need it. The API Reference gains
connection.dispatch, decode_bytes and decodable_tag; the Usage Guide
gains the fourth undescribed reason, which the page had been missing
independently of this change.
A table with no types is now always skipped and reported. Four places
described an untyped positional fallback that no longer exists.
Protocol Notes keeps its v1 findings as archive, reframed: they are still
true of the server, the committed fixtures were captured over that wire,
and the decoder that reads them survives as dev/test/crosscheck_v1.lua -
a cross-check on the BSATN reader, since BSATN is opaque and a wrong type
belief returns a plausible number instead of raising.
One factual error corrected on the way through. The Roadmap claimed the
official TypeScript SDK 'prefers v3, falls back to v2, and does not offer
v1 at all'. It is on v1.bsatn.spacetimedb
(packages/sdk/src/db_connection_impl.ts:233) - a protocol version behind
this SDK. The wire-ceiling section now tables where every official client
actually sits, read off source, and says what v3 actually is: not a new
message schema but permission to coalesce several v2 ServerMessages into
one payload.
Install URLs at v4.0.0. Benchmark tables measured on the JSON wire keep
their numbers and gain a note saying so - re-running the sweep on the
current branch is what retires them, and inventing replacements would be
worse than dated figures.
The server's default scheme is brotli and it compresses anything over 1KiB, so
the connect URL never omits the parameter - it asks for gzip when a gunzip is in
reach. Protocol Notes had the envelope wrong for the compressed case: the tag
byte replaces the message's leading byte rather than prefixing the stream, so
the gzip magic sits at byte 2. Roadmap moves frame compression out of Not
planned, where the stated reason - that a pure-Lua inflate would be large and
slow - stopped applying the moment the engine shipped one.
Record the cross-client light finding as a test, and the one-codec rule
Phase 8 of the v1 conformance run now asserts what the four-observer table
measured by hand: one commit, an ordinary observer receiving
TransactionUpdateLight while the caller receives a full TransactionUpdate. The
table stays as provenance, with the row a test now holds marked as such.
The API reference gains the one-codec-per-process rule on the json option,
which is new behaviour: a second connection passing a different implementation
raises rather than silently re-pointing the connections already running.
The quickstart's send moves into on_applied, matching the README exactly, so
neither placement reads as load-bearing when only the socket is.
docs: make the default wire the spine, and split the two audiences
The Usage Guide documented the JSON opt-out for 1144 lines before saying it
was not the default. The v2 material is folded into the sections it belongs
to, and the v1-only knobs - light, on_out_of_energy, the whole-set subscribe,
the older message shapes - move to V1-Opt-Out.
Provenance moves rather than disappearing: captures, byte tables and the
upstream Rust citations to Protocol-Notes, the benchmark narratives to
Development. Home and the sidebar now read as two paths, one for a game using
the SDK and one for someone changing it.
Also documents what the SDK gained: stdb.schema.fetch, stdb.schema.to_lua and
the Project menu command that writes the generated module. Four code blocks
were false and are fixed - two syntax errors, load vs loadstring on 5.1, and
a quickstart still telling consumers to run a script they never receive.
Say how to decode a one-off row, and why the SDK will not
Both pages documented that one-off rows arrive encoded and neither said what to
do with them. The recipe is now in the Usage Guide, with the trap it is easy to
walk into: `tables[i].table_name` names a def, so decoding with it looks like
the obvious convenience, and it is wrong. A def is positional and a one-off
projects an arbitrary relation, so a projection reads the wrong columns -- and
need not raise. SELECT sender, text FROM message is caught, because the string
length prefix is read as the u64. SELECT id, text, sender has the same three
widths with two swapped, so it decodes clean and returns sender and text
reversed, silently.
Both cases are pinned upstream in dev/test/test_protocol_v2.lua.
`connect()` negotiates `v2.bsatn.spacetimedb` as of 2.0.0, so every page that
called v1 the default and v2 an opt-in was wrong the moment it merged. The
inversion is mechanical in most places — the `protocol` default, the two
SUBPROTOCOL rows, the version pins — and structural in three.
Quickstart was not merely stale, it could not run. Its sample connected with a
hand-written schema, subscribed with the legacy `subscribe` and called a reducer
with no `reducers`: on the default wire that decodes nothing, raises, and cannot
encode the call. Schema generation moves ahead of the first connect, where it is
now a prerequisite rather than an upgrade, and the sample passes `reducers` and
`procedures` and uses `subscribe_query`.
Usage-Guide's "everything above describes the default" is now the wrong way
round and cannot be fixed by swapping a word, so it says so plainly instead: the
page documents the opt-out first, an unqualified statement above is v1's, and the
differences are enumerated in the v2 section. The reducer contract grew the
second half it never had — v2 has two outcomes, and `on_out_of_energy` never
fires because nothing replaces it. API-Reference keeps the light-mode
investigation, scoped to the wire that still has a light mode.
Five things wrong beyond the flip, found by checking the pages against the
worktree rather than against the brief:
* Development and Roadmap both said conformance runs v2 by dispatch only. It
has been a matrix over both wires on every automatic trigger since #91.
* Both said the HTML5 tier reports instead of gating. It gates now — it had to
before v2 could be the default, since it is the only place the wasm build of
the binary wire runs.
* The smoke is seven phases on v2 and six on v1, not five, and the phase that
prints PASS is the bulk apply, not the identity-keyed table.
* The generated-schema sample called a reducer without passing `reducers`,
which the flip turned from redundant into broken.
* session_v2.jsonl holds 33 frames, not 29; the capture grew and the sentence
describing it did not.
`STDB_BULK_TYPED` is marked as the v1 knob it now is; the typed description is
not optional on a wire whose rows carry no names.
Name the two claims that were not true per protocol
Two guarantees on these pages were broader than the code behind them.
The value surface. Usage-Guide, API-Reference and Roadmap all said rows
decode to the same Lua values over either protocol. That holds for every
type tag but f32. BSATN carries the four bytes of the stored single, so
0.1 reads back as 0.10000000149011612, its exact value as a double; v1
sends decimal text and json.decode returns the double nearest 0.1. Only
values that do not fit 24 mantissa bits diverge, so an f32 column
carrying 0, -1.5 or 0.25 still matches on both wires. Narrow the claim
and state the exception with its values rather than delete it, because
it is true for everything else and that is what the differential test
proves. Say which side is faithful too: v2 returns what the server
stored, v1 reconstructs a double from a decimal rendering of it. The
Roadmap says it under the default-flip decision, where it is an input to
that decision rather than a footnote after it.
confirmed_reads. The API reference explained the tri-state as forward
compatibility with no difference visible today. There is a difference
today, because v2 is selectable today. Upstream resolves an absent
parameter in resolve_confirmed_reads_default (client-api subscribe.rs
103-111): false on v1, DEFAULT_CONFIRMED_READS on v2 and v3, which the
test at subscribe.rs 2838-2844 asserts is true. So a v2 caller who
passes nothing is already holding updates until the transaction offset
is durable where a v1 caller is not. Give the resolved default per
protocol and say that passing the option is how a caller pins it.
That was an open item under "make the documentation true"; it leaves the
Roadmap now, the way that section says landed items do.
Protocol-Notes gains the v2 frame envelope, the ClientMessage/ServerMessage
map and the four wire facts the live capture settled: the timestamp is micros
despite upstream documenting nanoseconds, identity hex is the byte-reverse of
the wire bytes, Option/Result ordinals, and a client frame carrying no
compression byte is accepted. Benchmark figures are marked as pending rather
than guessed.
Usage-Guide documents connect({ protocol = "v2" }), the event-table event
type, the generated-types requirement, light being v1-only, subscribe_query
replacing the legacy subscribe, and on_out_of_energy being unreachable on v2.
API-Reference covers the new public surface. Roadmap moves the BSATN item to
done, pending only the decision to flip the default.
