Manipulation System

Status: Designed Author: Nathan + Claude Last Updated: 2026-03-29 Implements Pillar: Meaningful Choices, Emergent Combos

Overview

The Manipulation System gives players active tools to modify dice during the roll phase of combat. It has two layers: innate abilities (permanent, mana-gated, used every turn) and consumables (single-use items, free to play, found as loot). Relics remain passive. This system is the primary source of player agency beyond hold/reroll — without it, turns reduce to "reroll and hope." With it, players craft hands deliberately.

Player Fantasy

"I'm not just rolling dice — I'm cheating fate." The player should feel like a cunning gambler who always has a trick up their sleeve. Innate abilities provide a steady baseline of control ("I can always nudge a die"), while consumables are dramatic moments of power ("I've been saving this Clone for the boss — watch this five-of-a-kind"). The tension of when to spend a rare consumable mirrors Balatro's Tarot card decisions.

Detailed Design

Core Rules

Layer 1: Innate Abilities

1. Each run starts with 2 innate ability slots, populated by the character's starting kit.
2. Default starting kit (Adventurer):
   • Nudge (1 mana): Select a die, change its value by +1 or -1. Cannot go below 1 or above the die's max face value. Can be used multiple times per turn if mana allows.
   • Reroll+ (1 mana): Gain +2 rerolls this turn. Stacks with base rerolls and relic bonuses. Can be used multiple times per turn.
3. Innate abilities can only be used during the roll phase (before scoring).
4. Using an innate ability does NOT consume a reroll.
5. Mana resets to max_mana at the start of each turn.
6. Base max_mana = 3. Modified by relics (Mana Crystal: +1).
7. Future character classes replace the default innates (architecture supports this, not implemented now).

Layer 2: Consumables

1. Players carry up to 5 consumables at a time. Attempting to gain a 6th requires discarding one first.
2. Consumables are free to use — no mana cost.
3. Consumables are single-use — removed from inventory after playing.
4. Consumables can only be used during the roll phase (before scoring).
5. Sources: combat rewards, shop purchases, rest site events (rare).
6. Consumable pool (8 types):

Targeting Flow (UX)

1. Player clicks a consumable slot or innate ability button.
2. If the ability needs a target die: UI enters targeting mode.
   • Dice glow/pulse to indicate they're selectable.
   • Phase label shows "Select a die…" (or "Select source die…" / "Select target die…" for Clone).
   • Clicking a die applies the effect.
   • Right-click or pressing Escape cancels targeting mode.
3. If the ability needs a second target (Clone): after selecting source, prompt for target die.
4. If the ability needs a value choice (Set Die): after selecting die, show value picker (1 through max faces).
5. If the ability needs no target (Add Die, Salvage, Reroll+): effect applies immediately on click.
6. Innate: Nudge shows ±1 buttons on the selected die (or up/down arrows).

States and Transitions

Transitions:

• IDLE → TARGETING_DIE: click consumable/innate that needs a die target
• IDLE → (effect applied): click consumable/innate with no target needed
• TARGETING_DIE → CHOOSING_VALUE: die selected for Set Die
• TARGETING_DIE → NUDGE_DIRECTION: die selected for Nudge
• TARGETING_DIE → TARGETING_SECOND: source die selected for Clone
• TARGETING_SECOND → IDLE: target die selected, clone applied
• CHOOSING_VALUE → IDLE: value picked, Set Die applied
• NUDGE_DIRECTION → IDLE: direction picked, Nudge applied
• Any targeting state → IDLE: cancel (right-click/Esc)

Interactions with Other Systems

Formulas

Mana

max_mana = BASE_MANA + relic_bonus_mana
# BASE_MANA = 3
# mana_crystal relic: +1

mana_at_turn_start = max_mana  (full reset each turn)

Nudge

new_value = clamp(current_value + direction, 1, die.max_faces)
# direction ∈ {-1, +1}
# If already at boundary (1 or max), that direction is disabled

Flip

new_value = die.max_faces + 1 - current_value
# d6: 1↔6, 2↔5, 3↔4
# d8: 1↔8, 2↔7, 3↔6, 4↔5

Shatter

direct_damage = die_value × SHATTER_MULTIPLIER
# SHATTER_MULTIPLIER = 10
# Die is removed from pool for remainder of combat
# Pool restored to pre-combat state after combat ends

Salvage

if hand_type == HIGH_DIE:
    score = sum(all_dice_values) × SALVAGE_MULTIPLIER
    # SALVAGE_MULTIPLIER = 2
else:
    no effect (consumable still consumed)

Reward Rates

# After combat, reward options (pick 1 of 3):
#   - Relic (weight 3)
#   - Consumable (weight 4)
#   - Gold (weight 3)
# Consumables appear more frequently since they're single-use

# Shop prices:
#   Common consumable: 15 gold
#   Uncommon consumable: 30 gold
#   Rare consumable: 50 gold

Edge Cases

Dependencies

Tuning Knobs

Acceptance Criteria

1. Mana display: Mana shows in combat UI, decrements on innate use, resets each turn.
2. Nudge works: Clicking Nudge → die → ±1 changes die value. Mana deducted. Boundary clamped.
3. Reroll+ works: Clicking Reroll+ adds 2 to reroll counter. Mana deducted.
4. All 8 consumables function: Each consumable applies its effect correctly per the rules table.
5. Targeting flow: Click consumable → targeting mode → click die → effect. Esc cancels. No mana/consumable spent on cancel.
6. Consumable persistence: Consumables carry between combats via SoloGameManager.
7. Consumable rewards: Consumables appear as reward options after combat.
8. Inventory limit: Cannot exceed 5 consumables. Prompted to discard when full.
9. Shatter guard: Cannot shatter last remaining die.
10. Lock persistence: Locked die survives into next turn, then auto-unlocks.
11. Temporary die cleanup: Add Die's extra die is removed after scoring.
12. Hand preview updates: Dice preview (hand name + score) updates live after any manipulation.
13. Scoring unaffected: HandScorer produces correct results regardless of how dice values were set.