Play Need for Speed: Underground 2 (2004) in Chrome and Firefox with WebGPU graphics, Web Audio, up to 120 fps widescreen, controller support, free roam and Online races with friends. Fan project, not
A 3D twisty-puzzle playground and solver for the 2×2, 3×3, 4×4 and 5×5 cubes and the Pyraminx. Turn the puzzle by dragging it, paint in a real puzzle's state (or scan a real one with your camera), and step through the solution. The Learn tab teaches a method on your own scramble, one explained step at a time: on the 3×3 the beginner's method, CFOP, Roux or ZZ; on every other puzzle a beginner's method (layer by layer on the 2×2 and Pyraminx, reduction on the 4×4 and 5×5).
A 3D twisty-puzzle playground and solver for the 2×2, 3×3, 4×4 and 5×5 cubes and the Pyraminx. Turn the puzzle by dragging it, paint in a real puzzle's state (or scan a real one with your camera), and step through the solution. Learn teaches a method stage by stage, with a guided solve of a scramble or your own cube, one explained step at a time: on the 3×3 the beginner's method, CFOP, Roux or ZZ; on every other puzzle a beginner's method (layer by layer on the 2×2 and Pyraminx, reduction on the 4×4 and 5×5).
pnpm install
pnpm dev # http://localhost:5173
pnpm verify # checks every solver and lesson against random scrambles
pnpm build
How it fits together
Each puzzle implements the Puzzle interface (src/core/types.ts): sticker geometry, pieces, moves, validation, a solver and UI hints. The 3D view and UI are shared by all puzzles.
src/core/ is what every puzzle shares: the Puzzle types, cube colors, permutation helpers (parity, ranking, breadth-first distance tables), and the two ways of running a solver — on the main thread (syncSolver.ts) or in a web worker (worker.ts: serveSolver on the worker side, SolverClient on the page). alg.ts reads an algorithm as people paste it (commas, grouping brackets, repeats like (R U R' U')2, commutators [R, U] and conjugates [F: R U R'], primes written ’, ′ or i), with each puzzle saying which words are its moves; anything that isn't a move is reported where it is, with a suggestion when there's an obvious one, so the algorithm box can select it and offer the fix.
src/cube/ holds every N×N cube, all on one model (model.ts): stickers and moves derived geometrically (R, Rw, 2R, 3Rw, M, x, …), pieces grouped into orbits by their coordinates (corners, midges, wings, each kind of center), and a validator that checks each orbit. puzzles.ts builds the 2×2, 3×3, 4×4 and 5×5 from it. Odd cubes take their orientation from the fixed centers; even cubes have none, so their solvers take it from the DBL corner.
3×3: a Kociemba two-phase solver (kociemba/solver.ts) in a worker, which finds a solution in milliseconds, keeps shortening it, and proves it optimal when its search finishes.
2×2 (solve2.ts): a breadth-first distance table over all 3.67M states (DBL fixed, U/R/F turns), so solutions are always optimal and scrambles are random-state.
3×3 lessons (beginner.ts): the layer-by-layer beginner's method in seven stages (white cross, white corners, middle layer, yellow cross, yellow edges, corner spots, corner twists). It works on the actual state: it finds each piece, picks the case and simulates the moves, so each step's text, move groups ("Turn the top", "R U R' U' ×3") and highlighted pieces match the cube. The cross edges come from a small breadth-first search; everything after uses the standard algorithms. Lessons average ~150 moves in ~20 steps. Its course has example cases for every stage (cross edges, white corners, middle edges, then each last-layer stage), and each step from the white corners on names its case.
CFOP, Roux and ZZ lessons (cfop.ts, roux.ts, zz.ts) share a toolkit (lessonKit.ts): pieces found by color, and small searches that track one sticker per piece. Blocks, pairs and the like are the cheapest run of moves or "macros" (conjugates such as R U R') that leave the solved pieces alone, so F2L pairs come out as intuitive pair-and-insert moves. Algorithm steps (algs.ts: 57 OLL, 21 PLL, and the two-look sets; shared by lastLayer.ts) find their case by trying each algorithm after each turn of the top.
CFOP: shortest cross (distance table over the four edges), F2L pair by pair, then two-look OLL (3 edge cases for a yellow cross, 7 corner cases) and two-look PLL (2 corner cases, 4 edge cases), the same cases as its course. Each last-layer step names its case (GuideStep.caseId), so the guided solve shows the case and opens it to practise; ZZ's OCLL and PLL steps and Roux's CMLL steps name theirs too. ~70 moves.
Roux: first block and second block (a square, then a pair; the second with U R r M only), two-look CMLL, then the last six edges with : orientation, the left/right edges, the M slice. ~59 moves. Its course ( in , 39 cases) has each block's last pair, two-look CMLL (OLL's seven corner cases, then the T or Y perm, shown with only the blocks and the top corners) and examples of each part of the last six edges.
src/pyraminx/ is the Pyraminx. Pieces and stickers come from barycentric cuts of a tetrahedron (model.ts). The solver (solver.ts) fixes the tips directly, then finds the optimal core solution with a meet-in-the-middle search (depth 6 + 5 ≥ God's number of 11), so every solution is optimal. Its lesson (lesson.ts) is the layer-by-layer method: tips, the bottom centers, the three bottom edges (a small search over X U X' moves), then one of five last-layer algorithms, some done from a side face. Its course (cases.ts, 16 cases) has a tip and a bottom center twisted either way, the last bottom edge from each of the seven places it can be (each the guided solve's own route), and the five last-layer cases, with arrows; a step that is one of them names it, the bottom edges seen from whichever side they go in from.
src/view/PuzzleView.ts is the Three.js scene; its zoom range scales with each puzzle's size. Drag-to-turn follows the pointer and snaps to the nearest quarter turn (cube) or third of a turn (Pyraminx).
src/view/net.ts draws the unfolded 2D map as SVG. Cubes also have a ring map (src/cube/rings.ts, drawn by src/view/rings.ts): each layer is a circle and each sticker a dot where its two layers' circles cross, so a turn slides the dots along their circle.
src/view/scanner.ts scans a real puzzle with the camera, face by face, guided by each puzzle's scan faces, whose stickers sit in square or triangular cells (src/scan/cells.ts). src/scan/classify.ts reads the colors: mostly by hue, matched to the scanned centers (or, on an even cube without fixed ones, to typical colors corrected by the whole scan's average, and then turned the way the puzzle is drawn, as the Pyraminx is), with each face's exposure evened out and every color used exactly as often as it should be.
The About button in the top bar (or the "Algorithm sources" link at the bottom of Learn) opens a dialog that links to the beginner tutorials the 2×2, 4×4, 5×5 and Pyraminx lessons follow.
The app has two places, switched in the top bar (a bar at the bottom on a phone): Cube, your own puzzle, and Learn, which works on practice cubes of its own (one for cases, one for a guided solve), so it never touches yours and opening a case from a guided solve loses neither. Each keeps what it had open (a solution, a guided solve, a case) while you're in the other, and picks it up again on return, marked out of date if the cube changed meanwhile.
In Cube, the left panel sets the puzzle up: Turn or Paint, and a Scan button for the camera. Every change to the whole cube (Reset, Scramble, Clear all, Fill solved, a scan, each painted sticker) can be undone, from the toast or the undo button, and each puzzle's cube is kept in localStorage for next time.
In Cube, the right panel solves it (shortest solution), and offers to learn to solve it yourself: a guided solve of a copy of your cube.
In Learn, the left panel is the course for the method picked at its top (the picker is just a name when there's only one): the method's stages as a stepper, the stage on screen, and its cases, if the stage has any, else a note that a guided solve teaches it. Every stage can be practised on its own: Practise this stage on a scramble plays a guided solve of a scramble silently up to the stage, then guides just that stage, and offers the next stage when it's done. The right panel starts a guided solve on a new scramble (or your cube), or shows the open step or case with the player pinned to its bottom. A guided solve on a new scramble starts with step 0, the scramble as move chips played from solved, to copy onto a real puzzle ("Done, start the solve ›"); stage practice's step 0 sets a real puzzle up with the stages before done, by the shortest of the scramble and the moves so far, the rest of the solve undone, or (on the 2×2, 3×3 and Pyraminx) the solver's solution undone (src/core/setup.ts). "Skip, I'm only using the screen" drops it from then on, until Learn's start card brings it back. A guided solve (a lesson) plays like a solution but pauses after each step, dims all but the pieces the step is about, and follows along when you make its next move yourself (a half turn may be made as two quarter turns); the course follows it from stage to stage. A stray turn can be undone to carry on, as with a case. A method (Method in src/core/types.ts, one per file in src/cube/ and src/pyraminx/lesson.ts) is its stages (Stage), each with optional case groups (CaseGroup of Cases) and course text, and solve, the guided solve; Learn's pieces that work for any method (the stage stepper, move sequences with triggers marked, a case's drill controls, the banner for a cube turned off plan) are in src/view/course.ts. The Upside down button in the top bar turns the whole cube over (z2), which dragging can't do; the Display button beside it (a palette) sets the map style (Net or Rings) and the cube colors (Typical or Bright).
The 3×3's case sets (src/cube/cases.ts) hold every case a course can teach, each under one id wherever it comes up (OLL 27 is oll-27, shown as "Sune (OLL 27)"): the beginner's method, stage by stage (the guided solve's own algorithms on the cases it meets; verify-tutorial checks it does exactly each case's algorithm), example cross edges, F2L, two-look OLL and PLL, full OLL (57) and PLL (21), and ZZ's and Roux's cases. CFOP's course (src/cube/cfop.ts) shows every case of each of its stages with its algorithm, so you can follow along on a real cube: a few example cross edges, F2L taught as one idea (build the corner–edge block, then insert it) through cases sorted by where the corner and edge are, the long ones marked to learn as algorithms, then two-look OLL (3 edge cases for a yellow cross, 7 corner cases) and two-look PLL (2 corner cases, 4 edge cases), drawn as small SVG pictures (src/view/snapshot.ts) that project the 3D view's own stickers, colors, rounding and light: from its usual angle, or the top from above with arrows for PLL, the top layer's hidden side stickers folded out. It sits in Learn's left panel, wider, with the 3D cube beside it. Each case is set up by undoing its algorithm on a solved cube held white down, with the stickers that don't matter yet left blank on the picture and the 3D cube alike, so picking one sets it up on the 3D cube and plays its algorithm with the usual player. Every sexy move (R U R' U') is highlighted where it appears: in the stage text, on the case cards and on the move chips. On a phone the case card itself is the controller, with no player: tap a case to set it up, tap it again for each move (played moves fade, the next one is a filled chip), ‹ steps back, ▶ plays the moves from the start and, once you've begun, gives way to ↻ to go back to the start, a case you come back to resumes where you left it, the card says when you've played the last move (a tap then starts again) or turned the cube, a swipe on the cube only turns the view, and the screen stays awake while you practise. pnpm verify checks every case of every set and every course.
Keyboard shortcuts (the ? dialog lists them by place): C switches between Cube and Learn; in Cube, ⌥S scrambles, ⌫ resets and K scans; in Learn, ⇧← / ⇧→ go a step of a guided solve (with a case open, a case; else a stage), N opens the next case (or, after a stage's practice, the next stage) and Esc goes from a case back to the guided solve. They only use letters no puzzle turns with, or ⌥ where the letter is a move, so every move key still turns.
src/main.ts builds the puzzle tabs from PUZZLES and handles UI state, a per-puzzle session, the move queue, playback, keyboard shortcuts, and share links (#pyra:… / #3x3:… / #5x5:… in the URL hash).
ZZ: edge orientation (a distance table over flip patterns) and the line, both blocks with L U R, then OCLL (edges are already oriented) and PLL. ~57 moves. Its course (zz in cases.ts, 57 cases) has example edge orientations and line edges, each block's last pair, OCLL's seven cases and all 21 PLLs.
A block's last pair, in ZZ and Roux, goes in like an F2L pair turned with only R and U, or mirrored with L and U: the right-hand ones are F2L's cases under their ids, the left-hand ones their mirror images, pictured from the front left.
2×2 lesson (beginner2.ts): layer by layer. A 2×2 has no centers, so the lesson starts from one white corner and reads every face's color off it. The white layer goes in with R U R' U', the top turns yellow with repeated Sunes (held by the usual one/none/two-yellow rule), and R' F R' B2 R F' R' B2 R2 with the headlights at the back swaps the last corners. ~60 moves. Its course (cube2Cases in cases.ts, 14 cases) has the white corners as on the 3×3 (one, three or five rounds, or twisted in its spot), all seven shapes of the yellow top, each with the run of Sunes the rule gives, and the two corner swaps, with arrows; every step from the first white corner on names its case.
4×4 and 5×5 lessons (reduction.ts): the reduction method. Centers are built one color at a time, a piece at a time, by a search over the set of slots holding that color, using single turns and slice–face–slice moves (Rw U Rw') that leave the finished centers alone; when those can only swap pairs (the 5×5's last t-centers), commutators. Edges are paired one at a time by a search that follows one sticker per piece, with "join with a slice, swap out with R U R', slice back" moves and refuses any move that would split a finished edge; the last two use Uw' R U R' F R' F' R Uw, and on the 5×5 sometimes the edge-parity algorithm. The 3×3 stage runs the 3×3 beginner's stages on the reduced cube, with the 4×4's OLL parity (before the yellow cross) and PLL parity (after the yellow edges, when the corners would need an odd permutation). ~275 moves on the 4×4, ~400 on the 5×5. Its course (bigCubeCases in cases.ts: 32 cases on the 4×4, 30 on the 5×5) has example centers and edges (each the guided solve's own moves where it can be), the 3×3 beginner's cases on the big cube, and the parities: OLL parity (three edges up, or one) and PLL parity on the 4×4, edge parity on the 5×5. The 3×3 steps name their cases as on a 3×3, and each parity step names its own.
4×4 and up (reduce.ts, one bigcube worker for every size): reduce to a 3×3. It fixes parity first, then solves every orbit a 3×3 doesn't have (wings, x- and t-centers) with pure 3-cycle commutators found by search at startup. Wings go home on an even cube and pair up with their edge's midge on an odd one. The corners (plus midges and fixed centers on an odd cube) go to the Kociemba solver. Solutions are correct but long (~170 moves on the 4×4, ~240 on the 5×5), not optimal.
