Ink Match-3

A terminal Match-3 swap puzzle built with Ink. Swap adjacent gems to line up three or more of a kind, then watch the cascades chain for bonus points. Endless mode — play for a high score.

Install

Requires Node 20+.

The unscoped name ink-match3 is published under the games org, so this package is @terminalgames/ink-match3. The command is still ink-match3.

Run without installing (easiest)

npx @terminalgames/ink-match3

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-match3

Then:

ink-match3

How to play

1. Move the cursor over a gem.
2. Press space / enter to pick it up (it highlights).
3. Move toward an orthogonal neighbour (h j k l or arrows) to swap.

A swap is only allowed if it forms a line of 3 or more matching gems — otherwise it flashes red and reverts. Matched gems clear, the gems above fall, and fresh gems drop in from the top. If the new board makes another match, it cascades — and each link in the chain multiplies your score. When no moves remain, the board reshuffles so play never stalls.

Scoring

Each cleared gem is worth 10 points, multiplied by the cascade depth: the swap's own match scores ×1, the first cascade ×2, the next ×3, and so on. Longer lines clear more gems, so they score more. Combo shows the deepest chain you reached; Best tracks your high score for the session.

Controls

| Key | Action | | --- | --- | | h / ← | Move cursor left (or swap left when a gem is held) | | l / → | Move cursor right (or swap right) | | k / ↑ | Move cursor up (or swap up) | | j / ↓ | Move cursor down (or swap down) | | space / enter | Pick up / drop the gem under the cursor | | p | Pause / resume | | r | Restart | | ? | Toggle help | | q | Quit |

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/ (board operations, match detection, the cascade state machine); the Ink UI is under src/ui/.

Publish

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

npm login
npm publish --access public