Peakjoker

A TriPeaks solitaire roguelike that grafts Balatro's full system stack onto the TriPeaks card-clearing loop. Clear chains of rank-adjacent cards to build a chips × mult score, beat rising blind thresholds across antes, and spend money in a shop on jokers, consumables, deck upgrades, and vouchers — chasing emergent, run-defining combos.

The defining adaptation: a streak is a "hand." Clearing rank-adjacent cards in a row builds the streak (each clear adds chips and pumps mult); drawing from the stock banks the streak and starts a new one. "Push the streak vs. bank it and draw" is the core tension — the direct analog of Balatro's limited hands.

The strategy is "the spatial Balatro": board geometry (which peak, how deep, what a card covers, the order you free it) is a first-class scoring and build surface — the axis Balatro structurally can't touch, because its cards have no position.

Status

M0–M17 complete + Phase-3 polish arc complete — 0.18.0, a tester-ready beta. The full game is built: a complete TriPeaks-roguelike run (board → blinds → shop → jokers / consumables / vouchers → boss → ante escalation), meta-progression + versioned save, daily seed + run-share, mid-run save/resume, a win-gated stakes ladder, modding, and controller / Steam-Deck support — 743 headless tests green. The game was built by the autonomous /milestone-cycle loop across the M0–M17 arc in ROADMAP.md; a subsequent Phase-3 polish arc — in-game QA plus a 19-commit "clear the invisibility gaps" sweep that surfaced everything the engine computes but no screen showed — brought it to a tester-ready beta. Remaining work is tester-feedback-driven (feel / difficulty tuning), tracked in docs/SESSION_NOTES.md; the beta-tester guide is BETA_TESTING.md.

• Roadmap: ROADMAP.md — M0–M17, each with scope + acceptance criteria
• Master design spec: docs/superpowers/specs/2026-06-06-peakjoker-design.md
• Strategy / scope: docs/designs/peakjoker-balatro-expansion.md
• Session handoff: docs/SESSION_NOTES.md
• Deferred work: TODOS.md · Changelog: CHANGELOG.md

Tech stack

Area	Choice
Engine	Godot 4.6.3 stable, Compatibility renderer (2D, keeps web export cheap)
Language	GDScript (headless-testable; no C# toolchain weight)
Tests	gdUnit4 (headless, CI-wired from M0)
Scoring	Fixed-point integer math (cross-platform deterministic)
Cards	Adrian Kennard SVG deck (CC0) · icons Kenney.nl (CC0) — see assets/ATTRIBUTION.md
CI	GitHub Actions (gate) + Codeberg/Forgejo (best-effort)

Architecture (in one breath)

A decoupled deterministic core + data-driven content. The core/ is pure GDScript (RefCounted/Resource only) and never touches the scene tree — it is a deterministic state machine with a single mutation entry, apply(action) → [events]. Presentation observes events and renders; it never mutates the core. Same seed + same actions[] ⇒ bit-identical result, every run — so a replay is a unit test. Content (jokers, bosses, consumables, vouchers, …) is authored as validated, read-only Resource .tres files composed from a small effect-primitive vocabulary. See the design spec §3 for the full layout.

res://
├── core/          # pure GDScript: rng, card, deck, board_state, score_engine, run_state, shop, blind, game_controller
├── content/       # data-driven content: defs/ (Resource classes), effects/ (hooks), data/ (.tres instances)
├── presentation/  # Godot scenes/nodes — observe the core, never mutate it
├── app/           # autoloads: Game, Save, Assets, Audio
└── tests/         # gdUnit4 — seeded, headless

Build & test

# build the import cache once (required before headless tests)
godot --headless --import

# run the headless test suite — canonical local runner (exit 0 = pass)
./run_tests.sh                  # CI uses ./addons/gdUnit4/runtest.sh -a res://tests under xvfb

# play it (windowed)
godot --path .

License

Peakjoker is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE.

Bundled art assets are licensed separately under their own permissive terms (CC0 / CC BY) — see assets/ATTRIBUTION.md.