Merge workshop puzzles

What it does

The board is a set of cells the player can drag between freely. Two identical items merge into one of the next tier in their named chain, and an order is filled when the exact tiers it asks for are on the board or in storage. Producers hand out items from finite queues, with charges, cooldowns, energy costs and optional order prerequisites. Sealed items cannot move or fill orders until an identical movable item merges into them, and closed cells open after a number of deliveries.

Every merge keeps the total value of its chain and reduces the item count by one, and generated levels hold exactly the material their orders need. So the number of merges a level needs is exact: the items on the board plus the supplies still to come, minus the items the orders take. The generator checks that its replayed route uses exactly that many. With nothing to spare, a careless merge or a supply taken too early can fill the last usable space before the right item arrives.

At medium difficulty and above, the generator also plays each candidate with three simple strategies, taking from the queue first, merging first and filling orders first, and keeps it only when a separate solver proves each of them reaches a dead end. That is a concrete guarantee that the level needs planning, not a claim about how often people win. solve searches for a route from any position and tells a proven dead end apart from a search that ran out of budget, and both generation and solving can run as cancellable background jobs.

Features

• Pair merges by chain — two identical items become one of the next tier, and exact tiers fill orders.
• Finite producers — visible supply queues with charges, cooldowns, energy costs and order prerequisites.
• Storage, sealed items and locked cells — tight storage slots, sealed twins to free, and cells that open after deliveries.
• Seeded generation — four difficulties, from 3 to 8 required merges at easy to 39 to 49 at very hard.
• Six board shapes — rectangle, courtyard, wings, terraces, islands and mosaic, rotated through by default.
• A planning check — harder levels are kept only when three simple strategies are proven to fail.
• Exact merge counts — requiredMerges gives the merges a level needs from any position.
• Honest solving — solve returns solved, unsolvable or budget-exhausted, and resourceFailure proves a missing tier or energy cheaply.
• Background jobs — cancellable generation and solving off the main thread.
• Undo, redo and reset, with every action checked and applied whole.

Good for

• Merge-workshop puzzles in the style of Merge Mansion or Travel Town, made into finite levels with a solution.
• Puzzle ladders that rise from a generous starting board to tight, multi-order levels with prerequisites.
• Daily puzzles, where a seed reproduces each level and its winning route.
• Hint buttons and dead-end warnings, from live solving in the background.
• Hand-made levels with your own chains, producers and orders, checked by the same rules and solver.

Make it yours

The generator takes a seed and a difficulty, and you can set the board layout, the number of chains, orders and required merges, the working cells, the storage slots, the sealed targets, the producers, and whether the planning check applies. Within those, the seed varies the order tiers and their dependencies, how the merge trees split, the starting items, the sealed targets, the producer queues and which cells unlock.

Two quite different uses: a relaxed level with the planning check turned off, a large starting inventory, sealed twins and cells that open as orders are delivered, for a calm early game; and a very hard level with ten working cells, one storage slot and three competing supply queues, where order prerequisites mean the sequence of producing, merging and delivering is the whole puzzle. Authored configurations can go further, up to 100 cells, 8 chains, 24 orders and tier 10.

A quick look

Generate a level, inspect the actions available, and play one:

const level = game.mergeWorkshop.generateMergeWorkshop({ seed: 7, difficulty: 'hard' });
const puzzle = game.mergeWorkshop.createMergeWorkshop(level.config);
const played = puzzle.apply(puzzle.actions()[0]!);   // { valid, reason }
const hint = puzzle.solve(5000);                      // solved, unsolvable or budget-exhausted
if (hint.status === 'solved') highlight(hint.actions[0]);

Works with

• match3 — for merges made by placing and matching adjacent groups rather than dragging pairs.
• place-merge — for placing tiles that merge with their neighbours on a grid.
• tween — to animate merges, deliveries and items moving to storage.

Good to know

• These are bounded puzzles with visible supplies, not an endless random producer economy; there is no expiry, selling, random refill or real-time waiting.
• Board shapes affect presentation only: dragging is unrestricted, so the challenge comes from queues, capacity and exact orders, not adjacency.
• A search that runs out of budget is not a dead end, and should never be shown to the player as one.
• Routes from solve are valid but not promised to be the shortest in total actions.
• Over-merging a requested tier or using up a sealed item's last partner can make a level unsolvable; undo and reset recover.