Roads terrain cache

The /roads/* HTTP API serves dense per-region terrain grids, paving overlays, global paving/terraform catalogs, and a hex-list harvestable lookup as protobuf only (Accept: application/x-protobuf). It is separate from the JSON-friendly /claim / /player relay-cache API documented in relay-cache joins, though both are fed by the same embedded mirror process on the relay host.

Protobuf only. These routes do not emit JSON. Download schemas from /proto (roads_cache.proto, roads.proto) and decode with your language’s protobuf runtime. Wire types match the bitcraft-roadd client.

What it provides

For each live BitCraft region the cache maintains:

A super-hex terrain grid (elevation, original elevation, water level, water-body type) built from terrain_chunk_state.
A small-hex overlay grid (paving type + claim index per tile) built from paved_tile_state, claim_tile_state, claim_state, and location_state.
Global catalogs from paving_tile_desc and terraform_recipe_desc, plus region metadata from world_region_state / region_name_state.

The heavy endpoint is GET /roads/region/<id>/map, which returns one atomic RegionMapSnapshot protobuf per request (~280 MiB). See Region map format for grid layout, coordinate math, and cell bit-packing. Harvestable trees/ore/rocks are not in that snapshot — use POST /roads/region/<id>/resources with the hexes you care about (max 16 384 per request).

Recommended client workflow

Poll fleet readiness — GET /roads/health until ready is true and your target region’s state is READY (3).
Fetch region catalog — GET /roads/regions for live flags, grid coords (rx, rz), and world origins.
Load global catalogs once — /roads/paving-types and /roads/terraform-recipes (small, cache locally).
Download region map — GET /roads/region/<id>/map. Store the ETag header; on refresh send If-None-Match to receive 304 Not Modified when nothing changed. While a region is still loading the server returns 202 Accepted with an empty body.
Look up harvestables on planned tiles — POST /roads/region/<id>/resources with a protobuf ResourceQuery of world small-hex (x, z) tiles. See Hex resources.

Your client │ GET /roads/health → fleet + per-region state │ GET /roads/regions → live region list + origins │ GET /roads/paving-types, /roads/terraform-recipes ▼ GET /roads/region/14/map → RegionMapSnapshot (terrain + overlay + claim_table, ~280 MiB) ← ETag header for conditional refresh POST /roads/region/14/resources → ResourceQuery { tiles } (max 16384 world small-hexes) ← ResourcesResponse { nodes: [{x, z, resource_id}] }

Endpoint reference

Base URL: https://relay.bitcraftsync.app. All responses use Content-Type: application/x-protobuf.

Endpoint	Protobuf message	Notes
GET /roads/health	`roads_cache.RoadsCacheHealth`	Top-level `ready`, `regions_ready` / `regions_total`, `total_memory_bytes`. Each region row: `state` (idle=1, loading=2, ready=3, error=4), `connected`, timestamps, tile counts, `memory_bytes`, optional `error` string.
GET /roads/regions	`bitcraft.roads.RegionsResponse`	All known regions with `id`, `name`, `live`, grid position (`rx`, `rz`), world origin (`origin_x`, `origin_z`). Also `region_width_chunks` and `region_height_chunks` (typically 80).
GET /roads/paving-types	`bitcraft.roads.PavingTypesResponse`	Global paving catalog: `tile_type_id`, name, duration, tier, input cargo, `consumed` material stacks (`item_id`, `quantity`, `cargo` bool). Overlay cells store `tile_type_id` in bits 0–15.
GET /roads/terraform-recipes	`bitcraft.roads.TerraformRecipesResponse`	Height-difference keyed recipes: `difference`, `actions_count`, `stamina_per_action`, `time_per_action`.
GET /roads/region/<id>/map	`roads_cache.RegionMapSnapshot`	Full region snapshot. Unknown region → `404`. Still loading → `202` empty body. Ready → `200` + `ETag` header. Format details: Region map format.
POST /roads/region/<id>/resources	`roads_cache.ResourcesResponse`	Body: `ResourceQuery { repeated Hex tiles }`, max 16 384. Returns sparse `ResourceNode { x, z, resource_id }` for allowlisted forestry/mining/clay/sand nodes on those tiles (overworld only). Unknown region → `404`. Still loading → `202` empty body. Oversize / invalid protobuf → `400`. Details: Hex resources.

Protobuf schemas

Listed alongside relay_cache.proto on GET /proto:

roads_cache.proto — fleet health, region map snapshot, hex resource lookup
roads.proto — regions, paving types, terraform recipes

Example requests

# Fleet readiness (decode with roads_cache.proto)
curl -sH 'Accept: application/x-protobuf' \
  https://relay.bitcraftsync.app/roads/health -o roads-health.pb

# Region catalog
curl -sH 'Accept: application/x-protobuf' \
  https://relay.bitcraftsync.app/roads/regions -o regions.pb

# Global catalogs (cache on disk — change rarely)
curl -sH 'Accept: application/x-protobuf' \
  https://relay.bitcraftsync.app/roads/paving-types -o paving.pb
curl -sH 'Accept: application/x-protobuf' \
  https://relay.bitcraftsync.app/roads/terraform-recipes -o terraform.pb

# Full region map (~280 MiB) — save ETag from response headers
curl -sH 'Accept: application/x-protobuf' -D /tmp/headers.txt \
  https://relay.bitcraftsync.app/roads/region/14/map -o region14.pb

# Conditional refresh (replace with ETag value from prior response)
curl -sH 'Accept: application/x-protobuf' \
  -H 'If-None-Match: abc123…' -D /tmp/headers2.txt \
  https://relay.bitcraftsync.app/roads/region/14/map -o /dev/null

# Harvestables on a hex list (encode ResourceQuery as query.pb)
curl -sH 'Content-Type: application/x-protobuf' \
  -H 'Accept: application/x-protobuf' \
  --data-binary @query.pb \
  https://relay.bitcraftsync.app/roads/region/14/resources -o resources.pb

# Download .proto sources
curl -s https://relay.bitcraftsync.app/proto
curl -OJ https://relay.bitcraftsync.app/proto/roads_cache.proto
curl -OJ https://relay.bitcraftsync.app/proto/roads.proto

When to use which API. Use the wss:// mirrors when you need arbitrary tables or custom filters. Use relay-cache HTTP for enriched claim/player JSON. Use /roads/* when you need whole-region terrain and paving grids without building them yourself from terrain_chunk_state and tile tables, or when you need harvestables on a planned hex list (not a location_state subscribe).

← relay-cache joins Next: Region map format grids, coords, bit layout