Simple Klotski

What it is

Simple Klotski generates sliding-block puzzles — the genre of the wooden Huarong Dao puzzle and of every "shunt the vehicles out of the lot" game. A board is a small grid holding rectangular blocks; a move slides one block, in one direction, as far as you like.

It doesn't just make boards — it solves them. Every generated puzzle carries its proven shortest solution (the par), how many shortest solutions exist, the moves themselves, a 1–5★ rating and a generation report — all deterministic from a seed string, all stored in a ScriptableObject.

The five modes

Why "verified" matters

• The par is real. Breadth-first search over a canonical state space returns the shortest solve that exists — so a "20-move puzzle" takes 20 moves.
• Difficulty is engineered. Klotski boards are built backwards from the solved position to hit the depth you asked for, then re-verified forwards.
• Clear cannot dead-end. Removing a block only unblocks others, so the player can never strand themselves — a property of the mode, proven once.
• Checkpoint boards solve as one problem. The win test is hero and plate coverage together, so the par accounts for the plates.
• Fallbacks are reported. When constraints can't be met you are told, rather than quietly shipped an easier board.

Quick start

Requirements: Unity 6000.3+. The core is pure C# with no package dependencies; the demo uses TextMesh Pro and the Input System. Built-in, URP and HDRP.

Dials & difficulty

Board size (3–16 a side for flat Clear, 3–8 elsewhere), piece count, obstacles, checkpoints, seed, batch count, and the move window. Two ways to ask for difficulty:

• Target difficulty (0–5★) snaps the window to that star's band.
• Min / Max moves is the window itself — a board is accepted only if its proven par lands inside it. In Clear the window measures chain depth, since every Clear board takes one tap per block.

Star bands — Gridlock: ≤4 / ≤8 / ≤13 / ≤19 / 20+ moves. Klotski: ≤10 / ≤25 / ≤45 / ≤70 / 71+ moves. Clear: chain depth ≤2 / ≤3 / ≤5 / ≤7 / 8+.

Per-mode notes

Gridlock. Shape sets the axis — wide blocks slide sideways, tall ones up and down. The hero starts biased away from its exit, traffic is packed to a tight density, and layouts whose hero lane is already clear are vetoed. Windows above ~12 moves are where the brain-burners live.

Klotski. Built backwards from the solved position and re-proved forwards. Hero size is 1–2 per side (2×2 is the classic; the cap exists because a 3-wide hero needs three aligned free cells to move at all). The heavy mode: ~0.2–1 s per board.

Clear. Built from a witness removal order, so solvability is structural. Two looks from two dials: max piece length 1 + high fill gives the packed arrow-grid; lengths 2–3 at moderate fill gives the parking-lot look. Leave Pieces at 0 or it overrides Fill.

Clear 3D. Raise Board depth above 1. A lattice caps at 63 blocks, so the window warns when the volume can't be covered; 4×4×4, 6×6×3 and 8×8×2 pack solid. Obstacles and checkpoints are 2D-only.

Clear Snakes. Pieces bent into ropes with one arrowhead, which slither out head first along their own body — so only the single lane ahead of the head has to be clear, however much the body winds. Three dials: Snake ratio (share of pieces grown as ropes), Max length (a multiple of width + height, so it travels between board sizes) and Bendiness. Ropes are what make large boards work — 63 pieces cover a 16×16 only at about four cells each.

Obstacles & checkpoints

Obstacles are permanently blocked cells, scattered by a distribution scorer that penalises clumping so they read as designed walls; Gridlock also keeps them out of the hero's escape lane.

Checkpoints are pressure plates: the win becomes "hero home and every plate covered". Because the solver treats that as one conjoined condition, a non-hero block settling the last plate can be the winning move — and the par accounts for it.

API essentials

Generate:

Read: puzzle.MinMoves (par), puzzle.Difficulty, puzzle.Solvable, puzzle.Report.Matched, and puzzle.Analysis.BestSolution for the moves.

Play: game.LoadLevel(puzzle), then TrySlide / TryRemove, Undo, PlayHint, StartAutoSolve, and the LevelSolved event. Solve anything yourself with KlotskiSolver.Analyze(puzzle) or ClearSolver.Analyze(puzzle).

Many boards, or boards without a frozen frame: KlotskiBatch.Generate(settings) picks the right generator for the mode, and KlotskiBatch.GenerateAsync(settings, count, progress, cancel) runs a whole batch on a background thread with per-attempt progress for a loading bar. The progress callback arrives on the worker thread — read it back in Update(), do not touch UnityEngine objects from it.

Full surface in the API Reference.

The demo

One scene plays all five modes: Canvas menu, 3D board, HUD with par scoring, undo, hints, a step-by-step auto-solver, procedural sound and a win flow.

Controls — Gridlock/Klotski: drag a block to slide it. Clear: click a block to send it off. Clear 3D: click to pull free, Alt-drag or right-drag orbits, middle-drag or Shift-drag pans, scroll zooms. R reset, Z undo, H hint, F auto-solve.

Assign packs to the KlotskiDemo component to light up each mode's Play Level Pack button; Play Endless needs nothing.

Reskinning

• Piece / hero prefabs — authored for a 1×1 cell; the renderer scales them to each block's footprint.
• Arrow glyphs — three optional textures (arrow, circled dot, circled cross), white on transparent, 512×512 with margin. Empty slots fall back to generated glyphs, so zero-art projects still read correctly.
• Colours & layout — every colour, cell size and height is a field. Tints set both _BaseColor and _Color, so Built-in, URP and HDRP all work without shader swaps.

Troubleshooting

Easier than I asked? Read the generation report — "Fallback" means the window wasn't reachable in the attempts allowed. Raise Max attempts, widen the window, or grow the board.

Require unique didn't? Unique boards are scarce; you got a reported fallback. Generate a batch and use Save ▸ Pack (unique only).

"Removal orders not counted above 16 pieces"? A design note, not an error — the count is astronomically large above 16 blocks. The board is fully verified; only Require-unique can't be checked there.

Gaps in a Clear board? The Pieces dial overrides Fill; set it to 0.

3D structure came out sparse? A lattice caps at 63 blocks — use 4×4×4, 6×6×3 or 8×8×2, and raise max piece length.

Slow? Klotski searches every candidate; use smaller batches and a realistic window. Generation is threaded and cancellable.

Missing demo builder menu items? Deliberate — the scene ships built, and the builders' [MenuItem] lines are commented out in Editor/Tools/.

The full list lives in Troubleshooting.

Limits, honestly

• Flat Clear boards run 3×3 to 16×16; the sliding modes stop at 8×8, where their search already costs seconds a board. Any board holds at most 63 pieces.
• Single-solution boards are scarce — hunt for them, but expect fallbacks.
• Clear counts removal orders exactly only up to 16 blocks.
• High star bands need board room; small boards genuinely don't contain them.
• Seeds reproduce boards within a version; saved assets store the board itself, so they are unaffected by future generator changes.

Support

livingfailuregames@gmail.com — include your Unity version, and the seed and settings for board-specific questions. Seeds make it exact.