The Game
EVEN STEVEN is a pure 2D puzzle built on graph chip-firing. The board is a graph; every vertex holds an amount of money, and it can go negative. You win by making every vertex hold the same amount. Every generated board sums to $0, so the amount to reach is always $0. There is no way to lose and no undo: every move is made for good, and running long only costs points.
Every player gets the same board for a given level number, because levels are seeded from the number and nothing in the game is random per player.
How It Plays
Two moves, one goal. Vertices draw green once they hold their share and red until they do, so the whole board turns green at exactly the moment it is won.
Fire
A vertex gives $1 to each neighbour and pays $1 per incident edge. Firing a degree-3 vertex pays out $3.
Left-click · touch tap · keyboard Enter · gamepad A, left shoulder or left trigger
Borrow
The exact inverse: the vertex takes $1 from each neighbour. Green dollars travel for a fire, red ones for a borrow.
Right-click · long-press or second finger · keyboard B · gamepad right shoulder or right trigger
Even Steven
Reach a position where every vertex holds the same amount. Each level is timed, and a win raises a banner with stars and the score, with a fanfare and fireworks that grow with the stars.
Restart or Next: button, keyboard N, or gamepad Y
Money dividing evenly is necessary, not sufficient. The positions a board can reach by firing form one class out of exactly as many as it has spanning trees. A tree has one, so there dividing evenly is the whole condition. Anything with a cycle has more, and which class the money sits in decides the answer.
On a triangle, (1, −1, 0) sums to $0 and can never be evened out, while (1, 1, −2) and (2, −1, −1) both can. The solver decides this exactly; the cheap counting check answers “undetermined” for any board with a cycle rather than guessing.
Current State
The game is playable end to end. What is left is polish, tuning and the shape of the release, listed under the roadmap below.
- Flow
- Splash, then the menu, then the board, then the next level, over a 300-level campaign of five chapters and then Endless. Tapping the splash sends up a firework to wherever you tapped. The first three levels are the tutorial: pay, steal by holding, then steal with a second finger, with an animated finger showing where.
- Input
- Mouse, touch, keyboard and gamepad all play the board. Arrow keys or the d-pad move a cursor between vertices; the cursor stays hidden until a directional press asks for it. The hint under the board names the moves for whatever you are playing with.
- Progression
- Levels unlock a page at a time: every level on an open page can be played in any order, and beating 8 of its 12 opens the next, so one puzzle you can't crack never stops you. The open pages, the level to continue from and the best run on every level beaten are saved between sessions.
- Level select
- One page of 12 levels at a time under its chapter and theme, with how many are beaten, or that it is mastered or locked. Beaten levels show their stars, every tile shows a difficulty tier, and Next reaches one locked page ahead as a preview.
- High Scores
- A personal scoreboard, one row per beaten level: stars, score, moves and time, with the career total above. It is a progress view, not a leaderboard.
- Career total
- Shown in the header while you play, and the win banner says what the win just added to it.
- Settings
- Fullscreen, the visual style, three volumes (master, music, effects) and a Reset-progress confirmation. The music and sound icons on the board mute their volume and bring it back. Reset is the only destructive action in the game, so it is the only one that asks first.
- Visual styles
- Classic, CRT Green, Synthwave and Retro Sunset, each with its own music. One screen shader restyles the finished picture, so no scene knows styles exist; Classic draws exactly what the game always drew.
- Lettering
- The logo is Orbitron Bold and everything else Exo 2 SemiBold, both SIL OFL. On a narrow phone screen the logo shrinks to fit.
- Demo
- This build is the demo: Chapter 1 (levels 1–60) plays. Level Select still pages through the later chapters and the first page of Endless, marked “Full version”, and a Full version screen lists what the full game adds. Every build is the demo unless it carries the full feature tag; no full-game preset exists yet.
- Level editor
- A separate project under leveleditor/ that exports versioned JSON, with its own copy of the difficulty rating.
- Dev importer
- “Import Level (dev)” on the menu plays editor exports from user://levels/. It is visible on debug builds only and is meant to be deleted before release.
- Platforms
-
Windows x86_64macOS universal Linux x86_64Android arm64-v8aAndroid runs the custom Gradle build and is verified on a Pixel 8. All four are exported by ./release.sh.
Architecture
The line that matters: the rules, geometry and easing live in pure classes with no scene dependency, and the board scene only draws and forwards input. That is what keeps them testable.
| Piece | File | Job |
|---|---|---|
| DollarGraph | scripts/dollar_graph.gd | The rules: fire, borrow, the share check. Validates a graph on build and returns null on a bad one. |
| DollarSolver | scripts/dollar_solver.gd | Decides winnability exactly with Dhar's burning algorithm, and returns the true fewest moves (par). |
| LevelGenerator | scripts/level_generator.gd | Runs the game backwards from an all-$0 board, so every level is winnable by construction. Builds to a spec: shape, size, par and the twists a page asks for. |
| Campaign | scripts/campaign.gd | The 300-level campaign as data: chapters, page themes and ranges, page rhythms, and the spec each level resolves to. |
| Tutorial | scripts/tutorial.gd | The lessons on levels 1–3: which move each teaches and where the pointer goes next, including after a stray move. The boards themselves are Campaign.TUTORIAL. |
| Edition | scripts/edition.gd | Demo or full game, and the last level the demo plays. Demo unless built with the full feature tag or run with -- --full-version. |
| BoardLayout | scripts/board_layout.gd | Where vertices sit and which one a click hit. A spring layout that cuts crossings but cannot remove them on dense boards. |
| FirePulse | fx/fire_pulse.gd | Timing and easing for one move. The engine moves the money instantly; the pulse only delays the sight of it. |
| Fireworks | fx/fireworks.gd | The win's fireworks, sized by its stars, and the splash's tapped rockets. Pure timing and geometry, seeded so it is testable. |
| BoardView | scenes/board.tscn | The playing field. Draws the graph and forwards input, owns no rules, geometry or easing. |
| LevelScore | scripts/level_score.gd | Stars and score from moves against par and the time on the clock. |
| LevelDifficulty | scripts/level_difficulty.gd | Rates the board itself, not the player, into five tiers, counting its traps. Also vendored into the level editor. |
| GameProgress | autoload/game_progress.gd | Open pages, the level to continue from, and best score, stars, time and moves per level, saved to user://progress.cfg. |
| GameSettings | autoload/game_settings.gd | Fullscreen, the visual style and the three volumes, kept apart so resetting progress leaves them alone. |
| VisualStyle | scripts/visual_style.gd | The style presets: shader settings and a music track each. Drawn by the StyleLayer autoload with fx/crt.gdshader. |
Difficulty
Designed, then measured. One page to learn the rules, then harder thinking rather than bigger numbers: pages differ in the shape of the board, which way the solution runs, and boards where the obvious move is the wrong one. Par is the true fewest moves, and it lands exactly on what the design asks for on every level.
- The campaign
- 5 chapters × 5 themed pages × 12 levels. Each page plays a rhythm of warm-up, harder levels, breathers below the page and a challenge at the top. Levels 1–3 are hand-made tutorial boards; every other level is generated to its spec. Money never passes $45 on a vertex.
- The levers
- Shape (chains, rings, hubs, wheels, two halves joined by a bridge), direction (pay-only, steal-only, both), breadth, and two traps: detours, moves that bring the board no closer to even, and misleading starts, where the best-looking first move is in no minimal solution. Move order is not a lever: firing commutes.
- Endless
- Past level 300, a full-size board in a sawtooth: 24 levels climbing 16 moves, a reset that keeps a little of the climb, and a breather every 9th level. It starts at par 22, inside chapter 5's range.
- Tiers
-
GentleEasyMediumHardBrutalPage 1 is all Gentle, chapter 1 Gentle and Easy, chapters 2–3 mostly Medium, chapters 4–5 mostly Hard, and Brutal is kept for the hardest challenges. Rated from size, cycles, money spread, how the solution is spread, and its traps; the trap weights and the direction-mix weight are bets on the player, not graph facts.
Scoring
What a solved level is worth. The tests assert the shape of the scoring, not its totals, so the constants can move freely.
- Stars
- Up to 3, from moves against par. Par is the true minimum, so no run beats it; matching it exactly is the best any run can do.
- Score
- From how close to par the run came and how fast. Full marks on the clock need par × 6 seconds, and the time bonus is gone past par × 24 seconds.
- The clock
- Starts when the level is on screen and ready, not on the first move, so a one-move level cannot read 0:00. Running long costs points, never the level.
- Bests
- Score, stars, time and moves are kept per level, all from the same run that set the best score. The career total is summed from the bests rather than stored, so replaying cannot farm it.
- Trust model
- Local only, no server and no online toplist. Levels are deterministic and the solver ships in the client, so scores are a personal record, never a verified ranking.
Roadmap
The campaign is built and measured, so the most useful next input is not code but play: put the v0.4.0 demo in front of a few people and see how far they get and where they stall. That settles the tutorial, the trap weights, the page rhythms, the 8-of-12 unlock and the scoring constants.
The activation effect is still the cheapest visible upgrade if you want something to work on before then.
| Item | Status | Notes |
|---|---|---|
| Playtest the campaign | Needs playtests | The trap weights in the rating, the page rhythms and the 8-of-12 unlock are all guesses until the campaign is played. |
| Misleading-start misses | Open | 25 of 300 levels miss a wish, mostly misleading starts on big boards (Deep Traps, The Hard Way, False Starts, No Easy Moves). |
| Hand-place every level's vertices | Before v1.0.0 | Portrait and landscape, once the campaign's tuning settles; needs a per-level position override first. |
| Hand-made levels | Seam built | The brief's “aha” moments. Campaign.TUTORIAL already pins levels 1–3 to boards written in code; the same seam could take an editor export. |
| Tutorial follow-ups | Needs playtests | A hold-progress ring on every level, not only in the tutorial, and a phone playtest of the two-finger steal and whether the captions fit. |
| Activation effect on fire and steal | Scoped | A shockwave ring is recommended first, on top of the existing glow. See docs/activation-effect-scope-2026-09-08.md. |
| Monetization | Demo built | Desktop: a free Demo and a paid full game. Android: free with one in-app unlock. The demo cap is built (Chapter 1, levels 1–60). Still open: full-game export presets, the store link on the Full version screen, and billing. |
| Tune the score constants | Needs playtests | Base, par bonus and time allowance need real played runs behind them. |
| Re-grade old saves | Not free | Par is never stored, so a star-scale change would mean re-solving every beaten level once. |
| Delete the dev importer UI | Before release | Remove the screen and menu button; keep the JSON parser, importer and open_imported. |
Dev Guide
| Task | Command |
|---|---|
| Test | godot --headless -s res://addons/gut/gut_cmdln.gd -gexit |
| Lint | gdlint scripts/ scenes/ tests/ ui/ fx/ autoload/ |
| Format | gdformat scripts/ scenes/ tests/ ui/ fx/ autoload/ |
| Run (virtual display) | DISPLAY=:99 godot --path . |
| Release | ./release.sh (also publishes these pages) |
- Repo layout
-
scenes/scripts/ui/fx/ autoload/tests/data/docs/ leveleditor/assets/addons/
- Never use :0
- Never run the game against DISPLAY=:0. That is the live desktop, and a window torn down abruptly there can leave keyboard focus stuck until you log out. Use Xvfb on :99 and close the game gracefully.
- Working rules
- Work directly on main, use Conventional Commits, and keep tests green. Tests that touch GameProgress or GameSettings must put them back, since both are global and write to disk.