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. Prefer
v1.bsatn.spacetimedb when you need reducer call-stack
provenance; v2.bsatn.spacetimedb is fine for row data alone.
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)
|
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 |
Point lookup of allowlisted harvestables
(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 } (forestry, mining,
clay, sand; overworld only). 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 |