Sliding Number Puzzle (15-Puzzle) — Free JS Snippet

The 15-puzzle is one of the oldest mechanical puzzles ever popularized, dating back to the 1870s, and it remains a genuinely interesting programming exercise because a naive implementation is broken by default: a puzzle shuffled by fully randomizing 16 numbers is only solvable half the time. This snippet implements the correct approach — shuffling by performing a long sequence of random legal slides starting from the solved position — alongside smooth, transform-based tile animation and accurate win detection.

Why a random permutation is the wrong shuffle

The 15-puzzle's underlying mathematics involves permutation parity. Every legal slide move is equivalent to a single transposition combined with moving the blank tile, and it can be proven that exactly half of all 16! possible tile arrangements are reachable from the solved state through legal moves — the other half are permutation-parity odd and mathematically unsolvable no matter how the player slides tiles. Generating a shuffle by calling something like Array.sort(() => Math.random() - 0.5) on the 16 values ignores this entirely and will produce an unsolvable board roughly 50% of the time. This snippet avoids the problem completely: shuffleFromSolved() starts from the perfectly solved tiles array and performs 250 random legal slides in a row, each one swapping the blank with a randomly chosen adjacent neighbor. Because every individual move is legal and reversible, the resulting board is, by construction, always reachable back to the solved state — no parity checking required.

Avoiding a lazy, oscillating shuffle

A subtle secondary bug in naive "random legal slide" shufflers is that the blank tile can bounce back and forth between the same two cells repeatedly, producing a shuffle that looks busy but barely moves anything overall. This snippet tracks lastEmpty, the blank's position before the previous move, and filters it out of the candidate neighbor list on each iteration (neighbors.filter(n => n !== lastEmpty)). This forces every shuffle step to make genuine progress rather than immediately undoing the prior move, producing a well-mixed 4x4 board after 250 iterations.

Representing the board as a flat array, not a grid

The puzzle state lives in a single flat array, tiles, of length 16, where tiles[i] is the value shown at cell index i and 0 represents the empty slot. Helper functions indexToRowCol() and areAdjacent() convert between the flat index and a 2D row/column coordinate using simple integer division and modulo (row = Math.floor(index / 4), col = index % 4), and determine legality of a move by checking that the Manhattan distance between the clicked tile's cell and the empty cell equals exactly 1. This flat-array-plus-coordinate-math representation avoids nested arrays entirely and keeps the swap logic ( [tiles[a], tiles[b]] = [tiles[b], tiles[a]] ) a single line using array destructuring.

Transform-based sliding instead of layout reflow

Each numbered tile is an absolutely positioned div inside the .board container, sized to exactly 25% width and height. Rather than reordering DOM elements or changing top/left (which forces the browser to recompute layout), every tile's position is set with el.style.transform = 'translate(x%, y%)', computed from its cell index. Because transform is a compositor-only property, the browser can animate the 0.16s ease transition on the GPU without triggering layout or paint, which is why the tiles glide smoothly even during a rapid sequence of clicks. On every move, render() fully re-derives each tile's transform from the current tiles array and re-attaches its click handler, keeping the DOM state and the logical state trivially in sync.

Win detection and move counting

After every successful attemptMove(), checkWin() compares the live tiles array against the canonical solved array (1 through 15 followed by 0) element-by-element. On a match, a green .solved-flash class is applied to every tile and a banner reports the final move count — a lower move count indicating a more efficient solve, similar in spirit to the scoring feedback in a memory-matching game.