Structs Intel

Information is the cheapest weapon in Structs — queries are free and instant. Before you commit hours of proof-of-work to a raid or a build, scout. The most valuable single fact in v0.18.0 is whether a target’s Command Ship is offline or destroyed: a planet can only be raided to completion while its shields are vulnerable (see structs-combat). Intel that isn’t written down dies with your context window — persist it to memory/intel/.

Conventions are in conventions.md. Everything here is read-only (queries) — no transactions, no charge, no risk.

When to use it

Decisions

Scout before you commit. A raid is ~hours of PoW; a single query tells you if it’s even possible. Always check, in order:

  1. Shield vulnerability — is the owner’s Command Ship offline/destroyed? If not, the raid cannot complete. Stop here.
  2. Defenders — Planetary Defense Cannons, Tanks, generators (armoured: damage-reduction 1), shield contribution. Can your fleet out-damage the defense within the vulnerability window?
  3. Reward — unrefined ore on the planet (stealable) vs. your cost. Refined Alpha can’t be raided.
  4. Power — is the target online at all? An offline player can’t react but also may have little worth taking.

Read playstyle, then counter it. Map observations to an archetype with playbooks/meta/reading-opponents and pick a response from playbooks/meta/counter-strategies.

Freshness matters. Power/fleet state changes block-to-block; a “vulnerable” reading minutes old may be stale. Re-scout immediately before fleet-move on a raid.

Procedure

1. Target a player/planet

structsd query structs player [player-id]
structsd query structs planet [planet-id]
structsd query structs struct-all-by-planet [planet-id]   # defenders, generators, Command Ship
structsd query structs player-charge [player-id]          # are they accumulating to act?

Determine: Command Ship online? defenders & armour? ore present? Use scout.sh for a one-shot bundle when available.

2. Profile a guild

structsd query structs guild [guild-id]
structsd query structs reactor [reactor-id]               # commission, total infusion = strength
structsd query structs guild-membership-all-by-guild [guild-id]

3. Survey the galaxy

structsd query structs planet-all
structsd query structs guild-all
structsd query structs reactor-all
structsd query structs provider-all                       # market pricing/supply

4. Persist to memory

Write structured findings to memory/intel/ so the next session inherits them. Suggested shape:

// memory/intel/targets/<player-id>.json
{
  "playerId": "1-42",
  "scoutedAtBlock": 1284551,
  "commandShipOnline": false,
  "shieldsVulnerable": true,
  "defenders": [{ "id": "5-310", "type": "Planetary Defense Cannon", "hp": 6 }],
  "orePresent": 1200,
  "guildId": "0-7",
  "archetype": "turtle",
  "notes": "CS offline 3+ checks; raid window open"
}

Keep a memory/intel/galaxy.json for guild/market snapshots and memory/intel/targets/ per-target files. Record the block height with every reading so staleness is obvious. Memory schema conventions: memory/README.

Advanced: Guild Stack (PostgreSQL)

The CLI is enough for targeted scouting, but galaxy-wide or repeated intel is far faster against the Guild Stack’s Postgres mirror — sub-second joins across all planets/structs/players. Deploy via structs-guild-stack; schema and query patterns in knowledge/infrastructure/database-schema. Typical wins: “all planets with ore and an offline Command Ship,” “defenders by planet,” “providers sorted by price.” Pair with structs-streaming (GRASS) for live fleet/raid/attack events instead of polling.

Query catalog (read-only)

Target Command
Player structsd query structs player [id] / player-charge [id]
Planet structsd query structs planet [id] / planet-all
Structs on a planet structsd query structs struct-all-by-planet [planet-id]
Struct detail structsd query structs struct [id]
Guild structsd query structs guild [id] / guild-all
Guild members structsd query structs guild-membership-all-by-guild [guild-id]
Reactor structsd query structs reactor [id] / reactor-all
Provider / market structsd query structs provider [id] / provider-all
Fleet structsd query structs fleet [id]
Substation / power structsd query structs substation [id]

Requires structsd on PATH (no key needed for queries).

Verification

Intel is only as good as its freshness. Confirm a raid window by re-running struct-all-by-planet + the owner’s Command Ship status immediately before acting, and compare the new block height to your stored scoutedAtBlock.

Errors

See also