How itwas built

Why a snapshot

Compose recomposes whenever an observed state changes. The renderer, with direct access to WorldState, would be reading a mutable object that is running and updating the simulation, whilst recomposition would be triggered by every individual field write.

Instead, WorldState.toSnapshot() builds a GameSnapshot - flat lists of render structs with positions already interpolated and textures already resolved. The composable always holds one snapshot reference and swaps it a new one. Simulation types never cross into the UI layer, so the renderer cannot accidentally mutate the world, and the simulation can be tested without Compose in the loop.

Services rather than one god object

Whilst technically, our game isn't complicated enough to hold all of these operaitons in a single file, we decided to create the split for readability's sake. The rules are split into stateless companion objects, each taking the grid and returning a result: GridService generates terrain, HazardService places lava and quicksand, TravelService does pathfinding, EntityService builds enemy routes, UpgradeService handles pickaxes.

WorldState holds the mutable data and orchestrates them. GameEngine sits above it, owning the player across levels and translating queued commands into world requests. The layering means a level transition is world = createWorld() and nothing else needs to know.

Ore distribution, and a mistake in it

Each tile rolls through a chain of independent random checks, with rarer ores unlocking at set levels and their odds rising slowly with depth:

if (random() < dirtChance)      DIRT
else if (random() < stoneChance) STONE
else if (random() < ironChance)  IRON
else if (random() < goldChance)  GOLD
else if (random() < diamondChance) DIAMOND
else STONE

This does not do what the constants suggest. Each check only runs if every earlier one failed, so the real probability of iron is (1−dirt) × (1−stone) × iron, not ironChance. And the final else is stone, so stone silently absorbs all the leftover probability mass.

It produces boards that play well, which is why it survived. But the tuning constants don't mean what they appear to, and any future adjustment has to reason about the whole chain rather than one number. The correct form is a single roll against cumulative weights.

Hazard clustering

Lava and quicksand are placed after terrain, onto dirt and empty tiles only, with the spawn corner excluded. Placement seeds a tile then tries to grow into shuffled neighbours, so hazards form small patches rather than pepper — a scattered single-tile hazard is trivially walked around and adds nothing.

The solvability invariant

The generator originally enforced a local property: every ore your pickaxe can break must have at least one neighbour it can also break. If it didn't, one neighbour was demoted to dirt.

Local adjacency does not add up to global reachability. Nothing checked that a route existed from the spawn corner, so a well-connected pocket of ore completely walled off by harder rock satisfies the invariant and is still unreachable. It's the kind of bug that's rare enough to survive a lot of playtesting and obvious in hindsight.

The fix reuses the pathfinder: flood-fill from the spawn corner over tiles the current pickaxe can pass or break, and confirm every countable ore is inside the reachable set. No new algorithm — the same BFS that already answers "can the mole get there," asked once per generated board.

The level that couldn't be completed

Levels end when the count of remaining mineable ore reaches zero. That count was computed in the world's constructor. Chest generation ran afterwards, overwriting a 3×3 region with hardstone.

Any ore inside that region was destroyed but still counted, and hardstone isn't countable, so nothing could ever decrement it. The count could not reach zero and the level could not be finished.

It only triggered with a diamond pickaxe, which is deep enough into a run that it took a long time to see. The fix is recomputing the count after generating the chest. The lesson is that a constructor default is evaluated at construction, and anything mutating the object afterwards owns the consequences.

A loop that iterated values as indices

The solvability repair collected four neighbour states into a list — 1 diggable, 0 not, -1 off-grid — then looped to find one to demote:

for (index in validTiles) {        // iterates VALUES, not positions
    if (validTiles[index] == 0) {  // validTiles[-1] throws

Kotlin's for (x in list) gives elements, not indices, and it compiles fine when the elements happen to be integers. It needed validTiles.indices.

It hid behind a second bug. A neighbouring function returned coordinates as (col, row) while everything else used (row, col), so the check was validating a transposed grid — and on a square board that looks like it works. Correcting the transposition immediately exposed the crash, because the check finally started examining tiles that needed repairing. Two bugs, each concealing the other.

A trim applied to the wrong kind of movement

Pickaxe reach works by removing the last n tiles from a path. Being hit also produces a path — a two-tile knockback. The trim didn't distinguish between them.

With a diamond pickaxe, three entries were removed from a three-entry knockback path, leaving nothing. The knockback moved the mole zero tiles, and invincibility ends the moment a path empties, so the player was still standing on the enemy and lost a heart every tick until dead. It read as instant death on contact.

It also crashed elsewhere: with reach 3 and an adjacent target, the path is two entries and the third removal calls removeAt(-1). Both had gone unnoticed because the arithmetic only breaks at the highest pickaxe tier, and by then most adjacent tiles are already empty and take a different code path.