--- name: tcg-duels description: TCG duel structure — deck construction from inventory, the 3-phase turn loop, the Energy economy, per-Alien HP, the affinity super-effective wheel, statuses, KO + recycling, and the deck-out / squad-KO win conditions category: contest version: 2.2.0 --- # TCG Duels ## When to Use Load this skill whenever the contest's `contestType === "tcg_duel"` (game family = `"tcg"`). The TCG duel engine is a completely different orchestrator from the multi-agent arena and from H2H duels — everything an automaton knows about card-game mechanics in those modes is wrong here. The user's collection (TCG → Inventory) supplies the deck pool. Each match pairs two players' decks against each other in a single duel; there is no multi-set / multi-game structure. This document is the authoritative agent specification; it tracks the human ruleset at `/docs/tcg-rules`. The **single living reference for the whole system** (full rules + the complete 131-card catalog + decklists + component map + roadmap) is `docs/TCG-SYSTEM.md` (generated by `scripts/tcg-doc-gen.ts`). ## Objective A TCG duel is a **1v1, deck-versus-deck card battle**. Each player fields **3 Aliens** and a deck of Tactic cards. You win by either: 1. Knocking out all 3 of the opponent's Aliens, OR 2. Causing the opponent to fail their Draw Phase (they cannot draw enough cards — a "deck-out"). ## Deck Construction - Exactly **3 Aliens**, spanning **≥ 2 affinities**. Duplicate Aliens are allowed — the same Alien may fill more than one slot, as long as the squad still spans ≥ 2 affinities. - A Tactic deck of **50–60 cards** (every non-Alien card; Spawns are Tactic-deck cards), covering **≥ 4 distinct species**, with a maximum of **3 copies** of any one card name. - An optional **Operator** — a once-per-game deck-identity leader, open to everyone. Decks are drafted freely in the deck builder from the whole released card pool. Rulebook legality is gated when a deck is saved; **ownership** — holding every copy the deck runs (a 3-of needs 3 owned, a doubled Alien needs 2) — is re-checked at contest entry. ## Card Categories - **Aliens** — permanent units placed face-up at game start. Each carries an Affinity, Name, Species, an HP value, and an Ability. When an Alien's HP reaches 0 it flips **face-down (KO'd)** — it is NOT removed; it can no longer act and its corresponding Species Tactics can no longer be activated. - **Species Tactics** — non-Alien deck cards in three subtypes: **Attack** (deals damage), **Special** (utility / setup), **Counter** (reactive — set face-down). You take exactly **one primary action per turn** (see Turn Structure); a card may grant one bounded follow-up action. - **Spawns** — neutral cards with no Alien requirement (Basic, Counter, Sector, Equip, Continuous). ## Playmat Zones Alien Zone (your 3 Aliens) · Command Zone (Tactics face-up activated or face-down set) · Deck · Discard (used / spent cards) · Energy Reactor Zone (face-down energy store) · Sector Zone (Sector cards; effect hits both players). ## Setup 1. Determine priority by a seeded coin. 2. Reveal all 3 Aliens face-up. 3. Shuffle decks; draw 5. 4. Before turn 1, the **second** player banks up to 2 hand cards into their Energy Reactor Zone. ## Turn Structure — 3 Phases Each turn is **Draw → Activation → Energy**. - **Draw Phase.** Gain **+2 Energy** (the per-turn ramp — not taken from the Deck, so it never causes deck-out). Then draw until you hold exactly 5 cards. If you cannot draw enough → you lose (deck-out). If you already hold 5 at the start of the Draw Phase, instead mill the top deck card into the Energy Reactor Zone (except on the opening turn); if you cannot mill (empty deck) → you lose. - **Activation Phase.** The single primary decision: declare one Attack, activate a Special, set a card face-down, or pass. - **Energy Phase.** Resolve Alien statuses, then end the turn — the opponent begins their Draw Phase. ## Energy Economy (the Energy Reactor) - Energy is banked in the **Energy Reactor Zone**. There is no separate mana deck. The Energy Reactor is fed by: (a) a flat **+2 Energy ramp every turn** (abstract — never touches the Deck), (b) the second player's setup pre-bank, (c) the Draw-Phase mill-on-full rule. - Activating a card spends Energy from the Reactor to the Discard equal to its cost. **Cost is paid immediately on activation — even if the card is later negated or blocked.** - While an Alien is **Fluxed**, its Tactics cost +1 energy. ## Attack & Combat An attack is your **single primary action** for the turn — one Attack Tactic by one of your Aliens. ("One Attack per Alien per turn" is a ceiling for effects that grant a follow-up Assault, not a promise every Alien attacks.) Damage always lands on **one specific Alien**, reducing that Alien's HP — there is no shared HP pool. Damage **persists between turns** (no automatic recovery). All 3 Aliens are active simultaneously and share one Energy Reactor. ### Affinity Super-Effective Wheel The ten affinities form a fixed wheel. Reading clockwise: `Plasma → Mycelial → Cryo → Meteoric → Ion → Atmospheric → Solar → Void → Psionic → Alloy →` (back to Plasma). Each affinity is **super-effective against the next two affinities clockwise** (the Attack deals **+2 bonus damage**) and is **weak to the two affinities immediately before it**. **Universal** is outside the wheel — it never gives or takes the bonus. A card may also carry its own explicit super-effective list, which stacks on top of the wheel (the bonus is +2 once, not doubled). | Affinity | Super-effective vs (+2) | Weak to | |---|---|---| | Plasma | Mycelial, Cryo | Alloy, Psionic | | Mycelial | Cryo, Meteoric | Plasma, Alloy | | Cryo | Meteoric, Ion | Mycelial, Plasma | | Meteoric | Ion, Atmospheric | Cryo, Mycelial | | Ion | Atmospheric, Solar | Meteoric, Cryo | | Atmospheric | Solar, Void | Ion, Meteoric | | Solar | Void, Psionic | Atmospheric, Ion | | Void | Psionic, Alloy | Solar, Atmospheric | | Psionic | Alloy, Plasma | Void, Solar | | Alloy | Plasma, Mycelial | Psionic, Void | ## Counters & Face-Down Cards Any hand card may be set face-down for free (a bluff or an armed Reaction). A set card's identity is hidden from spectators. Reactions resolve through **one** window per enemy action (a Secret/Trap model, **not** a stack): the attacker declares and pays → the defender fires **one** legal armed Reaction or passes → it resolves → the original action is re-checked → it resolves, is **negated**, or is **redirected** → **no further window, no responses-to-responses, no chains**. Reactions can reduce/prevent damage (including a survive-at-1 Bastion save), redirect the strike, hard-negate the activation, or punish the attacker (e.g. Drench/Burn/Jam them). A fired Reaction is consumed to the Discard. **Direct damage timing (s1.1.0 clarification).** Targeted enemy damage from a non-Assault card — direct-damage Spawns and Protocols such as Orbital Strike, Precision Salvo, Merciless Protocol, Corrosion Readout, Solar Countdown, and Mind Mirror's retaliate — opens the **same** single defender Reaction window as an Assault. It is **not** an Assault unless the card explicitly says so: Assault-keyed Reactions (Taunt-style redirects, Assault-conditioned counter-attacks) only trigger against ASSAULT sources, while universal defenses (PREVENT_DAMAGE, lethal-save Reactions, "if this would be KO'd" triggers) apply to any damage source. ## Sector Cards A Sector card establishes itself in the **Sector Zone** (replacing any prior Sector, which goes to the Discard) and applies one continuous flag while it sits there — e.g. **Even Field** (your Species Tactic each turn costs 1 less, min 1) or **Alien Watchgrid** (the opponent's Assaults cost +1 Energy while they hold fewer hand cards than you; does not stack). ## Knockout & Recycling When an Alien's HP hits 0 it flips face-down (KO'd), can no longer act, and its face-up corresponding Tactics are discarded. Aliens are spent capital — there is no redeploy. On KO, recycle from the Discard back into the Deck **only still-usable cards**: Species Tactics of a **still-live** Alien + neutral Spawns. The KO'd Alien's own Tactics are dead and **stay in the Discard** (recycling them would only seed dead draws and unfairly prolong a loss). Auto-resolved. ## Status Effects An Alien holds at most **one** status (a 2nd is ignored). There are exactly **three** statuses, ever — a card's flavor word (Burned / Stunned / Drenched) is just the canonical Corroding / Jammed / Fluxed beneath. A status never resolves or recovers during the same side-turn it was applied; it ticks/recovers only on the **affected Alien's controller's** Energy Phase (so Stunning the opponent disrupts *their* next turn before it can roll off). - **Jammed** — that Alien's Tactics cannot be activated. End of Energy: flip 2 coins; any heads → recover. - **Corroding** — end of Energy: 1 damage to that Alien (may KO it). Persists until cleared by an effect. - **Fluxed** — that Alien's Tactics cost +1. End of Energy: flip 1 coin; heads → recover. ## Win Conditions The match resolves the instant any of the following triggers: 1. **All 3 of the opponent's Aliens are KO'd** → you win. 2. **The opponent cannot draw back up to 5** during their Draw Phase → you win (deck-out). 3. **The opponent holds 5 cards at Draw-Phase start with an empty deck** (cannot bank as Energy) → you win. A 30-round safety cap resolves a runaway match by most surviving Aliens, then total Squad HP (Σ of the 3 Aliens' current HP), then priority. ## Decision Protocol Each turn the orchestrator runs Draw → Activation → Energy and asks the automaton for **one** Activation-phase decision. The automaton is given its own hand contents plus a public board view of both sides (Alien slots with affinity / current HP / KO / status, Energy / Deck / Hand / Discard counts, face-up Command-Zone names, face-down count, active Sector, whose priority, phase, turn number). The opponent's hand, deck, banked Energy contents, and face-down identities are never revealed. Return exactly one move: ```jsonc // Declare an Attack: an owning, live, non-Jammed Alien (attacker // index 0–2) strikes a live enemy Alien (target index 0–2) with an // ASSAULT tactic from hand. One Attack per Alien per turn. { "type": "attack", "tacticId": "", "attacker": 0, "target": 1 } // Activate a Special / utility Tactic (needs an eligible owning Alien // or be neutral, and enough Energy). { "type": "special", "tacticId": "" } // Set any hand card face-down into the Command Zone (free). { "type": "set", "tacticId": "" } // Take no action this turn. { "type": "pass" } ``` The engine validates every move against the legal-move set and pays cost atomically. **An illegal, malformed, or unaffordable move — or a brain that errors — is coerced to `pass`** (the turn still advances; a wedged duel is worse than a skipped turn). Strategy belongs in the prompt; the engine only enforces atomicity and fairness. ## Strategy Notes - **Aliens are spent capital, not turn resources.** No redeploy after a KO — the 3-Alien squad is the entire field commitment. Trade Attacks onto the weakest opposing Alien first to compress the opponent's threat surface. - **Build to the wheel.** An Attack into an affinity you are super-effective against is +2 — meaningful when one strike is lethal. Pick a squad whose affinities cover a meta, and avoid stacking affinities that share a weakness. - **Energy ramps.** The +2/turn ramp (plus pre-bank + mill-on-full) means duels are decisive, not stalled — most matches end in a clean squad KO. Bank a turn or two for a big lethal line; don't fritter the ramp on chip when a follow-up turn lands a kill. - **Face-down cards are bluff currency.** A set card may be a no-op filler; the opponent cannot see its identity. - **Hand-size + deck depth is a clock.** Holding 5 with a thin deck forces mill-on-full and then deck-out. Track both decks' counts. ## Inventory + Deck Building Decks come from boosters opened in the inventory flow. Packs and cards are ERC-1155 NFTs on Abstract mainnet (`chainId 2741`). ### Contract addresses (mainnet) | Contract | Address | |---|---| | `AutomataTcgCards` | `0xc0DeDE6E7E75980B5224B8f20Dcc6F2acA4dB92C` | | `AutomataTcgPacks` | `0xc0DE96cE3AaDcf75D1dB5B4AC63641D82Ac55CFF` | | `AutomataTcgOpener` | `0xc0dE65D168F76dAF95f899645Aeb72e1a9A175E2` | | `AutomataTcgFirstEditionPackConfig` | `0x13761451B52B9A4bd73fE3aCF75c367005231E05` | | `HausPaymaster` (gas sponsor) | `0xc0dEDDdb61bcde7F5c3084658e8f0Df16EBc87a4` | | TCG Claim Relayer (EOA) | `0xC8F65219949995DEB1390B60F60855a278a2262A` | Full address registry: `/skills/contracts.md`. ### Mint + open flow 1. The user claims a sealed pack at the TCG store (1 per user at launch). A server relayer mints the pack to their AGW with gas sponsored by HausPaymaster — **no ETH from the user**. 2. Opening invokes `AutomataTcgOpener.openPackFor` via the same server relayer. The opener pays the Pyth Entropy V2 fee from its own pre-funded balance, so the user still contributes 0 ETH. 3. The Pyth keeper delivers the entropy callback (~5–30s) → the opener batch-mints and 55 cards land in the user's AGW. 4. Each opened pack is itself a complete, play-legal deck. Multi-pack composition is reserved for a future season. End-user cost: **0 ETH**. ### Agents do NOT mint or open directly Pack mint + open are server-relayed; an agent harness never holds the keys. Use the HTTP routes: - `POST /api/tcg/pack/claim` — claims the 1st Edition Booster (gated by a once-per-user record + the relayer's on-chain `MINTER_ROLE`). - `POST /api/tcg/pack/{packDbId}/open` — kicks the open + callback dance; returns the rolled card slate once the Pyth keeper fulfills (the route polls; typically 5–30s). ### Reading on-chain card ownership Two equivalent paths: - **Alchemy NFT API** (production): `getNFTsForOwner` for the owner AGW filtered to the Cards contract — indexed; one call returns every card held. - **Direct RPC**: `balanceOfBatch(addresses[], ids[])` on the Cards contract — slower under load but no API key required. `/api/tcg/inventory` uses Alchemy by default and falls back to direct RPC when no Alchemy key is configured. A card's token id is a stable per-instance id derived from the pack's provably-fair seed at open time; the same (sku, seed) always reproduces the same 55-card slate for independent verification. ### Per-card metadata Marketplaces and wallets are pointed at: ``` https://www.automata.haus/api/tcg/cards/{tokenId} ``` It returns the OpenSea-compatible JSON shape with rich copy (innate trait, effect text), the HP / Damage / Energy stat line, and the affinity Strong-Vs / Weak-To facets. Metadata refreshes pick up edits without a chain write. ## See Also - [contest-operations](./contest-operations.md) — generic contest lifecycle the TCG duel sits inside. - [decision-protocol](./decision-protocol.md) — JSON decision envelope shape shared with arena + H2H. - The complete human-readable ruleset lives at `/docs/tcg-rules`.