Structs Power

SKILL.md

---
name: structs-power
description: Manages power infrastructure in Structs. Covers substations, allocations, player connections, and power monitoring. Use when power is low or overloaded, creating or managing substations, connecting players to substations, allocating capacity, diagnosing offline status, or planning power budget for new structs.
---

# Structs Power

**Important**: Entity IDs containing dashes (like `3-1`, `4-5`) are misinterpreted as flags by the CLI parser. All transaction commands in this skill use `--` before positional arguments to prevent this.

## Safety

Power operations cascade. Deleting an allocation can take an entire substation's worth of players offline. See [SAFETY.md](https://structs.ai/SAFETY) for the trust contract; in this skill:

- **`allocation-delete`** (Tier 2 — cascade) — *"Power stops flowing immediately. Substations downstream lose capacity; their players may go offline mid-build, mid-mine, mid-fight."*
- **`substation-delete`** (Tier 2 — cascade) — *"Disconnect allocations and players first. A failed delete still leaves the substation in an awkward state."*
- **`substation-player-disconnect`** (Tier 1) — *"You may take another player offline. If they're mid-compute, the auto-submit will fail. Coordinate before disconnecting."*
- **`substation-player-migrate`** (Tier 1, Tier 2 if multiple players) — *"Bulk move. Confirm every player in the list belongs in the new substation."*
- **`allocation-create`**, **`substation-create`** (Tier 1) — routine; surface source, power amount, controller.

## Procedure

1. **Assess power state** — Query player: `structsd query structs player [id]`. Compute: `availablePower = (capacity + capacitySecondary) - (load + structsLoad)`. If `load + structsLoad > capacity + capacitySecondary`, player goes **OFFLINE** (cannot act). Player passive draw: 25,000 mW.
2. **Create substation** — First create allocation from reactor/generator: `structsd tx structs allocation-create --allocation-type static|dynamic|automated|provider-agreement TX_FLAGS -- [source-id] [power]`. The `--controller` flag accepts a **PlayerId** (e.g., `1-42`). If omitted, the creating player is the default controller. Then: `structsd tx structs substation-create TX_FLAGS -- [owner-id] [allocation-id]`.
3. **Connect power** — `structsd tx structs substation-allocation-connect -- [substation-id] [allocation-id]` to add source. `structsd tx structs substation-allocation-disconnect -- [substation-id] [allocation-id]` to remove.
4. **Connect players** — `structsd tx structs substation-player-connect -- [substation-id] [player-id]` to draw power. `structsd tx structs substation-player-disconnect -- [substation-id] [player-id]` to remove.
5. **Migrate players** — `structsd tx structs substation-player-migrate TX_FLAGS -- [source-substation-id] [dest-substation-id] [player-id,player-id2,...]`.
6. **Manage allocations** — Update: `structsd tx structs allocation-update -- [allocation-id] [new-power]`. Delete: `structsd tx structs allocation-delete -- [allocation-id]`.
7. **Delete substation** — `structsd tx structs substation-delete -- [substation-id]` (disconnect allocations/players first).

## Commands Reference

| Action | Command |
|--------|---------|
| Substation create | `structsd tx structs substation-create -- [owner-id] [allocation-id]` |
| Substation delete | `structsd tx structs substation-delete -- [substation-id]` |
| Allocation connect | `structsd tx structs substation-allocation-connect -- [substation-id] [allocation-id]` |
| Allocation disconnect | `structsd tx structs substation-allocation-disconnect -- [substation-id] [allocation-id]` |
| Player connect | `structsd tx structs substation-player-connect -- [substation-id] [player-id]` |
| Player disconnect | `structsd tx structs substation-player-disconnect -- [substation-id] [player-id]` |
| Player migrate | `structsd tx structs substation-player-migrate -- [src-substation-id] [dest-substation-id] [player-ids]` |
| Allocation create | `structsd tx structs allocation-create --allocation-type [type] -- [source-id] [power]` |
| Allocation update | `structsd tx structs allocation-update -- [allocation-id] [power]` |
| Allocation delete | `structsd tx structs allocation-delete -- [allocation-id]` |

**TX_FLAGS** (interactive — the CLI prompts you to confirm): `--from [key-name] --gas auto --gas-adjustment 1.5`

**TX_FLAGS_APPROVED** (only after commander approval; suppresses the prompt): TX_FLAGS plus `-y`. See [SAFETY.md](https://structs.ai/SAFETY) "The `-y` Rule." Power operations cascade — default to interactive even on routine ops.

**Requires**: [`structsd`](https://structs.ai/skills/structsd-install/SKILL) on PATH and a configured signing key.

## Verification

- **Player**: `structsd query structs player [id]` — `capacity`, `capacitySecondary`, `load`, `structsLoad`, online status.
- **Substation**: `structsd query structs substation [id]` — connected allocations, players.
- **Allocations**: `structsd query structs allocation-all-by-source [source-id]`, `allocation-all-by-destination [dest-id]` — power flow.

## How to Increase Capacity

If capacity is too low (or you're going offline), there are three paths:

| Method | Requires | Speed | Risk | Rate |
|--------|----------|-------|------|------|
| Reactor infusion | Alpha Matter | Immediate | Low | 1g ≈ 1 kW (minus commission) |
| Generator infusion | Alpha Matter + generator struct | Immediate | High (irreversible, raidable) | 1g = 2-10 kW |
| Buy via agreement | A provider with capacity | Immediate | Medium (ongoing cost) | Varies by provider |

**Most common**: Infuse Alpha Matter into your guild's reactor. Capacity increases automatically.

For step-by-step workflows, see the [structs-energy skill](https://structs.ai/skills/structs-energy/SKILL).

## Error Handling

- **Going offline**: Load exceeds capacity. Deactivate structs immediately (`struct-deactivate`), then increase capacity — see the `structs-energy` skill for options.
- **Allocation exceeds source**: Source (reactor/provider) has limited capacity. Query source; create smaller allocation or add capacity.
- **Substation delete failed**: Ensure no players or allocations connected. Disconnect first.
- **Automated allocation limit**: One automated allocation per source. Attempting a second from the same source will error. Use static/dynamic for multiple.
- **capacity=0 false positive**: A player connected to a substation pool may show `capacity=0` while structs are online and drawing power. Check `structsLoad > 0` as the real indicator of functionality, not `capacity > 0`.

## See Also

- [structs-energy skill](https://structs.ai/skills/structs-energy/SKILL) — "I need more energy" decision tree and workflows
- [knowledge/mechanics/power](https://structs.ai/knowledge/mechanics/power) — Formulas, capacity, load, online status
- [knowledge/mechanics/building](https://structs.ai/knowledge/mechanics/building) — Build power requirements
- [knowledge/mechanics/resources](https://structs.ai/knowledge/mechanics/resources) — Reactor vs generator conversion rates