Planet mechanics: explore and deplete

Purpose: AI-readable reference for Structs planet system. Lifecycle, ore depletion, exploration, charting.

Planet Lifecycle

Status	Condition
active	Has remaining ore
complete	Ore depleted (0)

Ore Depletion

When planet ore reaches 0:

Planet status becomes complete
All structs on the planet are destroyed
All fleets are automatically sent away (peace deal)
Player must explore a new planet to continue

Strategy options before depletion: Keep some ore in reserve. Move critical operations before the last ore is mined. Accept completion and rebuild elsewhere.

Starting Properties

Property	Value
maxOre	5
spaceSlots	4
airSlots	4
landSlots	4
waterSlots	4

All newly explored planets start with identical properties.

Exploration

Creates new planet with fresh ore and slots
Fleet moves to new planet
Optional planet name at explore time: planet-explore [player-id] [name] — validated before explore burns state (same rules as MsgPlanetUpdateName)
Explore does not consume the player’s charge bar
Old planet is completed and its planet structs are destroyed (explore requires ore already at 0 / status complete)
Chart new planet to reveal resource attributes before committing
Requirement (existing players): Current planet must be complete (ore depleted) before exploring AND the fleet must be onStation at the current planet, not away. Recall the fleet first if needed via fleet-move.
Requirement (first-time players): No fleet check applies — a brand-new player with no current planet can call planet-explore immediately after creation. The chain only enforces the fleet/ore checks for players who already own a planet.
Ownership: One planet per player at a time

Charting

Planet attributes queryable via planet_attribute endpoints
Resource charting informs mining strategy

Raid Vulnerability

What gets stolen: The player’s storedOre (StoredOreAttributeId on the player object). Raids seize ore from the player who owns the planet, not from the planet itself.
What is NOT at risk: The planet’s unmined buriedOre (BuriedOreAttributeId, still in the ground). LCD payloads may label both as gridAttributes.ore — they are different attributes on different objects. Unmined ore can only be extracted by an Ore Extractor — raiders cannot touch it.
Once ore is refined into Alpha Matter, it is cryptographically secure and cannot be stolen.
Fleet/CMD gate the raid, not the shield number. Raidability is IsDefenderCommandStructVulnerable() (no fleet / fleet off-station / no CMD ship / CMD destroyed / CMD offline). The displayed shield value only sets raid PoW difficulty. A planet can only be raided to completion while that predicate is true (shieldsVulnerable is the status name for an open gate). The Command Ship defends the home planet only while the fleet is on station; an off-station fleet (for example, one you sent away to raid) opens your gate. Keeping the fleet on station with the Command Ship online — and well defended — is the primary raid defense. See the raid phases in combat.md.
A raid only steals ore: A successful raid seizes all storedOre and nothing more — it does not destroy the player or their structs. Settlement is atomic at MsgPlanetRaidComplete; there is no partial-loot or refund. Killing the defender’s Command Ship opens the shieldsVulnerable window that lets the raid complete; if the defender restores or rebuilds the Command Ship before completion, the raid is rejected (shields_active). The trigger_raid_defeat_by_destruction property defeats an attacking fleet: if the raider’s Command Ship is destroyed while away from home, the raiding fleet is defeated (attackerDefeated). See combat.md — what a raid does.
Planetary defense beyond shields: The Jamming Satellite struct provides a low-orbit ballistic interceptor network that can evade incoming guided ordnance aimed at planetary structs on their own planet, regardless of ambit (evadedByPlanetaryDefenses); unguided ordnance passes through untouched. See combat.md — Other Planetary Defense Structs.
Seized ore tracking: The planet_raid table includes a seized_ore field that records the amount of ore stolen from the player during a raid.
See combat.md, resources.md