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 — every resource type on 1–16k tiles. B1 Bit-Me app API & BMR1/BME1 maps JSON polling endpoints + the packed 400×400 BMR1 resource window format and its resources/ws live change stream. 06 If it fails /health checks, 502, 90s resets, common mistakes.

Global vs regional

Regional (3000 + N, bitcraft-live-N) holds live world state for that BitCraft region — players, claims, inventories. Global (:3000, bitcraft-live-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) bitcraft-live-global / bitcraft-live-<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 bitcraft-live-14) ▲ │ 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 — the default protocol; it is the only one that carries the event tables (market_trade_event, craft_event, …) as insert-only EventTable frames. v1 still works for state tables 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, …).