Ink Sokoban

Terminal Sokoban built with Ink. Push every crate onto its mark to clear each of the bundled puzzles — a 40-level campaign that starts with tiny one-screen warm-ups and grows into wide, walled vaults with a dozen crates to shuffle.

Install

Requires Node 20+.

The unscoped name ink-sokoban may be taken on npm, so this package publishes as @terminalgames/ink-sokoban. The command is still ink-sokoban.

Run without installing (easiest)

npx @terminalgames/ink-sokoban

Global install

If npm install -g fails with EACCES, your npm global prefix is probably system-owned (/usr/local). Either use npx above, or point npm at a user-owned directory:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @terminalgames/ink-sokoban

Then:

ink-sokoban

How to play

Move the player (☻) around the grid and push crates (◇) onto the target marks (·). A crate sitting on a mark turns into ◆. Clear a level by filling every mark; then press n for the next puzzle.

Moves are turn-based and grid-aligned. You can only push crates — never pull — and a push is blocked if a wall or another crate is behind the crate. Stuck? Press u to undo (unlimited, back to the level start) or r to restart.

Controls

| Key | Action | | --- | --- | | h / ← | Move left | | j / ↓ | Move down | | k / ↑ | Move up | | l / → | Move right | | u | Undo last move | | r | Restart level | | n | Next level (after a solve) | | p | Pause / resume | | ? | Toggle help (shows legal pushes) | | q | Quit |

The sidebar tracks the current level, move count, push count, undo count, and resets.

Development

npm install
npm run build
node dist/cli.js

npm test
npm run typecheck

Game logic lives in pure TypeScript modules under src/game/ (levels.ts for the puzzle data + XSB parser, engine.ts for the move/push/undo rules); the Ink UI is under src/ui/. Every shipped level is verified solvable by a search in tests/game/levels.test.ts.

Two dev-only helpers live under scripts/ (build first, then run with node): verify-levels.mjs runs that same BFS but prints per-level diagnostics (dimensions, crate count, solution depth, nodes explored) for tuning new layouts, and preview.mjs <index> renders a single level the way the player sees it.

Credits

The bundled levels are original layouts written in the compact, one-screen style popularised by the Microban collection by David W. Skinner.

Publish

Maintainers only. Requires access to the @terminalgames npm organization:

npm login
npm publish --access public