"My board is easier than I asked for"
Check the Generation report in the analysis pane. If it says "Fallback — filters relaxed", the generator ran out of attempts without finding a board in your window and returned the closest one it saw, rather than pretending.
Usually one of three things: the window is unreachable on that board size (a 4×4 Gridlock board has no 20-move puzzle in it), the attempt budget is too small, or you have stacked constraints — a tight window and Require unique and an exact target. Raise Max attempts, widen the window, or grow the board.
"Require unique gave me a board with several solutions"
It didn't — it gave you a fallback, and the report says so. Boards with exactly one shortest solution are genuinely scarce in this genre, especially on small boards and in Klotski's deep windows.
What helps: more attempts, a slightly wider move window, a larger board. What doesn't: hoping. If uniqueness matters for your design, generate a big batch and use Save ▸ Pack (unique only) to keep the ones that made it.
A board is only reported unique when the solution count is complete. If the search hit its budget mid-count, the board is never treated as proven-unique — a lower bound is not a proof.
"Removal orders not counted above 16 pieces"
That is a design note, not an error. Clear counts the exact number of valid removal orders by subset dynamic programming, which is only feasible up to 16 blocks; above that the count is astronomically large and simply not computed.
The board is still completely verified — solvable, chain depth exact, difficulty rated. The only consequence is that Require unique (a forced removal order) can't be checked on boards with more than 16 blocks.
"Search budget exhausted" / "budget hit while finishing the winning layer"
The BFS has a state cap far above any sane board. Hitting it means the layout is pathological — usually many identical blocks on a large open board.
- "Budget hit while finishing the winning layer" — the par is proven; only the solution count is incomplete. The board is fine to ship unless you needed uniqueness.
- "Search budget exhausted" — the board wasn't proven either way and the generator will reject it. If you see this constantly, shrink the board or reduce the piece count.
"My Clear board has gaps even at Fill 1"
Pieces overrides Fill. If the Pieces dial is non-zero, placement stops at that many blocks and the rest of the board stays empty, whatever Fill says. Set Pieces to 0 and Fill takes over.
Or the board ran out of pieces. Every block carries a bitmask of what blocks it, and that mask is 64 bits wide, so a board holds at most 63. On a large board of single cells the ceiling arrives long before the board is full — a 16×16 wants 256 cells covered and 63 single blocks reach a quarter of them. Generation does not hide this; the analysis says “Piece budget reached (63 max): 84 of 256 cells left empty” and names the two dials that fix it.
Both fixes are the same idea — cover more cells with fewer pieces. Raise Max piece length to 2–3, or use Clear Snakes, where a rope averages several cells: a packed 16×16 needs about four cells per piece, which a car cannot reach and a rope manages comfortably.
Blocks longer than one cell can also leave a hole where nothing fits, which is normal and usually reads as deliberate spacing.
"Why won’t Gridlock go past 8×8?"
Flat Clear boards (including Clear Snakes) reach 16 a side; every other mode stops at 8. The split is measured, not arbitrary.
Clear is a dependency graph — it works out which block blocks which, then peels the board in layers. That costs about the same whatever the board size: 0.2–0.9 ms a board from 4×4 to 8×8.
Gridlock and Klotski have to SEARCH: they explore reachable arrangements until the hero reaches its goal, because that is the only way to prove a shortest solve rather than guess one. At 8×8 that is already about 6 seconds a board for Gridlock and 23 for Klotski, and it grows sharply from there. The cap protects you from a frozen editor.
Bigger is also easier for those modes: more space means blocks get in each other’s way less, which is the opposite of what a bigger board suggests. Klotski’s classic layout is 4×5 for exactly that reason.
"My 3D structure came out as a scatter"
A lattice caps at 63 blocks, so a large volume cannot be filled — an 8×8×8 request wants 512 cells covered and can only get about 140. The window warns you before you generate when the volume exceeds what the budget can cover.
Sizes that pack solid: 4×4×4, 6×6×3, 8×8×2 — all three ship as presets. Raise Max piece length to 2–3 so each block covers more cells.
"Generation feels slow"
Klotski is the heavy mode by design: every candidate is fully searched, and depth engineering maps the whole reachable space first — roughly 0.2–1 second per board. Gridlock and Clear are far cheaper.
Generation runs on a background thread, so the editor stays responsive and Cancel works mid-batch. For large Klotski batches, lower Max attempts (60 is plenty when the window is realistic) and generate in several smaller batches.
"Invalid board" or an unsolvable hand-built puzzle
KlotskiPuzzle.Validate explains itself: blocks out of bounds, overlapping blocks or obstacles, the wrong number of heroes, a Clear block with no arrow, a checkpoint sitting on an obstacle, a Gridlock hero that isn't on its exit lane or whose axis can never reach the exit side.
For hand-built boards, call Validate first and then KlotskiSolver.Analyze (or ClearSolver.Analyze) — the analysis carries a plain-language warning when no solution exists.
"Blocks render pink or ignore my colours"
Pink means the material's shader isn't valid for your pipeline — that's a project-level issue, not the toolkit. The demo tints through a material property block that sets both _BaseColor (URP/HDRP) and _Color (Built-in), so a standard-lit prefab tints correctly in all three.
If your own prefab uses a custom shader with different property names, either add those names to your shader or tint the blocks yourself and leave the renderer's colours alone.
"The demo builder menu items are missing"
Intentional. The demo scene ships pre-built, so the one-click builders that construct it are commented out — a menu item that can wipe a scene doesn't belong in a shipped package. They're still in Assets/SimpleKlotski/Editor/Tools/; uncomment the [MenuItem] line to use one.
Seeds & reproducibility
A seed plus the same settings always reproduces the same board within a given version of the toolkit. Seeds travel with the puzzle asset, so a board you liked can always be regenerated — and a bug report with a seed is a bug report I can reproduce exactly.
Generator improvements in a future version may change what a given seed produces. Saved puzzle assets are unaffected — they store the board, not a recipe to re-derive it.
Still stuck
Email livingfailuregames@gmail.com with your Unity version, the mode, and — for anything board-specific — the seed and settings. Seeds make it exact.