Hex resource lookup

POST /roads/region/<id>/resources returns resource nodes on a list of small-hex tiles in one region — every resource type (trees, ore, clay, sand, mushrooms, berry bushes, fiber plants, flowers, event resources, hexite nodes, …), served from the region's dense resource tile map. It is a point lookup, not a region dump: send the hexes your planner already has (typically 1–16 384), get back sparse ResourceNodes. Schema: roads_cache.proto.

HTTP semantics

Protobuf on both sides. Send Content-Type: application/x-protobuf and Accept: application/x-protobuf. There is no JSON variant.

Protobuf messages

From roads_cache.proto (package roads_cache):

message Hex {
  int32 x = 1;
  int32 z = 2;
}

message ResourceQuery {
  repeated Hex tiles = 1;          // max 16384
}

message ResourceNode {
  int32 x = 1;
  int32 z = 2;
  int32 resource_id = 3;           // resource_desc.id
  // resource_state.direction_index of the owning resource (0..=5).
  uint32 direction = 4;
  // True when this tile is the resource's anchor (origin) tile.
  bool origin = 5;
}

message ResourcesResponse {
  repeated ResourceNode nodes = 1; // sparse; omitted hexes had no match
}

• x / z are world small-hex coordinates — the same space as location_state.x/z and the overlay grid in Region map format (not region-local lx/lz).
• Duplicate hexes in tiles are ignored after the length check (first occurrence wins).
• direction (0–5) and origin let clients reconstruct whole resource instances from per-tile rows: origin tiles anchor an instance of the direction-rotated resource_desc.footprint.
• At most one node per hex: the tile map keeps a single resource per tile. Multi-hex shapes win shared tiles; a single-hex newcomer (e.g. a forageable spawned under a tree) is not stamped on an already-occupied tile.
• Hexes outside this region, or with no resource, produce no row — not a sentinel.

What is indexed

The response comes from a dense per-region resource tile map (one u16 word per odd-r tile across the whole 7680×7680 grid), stamped server-side from resource_desc.footprint × direction for every resource_state row joined to an overworld (dimension = 1) location. There is no allowlist anymore:

resource_id matches resource_desc.id (and resource.json id). This API does not return names. Hexite claims with parsed coordinates remain available in the friendlier GET /deposits view.

Example (Python)

Generate stubs from /proto/roads_cache.proto (protoc --python_out=.), then:

import requests
from roads_cache_pb2 import ResourceQuery, ResourcesResponse

REGION = 14
# World small-hex, same space as location_state / overlay.
# Region 14 origin is (23040, 15360); these two tiles sit on that origin.
query = ResourceQuery()
query.tiles.add(x=23040, z=15360)
query.tiles.add(x=23041, z=15360)

r = requests.post(
    f"https://relay.bitcraftsync.app/roads/region/{REGION}/resources",
    data=query.SerializeToString(),
    headers={
        "Content-Type": "application/x-protobuf",
        "Accept": "application/x-protobuf",
    },
    timeout=30,
)
r.raise_for_status()
if r.status_code == 202:
    raise RuntimeError("region still seeding; retry after /roads/health READY")

resp = ResourcesResponse()
resp.ParseFromString(r.content)
for n in resp.nodes:
    print(n.x, n.z, n.resource_id, n.direction, n.origin)

With a pre-encoded body file:

# query.pb is a serialized roads_cache.ResourceQuery
curl -sS -H '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 -w '%{http_code}\n'
# 200 → decode resources.pb as ResourcesResponse
# 202 → empty body, region not ready
# 400 → too many tiles or invalid protobuf

Client workflow

1. Wait until GET /roads/health reports your region READY (same gate as the map snapshot).
2. Collect the odd-r small-hex tiles on the planned path (world x, z). Chunk requests at 16 384.
3. POST one ResourceQuery per chunk to /roads/region/<id>/resources.
4. Resolve resource_id to names/tags via your local resource.json / resource_desc catalog, or fetch GET /bitme/region/<region>/resource-dictionary (per-resource name + harvestable flag + gamedata).