README

15-puzzle 🧩

15-puzzle is a simple 15 puzzle library with many useful features. 😎

Usage

Installation

Use npm to install (or yarn if you'd like).

npm install 15-puzzle

Then import the class RandomPuzzle from '15-puzzle' in your script.

import { RandomPuzzle } from '15-puzzle'      // ES Module
const { RandomPuzzle } = require('15-puzzle') // CommonJS

Generating

You can generate a random valid puzzle using a static method called generate() 🎰✨. To specify the size, give a number for both width and height, two numbers for width and height respectively, or nothing for 4x4.

import { RandomPuzzle } from '15-puzzle'

const foo = RandomPuzzle.generate()      // 4x4
const bar = RandomPuzzle.generate(5)     // 5x5
const baz = RandomPuzzle.generate(6, 7)  // 6x7

See the type definition to learn what you can do. 🧐

Now (actually since v2.0.2 😅), as we use random-seed to generate a puzzle, this feature is actually supported! 🎉 Just give a seed as the first argument. A seed must be a string, and here's why.

import { RandomPuzzle } from '15-puzzle'

const foo = RandomPuzzle.generate('kazukazu123123')        // 4x4
const bar = RandomPuzzle.generate('kazukazu123123', 5)     // 5x5
const baz = RandomPuzzle.generate('kazukazu123123', 6, 7)  // 6x7

If you have an array of pieces, instead, use Puzzle which allows you to create an instance without seed. Note that 0 means an empty square.

FYI, RandomPuzzle actually extends Puzzle.

import { Puzzle } from '15-puzzle'

const pieces = [ [  1 ,  2 ,  3 ,  4 ]
                 [  5 ,  6 ,  7 ,  8 ]
                 [  9 , 10 , 11 , 12 ]
                 [ 13 , 14 , 15 ,  0 ] ]

const puzzle = new Puzzle(pieces)

Checking

You can check if the puzzle is solvable, being solved, or completely solved. 🧐

import { Puzzle } from '15-puzzle'

const foo = new Puzzle([ [  1 ,  2 ,  3 ,  4 ]
                         [  5 ,  6 ,  7 ,  8 ]
                         [  9 , 10 , 11 , 12 ]
                         [ 13 , 14 , 15 ,  0 ] ])
foo.isSolvable() // true
foo.isSolving() // false
foo.isSolved() // true


const bar = new Puzzle([ [  1 ,  2 ,  3 ,  4 ]
                         [  5 ,  6 ,  7 ,  8 ]
                         [  9 , 10 , 11 , 12 ]
                         [ 13 ,  0 , 14 , 15 ] ])
bar.isSolvable() // true
bar.isSolving() // false
bar.isSolved() // false

bar.tap(2, 3)
bar.isSolving() // true
bar.isSolved() // false

bar.tap(3, 3)
bar.isSolving() // false
bar.isSolved() // true


const baz = new Puzzle([ [  1 ,  2 ,  3 ,  4 ]
                         [  5 ,  6 ,  7 ,  8 ]
                         [  9 , 10 , 11 , 12 ]
                         [ 13 , 15 , 14 ,  0 ] ])
baz.isSolvable() // false

Controlling

Use Puzzle.prototype.tap(x, y).

import { RandomPuzzle } from '15-puzzle'

const puzzle = RandomPuzzle.generate('kazukazu123123')
console.log(puzzle.toString())
// +--+--+--+--+
// | 5|  | 1|12|
// +--+--+--+--+
// |13|10| 8| 4|
// +--+--+--+--+
// | 3|14| 6| 7|
// +--+--+--+--+
// |11|15| 9| 2|
// +--+--+--+--+

puzzle.tap(0, 0)
console.log(puzzle.toString())
// +--+--+--+--+
// |  | 5| 1|12|
// +--+--+--+--+
// |13|10| 8| 4|
// +--+--+--+--+
// | 3|14| 6| 7|
// +--+--+--+--+
// |11|15| 9| 2|
// +--+--+--+--+

There's a method called swap which literally swaps two pieces, but using this method is not recommended, because calling this manually might make the puzzle become unsolvable.

Usage no npm install needed!