Mecha Skirmish — Game Design Document

v0 draft · 2026-09-05 · owner: pufferhaus

This document describes the whole game. The rules themselves live in rulebook.md and are referenced here by rule ID (A1, F4…) rather than repeated. Where this document and the rulebook disagree, the rulebook wins for rules and this document wins for intent.

Status markers, same as the rulebook: Locked decided · Proposed recommendation that needs a yes · Open undecided.

1. Overview

One line. A digital hex board game where two players each field three custom-assembled mechs and fight a fast, dice-driven skirmish. Assembling the roster is the metagame; the fight is twenty minutes of visible dice and breaking parts.

Pillars — Locked

1. Every roll is a die on the table (A1). Hit, location, penetration, damage, initiative, stress. Modifiers are dice too. Nothing is a hidden percentage.
2. Roster building is a small number of real decisions (A2). Depth like a Magic deck, setup cost like picking three kits.
3. Damage lands on parts (A3). Where a shot lands depends on how big the part is; what it does depends on that part's armor. Losing an arm loses a weapon.
4. A game ends in about twenty minutes (A4). Alternating activations, a round cap, objectives that force contact.
5. The sprue is the identity. You build from runners like a model kit. Parts are physical objects with size and weight, and the interface never hides that.

What we take from where

Audience. Competitive tactics players (Into the Breach, Duelyst, Atlas Reactor alumni), mech and gunpla fans, and TCG deckbuilders who want a build phase with teeth. Sessions are short and legible enough to watch.

Platform — Locked 2026-09-05. PC as a full engined game, targeting desktop and Steam Deck explicitly, with iPad as a potential later target. Controller and touch are therefore first-class inputs alongside mouse. Engine — Open (TASK-010): Godot, Unity or Unreal; the TypeScript engine in this repo stays the reference implementation and a server candidate regardless.

2. Player fantasy and tone

You run a small hangar. Your pilots are characters with allegiances and friendships. Your mechs are things you built, and you can point at the part that won or lost the game. Losing an arm mid-fight looks like a piece popping off a runner.

Tone is bright, clean, and mechanical rather than grimdark: flat color fields, line art, pop accents. The visual reference is the countdown poster style where a character stands next to their own parts on a sprue: model-kit iconography treated as pop art.

3. Core loops

Macro loop (hangar). Build a roster of four mechs from kits and parts → queue for a match → play best of three → earn decorations and rating → adjust the roster.

Match loop (I). Deploy → rounds of initiative and alternating activations → score kills and zones → sideboard swap → next game.

Activation loop (E). Move → two Quick actions or one Full → opponent may react → heat check.

Shot loop (F). Hit → Location → Penetration → Damage, each its own die, each shot of a burst resolved in turn.

The loops nest so that every level has a visible decision: which kit, which swap, which hex, which weapon, which band to aim at.

4. Game modes

5. Roster and assembly

Rules: B1–B8. Intent here.

The hangar screen is a sprue. Runners are tabs; parts hang on gates; you clip a part and it snaps to the frame. Size on the runner is the Size stat. The build screen never shows a part smaller than its hit band.

Kits are the on-ramp (B6). Four kits is a legal roster and a viable one. Every kit ships with a suggested pilot and a one-line identity ("Courier: fast, fragile, spots for the team"). Tweaking a kit is how players discover the depth.

Gauges. Per-mech weight vs class cap with the overload zone marked; team weight vs Team Cap; the hit tape; derived stats live as you clip. Illegal states are shown, not blocked, until you press Ready.

Sideboard is visible. The fourth frame sits on the sprue next to the three fielded ones.

Roster codes — Proposed. A short shareable string encodes a roster (the CLI already accepts chassis:head:rightArm:leftArm:legs:back:pilot). Import, export, copy from a replay.

Collection model — Locked 2026-09-05. A broad base set of parts and pilots is always available to every player. DLC is possible later and should lean cosmetic (paint, decals, pilot cosmetics); if DLC ever carries gameplay content, it must be balanced against the base set and never required to compete.

Complexity budget — Open (B8, TASK-004). Seven slots × three mechs is the current shape. Revisit once the catalog has 3–4 options per slot per runner (TASK-008); if it reads as homework, merge Head into Chassis or fold Back into Legs.

6. Parts and runners

Rules: C1–C8. The five runners are also the five factions (D2). Each has a design philosophy that should be legible from the sprue alone.

Part design rules

• Every part trades at least two of Size, Armor, Durability, Weight against its function. Bigger means tougher and easier to hit; the shield arm is the archetype.
• No part is strictly dominant within its slot at its weight. The simulator's sweep and batch stats are the check (TASK-006, TASK-002).
• Cross-runner builds are always legal (B6). Runner identity is a suggestion, not a lock.
• Catalog target for v1: 3–4 options per slot per runner, roughly 90–100 parts (TASK-008). Content cadence after launch is Open; a new runner per season is the obvious shape.

7. Pilots and factions

Rules: D1–D6.

Pilots are the characters. Each has stats (Gunnery, Piloting, Systems, Initiative), a Faction, a Specialty, one Additional Ability that switches on only when a teammate shares Faction or Specialty (D3), and at most one bond partner (D4). The roster puzzle is lighting up three abilities without giving up the three best individual pilots.

Targets for v1. Three pilots per faction, fifteen total, covering all six Specialties at least twice. Six exist as examples. Bonds should cross factions at least half the time so that "light everyone up" and "bring both bond partners" pull against each other.

Characterization. Portrait, a short bio, a handful of voice barks on kill, part loss, and bond triggers. Bond partners get a few lines of banter when adjacent. All cosmetic, all skippable.

Progression is cosmetic (D5, Locked). Decorations (kill marks, medals, paint) never touch a stat.

8. Combat

Rules: F1–F10, G1–G3. Intent:

• d20 plus dice modifiers because a stack of physical [+] and [−] dice cancelling on screen explains the situation better than a number. The whole modifier table (F2) fits on a card.
• Location by size because it makes assembly matter in the fight and creates decoy builds (a big shield arm soaks) without a rule saying so.
• Penetration as its own die so armor is a wall, not a subtraction. Light weapons chip heavies; they do not ignore them.
• Overflow to the core so a destroyed part is never a free hit sink.
• Heat is the push-your-luck lever. Overcharge and Barrage are how a losing player forces a swing.
• No facing (E8, Locked). Position and cover carry all the geometry; there are no arcs to track.
• Melee — Open (F11, FEAT-009). The Blade arm is a placeholder. A full melee layer is planned: improvised strikes for every mech, knockdown and grapple, a charge bonus, and defined interactions with Guard and Brace. It is designed and simulated before the catalog expands so melee parts have a system to live in.

9. Map and terrain

Rules: H1–H9.

Board. 32×20 hexes, deployment on the short ends, three zones offset along the long axis (H7). Elevation 0–3. A Medium reaches midfield in round 2.

Map design guidelines — Proposed

• Two approach lanes per side with a contested middle; no lane should give LOS to all three zones.
• One elevation island per half, reachable without Jump legs by one path, so high ground is a decision not a gift.
• Hard cover (low walls) near zones but not inside them; standing on the objective should be exposed.
• Foliage/smoke lines that break long sightlines so Cannons cannot see deployment to deployment.
• Maps are hand-crafted (Locked). Ranked pool size for v1 is Open (TASK-014).
• Hold zones are the v0 objective. Other objective types (capture and carry, escort, timed relays) are expected and maps will be built around them (IDEA-002).

10. Match structure and competition

Rules: I1–I6.

Best of three with a hidden simultaneous sideboard swap (I2). Scoring is kills plus zones (I4). The 45-second activation clock with a bank (I6) is the pace enforcer; the twenty-minute pillar assumes dice animation is fast (section 11).

Rating — Open (TASK-011). Recommendation: a single ladder per season, MMR hidden behind ranks, placement by roster-agnostic rating (rosters change too often to rate them).

11. Presentation and UX

Dice. Every roll is a rendered die that lands on the board. Modifier dice appear as a row, cancel visibly, and the survivor rolls. The location die lands on the target's silhouette and the struck band lights up. This is the signature moment of the game and gets the animation budget.

Speed budget. A 3v3 game has about 40 activations and roughly 150 dice. To hit twenty minutes, a full shot (four dice) must resolve in under two seconds, with an instant-skip for the opponent's rolls once seen.

Damage feedback. Part bars on the HUD; a destroyed part visibly detaches. Core death is the only "explosion."

HUD. Activation order with initiative result; per-mech heat gauge and part bars; the hit tape on hover; a dice log that can be scrubbed (the bench's Battle tab is the prototype).

Camera — Locked 2026-09-05. 2.5D isometric with the ability to pivot the camera 90 degrees repeatedly for full rotation. Elevation reads as stacked tiles. One flag for the art and UI pass: a hex grid has 60-degree rotational symmetry, not 90, so 90-degree stops alternate between a pointy-top and a flat-top look of the same board. Six 60-degree stops keep the grid identical at every angle; if 90 stays, the UI must keep hex labels and coordinates readable in both looks.

Accessibility. No color-only encoding (side, outcome and part identity all carry labels or shape); colorblind-validated palettes (the bench's series pair was validated); scalable text; reduced-motion mode that snaps dice.

Replays and spectating. The engine is deterministic per seed and every game is an event log, so replays are free and shareable as seed + roster codes. Spectator view is the replay view running live.

12. Art direction

Model-kit manual meets neon countdown poster. Flat color grounds, ink line art, pop accents. Palette tokens from the rulebook: cyan, sprue pink, amber, deep ink; dark ground in-match, paper ground in the hangar. Each runner has a silhouette language (Kessler boxy, Meridian tapered, Hollow Saints asymmetric and scrappy, Nine Suns slab-sided, Tessellate faceted). Decorations are decals and paint schemes on those silhouettes.

Typography in the prototype is Chakra Petch for display and IBM Plex for text and numbers; the game UI should echo the squared, technical feel.

Production approach — Open (TASK-013): 2D sprites with part swapping vs 3D models with modular parts. Modular 3D fits kitbashing and a freely pivoting camera; 2D fits the poster look and ships faster but needs four (or six) pre-rendered angles per part to survive camera rotation.

13. Audio

Open. Direction: mechanical clicks for clipping parts, dice on a table for rolls, short pilot barks, a hangar ambience. No music decision yet.

14. Technical direction

Engine is the source of truth (Locked). The TypeScript engine in this repo implements the rulebook, is deterministic per seed, and emits a typed event log. Any client, in any technology, renders events; any server runs the engine. Rule changes land in the engine and the rulebook together, with a test.

Data-driven. The catalog is JSON. Balance patches are data changes, versioned so replays from an older catalog still resolve.

Online model — Proposed. Authoritative server runs the engine; clients send intents, receive events. Reconnection replays the log. Turn-based means latency is irrelevant; the clock is server-side.

Production client — platform Locked (PC, Steam Deck, iPad potential), engine Open (TASK-010) among Godot, Unity and Unreal. Whichever engine wins, the rules ship either as a port with golden-replay tests against this engine, or by embedding a JavaScript runtime for the TypeScript engine. The hotseat prototype (FEAT-008) informs the choice by showing what the presentation needs. Steam Deck means controller navigation of the sprue and the hex board is a design requirement, not a port task.

AI. The simulator's policies double as practice bots and as the tuning oracle. A second, cautious policy (TASK-007) exists to tell rule problems from bot problems.

Tuning pipeline. pnpm sim batch and a planned sweep over catalog values; results and interpretation in docs/tuning/. Nothing changes in the catalog without a batch that shows why.

15. Content and live plan

Open. Working shape: seasons of a few months, each adding a runner (parts + three pilots) and one or two maps, with balance patches driven by simulator sweeps and ladder data. Nothing in a season gates gameplay.

16. Monetization

Locked 2026-09-05 in shape, open in detail. A broad set of always-available parts and pilots ships with the game. DLC may follow and should be cosmetic where possible. Premium versus free-to-play is not decided; the constraint that holds either way is that nothing required to compete is behind a paywall.

17. Risks

18. Open decisions

Tracked in liste under EPIC-002. Decided on 2026-09-05: platform (PC, Steam Deck, iPad potential), online scope (ranked, quick play, real-time and async), collection model (broad base set, DLC cosmetic-leaning), camera (2.5D isometric, 90-degree pivots), and every rule the rulebook had marked Proposed (TASK-003).

Still open:

• Production engine: Godot, Unity or Unreal (TASK-010)
• Art production approach: 2D modular sprites vs modular 3D (TASK-013)
• v1 content scope: how many hand-crafted maps and pilots (TASK-014)
• Melee system design (FEAT-009, rulebook F11)
• Additional objective types (IDEA-002)
• Working title (IDEA-003)
• Premium vs free-to-play (section 16)

19. Milestones

Appendix

• Glossary: rulebook A5.
• Rulebook: rulebook.md, styled rulebook.html.
• Simulator design: superpowers/specs/2026-09-05-simulator-design.md.
• Tuning notes: tuning/.
• Work queue: liste next in the repo root.