miaoda-game-grid-piece-core

Use this package for pieces that occupy several grid cells: sliding-block puzzles, Tetris-like shapes, grid inventories, packing puzzles, and building footprints. It handles occupancy, bounds, walls, fit tests, one-cell slides, and normalized 90-degree rotation.

Install and use

pnpm add miaoda-game-grid-piece-core

import { PieceBoard, rect, shapeFromRows } from 'miaoda-game-grid-piece-core';

const board = new PieceBoard({ width: 6, height: 6 });
board.add({ id: 'block', shape: rect(2, 2) }, { x: 0, y: 0 });
board.add({ id: 'ell', shape: shapeFromRows(['#.', '#.', '##']) }, { x: 4, y: 0 });

board.slide('block', { x: 1, y: 0 });
board.rotate('ell', 1);
const spot = board.firstFit(rect(2, 1));

Rotations are derived from the original shape and normalized, so four quarter-turns return to the original footprint without coordinate drift. Fit checks exclude the moving piece itself and always reject walls or off-board cells.

Public operations

| API | Purpose | | --- | --- | | add / remove | Manage pieces and their placements | | moveTo / slide | Move one or several cells when free | | rotate / setPlacement | Change orientation and position atomically | | canPlace / canFitShape | Preview a placement | | firstFit | Find the first available placement | | pieceAt / cellState / currentCells | Inspect occupancy | | onChange | Observe detached placement events for UI |

Shapes can be authored with rect, shapeFromRows, or transformed with rotate, normalize, and cellsAt. The board does not implement stacking, equipment slots, puzzle solving, line clears, or scoring.