zfxaction25/design.md

Donkeys and Droids - Design

Fantasy promise: you are “programming” a delivery robot in a noisy, glitchy world where logistics (carry, routing, instruction budget) fights entropy (corruption, unreliability, race conditions, weather). The donkey is a great tonal contrast: low-tech capacity as a counterweight to high-tech brittleness.

Metagame and Setup

• Run parameters
  • MatchParameters carries RobotType, Difficulty, and Seed to ensure deterministic runs.
• Difficulty settings and starting currency
  • Easy
    • Energy: 50
    • MaxCarry: 10
    • HandSize: 9
    • TapeLength: 6
  • Medium
    • Energy: 40
    • MaxCarry: 8
    • HandSize: 8
    • TapeLength: 5
  • Hard
    • Energy: 30
    • MaxCarry: 6
    • HandSize: 7
    • TapeLength: 4
• Currency fields
  • Energy: spent by most actions and restored by some cards and cells.
  • MaxCarry: total goods capacity.
  • Carry: goods currently held.
  • Delivery: goods already delivered.
  • TapeLength: available instruction slots.
  • HandSize: number of cards that can be held.
  • Preview: intended for future preview capacity; not yet wired in code, but kept in design for Foresight.
• Robots and starting decks
  • Vintage (selectable)
    • ProgramCount: 5 programs per day.
    • Starting deck: 4 Move, 4 TurnRight, 4 TurnLeft, 4 Interact, 4 NoOp.
  • Analyst (code-defined, not currently pickable)
    • ProgramCount: 5.
    • Starting deck: Vintage deck plus AluminumHat.
    • Stats: HandSize increased by 1.
    • Modifier: first glitch deferral costs 1 energy less.
    • Identity: information, preview, controlled deferrals.
  • Courier (code-defined, not currently pickable)
    • ProgramCount: 5.
    • Stats: MaxCarry +1; TapeLength -1.
    • Deck tweak: +1 Move (and one fewer NoOp than Vintage).
    • Modifier: CourierOverspill converts any delivery delta into +5 Energy once per delivery intent batch.
    • Identity: delivery loops, overspill energy, routing greed.
  • Ranger (code-defined, not currently pickable)
    • ProgramCount: 5.
    • Stats: Energy +2.
    • Starting deck: Vintage deck plus DetoxiumPrime.
    • Modifier: resting on Fertile restores +1 extra Energy.
    • Identity: terrain mastery, resting economy, survival
• Unlock notions (not enforced in runtime)
  • Finish a full run.
  • Deliver a threshold in one day.
  • Complete a delivery under a low-instruction budget.

Core Loop and Phases

• High-level phase order
  • Init
  • ExecuteProgram (initial preview occurs here)
  • Scoring
  • DrawGlitch
  • Improve
  • Optional side loops: Gamble or BufferOverflow
  • Return to ExecuteProgram and repeat until termination.
• Init
  • Seeds the first ExecuteProgram.
  • Immediately jumps to ExecuteProgram.
• ExecuteProgram
  • Player actions before execution
    • MoveCards: freely reorder cards between hand and tape, respecting HandSize and TapeLength by counting OccupiedSpace (Efficient cards count as 0).
    • Discard: pay 1 Energy per selected hand card; each discarded card is replaced from the top of the deck if available.
    • RunProgram: execute the current tape.
  • RunProgram flow
    • Bookkeeping: ProgramCount decrements; ProgramsExecuted increments.
    • Pre-run shuffle: each RaceCondition card has a 25% chance to swap with its neighbor (next if normal, previous if the card is Corrupt) within the TapeLength window.
    • Modifier stack: intents are processed by Robot modifiers first, then the current Cell, then the Card; modifiers with active debuff sources are skipped.
    • Intent validity: intents require sufficient Energy and no active debuffs unless forced execution is used.
    • Card resolution
      • Persistent cards return to hand after execution; other cards move to discard.
      • ShortTerm modifiers are cleared after each program.
      • Temporary modifiers are cleared when entering Scoring.
    • Termination check after execution
      • If ProgramCount reaches zero, PatchDeck is empty, Energy is zero or below, or all sheds are filled, then:
        • Add 10 Energy.
        • Clear all Temporary modifiers.
        • Set phase to Scoring.
      • Otherwise, draw back up to HandSize and remain in ExecuteProgram for the next program.
• Scoring
  • NextAssignment command resets shop state by collecting tape, hand, and discard into the deck, shuffling, and preparing a fresh hand on the next day.
  • Phase moves to DrawGlitch; board and robot state persist between days.
• DrawGlitch
  • Glitch deck is a fixed set, shuffled once, and loops forever without depletion.
  • Accept: apply the current glitch immediately.
  • Defer: advance the cursor and charge Energy equal to (deferCount+1)(deferCount+2)/2; deferCount never resets. After either action, advance to Improve.
• Improve
  • Shop
    • Five unique patch cards are offered using rarity weights: Common 108, Magic 36, Uncommon 12, Rare 3, Legendary 1.
    • Shop cards never include buffs or debuffs.
  • Buying
    • Pay the card’s ShopCost (or zero if taken from a booster) and add it to the deck.
  • Rerolling
    • Costs rerollCount + 1 Energy.
    • Increments rerollCount and rebuilds the shop with new cards.
  • PreviewProgram
    • Moves to ExecuteProgram and re-enters preview: reshuffles, draws a new hand, and resets ProgramCount to the robot’s value.
  • One-time flags per day: CanGamble and CanBufferOverflow start true and flip to false after use.
• Gamble (optional branch from Improve)
  • Entry costs 5 Energy and requires CanGamble.
  • Produces a booster of six patch cards.
  • Each booster card independently rolls for modifiers: 25% buff chance scaled down by difficulty, 25% debuff chance scaled up by difficulty.
  • Booster cards are free to take; stopping returns to Improve.
• Buffer Overflow (optional branch from Improve)
  • Entry costs 10 Energy and requires CanBufferOverflow.
  • Shuffles the deck and draws a new hand.
  • DestroyCard lets the player remove one hand card, then returns to Improve. StopBufferOverflow returns to Improve and puts the drawn hand back into the deck.

Board and World

• Generation rules
  • Hex board radius = 2 + fDifficulty * 2, where fDifficulty = 0.5 + difficulty/4.
  • An outer ring beyond the playable radius is also generated.
  • The avatar starts at (0,0) facing a random direction.
  • Terrain splats (scaled by difficulty) place Blocked, Dry, Fertile, Mud, and Rocky cells.
  • Corrupt cell modifiers are placed after POIs.
  • Blocked and Corrupt cells are treated as walls for reachability.
• Points of interest
  • Donkey: sprinkled on 5% of eligible cells; each gets a random facing.
  • Shed: sprinkled on 10% of eligible cells; each holds a delivery request.
  • Crate: sprinkled on 20% of eligible cells; each holds goods.
  • Tower: sprinkled on 5% of eligible cells; each receives permanent Unreliable and gives Unreliable to neighbors.
• Requests and offers
  • TargetDeliveryAmount equals the sum of shed requests.
  • Default shed request is 10, with per-shed variance.
  • Crate amounts sum to a bonus total that scales down with higher difficulty.
• Connectivity constraints
  • Placement rejects any change that would break reachability from the avatar when treating Blocked and Corrupt cells as impassable.
  • FindCellIndex currently scans linearly (O(n)); reordering or indexing would enable O(1) lookup (TODO).
• Terrain effects during play
  • Mud: Move intents incur an additional 1 Energy via a follow-up currency change.
  • Fertile: Rest intents restore an additional 1 Energy.
  • Dry: Rest restores 1 less Energy; Interact costs 1 extra Energy.
  • Rocky: has no runtime effect (only a generation tag).
  • Corrupt, Unreliable, RaceCondition on a cell: entering the cell applies that modifier temporarily to all remaining tape instructions.
  • Towers can be toggled inactive; inactive towers debuff their Unreliable modifiers so they stop applying.

Currency and Metrics

• Currency handling
  • All changes flow through ModifyCurrency, which prevents negative Energy, MaxCarry, Carry, Delivery, TapeLength, or HandSize.
  • Recruiting or dismissing a donkey changes MaxCarry by 10 (positive when recruited, negative when released).
• Metrics tracked
  • ProgramsExecuted: number of programs run.
  • InstructionsUsed: one per card executed.
  • PathLength: total movement distance.
  • CellsVisited: set of all visited cells.
  • Overspill: amount delivered beyond shed requests.

Modifiers and Intent Pipeline

• Processing order per card
  • Robot modifiers.
  • Cell modifiers on the current avatar cell.
  • Card modifiers on the card being executed.
• Duration types
  • Permanent: persists across the entire run.
  • Temporary: cleared when entering Scoring.
  • ShortTerm: cleared after each program.
• Corruption effects (when a Corrupt modifier is active and not debuffed)
  • Move: reverses direction.
  • Turn: flips the rotation delta.
  • Rest: original rest is debuffed; a forced backward Move is added.
  • Interact
    • Crate: dumps all carried goods into the crate.
    • Shed: fails and refunds Energy instead of delivering.
    • Tower: toggles the tower active.
    • Donkey: drops a carried donkey onto an empty cell if present.
  • ImmunizeCard with CanCorrupt: removes immunity instead of adding it.
  • ModifyCurrency with CanCorrupt: flips the sign of all deltas.
  • DetoxiumPrime: harms the target cell instead of healing it.
  • References to "next" become references to "previous" when the referencing card is Corrupt.
• Other modifier behaviors
  • Unreliable: 25% chance to debuff intents, causing them to do nothing.
  • RaceCondition: 25% chance to swap position with a neighbor before execution (next or previous if Corrupt).
  • Effective: 25% chance to duplicate the current intents.
  • Optimized: reduces CardCostIntent by 1.
  • Throttled: increases CardCostIntent by 1.
  • Efficient: OccupiedSpace becomes 0 for hand/tape limits.
  • Persistent: card returns to hand instead of discard after execution.
  • GlobalImmunity: suppresses specified modifiers across entities while active.
  • Gravity: lowers MaxCarry by 2 and increases Move cost by 1 while active; restores on removal.
  • HeatWave: immediately removes 10 Energy when applied; restores 10 on removal.
  • Pest: halves Delivery gains applied via ModifyCurrency.
  • CourierOverspill: adds 5 Energy whenever a Delivery delta is detected.
  • RangerFertileRest: adds 1 Energy when resting on a Fertile cell.
  • Analyst: reduces the Energy cost of the first glitch deferral by 1.

Cards - Patches

• Common
  • Move: move forward 1 cell if free.
  • TurnRight: rotate 60 degrees clockwise.
  • TurnLeft: rotate 60 degrees counter-clockwise.
  • Interact: interact with the forward cell.
  • NoOp: rest and restore 5 Energy.
• Magic (temporary buffs to following tape cards; when Corrupt they instead grant temporary immunity to that modifier)
  • Potentiate: adds Effective to following cards.
  • Optimize: adds Optimized to following cards.
  • Streamline: adds Efficient to following cards.
  • Persist: adds Persistent to following cards.
• Uncommon
  • DetoxiumPrime: heals the forward cell (or harms if Corrupt).
  • FlyingDisk: move forward 1 ignoring blocking and POIs.
  • AluminumHat: grants ShortTerm immunity to Unreliable for following cards.
  • EMField: grants Temporary immunity to Corrupt for following cards.
  • AtomicClock: grants ShortTerm immunity to RaceCondition for following cards.
  • Load Balancer: grants ShortTerm immunity to Throttled for following cards. (design intent; not yet implemented).
• Rare
  • Remember: permanently increases TapeLength by 1 (Corrupt can invert the delta).
  • Reason: permanently increases HandSize by 1 (Corrupt can invert the delta).
  • Foresight: intended to permanently increase Preview by 1 (Corrupt can invert the delta); design placeholder for future preview mechanics.
• Legendary
  • Jump: move forward 2 cells, ignoring blocking and POIs.
  • Repeat: re-executes the next card (or previous if Corrupt) with safeguards against loops.
  • Rest: restore 20 Energy.
  • Stabilize: temporarily nullifies all modifiers on the next card (previous if Corrupt).
• Costs
  • Default play cost for patches is 1 Energy.
  • NoOp, Repeat, Jump, and Rest have a play cost of 0 Energy.
  • Shop costs follow Balancing values per card type.

Cards - Glitches

• Permanent single-card modifiers applied to a random deck card
  • Bitflip: adds Corrupt permanently.
  • ShortCircuit: adds Unreliable permanently.
  • Slipstream: adds RaceCondition permanently.
  • Latency: adds Throttled permanently.
• Temporary modifiers applied to all deck cards
  • SolarFlare: adds Corrupt temporarily.
  • LightningStorm: adds Unreliable temporarily.
  • MeteorStorm: adds RaceCondition temporarily.
  • WindStorm: adds Throttled temporarily.
• Map and robot glitches (Temporary)
  • Rain: converts Rocky to Dry; may convert Grass to Mud.
  • Drought: converts Fertile to Grass; may convert Grass to Dry.
  • Pest: halves Delivery gains.
  • Gravity: lowers MaxCarry by 2 and adds 1 Energy to Move.
  • HeatWave: immediately removes 10 Energy.
  • SandStorm: preview malus is planned but not implemented.

Known Gaps / TODOs

• Implement Load Balancer patch.
• Optimize board lookup (FindCellIndex is O(n)); consider indexed storage for O(1).
• Expose Analyst, Courier and Ranger in selection when ready.
• Extend modifier hooks so Delivery/Rest effects triggered in Interact/Rest logic also route through ModifyCurrency, aligning courier/ranger/pest behaviors.
• Implement the Preview mechanic and stat, including other design elements (like e.g., Foresight).
  • For each tape slot, show predicted position/facing/energy/carry changes.
  • Limit the previewable tape length with the Preview stat.
• “Add 10 Energy when day terminates (including when Energy reaches zero)” can read like a magical bailout unless framed as “enter sleep cycle, recharge.”
• Diegetic wrappers for each phase
  • ExecuteProgram = “Compile & Run”
  • Scoring = “Telemetry Report”
  • DrawGlitch = “Incoming Anomaly”
  • Improve = “Repair Bay / Patch Installer”
• Make the stack legible in fiction and UI: For every instruction step, show: robot modifiers → Local modifiers (cell aura/tower) → Instruction modifiers.
• Presort hand
• Multiselect drag
• Clear tape command
• Glitch deferral mechanic can collapse into a single dominant behavior. If deferCount never resets and cost grows triangularly, optimal play often becomes “defer early only when absolutely necessary, then never defer again,” reducing meaningful choice.
  • Glitch decision becomes richer if it’s a trade, not a tax. Replace infinite defer escalation with one of:
    • Reset automatically after X days.
    • Reset dynamically (drops by N after triggering a core-loop mechanic).
    • Convert to a “heat meter” where deferring increases heat, accepting reduces it.
• Shop offers without synergy steering. Weighted rarity alone does not guarantee players see “build paths.” Without mild biasing toward current deck/robot, the shop can feel random rather than responsive.
  • Give the player an intentional “build direction” mechanism. Light drafting: choose one of two “contract modifiers” each assignment that biases shop pool and rewards a playstyle.
• Make assignments meaningfully distinct, e.g. introduce “priority sheds,” timed bonuses, or “fragile goods” constraints.
• Unlocks should teach, not just gate
  • Unlock robots/cards via challenges that naturally demonstrate the mechanic (low tape budget run unlocks “Efficient” archetype).
• Punctuate “milestones”
  • Filling a shed, recruiting a donkey, disabling a tower, completing an assignment: each should be a mini-celebration with strong feedback.
• Variable reward that is still fair: In Gamble boosters: guarantee at least one “clean” high-rarity card or one buffed card so the purchase rarely feels like regret.
• Combo feedback: When Effective duplicates, when Persist chains value, when Optimize saves energy: show “savings” and “extra actions” as highlighted wins.
• Permanent negative modifiers need permanent solutions: cleansing, “firmware reset,” or “quarantine a card” systems.
• Telegraph uncertainty: Show on the tape which slots are unstable and why (tower aura, corrupt cell, race swap risk).
• Show last program’s path, and a “why did this fail?” postmortem that points to the modifier responsible.
• Add a rare “Reflash Firmware” card: remove a modifier from 1 card permanently.
• Disabling a tower could grant a one-time reward (energy, clean patch, or “stability” buff for next program) so it feels worth the detour.
• Mitigation economy: New resource: “Stability” earned by deliveries or disabling towers. Spend it to cleanse or to defer without energy cost.
• Add a few more “benign glitches” (small upside with small downside) so the glitch screen isn’t always dread.
• Rebalance nop: reduced baseline, scale stronger with terrain (e.g. zero energy on dry)
• “Scrubber” shop service: pay energy to remove a modifier from a card.
• Avoid “randomly hit my best card” feel: Permanent glitch targeting can be weighted toward a visible “at-risk” subset the player can influence.
• Reward exploration
  • Hidden caches or “debug terminals” that grant a free reroll, a cleanse, or a preview increase.
• “Modifiers with active debuff sources are skipped” is subtle. Players need to see what’s suppressed and why.
• Low-rarity answers to high-rarity problems prevent runs from hinging on rare draws:
  • “Checksum”: remove Temporary modifiers from the next 2 tape cards.
• Expose a “seed replay” summary. Deterministic runs are a gift: let players replay a seed, share it, and compare strategies.
• Cosmic Rays should have a flatter rarity weight curve.
• Remove randomness from RaceCondition
• Replace randomness from Unreliable with an incrementing wrapping counter, replacing an intent when the counter wraps around. The replaced intent could be some sort of NoOp.
• Replace "opposite" from Corrupt with Damplen+Wear:
  • Dampen: all numeric deltas produced by that card are shifted 1 step toward zero.
    • ModifyCurrency: +10 → +9, -2 → -1
    • Rest energy, card-cost intents, Move distance, Turn delta magnitude: all shrink by 1 step where applicable
    • Clamp at +/- 1 to not introduce sign-flip betrayal or make cards useless.
  • Wear: after resolution, add a Worn stack to the card.
    • Each Worn stack adds +1 Energy to that card’s play cost (implemented as a follow-up CardCostIntent(+1) when the card is played).
• Make Jump rare instead of legendary
• Make Repeat rare instead of legendary

New card ideas

• Reflash Firmware (Rare): Permanently remove one modifier from a random card in your deck.
• Load (Uncommon): interact only with crates, bonus carry.
• Drop (Uncommon): interact only with sheds, bonus delivery.
• Grabber arm (Rare): Interact with forward Crate or Shed at range 2.
• Burst (Legendary): Move forward 3 (stops early if blocked).
• Backflip (Rare): Turn around 180°
• Strafe right (Rare): Move forward if not blocked, otherwise strafe 60° to the right.
• Strafe left (Rare): Move forward if not blocked, otherwise strafe 60° to the left.
• Black Box Recorder (Legendary): Create a copy of the next card and add it to your deck.
• Adaptive Turn (Legendary): Turn towards the nearest tower, donkey, crate or shed.
• Macro (Legendary): re-executes the next two cards with safeguards against loops.