Shelf sorting puzzles

What it does

A puzzle is a set of shelves. Each has a front of visible slots and, behind it, an ordered queue of stock rows. The player moves one item from any front slot into any empty slot on another shelf. When a front holds enough identical items, three by default, they clear at once, even if the shelf holds other goods too. When a whole front is empty, the next row of its stock fills it from the left. Some working bays start locked and open once a set number of groups has been cleared.

Every move goes through preview first if you want it to: it says whether the drop is legal without changing anything, which is all a drag needs for green or red feedback. apply makes the move and returns its events in order, moved, matched, refilled and unlocked, for your game to animate. An illegal move, such as into a locked shelf or an occupied slot, changes neither the state nor the history. Undo, redo and reset restore the fronts, the hidden stock order, the locks and the move count exactly.

generateShelfSort makes the levels. It builds complete stock waves, constructs a solution through the working bays, mixes the fronts with reversible legal moves and replays the whole route through the matching, refill and unlock rules before handing it back, with measurements of what it made. It also returns a layout: where each shelf sits, in slot widths, as a cabinet, staggered rows, islands, a pyramid or a seeded procedural cabinet, so a 2D or a 3D presenter can place the shelves without layout code of its own.

Features

• Fronts and hidden stock — each shelf has visible slots and an ordered queue of rows revealed only when its front is empty.
• Matching on the shelf — a front clears a group of identical items as soon as it holds enough; the group size is two to five in generated levels.
• Locked working bays — extra bays open after a number of groups is cleared, and move limits are optional.
• Previews and events — preview checks a drop without changing anything; apply returns ordered moved, matched, refilled and unlocked events.
• Seeded generator — easy, medium and hard presets, from three source shelves and one stock wave up to five shelves and three waves, with a replay-checked winning route.
• Measured levels — the generator reports goods, hidden stock, opening choices, mixed fronts, mixing moves actually made, solution length and refills.
• Shelf layouts — five arrangement families, chosen directly or rotated through by level number, in renderer-independent units.
• Hints with honest answers — solve follows the level's checked route or searches within a state budget, and says solved, unsolvable or budget-exhausted.
• Undo, redo and reset — and a saved config plus the accepted moves reproduces a session.

Good for

• Goods-sorting puzzles in the style of Goods Sort, with stocked shelves, hidden rows and limited working space.
• Mobile puzzle sagas that need a steady supply of seeded levels with rising stock depth and mixing.
• Daily or endless modes, where a seed and a level number produce the next level and its shelf arrangement.
• Move-limit challenges, where maxMoves turns a relaxed sort into a tight one.
• 3D shop or pantry scenes, since the layout gives every shelf a pose and the rules never touch the renderer.

Make it yours

Levels can be authored or generated. An authored ShelfConfig lists the shelves, each with its slots, optional stock rows and an optional unlock threshold, plus the group size and an optional move limit; shelves may have different capacities. The generator takes a seed and a difficulty, then lets you override the number of source shelves, stock waves, group size, working bays and their capacity, locked bays and when they open, and how many mixing moves to make. Layout is its own choice: pick a family, or pass a level number and a period and the families rotate as the player progresses.

Two materially different setups:

• A gentle early level: three source shelves, one stock wave, one open bay and no locks, from the easy preset.
• A hard late level: six source shelves with four waves of stock, two locked bays that open after several clears, a four-slot working bay and a procedural cabinet layout, with a move limit added to the generated config.

A quick look

Generate a hard level, check a drag, make the move and ask for a hint:

import { createShelfSort, generateShelfSort } from '@phaser-ae/shelf-sort';

const level = generateShelfSort({ seed: 12345, difficulty: 'hard', waves: 4, layout: 'procedural' });
const puzzle = createShelfSort(level.config, level.solution);
const action = { from: 's0', slot: 0, to: 'b0', target: 0 };
if (puzzle.preview(action).valid) puzzle.apply(action);   // moved, matched, refilled, unlocked
const plan = puzzle.solve(5000);                          // only 'solved' is a proven hint
for (const c of level.layout.compartments) placeShelf(c.id, c.x, c.y, c.width);

Works with

• container-sort — for games where whole stacks pour between containers instead of single items moving.
• tray-match — for collecting accessible items into one holding tray instead of sorting shelves.
• world-3d and render-3d — to present the shelves and goods as a 3D scene.

Good to know

• A checked route proves a level can be won, not that it is the shortest route or how hard a person will find it.
• lost means the move limit is reached or no useful move is left; it does not prove that every other position is winnable.
• Search is synchronous and bounded, so large authored puzzles may exhaust the budget; call hints on demand and move heavy authoring searches to a worker.
• Stock is a fixed queue per shelf, not a free-form inventory, and a puzzle has at most 16 shelves.
• The pack draws nothing and does no picking or dragging; your game presents the events.