A community SpacetimeDB public-mirror for BitCraft. It holds a single
persistent subscription to each upstream game region and fans it out to
any number of downstream clients — so
community tools (BitCraftMap, BitCraftSync, BitJita, …) share one
upstream cost instead of each holding their own subscription. Point your
SpacetimeDB SDK at the addresses below (bitcraft-live-*
databases); it’s a drop-in
wss:// replacement. New here?
Start with the step-by-step tutorial
(connect, subscribe, schema, relay-cache joins, live inventory WS), or open the
data explorer to browse mirror tables in the browser.
Community project — not affiliated with Clockwork Labs. SpacetimeDB™ is a trademark of Clockwork Labs. · How to use the relay · Data explorer
| Source | Port | Status | Uptime | ||
|---|---|---|---|---|---|
| Loading… | |||||
Status is each source’s connectivity
(connecting / subscribing / live /
disconnected); throughput is
transactions_per_sec from the coordinator’s 60×1s
rotating window (or legacy updates/s); uptime is duration since
connected_since (or reconnect ETA when disconnected). Host
CPU / memory / network stay in the system cards above.
Each row is a live mirrored region served by a single public-mirror
backend. Databases are named bitcraft-live-*
(bitcraft-live-global and bitcraft-live-N per
region). Connect your SpacetimeDB SDK with the SDK address as the
host and the Database as the database name, or open the full
subscribe URL for raw-WebSocket testing. Use
v2.bsatn.spacetimedb (the default of current SDKs) —
it is the only protocol that carries the mirrored event tables
(market_trade_event, craft_event,
player_death_event, … delivered as insert-only
EventTable frames with no snapshot — persist rows as
they arrive). The v1 subprotocols still serve every state table and
remain the way to get per-transaction caller identity and timestamp
(v2 frames carry rows only); event tables are unsupported on v1
(rejected on v1.bsatn, empty snapshot on
v1.json).
See also the
How to use the relay tutorial (Python & Rust)
and the in-browser data explorer.
Ports with no source behind them return nginx
502; only sources reported live by /health are listed.
| Instance | Port | SDK address | Full subscribe URL | |
|---|---|---|---|---|
Loading live sources from /health… | ||||
Each relay also serves its upstream’s schema as SATS-JSON over plain
HTTP on the same port as its wss:// listener. Substitute the
Port and Database (mirror) values from the table above.
The response carries Content-Type: application/json and is the
cached upstream schema (the bytes the relay fetched at startup and codegen
’d its mirror from) — about 580 KB for a BitCraft module,
with Cache-Control: public, max-age=60. The
?version=9 query is accepted but ignored: only the v9 format
is cached. Useful for codegen, type inspection, or feeding a local SDK
without hitting upstream. The data explorer
uses this endpoint to list tables.
| URL template |
|---|
https://relay.bitcraftsync.app:<port>/v1/database/<mirror-database>/schema?version=9
$ curl https://relay.bitcraftsync.app:3014/v1/database/bitcraft-live-14/schema?version=9
|
Read-only JSON (protobuf available via
Accept: application/x-protobuf on the cache routes;
schemas at /proto).
Fleet health refreshes every 30 seconds; the claim, player, deposit,
and storage-log cache is live in-memory state mirrored from each region.
| Endpoint | Returns | Query params |
|---|---|---|
| /health |
Fleet source map: per-source port,
database name, schema_cached,
connectivity, tables_live /
tables_total, and lifetime
transactions_processed, plus the host’s
system.cpu.load_average,
system.memory (free / total), and
system.network rolling rate. schema_count
reflects the number of discovered sources.
$ curl https://relay.bitcraftsync.app/health
|
— |
|
/cache-health /proto |
Cache readiness (relay-cache): top-level
ready and per-region ready flags.
Protobuf schema list and raw .proto download for
the cache DTOs (relay_cache.proto,
roads_cache.proto, roads.proto).
Operational internals (memory pressure, stream counters, row
counts) are on loopback-only
127.0.0.1:8090/internal/stats.
$ curl https://relay.bitcraftsync.app/cache-health
$ curl https://relay.bitcraftsync.app/proto
$ curl -OJ https://relay.bitcraftsync.app/proto/relay_cache.proto
$ curl -OJ https://relay.bitcraftsync.app/proto/roads_cache.proto
$ curl -OJ https://relay.bitcraftsync.app/proto/roads.proto
|
— |
|
/claim /claim/<id> |
Claim cache (relay-cache): lookup by PK or name
substring (PK includes supplies, upkeep, tier, researched
techs, owner username), per-claim inventory (shared storage
only — no Town Banks; grouped by overworld / interior
dimension with entrance), members (roles + skills + hexcoins +
last login), and crafts. Legacy /citizens and
/hexcoins still work as projections of members.
(progressive + passive, optional completed filter).
$ curl 'https://relay.bitcraftsync.app/claim?name=concordia'
$ curl https://relay.bitcraftsync.app/claim/<id>
$ curl https://relay.bitcraftsync.app/claim/<id>/inventory
$ curl https://relay.bitcraftsync.app/claim/<id>/members
$ curl https://relay.bitcraftsync.app/claim/<id>/citizens
$ curl https://relay.bitcraftsync.app/claim/<id>/hexcoins
$ curl 'https://relay.bitcraftsync.app/claim/<id>/crafts?completed=false'
|
name (substring, for /claim);
completed (optional bool, for /crafts)
|
|
/player /player/<id> |
Player cache (relay-cache): username search
(incl. last_login_timestamp / signed_in /
last_active_timestamp),
personal inventories (pockets / toolbelt / wallet / bank /
wagon / cache / boat / recovery / deployable),
first-house contents resolved server-side from the
player id (status is ok or
noHouse), skill levels, and crafts
(optional completed filter).
$ curl 'https://relay.bitcraftsync.app/player?name=maple'
$ curl https://relay.bitcraftsync.app/player/<id>
$ curl https://relay.bitcraftsync.app/player/<id>/inventory
$ curl https://relay.bitcraftsync.app/player/<id>/housing
$ curl https://relay.bitcraftsync.app/player/<id>/skills
$ curl 'https://relay.bitcraftsync.app/player/<id>/crafts?completed=true'
|
name (substring, for /player;
clients should send ≥2 chars);
completed (optional bool, for /crafts)
|
| /deposits |
Hexite deposits (relay-cache): global flat list
with game coords (north=z, east=x).
Active deposits omit respawn_at; depleted ones
set it from public growth_state (Depleted→Hexite,
6–8 days). Join misses surface as
status: "unknown" (not harvestable).
$ curl https://relay.bitcraftsync.app/deposits
$ curl 'https://relay.bitcraftsync.app/deposits?region=14'
|
region (optional BitCraft region id)
|
| /storage-logs |
Storage deposit/withdraw history (relay-cache),
retained for the upstream ~15–16 day window. Exactly one
mode per request: by chest, by player, or by item scoped to a
claim or player. Each entry includes building
entity_id / name / nickname,
claim, player, action, and item stack.
$ curl 'https://relay.bitcraftsync.app/storage-logs?storageId=<id>'
$ curl 'https://relay.bitcraftsync.app/storage-logs?playerId=<id>&limit=50'
$ curl 'https://relay.bitcraftsync.app/storage-logs?itemId=<id>&claimId=<id>'
$ curl 'https://relay.bitcraftsync.app/storage-logs?itemId=<id>&playerId=<id>'
|
One of: storageId;
playerId;
itemId+claimId;
itemId+playerId.
Optional: itemType (Item|Cargo),
region, limit (newest N)
|
|
/bitme/resolve /bitme/session/<player_id> /bitme/session/<player_id>/resources wss…/bitme/session/<player_id>/resources/ws /bitme/region/<region_id>/resource-dictionary |
Bit-Me mobile-app API (relay-cache): exact-match
name → player entity id, identity, home region (name,
host, module) and live sign-in state; plus a ~1 Hz activity
snapshot per player — last-known position, current claim,
stamina (current/max), live buffs, action lifecycle, action
target with tracked health, and watched spawns (destroy-yield
respawn chains + Citric Giant berry bushes) scoped to the
player’s claim. The new resource-map endpoints: a packed
400×400 window centered on the player (binary
BMR1, ~320 KB, player at relative
200,200) merging every resource type with player paving
(10-bit paving index namespace) and a per-tile water flag;
world-anchored variants serve the same window at any tile
(/bitme/world/x/z/resources) plus a matching
elevation plane (/bitme/world/x/z/elevation,
binary BME1 v2: elevation, original elevation,
water level and water body type per super-hex — the
game’s terrain lattice at 3× tile scale,
134–137 × 136 cells per 400-tile window);
and the per-region tile dictionary
(index → resource_id / paving_type_id + name +
harvestable flag + gamedata; refetch when a window
header’s dict_version changes). The
resource map also has a live change stream
(wss://relay.bitcraftsync.app/bitme/session/<player_id>/resources/ws):
after a subscribed ack, every in-window
resource/paving tile change arrives as a small binary
BMD1 delta frame — the server follows the
player’s anchor, the client keeps convergence by
re-fetching the BMR1 window on close, resync,
moved, or a dict_version change.
Fleet-wide cap: 2048 streams. Polling is
the session registration (15 min TTL); the socket’s
5 s heartbeats refresh it too.
Walkthrough: Bit-Me app API &
BMR1/BME1 maps. Full reference:
crates/relay-cache/BITME-API.md in the relay repo.
$ curl 'https://relay.bitcraftsync.app/bitme/resolve?name=whisper'
$ curl https://relay.bitcraftsync.app/bitme/session/<player_entity_id>
$ curl https://relay.bitcraftsync.app/bitme/session/<player_entity_id>/resources -o window.bmr1
$ curl https://relay.bitcraftsync.app/bitme/world/<x>/<z>/elevation -o window.bme1
$ curl https://relay.bitcraftsync.app/bitme/region/<region_id>/resource-dictionary
|
resolve: name (required, exact,
case-insensitive). session and
session/resources: player entity id in the path.
resource-dictionary: region id in the path; JSON.
/resources is binary octet-stream — the only
non-JSON Bit-Me route; /resources/ws is the one
WebSocket (read-only stream; pre-upgrade errors are the same
JSON as /resources).
|
Protobuf-only read API (Accept: application/x-protobuf;
schemas at /proto).
In-memory terrain, paving overlay, claim index, and harvestable hex lookup per region.
Full format documentation:
Roads cache tutorial,
Region map format,
and
Hex resource lookup.
| Endpoint | Returns | Query params |
|---|---|---|
| /roads/health |
Fleet readiness (roads_cache.RoadsCacheHealth):
top-level ready, regions_ready /
regions_total, total_memory_bytes, and
per-region state (idle / loading / ready / error),
connection status, tile counts, and memory.
$ curl -H 'Accept: application/x-protobuf' https://relay.bitcraftsync.app/roads/health
|
— |
| /roads/regions |
Live region catalog (bitcraft.roads.RegionsResponse):
each region’s id, name,
live flag, grid coords (rx,
rz), world origin (origin_x,
origin_z), plus global
region_width_chunks /
region_height_chunks.
$ curl -H 'Accept: application/x-protobuf' https://relay.bitcraftsync.app/roads/regions
|
— |
| /roads/paving-types |
Global paving catalog (bitcraft.roads.PavingTypesResponse):
tile_type_id, name, duration, tier, input cargo,
and consumed material stacks per paving type.
$ curl -H 'Accept: application/x-protobuf' https://relay.bitcraftsync.app/roads/paving-types
|
— |
| /roads/terraform-recipes |
Global terraform recipe table
(bitcraft.roads.TerraformRecipesResponse):
height difference, action count, stamina and time
per action.
$ curl -H 'Accept: application/x-protobuf' https://relay.bitcraftsync.app/roads/terraform-recipes
|
— |
| /roads/region/<id>/map |
Atomic full-region snapshot
(roads_cache.RegionMapSnapshot) — terrain,
paving/claim overlay, and claim index table in one protobuf
(~280 MiB). Supports ETag /
If-None-Match; returns 202 while
loading. See the
region map format tutorial
for grid layout, coordinates, and cell bit-packing.
$ curl -H 'Accept: application/x-protobuf' -D - -o /tmp/region14.pb https://relay.bitcraftsync.app/roads/region/14/map
|
id (BitCraft region number, path segment) |
| POST /roads/region/<id>/resources |
Resource node lookup (roads_cache.ResourcesResponse)
on a list of world small-hex tiles. Body:
ResourceQuery { repeated Hex tiles }, max
16 384. Returns sparse
ResourceNode { x, z, resource_id, direction, origin }
for every resource type (forestry, mining, clay, sand,
mushrooms, berries, fiber, flowers, event resources, hexite
nodes — the old 215-id harvestable allowlist is gone;
filter client-side via
/bitme/region/<id>/resource-dictionary).
Multi-hex footprints land on every occupied tile; at most one
node per hex. 202 while seeding; 400
if oversize or invalid protobuf. See the
hex resource lookup tutorial.
$ curl -H 'Content-Type: application/x-protobuf' -H 'Accept: application/x-protobuf' --data-binary @query.pb https://relay.bitcraftsync.app/roads/region/14/resources
|
id (path); protobuf body, not query params |