Shape packing puzzles

What it does

You create a puzzle from a target and a list of pieces, then hand it placements: a piece, a position, a rotation and whether it is mirrored. The puzzle accepts a placement only when the piece stays inside the silhouette and overlaps nothing; otherwise it says why, such as overlap or outside-target, and changes nothing. Placing a piece that is already down moves it as one move, preview tells you what a drop would do before the player lets go, and solved turns true when every piece is placed and the target is covered exactly.

Three boards sit behind that one interface. Square cells suit pentominoes, polyominoes and block jigsaws. Hex cells use axial coordinates with 60-degree turns, for hexomino and hex jigsaw puzzles. The polygon board checks true area overlap and containment, exact to 1e-7, for the seven tangram pieces. Helpers turn a pointer into a cell and a cell into a point to draw at, so drag-and-drop needs no hex maths of your own.

generateShapePacking makes the content. It cuts a layout, or a silhouette you supply, into connected pieces of a chosen size, shows each one in a random pose, shuffles them and replays its own solution before returning it. That solution is also your hint source: solveBest hands back the next placement from it while it still fits around what the player has done, and falls back to a search when it does not.

The pack is pure rules, deterministic from a seed, and draws nothing, so a 2D or 3D presenter shows it in whatever style the game needs.

Features

• Three boards — square cells, axial hex cells and exact polygons, all with the same place, remove, preview and solved.
• Rotation and mirroring — the allowed angles and reflection are set per puzzle: multiples of 90 degrees on squares, of 60 on hexes, any angle on polygons.
• Clear rejections — an invalid move returns a reason (overlap, outside-target, invalid-transform, off-grid, unknown-piece) and leaves the puzzle untouched.
• Seeded generator — cuts a rectangle, cross or steps of squares, a hexagon, diamond or triangle of hexes, or your own silhouette into connected pieces, with a replay-checked solution.
• Four difficulties — easy, medium, hard and very hard set the board size, the piece size and whether pieces may be mirrored.
• Tangram deals — polygon mode deals the seven tangram pieces into a 4 by 4 square or its 45-degree diamond, with every fitting pose listed so the solver can work.
• Hints and a solver — solveBest follows the generated solution while it still fits; solve searches breadth-first within a budget you choose.
• Undo, redo and reset — every place and every remove is one move.
• Pointer helpers — cellAt finds the cell under a point and snaps polygon poses to a lattice; cellCentre and hexCentre say where a cell sits on screen.

Good for

• Pentomino and polyomino packing — the classic fill-the-rectangle puzzles, with rotation and mirroring.
• Fill-the-shape mobile jigsaws — generated levels of block pieces dropped into a silhouette, at rising difficulty.
• Hex jigsaws — hexomino puzzles in a hexagon, diamond or triangle with 60-degree turns, in the style of Hexa Puzzle.
• Tangram squares — the seven traditional pieces into a square or a diamond, checked with exact geometry.
• Custom silhouettes — a shape of your own, as a set of cells, cut into pieces by the generator.
• Pure fitting games — with rotation turned off, every piece keeps its pose and the puzzle is about position alone.

Make it yours

A puzzle is a plain config: the mode, the target cells or polygon, up to 32 pieces, the allowed rotations, whether pieces may be mirrored and, for polygons, the candidate poses the solver may try. You can author puzzles by hand and pass your own solution for hints, generate them, or mix the two by giving the generator your own silhouette.

The generator takes a mode, a difficulty, a seed, a layout and size, a piece size and a minimum piece size, and switches for rotation and mirroring, so a level ladder is a list of options rather than a list of levels. Three materially different uses:

• A hand-authored pentomino rectangle on square cells, mirroring allowed, with the solution you supply driving hints.
• A daily hex jigsaw generated from the date as its seed at hard: a radius-three hexagon cut into four-cell pieces that may be mirrored.
• A tangram diamond in polygon mode, with pointer poses snapped to the half-unit lattice by cellAt.

A quick look

Deal a generated hex puzzle, drop a piece where the pointer is, and ask for a hint:

import { cellAt, createShapePacking, generateShapePacking } from '@phaser-ae/shape-packing';

const deal = generateShapePacking({ mode: 'hex', difficulty: 'hard', seed: 23 });
const puzzle = createShapePacking(deal.config, deal.solution);

const at = cellAt('hex', { x: (px - boardX) / cell, y: (py - boardY) / cell });
const r = puzzle.place({ id: 'C', x: at.x, y: at.y, rotation: 120, mirrored: false });
if (!r.valid) bounce(r.reason);               // 'overlap', 'outside-target', …
const hint = puzzle.solveBest().actions[0];   // the next placement, or undefined
if (puzzle.solved) win();

Works with

• placer — the one to reach for when pieces drop onto a board to clear full lines, rather than fill a shape.
• sliding-blocks — for puzzles where pieces slide about a board instead of being placed.

Good to know

• A puzzle has at most 32 pieces; the generator throws when a cut needs more, so raise the piece size or shrink the target.
• The solver tries every pose at every cell without pruning, so beyond about 20 target cells its default budget of 20,000 positions is thin; keep the generated solution for hints.
• The generator makes only the square and diamond tangram at right-angle poses. Other tangram silhouettes need their own target and candidate poses, and pointer poses must be snapped, since polygon fits are exact.
• The generator checks that its solution works but makes no claim that it is the only one.
• A placement is a pose, not a path: a piece may be dropped anywhere it fits, and a wrong placement can block the generated solution until the player undoes it.