Magic-cubes NPM

Magic Cubes

JavaScript library for simulating the Rubik's cube and working with algorithms.

Installation

npm

  npm install magic-cubes

Yarn

  yarn add magic-cubes

Usage

Cube

import { Cube } from 'magic-cubes';

const cube = new Cube("L' R2 U2 B2 L2 U2 B2 L2 F U2 F2 L2 U R D' F D' F U L R");
console.log(cube.isSolved); // -> false

cube.solve("U2 D B R2 L2 U2 R L' F' U2 R2 D' F R D B2 R F'");
console.log(cube.isSolved); // -> true

Cube Model

import { Cube, CubeModel } from 'magic-cubes';

const cube = new Cube("D2 U2 B F2 D2 B D2 R2 D2 U2 R' U' B2 F2 R' U2 F L U R");
const colorScheme = {
  U: 'w', // white
  D: 'y', // yellow
  F: 'g', // green
  B: 'b', // blue
  L: 'o', // orange
  R: 'r', // red
};

const model = new CubeModel(cube, colorScheme);
const colors = model.colors();

const { U, D, F, B, L, R } = Object.fromEntries(
  Object.entries(colors).map(([face, colors]) => {
    return [face, colors.join('').match(/.{3}/g)];
  })
);

console.log(`
    ${U[0]}
    ${U[1]}
    ${U[2]}
${L[0]} ${F[0]} ${R[0]} ${B[0]}
${L[1]} ${F[1]} ${R[1]} ${B[1]}
${L[2]} ${F[2]} ${R[2]} ${B[2]}
    ${D[0]}
    ${D[1]}
    ${D[2]}
`);

// ->
//     oyo
//     rwg
//     ryr
// bwb wbw gwy grw
// oor bgg rrb obw
// byw gyy gwb oor
//     ogr
//     oyb
//     ygy
});

Algorithm

import { Algorithm } from 'magic-cubes';

const alg = new Algorithm('[Lw’ : [U , R’ D2 R]] ');
console.log(alg.clean); // -> [l', [U, R' D2 R]]
console.log(alg.inverse); // -> [l', [R' D2 R, U]]

try {
  const incorrectAlg = new Algorithm('foo');
} catch (error) {
  console.log(error.message); // -> Invalid character 'o' at position 2.
}

API Reference

Cube

new Cube(scramble?);

Parameters

scramble: Algorithm | string
- The scramble to apply on the cube.
- Calls the scramble method.

Properties

isSolved
- Checks if the cube is in the solved state.
- Ignores orientation.
isOriented
- Checks if the cube is oriented.

Methods

apply(alg: Algorithm | string)
- Applies an algorithm to the cube.
- An Algorithm will be created when providing a string, which throws when invalid.
scramble(alg: Algorithm | string)
- Alias of apply
solve(alg: Algorithm | string)
- Alias of apply
orient()
- Resets the orientation of the cube.

CubeModel

new CubeModel(cube, colorScheme);

Parameters

cube: Cube
- Required
- The Cube from which a model should be created.
colorScheme: Record<Face, string>
- Required
- An object that maps each Face to a string.
- Face is 'U' | 'D' | 'F' | 'B' | 'L' | 'R'.

Methods

colors: () => CubeColors
- Object that describes the colors of the cube.
- CubeColors is of type Record<Face, string[]>.
- string will be a color defined in colorScheme.
- Tip: Use as const when defining the color scheme in TypeScript to give CubeColors a stronger typing (Record<Face, string[]> becomes Record<Face, ColorScheme[Face][]>).

Algorithm

new Algorithm(alg);

Parameters

alg: string
- String representation of an algorithm.
- Supports sequences, e.g. "R U R' U' R' F R2 U' R' U' R U R' F'".
- Supports commutators and conjugates, e.g. "[l': [U, R' D2 R]]".
- Supports repeating groups, e.g. "F (R U R' U')2 F'".
- Will be silently normalized before operating on it:
  - Leading and trailing whitespaces will be trimmed.
  - Prime characters (', ’ and ′) will be converted to '.
  - Double prime turns (2' or '2) will be converted to 2.
  - Wide move notation with w will be converted to lowercase (e.g. Fw becomes f).
  - Asterisks before multipliers will be removed (e.g. (M U)*4 becomes (M U)4).
- Throws a descriptive error when the string is invalid.

Properties

raw: string
- The original string input.
parsed: string
- String representation of the parsed input
- Can be useful for debugging. In most other cases, clean is preferred.
clean: string
- Cleaned up version of the input.
- Normalizes spacing.
- Merges multiple turns (e.g. R R becomes R2).
- Removes repeating group with a multiplier of 0.
- Converts repeating groups with a multiplier of 1 to a sequence.
  This includes parentheses without multiplier (e.g. F (R U R' U') F' becomes F R U R' U' F').
- Applies multiplier to a single turn (e.g. (R)3 becomes R')
inverse: string
- Inverse of the input.
sequence: string
- A sequenced version of the input.
- Flattens commutators, conjugates and repeating groups.
rotationless: string
- A sequenced, rotationless version of the input.
- Translates rotations, wide turns and slice turns to face turns.
turns: TurnNode[]
- Array of turn nodes after sequencing the algorithm.
- Used by Cube when applying an algorithm. Shouldn't need to be accessed directly.