Game Design — Pour Decisions (Falling Sand Simulation × Roguelike Deckbuilder)

First read docs/design/00_concepts.md, docs/research/02_competitor_patterns.md. This skill only provides executable rules; mathematical and simulation details are in references/:

references/scoring-math.md: chips × mult formula, additive/multiplicative stacking, target curve templates, Balatro actual numbers
references/balance-sim.md: Monte Carlo balance simulation architecture, bot levels, metrics, dominant strategy detection, report format
references/content-archetypes.md: Draft archetypes for this game, rarity quotas, catalyst examples

0. Five Highest Principles (Resolve Conflicts by These)

Simulation must be fully deterministic: Same seed, same pour position → same result, pixel-by-pixel consistent. Without determinism, there is no skill, and no way to do balance simulation, replays, or previews.
Every reaction must be "visible and countable": The reaction location displays a number, and each type has a fixed color and sound; when players lose, they must be able to say why (Roguebook: If players don't understand how they lost, they quit).
Depth comes from combinations, not from rule quantity: The surface rules are minimal (BotW chemistry engine: elements change materials, elements change elements, materials don't change materials), depth comes from the interaction of 100–200 objects.
Every object has a unique purpose, not just equal strength (Slay the Spire GDC 2019): Effects that strongly warp strategy and are easy to assemble should be limited; combos that are strong but difficult to assemble and require active pursuit can exist—single-player games can allow players to occasionally "break out."
Data determines direction, playtesting determines feel: Automated simulations catch numerical issues, human playtesting judges if it's fun (Noita: Technical indicators are easy to verify, "is it fun" can only be verified by playtesting).

1. Core Loop and Round Structure

Round: Draw hand (vials) → Choose 1 vial + Choose pour position/angle → Simulation runs to settle or tick limit
           → Score reactions from this pour → Accumulate to round score → Exhaust pour count → Compare to target score
Between rounds: Shop (vial / catalyst / upgrade / beaker modification) → Next round
Run: 8 "Experiments" (Antes) × 3 rounds (Small/Big/Boss) = 24 rounds

Score per settle, not based on real-time reaction speed—avoids AI team weaknesses (reaction time) and makes results predictable.
Settle limit: Maximum simulation ticks (e.g., 600 ticks), screen display max 4–6 seconds, can fast-forward ×2/×4; then forced settlement.
Beaker state persists across pours (within the same round); clearing at end of round is a design knob: persistence = long-term planning depth, clearing = readability. Prototype with clearing, then test the persistence version.
Boss Round = One rule modification (e.g., "Water freezes" "Gravity reverses once"), corresponding to Balatro Boss Blind; must be announced at the start of the round.

2. Scoring Design (chips × mult)

Formula (display order = calculation order, players can follow along):

Score for this pour = (Σ reaction chips + bonus chips) × (base mult + Σ +mult) × Π(×mult)

chips: Base score for each reaction (depends on reaction type and quantity; quantity should use logarithmic or segmented scaling to avoid "more means better").
+mult: Derived from "variety"—the number of different reaction types appearing in this pour, chain depth (reactions triggering reactions).
×mult: Only from rare catalysts or special conditions. ×mult is the most powerful currency, distribute it most sparingly.
Settlement animation plays sequentially: reactions pop chips one by one → mult accumulates → ×mult multiplies individually (Balatro-style tally), larger numbers slow down with more vibration.

Rules:

Additive vs. Multiplicative: n +mult objects grow linearly; k ×1.5 objects are 1.5^k. Early game focuses on additive, late game shifts to multiplicative—this is a natural build arc: let common cards give additive, rare cards give multiplicative.
The marginal value of additive diminishes (+4 mult on base 20 is +20%, on base 100 it's only +4%), making "when to switch to multiplicative" a player decision. Good, keep it.
Scores > 1e6 use thousands notation, > 1e11 use scientific notation; internally use double, Endless mode uses log space or BigNumber.
Detailed formula, example numbers: references/scoring-math.md.

3. Target Score Curve

Balatro White Stake (ante 1–8): 300 / 800 / 2,000 / 5,000 / 11,000 / 20,000 / 35,000 / 50,000; Small/Big/Boss = ×1 / ×1.5 / ×2. Each ante multiplier decreases from ×2.7 to ×1.4 gradually—because player power grows quickly early, slowly later.
This game's approach: Don't set the curve by gut feel. Use the balance simulation's "competent bot (greedy)" to run 1,000+ runs, take the median score for each ante M(a), target T(a) = M(a) × k(a), where k increases from early 0.5 (generous) to late 0.9 (tight).
Goal: For White Stake, competent bot win rate 30–50%, strong bot 80–95%, random bot < 5%. Human first win happens in runs 3–8.
Endless: After ante 9, super-exponential growth (Balatro roughly x^(x²) scale), so builds eventually collapse, giving "how many rounds did I survive?" shareable moments.

4. Vial and Catalyst Design

Vials are "cards": Each vial = one material + quantity (pixel count) + possible modifiers (temperature, purity, enchantment).
Catalysts are "Jokers/Relics": Passive, persistent, modify chemistry or scoring rules. Limited slots (e.g., 5) force trade-offs.
Object Role Classification (each new object must be labeled with a primary role):
- Enabler: Makes an archetype possible ("Oil produces extra fire in fire")
- Payoff: Rewards after the archetype is established ("Each burn reaction +3 mult")
- Bridge: Connects two archetypes ("Steam also counts as a burn reaction")—prevents one-dimensional builds
- Economy: Money, discounts, extra shop slots
- Scaling: Gets stronger with use ("At the end of each round, if there are ≥3 reaction types, this catalyst gains +1 mult permanently")
- Utility/Consistency: Hand management, redraw, preview, beaker cleaning
Build-defining vs filler: Rare slots primarily hold build-defining (modify rules, allowing players to "pivot"); common slots hold filler (numbers, consistency), but every filler must still have a clear "when would I pick this?" purpose.
Rarity (starting point, adjusted by simulation): Common 70% / Uncommon 25% / Rare 5% (Balatro weights); Legendary does not appear in the shop, only from special events.
Buff enablers, don't buff completed engines (Luck be a Landlord 1.1): Weak archetypes should first get "entry-level" pieces so players feel comfortable investing early; and provide "escape hatches"—objects that allow pivoting when the archetype fails.
Don't force buff pieces at the start, which causes tunnel vision.
Archetype and rarity quota table: references/content-archetypes.md.

5. Shop Economy and Reroll

Starting values (Balatro baseline, adjusted by simulation):

Income per round: Fixed $3–5 for clearing + remaining pour count × $1 + interest ($1 for every $5 held, cap $5, not verified as Balatro exact value). Interest creates "save vs spend" tension; keep it.
Price ranges: Common $2–5, Uncommon $5–8, Rare $8–10; Sell price = Purchase price ÷ 2 rounded down, minimum $1.
Reroll: Starting cost $5, increases by $1 each time, resets on new shop. (Balatro rules)
Shop slots: 2 objects + 1–2 "material packs" (choose 1 of 3) + 1 upgrade (voucher-like, $10, permanent rule modification).
Economic health check (simulation output):
- Competent bot should buy 1–2 items per shop on average; 3 consecutive shops where it can't buy anything = economy too tight.
- The win-rate contribution of economy objects should not exceed that of payoff objects—otherwise "farm gold first" becomes the only solution.
- Reroll count distribution: median 1–2 times; if the bot's best strategy is to reroll ≥5 times per shop, it means rerolls are too cheap or slots are too few.

6. Run Length and Pacing (Target 30–60 minutes)

Budget: 24 rounds × (3–4 pours × 15–25 seconds + shop 30–60 seconds) ≈ 35–50 minutes. Adjust pour counts after measurement, not settle speed.
Every 3 rounds (one ante) should introduce something new: Boss rule, new rarity unlocked, new material appears.
The first 3 rounds must complete within 6 minutes: The window for new players to judge "is this fun" is very short (Peglin Demo median playtime 67 minutes can serve as a reference for the demo overall).
Fail early: Lost runs should end in antes 2–4, not ante 7, to avoid "playing 40 minutes only to find out the build won't work."

7. Difficulty Stakes / Ascension

8–10 tiers, cumulative, each tier adds only one rule (Slay the Spire Ascension 20, Balatro 8 stakes are cumulative).
This game's candidates (easy to hard): Target ×1.2 → Remaining pours don't give money → Shop has one fewer slot → Beaker starts with contaminated pixels → Material quantity -10% → Rare catalyst chance halved → Boss applies two rules → Target growth curve switches to Purple level.
Difficulty tiers are also a data tool: Win rates at different tiers give more granular balance information (Slay the Spire GDC).
Unlock each tier by winning once at the previous tier; displayed in the menu to give players long-term goals.

8. Meta-progression (Not Pay-to-Win)

Permanent progression is primarily horizontal unlocks: new materials, new catalysts, new beaker shapes, new starting decks, an encyclopedia. No permanent numerical bonuses (e.g., "all fire +5%").
Unlock order designed as a tutorial: Only open 2–3 archetypes initially, then unlock more complex ones after a few runs (Roguebook: Use progression to delay complex mechanics).
Every run (even a loss) should unlock or progress something (Ball x Pit "respects player time": almost every run has a new blueprint).
Provide a "full unlock" option for veteran players/streamers (Balatro also added this), at the cost of that save file not counting achievements.
Any paid DLC can only be content (new material packs), not power.

9. Making Chaos Simulation Read as Skill

Deterministic: Fixed timestep, integer or fixed-point numbers, fixed update order (bottom-up; left-right scan direction determined by tick parity, not RNG), all randomness derived from the run seed PRNG. Compare hash of two runs with same input, include in CI tests.
Preview: Show drop trajectory and "which materials will be touched" icons before pouring; because it's deterministic, simulate the first N ticks in a background copy for "predicted reaction icons." Reserve full score preview for catalysts/items ("scope") as a resource, don't give it away for free.
Reaction vocabulary is fixed and small: Each reaction has one color + icon + pitch; aggregate same-type reactions into one popup number ("Burn ×37 → +185"), don't jump numbers for every pixel.
Causality lines: Chain reactions show fine lines or flashes connecting "who triggered who", chain depth shown with large numbers (×2, ×3…); these are also highlight moments for video clips.
Variation control: The difference in pour position should significantly affect score, but the result for the same position should be stable. Measure "skill gap" = best position bot score ÷ random position bot score, target ≥ 2; < 1.3 means positioning doesn't matter.
Simulate only what the player will see: Noita found that subtle effects like moss growth and slow melting went unnoticed; invest resources in reactions that change the score or the visuals.
When simulation hinders gameplay, gameplay takes precedence (Noita): It's okay to cheat (e.g., reactions only count within X ticks after pour, particle count limits).

10. FTUE / Tutorial (Systemic Games)

First run uses a fixed seed and fixed hand: Pour 1 = sand (learn pouring), Pour 2 = water (learn reaction: sand+water→mud), Pour 3 = fire meets oil (learn chain and mult). Each pour teaches only one thing.
Teach through the beaker, not through text: Less text also reduces translation cost for 10+ languages and the burden of AI text disclosure.
"Reaction Codex": Automatically record and briefly highlight the first time each reaction occurs; player discovery = fun (Roguebook: Discovering synergies is core fun).
Every vial/catalyst tooltip has an icon list of "will react with X", no text.
Catalysts and shops open from round 2 onwards; Boss from the end of ante 1.
The first run can be won, but progression does not depend on winning the first run.

11. Playtesting Methods and Metrics

Method: Blind playtest (no explanation) → first 15 minutes think-aloud → then quiet observation → end with 3 questions: "How did you lose?" "What was the most satisfying moment?" "What was unclear?". Record video.
For HSU playtesting: Only verify 1–2 hypotheses per session, written in advance in docs/design/playtests/YYYY-MM-DD.md.
Required metrics (telemetry saved as local JSON, enabled for demo):
- Time to first reaction, time to first understanding of ×mult (see if players actively pursue multiplicative)
- Death ante distribution per run, run length, time per round
- Voluntary second run rate (the single most important indicator)
- Accuracy of "why did you lose" answer (readability indicator, target ≥ 70%)
- Tooltip views vs purchase count for each object (unclear vs unwanted)
Event format: run_start / pour{vial,x,angle,reactions[],score} / shop{offered[],bought[],rerolls} / run_end{ante,cause,build[]}.
Beware of "super playtester" bias: Data from the most familiar people does not represent average players (Slay the Spire GDC).

12. Balance Simulation (Summary; Details in references/balance-sim.md)

Balance simulation runs in sim/ (Python or headless C# using the same rule tables), rule data (materials, reactions, catalysts) uses the same JSON/CSV shared between Unity and sim, to avoid drift.
Bot levels: Random / Greedy (choose the step with highest expected score) / Lookahead (MCTS or beam search for pour + purchase).
Each numeric change runs at least 1,000 runs × each bot; reports saved to docs/design/balance/YYYY-MM-DD_<topic>.md.
Dominant strategy alerts:
- A single object's "win rate when picked − baseline win rate" > +10 percentage points
- A single archetype accounts for > 40% of wins (target: top 5 archetypes all between 10–30%)
- An object appears in greedy bot and has a pick rate < 3% → dead card
- Strong bot win rate > 98% on White Stake → game too easy overall
Simulation finds strange strategies = signal; first check if it's a bug (Google research: agent's strange behavior often reveals real parameter tuning errors).
Fixes: First adjust numbers (cost, rarity, bonus value), then conditions, only remake as last resort (LocalThunk: Most fixes are numeric).

13. New Vial / Catalyst Review Checklist

Check each item before submitting any new object, write into the object's data sheet notes:

Sources

Slay the Spire Data-Driven Balance (GDC 2019): https://www.gdcvault.com/play/1025731 ・ https://glasp.co/youtube/7rqfbvnO_H0 ・ https://podwise.ai/episodes/1459444
Balatro Design Interview: https://rogueliker.com/balatro-interview/ ・ https://toucharcade.com/2024/03/18/balatro-interview-mobile-port-localthunk-dlc-plans-updates-new-jokers-demo-feedback/
Balatro Values (Blinds, Shop): https://balatrowiki.org/w/Blinds_and_Antes ・ https://balatrowiki.org/w/Shop
Luck be a Landlord 1.1 Balance Notes: https://blog.trampolinetales.com/the-big-buffs-update-preview/
Ball x Pit "Respects Player Time": https://automaton-media.com/articles/newsjp/ball-pit-20251217-375231/
Peglin Data: https://howtomarketagame.com/2022/05/04/how-peglin-made-1049413-in-1-week/
Roguebook Build Design: https://www.gamedeveloper.com/design/tackling-deckbuilding-design-in-abrakam-s-roguebook
Noita Falling Sand Design & Technology: https://www.gamedeveloper.com/game-platforms/road-to-the-igf-nolla-games-i-noita-i- ・ https://80.lv/articles/noita-a-game-based-on-falling-sand-simulation/
BotW Chemistry Engine (GDC 2017): https://www.thumbsticks.com/gdc-17-breath-of-the-wild-science-lies
AI Agent Automatic Balance Testing (Google): https://ar5iv.arxiv.org/html/1811.06962

Waipjy/ClaudeGame

What is ClaudeGame?

Ask in your favorite AI

Documentation

Game Design — Pour Decisions (Falling Sand Simulation × Roguelike Deckbuilder)

0. Five Highest Principles (Resolve Conflicts by These)

1. Core Loop and Round Structure

2. Scoring Design (chips × mult)

3. Target Score Curve

4. Vial and Catalyst Design

5. Shop Economy and Reroll

6. Run Length and Pacing (Target 30–60 minutes)

7. Difficulty Stakes / Ascension

8. Meta-progression (Not Pay-to-Win)

9. Making Chaos Simulation Read as Skill

10. FTUE / Tutorial (Systemic Games)

11. Playtesting Methods and Metrics

12. Balance Simulation (Summary; Details in references/balance-sim.md)

13. New Vial / Catalyst Review Checklist

Sources

Individual skills in this repo

Waipjy/ClaudeGame

Related Skills

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me