Skip to content

Latest commit

 

History

History
222 lines (172 loc) · 5.24 KB

README.md

File metadata and controls

222 lines (172 loc) · 5.24 KB
Raw

npm

Magic Cubes

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

Table of Contents

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.

Roadmap

  • nxn support
  • Scramble generator
  • Kociemba solver

License

MIT