How to use the relay

Step-by-step guide to connecting a SpacetimeDB client to the public BitCraft relays, subscribing to tables safely at BitCraft scale, reading the schema, extracting real player column values (name, XP, skills), using relay-cache HTTP joins, and the /roads/* terrain cache API (including hex resource lookup).

UI Data explorer Browse tables in the browser — schema list, subscribe, filter/sort. 01 Connect over wss:// TypeScript, Python, Rust — host, database, InitialConnection. 02 Subscribe to tables Runnable sequential examples, SQL WHERE notes. 03 Discover the schema HTTP /schema?version=9 on the same port as the WebSocket. 04 Extract player data Concrete columns: username, entity_id, XP, skill names. 05 How relay-cache joins tables Endpoint map + query params, protobuf, /cache-health. R1 Roads terrain cache Protobuf /roads/* API — health, catalogs, region map, hex resources. R2 Region map format Grid layout, coordinates, terrain/overlay bit-packing, ETag caching. R3 Hex resource lookup POST /roads/region/<id>/resources — harvestables on 1–16k tiles. 06 If it fails /health checks, 502, 90s resets, common mistakes.

Global vs regional

Regional (3000 + N, relay-mirror-bcN) holds live world state for that BitCraft region — players, claims, inventories. Global (:3000, relay-mirror-bc-global) is the shared/reference mirror. Cross-region HTTP searches (/player?name=, /claim?name=, /deposits) already span every regional cache shard. Details: Connect.

What you are connecting to

Each BitCraft region (and global) runs as its own relay instance. The port is the region: region N listens on 3000 + N; global is 3000.

Piece Value
Host wss://relay.bitcraftsync.app:<port>
Port 3000 (global) or 3000 + regionID (e.g. region 14 → 3014)
Database (mirror) relay-mirror-bc-global / relay-mirror-bc<N>
Subscribe URL …/v1/database/<mirror>/subscribe?compression=None
Schema URL https://relay.bitcraftsync.app:<port>/v1/database/<mirror>/schema?version=9

Live ports and mirror names are listed on the home page (from /health). Prefer those over hard-coding — the fleet changes when regions are added.

Your client │ wss://relay.bitcraftsync.app:3014/…/subscribe ▼ Frontend proxy F (v1 / v2 negotiation, metrics) │ loopback ▼ Local SpacetimeDB L (mirror module relay-mirror-bc14) ▲ │ relay_apply_* writes Relay R ←── single upstream sub to BitCraft region 14

Recommended client path

  1. Pick a region from / or /health.
  2. Fetch schema over HTTPS (codegen / inspect table names).
  3. Open a WebSocket with v2.bsatn.spacetimedb (or v1 if your SDK needs it).
  4. Subscribe sequentially for large table sets — wait for each SubscribeApplied before the next query set.
  5. For enriched claim/player views without joining yourself, call the public HTTP cache (/claim, /player, …).