Combat mechanics: damage, raids, weapons

Purpose: AI-readable reference for Structs combat. Consolidates formulas, requirements, outcomes, and edge cases. If you only need to keep yourself alive — what a raid can take, what keeps shields up, and the minimum defensive posture — read the shorter defense.md card instead.

Combat Actions

Ambit Targeting

Combat in Structs revolves around four ambits. Each struct operates in one ambit, and each weapon can only target specific ambits. This creates a strategic mesh where fleet composition and positioning determine what you can hit and what can hit you.

The four combat ambits are Water/Land/Air/Space; none (1) is a placeholder and local (32) is the Command Ship’s “current ambit” flag (its weapon reaches whatever ambit it currently occupies).

Two ambit numberings — do not conflate. The bit values above are the reach bitmask (bit = 1 << enum) used for StructType.possibleAmbit and weapon-reach fields. Transaction messages (struct-build-initiate, struct-move) and a struct’s stored operatingAmbit use a different enum: none=0, water=1, land=2, air=3, space=4, local=5. When building or moving, pass the enum (the CLI takes the name space|air|land|water), not the bitmask number. See building.md — Ambit Encoding and api/integration-notes.md — Ambit.

Weapon Target Matrix

Which ambits each struct’s primary weapon can hit:

Threatened-By Matrix

Which structs can attack into each ambit:

The Command Ship can attack into any ambit but must first move there (see below). The Battleship’s armour-piercing primary covers Land and Water; its guided secondary reaches Space.

Targets per attack

struct-attack accepts a comma-separated list of target IDs, but how many of those targets a weapon engages is governed by that weapon’s primaryWeaponTargets / secondaryWeaponTargets value.

• Every weapon is single-target — primaryWeaponTargets = 1 on all fleet hulls, and secondaryWeaponTargets = 1 on the three hulls with a secondary (Battleship, Starfighter, Cruiser). Listing extra IDs does not let a targets = 1 weapon spread its volley across them.
• This is distinct from multi-shot (primaryWeaponShots), which is how many projectiles a weapon fires at a single target (e.g. Starfighter Attack Run = 3 shots, 1 target).

Command Ship Ambit Mobility

The Command Ship is the only struct that can change ambits (movable=true). All other structs are fixed in their operating ambit, and the chain rejects struct-move on a non-movable struct — only the Command Ship can be moved.

• Offensive use: Move the Command Ship to the target’s ambit before attacking. It can only hit structs in its current ambit.
• Defensive use: If the enemy fleet can only target water, moving the Command Ship out of water protects it from direct attack.
• CLI: structsd tx structs struct-move [cmd-ship-id] [new-ambit] [new-slot] [new-location] --from [key] --gas auto --gas-adjustment 1.5 -y

Health Points

Each struct has a Max HP that determines how much damage it can absorb before destruction.

Planetary structs are hardened so a raider cannot casually demolish a planet’s infrastructure; the power generators are the toughest (and carry armour, damage reduction 1), making a power kill a deliberate objective. Armour-piercing weapons (Battleship primary) bypass that reduction.

• Damage reduces current HP. At 0 HP the struct is destroyed (see Struct Destruction below).
• HP does not regenerate. A damaged struct stays damaged.
• Defenders absorb attacks directed at the struct they protect — the protected struct only takes damage after the defender is destroyed or fails to block.

Damage Formulas

Multi-Shot Damage

damage = sum(successful_shots) - damageReduction
if damage >= health then health = 0
else health = health - damage

Algorithm: For shot index i in 0..weaponShots, the shot hits if i < weaponGuaranteedShots OR IsSuccessful(weaponShotSuccessRate). The first weaponGuaranteedShots shots are auto-hits; only the remaining shots roll against the success rate. Sum the damage from successful shots, then apply damageReduction (unless the weapon is armour-piercing, in which case reduction is skipped). Minimum damage after reduction is 1. Cap at target health.

Armour-piercing: A weapon flagged armour-piercing negates the target’s damage reduction during volley resolution. The Battleship’s primary is armour-piercing — it deals full damage to Tanks and to power generators (which otherwise reduce incoming damage by 1). Each shot’s piercing is reported on EventAttackShotDetail.armourPiercing.

Why guaranteed shots exist: A weapon with shots=3 and successRate=1/3 has the same expected value as a single guaranteed hit, but its variance is much higher — most attacks would deal zero damage. Setting guaranteedShots=1 floors the damage at one hit per volley while preserving the upside of the other rolls. Guaranteed shots apply only to the Starfighter Attack Run (secondary weapon, secondaryWeaponGuaranteedShots = 1); other weapons leave the field at 0, which means “no guarantee, all shots roll”.

Querying note: primaryWeaponGuaranteedShots / secondaryWeaponGuaranteedShots are omitempty in the chain’s JSON output. Because the value is 0 for every struct type except the Starfighter secondary, the field is omitted entirely from most struct_type query responses. A payload with no guaranteed-shots key means the value is 0, not that the field was removed from the chain. (Verified present in current structsd source.)

Attack results: Attack events include health results (remaining health after attack) in addition to damage amounts.

Evasion

if weaponControl == guided then successRate = guidedDefensiveSuccessRate
else successRate = unguidedDefensiveSuccessRate
canEvade = IsSuccessful(successRate) if successRate.Numerator != 0

Weapon Control vs Defense Type

The interaction between a weapon’s control type (guided/unguided) and the target’s defense type is the core of combat tactics. This matrix determines whether shots can be evaded:

Tactical takeaways: Use unguided weapons against Signal Jamming targets (Battleship, Pursuit Fighter, Cruiser). Use guided weapons against Defensive Maneuver targets (High Alt Interceptor). Armour reduces damage by 1 regardless of weapon control — except against armour-piercing weapons (Battleship primary), which ignore it entirely. The Battleship is the dedicated answer to Tanks and to armoured power generators.

Stealth

Stealthed structs (Stealth Bomber, Submersible) are not invisible – they can still be targeted by structs in the same ambit. Stealth blocks cross-ambit targeting only. A stealthed Submersible (water) can be attacked by other water structs, but air/land/space structs cannot target it.

• Attacking breaks stealth: When a stealthed struct attacks, its stealth is instantly deactivated (firing reveals position).
• Re-activation: Stealth must be manually re-activated after deactivation. Costs 2 charge (from the player’s shared charge bar).
• Activation: struct-stealth-activate [struct-id] (2 charge). Deactivation: struct-stealth-deactivate [struct-id].

Recoil Damage

Attacker takes damage after firing: health = health - weaponRecoilDamage. Recoil only applies if the attacker survives the entire shot sequence (including counter-attacks).

Post-Destruction Damage

If health == 0 and postDestructionDamage > 0, damage applies to surrounding structs.

Assigning Defenders (struct-defense-set)

Only structs whose type has canDefend: true can be assigned. That is every fleet type (Command Ship through Submersible, IDs 1–13). Every planetary type (Ore Extractor through World Engine, IDs 14–22) has canDefend: false and is rejected (StructCannotDefend) — an Ore Bunker cannot be used as a block.

Assignment then checks that the defender is co-located with the protected struct (same planet or fleet) and is built and online — an offline or still-building struct is rejected. Ambit does not gate assignment; it gates what the defender can do once an attack lands:

• A same-ambit defender can block (soak a hit meant for the protected struct) and can counter.
• A cross-ambit defender cannot block, but still counters whenever its weapon reach includes the attacker’s ambit.

So assigning a water Submersible to defend a land struct is valid and useful: it will counter air/space-reachable attackers even though it can never block for the land struct. Spread defenders across ambits to widen counter coverage, and keep same-ambit defenders where you need actual damage interception. There is no per-ambit cap on how many structs can defend (see Edge Cases).

Blocking

if !evaded and defender exists and defender.operatingAmbit == target.operatingAmbit then
  if weapon.blockable and defender.ReadinessCheck() then
    canBlock = IsSuccessful(defender.blockingSuccessRate)

Requirements (all must be true):

1. The shot was NOT evaded – block does not fire on evaded shots
2. Weapon must be blockable (GetWeaponBlockable returns true)
3. Defender must pass ReadinessCheck – struct online AND owner online
4. Defender must be in the same ambit as the target being defended (not the attacker)

A struct cannot block for a friendly in a different ambit. Blocking is strictly same-ambit defense. Unlike counter-attacks, block is attempted on every shot (not limited to once per attack).

Counter-Attack

Each struct can counter-attack at most once per struct-attack invocation. Counter-spent state is tracked per struct per attack command (not per target, not per shot). For a 3-shot Attack Run: the defender counters on the first shot only, but can attempt to block all 3 shots. The target counters once after all shots resolve.

Counter-attacks are ambit-independent from the defended target. A space-based defender can counter-attack a space-based attacker even while defending a land-based struct. Defenders do not take counter-attack damage — only the original attacker and target can be damaged by counters.

Range rule: A struct on a fleet that is away from the home planet cannot defend planetary structs at that planet. Only on-station fleet structs (canDefend: true) can defend their home planet. Planetary structs cannot be assigned as defenders.

Counter damage comes from two per-type fields, not a flat number: counterAttackSameAmbit (when the counter-attacker shares the attacker’s ambit) and counterAttack (when it does not). Most hulls are 1 / 1; the Command Ship is 2 / 2; the Destroyer is 1 / 2 (cross / same). See struct-types.md — Defensive Properties for the per-type values.

Counters are a backstop, not a damage plan. The values are small (typically 1), and an attacker striking from an ambit your structs can’t reach takes no counter at all. Real damage comes from active struct-attack volleys — build offense around attacking from a safe ambit, not around baiting counters.

Requirements (all must be true):

1. Weapon must be counterable (GetWeaponCounterable returns true)
2. Neither counter-attacker nor attacker is destroyed
3. Defender’s weapons must be able to target the attacker’s ambit (via CanCounterTargetAmbit)
4. Location reachability to the attacker:
   • If defender on planet: attacker’s fleet must be at that planet
   • If defender on fleet on-station: attacker must be reachable at the planet
   • If defender on fleet away: attacker must be on same planet or adjacent in location list

Two types of counter-attack:

• Defender counter-attack: Fires before the block attempt, once per struct-attack invocation. Fires even on evaded shots.
• Target counter-attack: Fires after all shots resolve damage against the target, once per struct-attack invocation. Destroyed targets cannot counter.

Both the defender and the target can counter-attack – an attacker may take damage from two sources per target.

Planetary Defense Cannon

damage = planetaryShieldBase + sum(defenseCannon.damage for each cannon on planet)

• Limit: 1 Planetary Defense Cannon per player
• PDC fires automatically after all targets are resolved, not as a counter-attack
• PDC does NOT counter-attack – it only auto-fires at the end of the attack sequence
• Multiple players’ PDCs on the same planet stack correctly

Other Planetary Defense Structs

Two planetary defenses are wired to structs and affect combat: the Planetary Defense Cannon and the low-orbit ballistic interceptor network (provided by the Jamming Satellite struct).

• Low-orbit ballistic interceptor network (the Jamming Satellite, type 17) — the Jamming Satellite carries noUnitDefenses; its planetary effect gives the planet a chance to evade incoming guided ordnance aimed at a planetary struct sitting on its own planet. Source and target ambit are irrelevant — the only requirements are that the target is a planetary (non-fleet) struct on its owner’s planet and the incoming weapon is guided. Unguided ordnance carries no guidance to jam and passes through untouched. On a successful evade the shot is flagged evadedByPlanetaryDefenses: true with cause lowOrbitBallisticInterceptorNetwork, dealing 0 damage. Each additional interceptor on the planet compounds the evade chance.
• Two layers protect against guided fire. The target struct’s own unit-level signalJamming defense (Battleship, Pursuit Fighter, Cruiser — 66% guided miss) is checked first; only if that does not evade does the planetary interceptor network get its separate chance. So guided attacks on a defended planet face both the per-struct field and, for planetary targets, the planetary interceptor. See Weapon Control vs Defense Type.

Two different things are called “jamming” — don’t conflate them. Both defeat only guided ordnance (unguided passes through either), but they operate at different scopes:

	Unit signalJamming	Low-orbit ballistic interceptor network
Provided by	Being a Battleship, Pursuit Fighter, or Cruiser (per-unit trait)	The Jamming Satellite struct (type 17) on the planet
Scope	Protects only the struct that has it	Protects all planetary structs on that struct’s owner’s planet
Effect	66% miss on incoming guided fire	Per-shot evade chance; stacks with each extra interceptor
Ambit	N/A (self)	Source and target ambit irrelevant
Order	Checked first	Checked second, only if the unit field didn’t already evade
Flag on evade	normal weapon-control miss	evadedByPlanetaryDefenses: true, cause lowOrbitBallisticInterceptorNetwork

Attack Resolution Sequence

When struct-attack is executed, the following steps occur in order per target:

1. Validation – Verify weapon ambits can reach target ambit. Stealthed targets are only targetable from the same ambit. Verify target struct exists.
2. Stealth break – If the attacker has stealth active, it is instantly deactivated (attacking reveals position).
3. Evasion check (per-target, not per-shot) – Evaluate weapon control (guided/unguided) vs target defense type. If evaded, ALL shots against this target miss but counters still fire.
4. Defender resolution (ResolveDefenders) – all defenders are handled in a single pass, counters first:
   • Defender counter-attacks – every ready, in-range defender counters once (if the weapon is counterable), regardless of evasion. Counter damage from multiple defenders is simultaneous from the attacker’s perspective.
   • Block is deferred – the first eligible defender in the same ambit as the target is remembered as the blocker, but the block is not applied until every counter has resolved. This is order-independent: an earlier-sorted defender can no longer absorb a volley from an attacker that a later defender’s counter destroys.
   • Survival gate – if the combined counters destroy the attacker, no block occurs and the attack is fully neutralized.
5. Attack damage (ResolveAttackDamage) – the attacker’s volley lands only if it was not blocked and the attacker is still alive. A destroyed attacker deals no damage — its entire volley is voided (a Bomber killed by a counter does not still bomb). If it fires, per-projectile success rates and armour reduction apply (minimum 1 damage per hit), unless the target evaded in step 3, in which case all shots miss.
6. Target counter-attack (once per struct-attack invocation) – fires after the volley resolves. Destroyed targets cannot counter.
7. Early termination – If the attacker is destroyed mid-sequence, remaining targets do not process.

After all targets are resolved:

1. Recoil damage – Applied to attacker if it survived all shots
2. Planetary Defense Cannon auto-fire – If any target was a planetary struct, PDCs fire against the attacker

Per-Projectile Events

Each projectile gets its own EventAttackShotDetail row. For a 3-shot Attack Run, the attack event contains 3 separate shot detail entries with per-projectile hit/miss breakdowns. targetPlayerId is on EventAttackShotDetail (not EventAttackDetail).

In the live struct_attack event detail, the attacker context is flat at the top and the per-shot rows are a nested array eventAttackShotDetail[]. See api/integration-notes.md — struct_attack event detail schema for the exact field layout integrators receive.

Key implications:

• Evasion is per-target (entire volley evaded), while shot accuracy is per-projectile
• Both the defender and the target can counter-attack – an attacker may take damage from two sources per target
• Each struct counters at most once per struct-attack invocation, regardless of how many shots or targets
• Counter-attacks fire even on evaded shots (defender counter) – only block is suppressed by evasion
• All defender counters resolve before any block; if they destroy the attacker, its volley deals no damage and no block is needed
• If the attacker is destroyed during the target loop, remaining targets do not process
• PDC fires against any attacker of planetary structs, not only during raids

Requirements

An attack action depends only on the attacking struct (and its owner) being online — the attacker’s Command Ship does not need to be online, and the same holds for defensive changes (struct-defense-set) and stealth changes. The target must be a built struct; struct-attack against a struct that is still building is rejected (unbuilt), and a destroyed struct is rejected (destroyed). The target’s online status is irrelevant.

Visiting-fleet queue

A planet holds at most 1 + locationListExtra visiting fleets. locationListExtra defaults to 0, so capacity is one raider. The owner’s home fleet does not consume a slot. A fleet-move onto a foreign planet that is already at capacity is rejected (queue_full). The owner’s mine and refine proofs are rejected (under_raid) for as long as locationListStart is set.

Query locationListStart, locationListLast, locationListCount, and locationListExtra on the planet. First-in-queue (LocationListForward == "" on the raiding fleet) is still required to complete a raid — with default extra=0, the only visitor is first.

Note: planet-raid-complete does not consume charge (it is a proof-of-work message, not a charge message). Direct struct-attack does consume the player’s charge.

Raid Phases and SHIELDS_VULNERABLE

A raid cannot eliminate a player — the only prize is stored ore. No matter how one-sided the outcome, a successful raid seizes the defender’s unrefined stored ore and nothing more: it does not destroy the player, take their planet, capture structs, or touch refined Alpha Matter. Refined Alpha is untouchable; refine promptly and a raid can win you nothing. (This is the single most common combat misconception — treat raids as ore theft, not conquest.)

A raid is only winnable while the defending planet’s shields are vulnerable. Shields are vulnerable whenever the defender’s fleet is off-station (the Command Ship only defends the home planet while the fleet is on station), or the defender’s Command Ship is offline, destroyed, or non-existent. While the defender’s fleet is on station with a built, online Command Ship, the planet’s shields are up and planet-raid-complete is rejected (shields_active) no matter how much work the raider does. The single most effective raid defense is therefore keeping your fleet on station with the Command Ship online — and note that sending your own fleet away to raid someone else leaves your planet’s shields vulnerable until it returns.

This predicate is the chain function IsDefenderCommandStructVulnerable() (verified in structsd source, keeper/planet_cache.go): it returns vulnerable when the owner has no fleet, the defender’s fleet is off-station, there is no Command Ship, or the Command Ship is destroyed or offline. (Struct/player online is pure power math — load vs capacity — not recent activity; see power.md.)

Vulnerability is a state you can create — two ways to raid

The single biggest raid misconception is treating “shields vulnerable” as a fixed property to hunt for. It is a state, and you can put a defender into it. There are two modes:

• Opportunistic raid — the defender is already vulnerable when you scout (their fleet is off-station, or their Command Ship is already offline/destroyed/absent). You move in and grind the PoW. Cheap, but genuinely-vulnerable targets holding ore are rare.
• Siege raid (force vulnerability) — the defender is shielded (Command Ship online, fleet on station), so you manufacture the window: strip same-ambit blockers, destroy the defender’s Command Ship, and complete the raid before they rebuild it. Destroying (or power-starving) the Command Ship is the intended lever — see Raid attack doctrine below.

stateDiagram-v2
    [*] --> shielded: CMD ship online + fleet on station
    shielded --> vulnerable: defender fleet leaves / CMD ship offline / CMD ship destroyed
    vulnerable --> shielded: CMD ship back online with fleet on station (clock clears)
    vulnerable --> raidSuccessful: raider completes PoW while clock runs
    note right of shielded
        planet-raid-compute is rejected here
        ("no active raid window"); blockStartRaid = 0
    end note
    note right of vulnerable
        blockStartRaid running; PoW age accrues
    end note

Idle is not vulnerable

A dormant owner (no transactions for days) is not the same as a vulnerable one. A player who set up correctly and walked away keeps their structs powered, so their Command Ship stays online and their fleet stays on station — IsDefenderCommandStructVulnerable() returns false and the planet is unraidable by the opportunistic path, no matter how long they’ve been idle. Do not infer raidability from an inactivity signal (or from a UI “vulnerable”/”inactive” badge). Gate on the live predicate: Command Ship online + fleet on station.

The flip side is the key insight for offense: a dormant owner is the ideal siege target. Because they are not watching, they will not rebuild a destroyed Command Ship or restore a power-starved one — so once you force the window open it stays open. An active defender, by contrast, may rebuild the Command Ship and slam the window shut.

The trap (a strictly-negative move). Moving your fleet to a not-yet-vulnerable target and expecting to raid is worse than doing nothing: your fleet is now off-station, so your own shields drop and your stored ore is exposed — all for a raid that can never complete until you also destroy their Command Ship. If you commit your fleet, commit to the siege (destroy the Command Ship), not just the fleet-move.

The blockStartRaid attribute is the vulnerability clock, and raid PoW age is measured from it:

• The clock is only meaningful while a raider is present (the planet’s raid slot is occupied). It is set to the current block when the planet becomes vulnerable with a raider present — either raiders arrive to find it already vulnerable (opportunistic), or the defender’s Command Ship goes down while raiders are there (siege). The chain recomputes this on every relevant change via RefreshRaidVulnerability().
• Cleared (back to 0) when the planet stops being vulnerable (the Command Ship comes back online with the fleet on station), and when the raid ends. With the clock at 0, raid completion is rejected (raid_clock_unset).

So a raider must have their fleet at the target, catch (or make) the defender vulnerable, and let the clock age before the puzzle becomes solvable. If the defender restores their shields mid-raid (Command Ship back online with the fleet on station), the clock resets and the raid status flips to ongoing until the planet becomes vulnerable again.

The two rejection messages (don’t confuse them)

The tooling surfaces the vulnerability gate in two different places with two different strings — verified in structsd source:

Both point at the same fix: the defender is not vulnerable. Either wait/watch for them to slip (opportunistic), or open the window yourself by destroying their Command Ship (siege). Neither means “grind harder.”

One message, two independent gates. blockStartRaid is set only by RefreshRaidVulnerability(), which returns early unless GetLocationListStart() != "" (a raider is present). So blockStartRaid == 0 — and the single no active raid window string — collapses two independent conditions: (1) a raider is present at the target, and (2) the defender is vulnerable. If you have not moved your fleet in yet, the clock is 0 for reason (1), not (2); moving in against a shielded defender then flips the reason to (2) but the clock still stays 0. Completion (planet-raid-complete) adds two more gates the compute message doesn’t mention: your raiding fleet must be first in the queue (LocationListForward == "") and your player online. Read “no active raid window” as “one of {raider-present-and-first-in-queue, defender-vulnerable} is not yet true,” not as a hashing problem.

Raid statuses

Status values are the RaidStatus_* enum emitted on EventRaid. The most a defender loses to a raid is all of their stored ore (raidSuccessful).

Raid status also includes seizedOre – a convenience figure for the ore stolen, surfaced on the planet_raid record. For an authoritative count, derive it from ledger rows with action = 'seized' (which also record 0-gram seizures). See schemas/entities/planet.md for the planet_raid table schema.

What a raid does

A successful planet-raid-complete seizes all of the defender’s storedOre, sends the raider’s fleet home, and emits raidSuccessful. Ore is the only thing a raid takes — a raid does not destroy the defending player or their structs.

Destroying the defender’s Command Ship (or catching their fleet off-station) makes the planet’s shields vulnerable (shieldsVulnerable), which is the condition that lets a raid complete. If the defender restores their shields before completion — Command Ship back online with the fleet on station — the shields return and planet-raid-complete is rejected with shields_active. So the planet is either vulnerable at completion — and the raider takes all the ore — or shielded, and the raid is rejected.

trigger_raid_defeat_by_destruction is a property of the Command Ship. When a Command Ship is destroyed while away from home (its planet’s owner differs from its own owner), its fleet is defeated: the raid ends with attackerDefeated and the fleet is sent home. This defeats an attacking fleet whose Command Ship dies during a raid.

Raid attack doctrine

This is the siege path — how to force the window open when the defender is shielded. It is executable at the source level: an away raiding fleet that is first in the target’s raid queue can attack any struct on that planet, including the on-station defender’s Command Ship (isReachable, verified in keeper/struct_cache.go), subject to ambit reach and same-ambit blockers.

1. Move your fleet to the target (raid initiated). A foreign planet holds one visiting fleet by default — if someone is already parked, fleet-move is queue_full. While the defender is still shielded, blockStartRaid stays 0 and planet-raid-compute is rejected — this is expected; do not grind yet.
2. Strip same-ambit blockers so your attacks reach the Command Ship (cross-ambit defenders counter but cannot block — see Blocking).
3. Destroy the defender’s Command Ship to open the shieldsVulnerable window. The destruction path fires CommandStructRaidStatusHook() → RefreshRaidVulnerability(), which starts the clock and emits shieldsVulnerable because your raider is already present.
4. Run planet-raid-compute now that the clock is running, and complete while it is down to seize all stored ore.
5. Expect an online defender to rebuild the Command Ship — a destroyed Command Ship can be rebuilt (see Struct Destruction), which shuts the window. Sieges are most reliable against an offline or dormant defender who cannot/will not restore it.

Cost of a siege. It is a real commitment, not a free option: you must win the fleet engagement to kill the Command Ship (6 HP, usually defended), and while your fleet is away your own planet’s shields are down. Weigh the defender’s storedOre (all of which you seize) against that exposure and the risk your raiding Command Ship dies while away (attackerDefeated, trigger_raid_defeat_by_destruction). Small ore + a defended Command Ship often means “watch and wait” beats “siege.” But a dormant target holding meaningful ore, whose Command Ship you can reach, is exactly what a siege is for.

What the outcome data says

Everything above is derivable from the source. It is also confirmed by outcomes: roughly 300 raid episodes reconstructed from planet_activity (92k events, 2026-03 → 2026-07), used to tune the Desktop auto_raid loop. Four findings are worth internalizing before you raid anyone.

Vulnerability is not an edge, it is the entire game. Since the current mechanic landed on 2026-06-15, raids that reached shieldsVulnerable went 69 successful vs 7 retreats. Raids that never saw it went 0 successful vs 50 retreats — not “unlikely,” zero. This is why the shield-vulnerability doctrine is stated as a hard gate rather than a preference, and why moving a fleet onto a healthy planet is strictly self-harm: it drops your own shields for a raid that cannot complete.

Shield strength does not predict the outcome. Successful raids faced an average shield of 127.9; retreats faced 111.5. Both span 25–325. Shield is a timer, not armor — it sets the raid proof’s difficulty range. Score a target’s shield as speed, never as strength, and never skip a rich target because its shield number looks big.

Loot is a lottery with a fat tail. 123 successful raids yielded 1,336 ore in total, but the median haul was 1 and 52 of them seized nothing at all. Nine raids carried 74% of all ore ever stolen. Since a raid risks a Command Ship that costs far more than one ore, a minimum-ore threshold is not optional — below it you are taking an unpriced risk for a rounding error.

The attacker’s own risk is badly underrated. Across 22 raids by one well-instrumented operator: 2 wins, 11 retreats, and 9 attackerDefeated — a 41% loss rate against an ecosystem baseline near 5%, every one of them their primary’s Command Ship dying in the field. Raiding with the account you cannot afford to lose is the single most expensive habit in the data. If you run multiple players, raid with an expendable one.

Edge Cases

• Raid loot: Only the player’s mined ore (storedOre) can be stolen – not unmined ore on the planet (its gridAttributes.ore). Alpha Matter is secure. A successful raid seizes all of the target player’s storedOre, not a partial amount. One raid = total loss.
• Success rate: IsSuccessful uses hash(blockHash, playerNonce) % Denominator < Numerator
• Damage overflow: Post-destruction damage carries over to adjacent structs
• Blocking: Defender must be in the same ambit as the target being defended to block. Block does NOT fire on evaded shots. Counter-attacks are separate – they require the defender’s weapons to reach the attacker’s ambit.
• Minimum damage: After damage reduction, minimum damage is 1 – attacks always deal at least 1 damage
• Offline counter-attack: Offline/destroyed structs cannot counter-attack
• Counter-attack limit: Each struct can counter-attack at most once per struct-attack invocation. For multi-shot weapons (Attack Run with 3 projectiles), the defender counters on the first shot only but can attempt to block all 3 shots. The target counters once after all shots.
• Counter on evaded shots: Defender counter-attacks fire even when the shot is evaded. Only the block attempt is suppressed by evasion.
• EvadedCause: Only set on successful evasion. Not populated on failed evasion attempts.
• Target validation: Target struct existence is validated before attack proceeds
• Defense vs ore: Defensive posture protects structs from being destroyed during raids, but does NOT prevent ore seizure. Defense saves your structures; only refining saves your ore.
• PDC stacking: Multiple players’ Planetary Defense Cannons on the same planet stack correctly.
• No defender cap: there is no per-ambit limit on how many fleet structs can defend another — defense-set checks canDefend, co-location, built, and online, and attack resolution iterates every registered defender. Planetary types cannot be assigned. The planet’s slot structure provides 4 slots per ambit, which caps how many structs can exist per ambit, not how many can defend.
• No charge banking before an attack: Charge cannot be stockpiled for an alpha-strike. Any charge-consuming action resets the player’s shared bar to 0 and it only refills linearly (~1/block); you cannot “burst” multiple expensive attacks back-to-back. See building.md — Charge Accumulation.

Struct Destruction

When a struct reaches 0 HP, it is destroyed and removed from the game. The destroyed instance is gone forever and cannot be repaired. However, you can build a new struct of the same type as a replacement — full build PoW required.

FAQ: Can I rebuild a destroyed Command Ship?

YES. A destroyed Command Ship cannot be repaired, but you can build a brand new Command Ship (type 1) to replace it. The new Command Ship gets a new struct ID and requires full build PoW (~17 min at D=3). You choose the starting ambit at build time.

Until the replacement is online, the fleet cannot move, raid, or build in space. This downtime is the real cost of losing a Command Ship. Always assign defenders to protect it via struct-defense-set before engaging in offensive operations.

See Also

• defense.md — Survival quick card condensed from this page
• resources.md — Ore vs Alpha Matter security
• power.md — Power requirements for combat
• fleet.md — Fleet status for raids
• building.md — Status field (numeric) — Canonical decoder for the numeric struct status bitmask (e.g. 35 = destroyed)
• schemas/formulas.md — Verified formula definitions
• reference/action-quick-reference.md — Combat action endpoints
• protocols/action-protocol.md — Transaction flow