Fifteen Puzzle Solver

Interactive solver for the classic 15-Puzzle (sliding tile puzzle), featuring a Terminal User Interface (TUI) and multiple search algorithms even implemented in C++ with bindings to typescript layer.

Features

• Interactive TUI: Built with Ink, offering a modern and intuitive CLI experience.
• Multiple Algorithms:
  • BFS (Breadth-First Search)
  • DFS (Depth-First Search)
  • IDFS (Iterative Deepening DFS)
  • Best-First Search (Greedy)
  • A* (A-Star)
  • SMA* (Simplified Memory-Bounded A*)
• Hybrid Implementation:
  • TypeScript: Core logic and UI.
  • Native C++: Solver implementations for solving algorithms.
• Visualization: Step-by-step solution playback with metrics.

Usage

You can start the interactive solver in two ways:

1. Interactive Mode

Simply run the start command to enter the main menu:

15puzzle

or

npm start

From here, you can input your own configuration.

2. Direct Input

Pass a puzzle configuration directly as a JSON array or comma-separated list:

# JSON format
npm start -- "[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 0, 15]"

# Comma-separated
npm start -- "1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 0, 15"

Note: 0 represents the empty tile.

Development

Project Structure

• source/: TypeScript source code (UI, core logic).
• native/: C++ source code for native solvers.
• dist/: Compiled TS app output .
• build/: Compiled CPP app .

Installation

Ensure you have Node.js (v24+) installed.

# Clone the repository
git clone https://github.com/Oskarowski/fifteen-puzzle-tile-arrangement-solver.git
cd fifteen-puzzle-tile-arrangement-solver

# Install dependencies
npm install

# Build the native C++ addon
npm run addon:build

# Build the project
npm run build

Scripts

• npm run dev: Watch mode for development.
• npm test: Run tests using Vitest.
• npm run addon:rebuild: Rebuild the native C++ addon.

License