@houstonp/rubiks-cube 2.1.0 → 3.0.0

package/src/{core.js → core/index.js}

@@ -1,4 +1,36 @@
 // @ts-check
+
+/**
+ * reverses the direction of a movement or rotation
+ * @template {Movement | Rotation} T
+ * @param {T} action
+ * @returns {T}
+ * */
+export function reverse(action) {
+    let reversedAction = action;
+    if (action.at(-1) === "'") {
+        reversedAction = /** @type {T} */ (action.slice(0, -1));
+    } else {
+        const newAction = /** @type {T} */ (action + "'");
+        reversedAction = newAction;
+    }
+    return reversedAction;
+}
+
+/**
+ * Translates notation meant for a 3x3 into notation a big cube. This is so that 3x3 algorithms can be used on a big cube if desired. eg. for a 6x6 r -> 5r
+ * @template {Movement | Rotation} T
+ * @param {T} action
+ * @param {CubeType} cubeType
+ * @returns {T}
+ * */
+export function translate(action, cubeType) {
+    if (Object.values(Movements.Wide).includes(/** @type {WideMove} **/ (action))) {
+        return /** @type {T}  */ (LayerCount[cubeType] - 1 + action);
+    }
+    return action;
+}
+
 /**
  * @typedef {typeof Movements.Single[keyof typeof Movements.Single]} SingleMove
  * @typedef {typeof Movements.Wide[keyof typeof Movements.Wide]} WideMove
@@ -71,7 +103,7 @@ export const Movements = Object.freeze({
         u2: 'u2',
         uP: "u'",
         Dw: 'Dw',
-        Dw2: 'D2',
+        Dw2: 'Dw2',
         DwP: "Dw'",
         d: 'd',
         d2: 'd2',
@@ -357,6 +389,27 @@ export const Movements = Object.freeze({
         D2: '6D2',
         DP: "6D'",
     }),
+    /**
+     * Build a layer-range move for big-cube notation. e.g. Movements.Range(2, 4, Movements.Wide.Rw) returns '2-4Rw',
+     * meaning "rotate layers 2 through 4 from the right face." Accepts wide moves (`Movements.Wide.*`), face
+     * moves (`Movements.Single.{R,L,U,D,F,B}` and modifiers), and slice moves (`Movements.Single.{M,E,S}` and
+     * modifiers). Already-prefixed moves (`2R`, `2-4Rw`) are rejected.
+     * @param {number} lower
+     * @param {number} upper
+     * @param {WideMove | SingleMove} baseMove
+     * @returns {Movement}
+     */
+    Range: (lower, upper, baseMove) => {
+        if (!Number.isInteger(lower) || !Number.isInteger(upper) || lower < 1 || lower >= upper || upper > 7) {
+            throw new Error(`Invalid layer range [${lower}-${upper}]: require integers with 1 <= lower < upper <= 7`);
+        }
+        const move = /** @type {Movement} */ (`${lower}-${upper}${baseMove}`);
+        if (!isMovement(move)) {
+            throw new Error(`Invalid range movement: ${move}`);
+        }
+
+        return move;
+    },
 });
 
 /**
@@ -398,50 +451,28 @@ export const CubeTypes = Object.freeze({
     Seven: 'Seven',
 });
 
-/**
- * @typedef {typeof AnimationStyles[keyof typeof AnimationStyles]} AnimationStyle
- */
-export const AnimationStyles = Object.freeze({
-    Exponential: 'exponential',
-    Next: 'next',
-    Fixed: 'fixed',
-    Match: 'match',
-});
-
-/**
- * @typedef {typeof FaceColours [keyof typeof FaceColours]} FaceColour
- */
-export const FaceColours = Object.freeze({
-    U: 'white',
-    D: 'yellow',
-    L: '#fc9a05',
-    R: 'red',
-    F: '#2cbf13',
-    B: 'blue',
+export const LayerCount = Object.freeze({
+    [CubeTypes.Two]: 2,
+    [CubeTypes.Three]: 3,
+    [CubeTypes.Four]: 4,
+    [CubeTypes.Five]: 5,
+    [CubeTypes.Six]: 6,
+    [CubeTypes.Seven]: 7,
 });
 
 /**
- * @typedef {typeof PeekTypes [keyof typeof PeekTypes]} PeekType
+ *
+ * @param {string} rotation
  */
-export const PeekTypes = Object.freeze({
-    Horizontal: 'horizontal',
-    Vertical: 'vertical',
-    Right: 'right',
-    Left: 'left',
-    Up: 'up',
-    Down: 'down',
-    RightUp: 'rightUp',
-    RightDown: 'rightDown',
-    LeftUp: 'leftUp',
-    LeftDown: 'leftDown',
-});
+export function IsRotation(rotation) {
+    return /^([xyz])(\d)?(\')?$/.test(rotation);
+}
 
 /**
- * @typedef {typeof PeekStates [keyof typeof PeekStates]} PeekState
+ *
+ * @param {string} movement
+ * @return {boolean}
  */
-export const PeekStates = Object.freeze({
-    RightUp: 'rightUp',
-    RightDown: 'rightDown',
-    LeftUp: 'leftUp',
-    LeftDown: 'leftDown',
-});
+export function isMovement(movement) {
+    return /^([1234567]|[123456]-[1234567])?([RLUDFB]w|[RLUDFBMES]|[rludfbmes])([123])?(\')?$/.test(movement);
+}

package/src/rubiksCube/index.js

@@ -0,0 +1,3 @@
+import RubiksCubeController from './rubiksCubeController';
+export { RubiksCubeController };
+/** @typedef {import('./rubiksCubeController').AnimationOptions} AnimationOptions */

package/src/rubiksCube/rubiksCubeController.js

@@ -0,0 +1,111 @@
+// @ts-check
+/** @import {Slice} from '../state/slice' */
+/** @import {StickerState} from '../state/stickerState' */
+/** @import {CubeType, Movement, Rotation} from '../core' */
+/**
+ * @typedef AnimationOptions
+ * @property {boolean} [translate]
+ * @property {number} [animationSpeedMs]
+ * @property {boolean} [reverse]
+ */
+/**
+ * @typedef {Object} RubiksCubeViewInterface
+ * @property {function(Slice, any=): Promise<void>} slice
+ * @property {function(StickerState): void} setState
+ * @property {function(): void} reset
+ * @property {function(CubeType): void} setType
+ **/
+
+import { CubeTypes } from '../core';
+import { RubiksCubeState } from '../state';
+import { fromKociemba, toKociemba } from '../state/stickerState';
+
+export default class RubiksCubeController {
+    /**
+     * @param {CubeType} cubeType
+     * @param {RubiksCubeViewInterface} view
+     * */
+    constructor(cubeType, view) {
+        this.state = new RubiksCubeState(cubeType);
+        this.view = view;
+    }
+    /**
+     * @param {Movement} movement
+     * @param {AnimationOptions} [options]
+     * @returns {Promise<string>}
+     */
+    movement(movement, options) {
+        const slice = this.state.move(movement, { reverse: options?.reverse, translate: options?.translate });
+        if (slice == null) {
+            return Promise.reject(new Error(`Invalid movement: ${movement}`));
+        }
+        return this.view.slice(slice, { animationSpeedMs: options?.animationSpeedMs }).then(() => toKociemba(this.state.getState()));
+    }
+
+    /**
+     * @param {Rotation} rotation
+     * @param {AnimationOptions} [options]
+     * @returns {Promise<string>}
+     */
+    rotation(rotation, options) {
+        const slice = this.state.rotate(rotation, { reverse: options?.reverse });
+        if (slice == null) {
+            return Promise.reject(new Error(`Invalid rotation: ${rotation}`));
+        }
+        return this.view.slice(slice, { animationSpeedMs: options?.animationSpeedMs }).then(() => toKociemba(this.state.getState()));
+    }
+
+    /**
+     * @param {(Rotation | Movement)[]} actions
+     * @param {AnimationOptions} [options]
+     * @returns {string}
+     */
+    do(actions, options) {
+        this.state.do(actions, { translate: options?.translate, reverse: options?.reverse });
+        this.view.setState(this.state.getState());
+        return toKociemba(this.state.getState());
+    }
+
+    /**
+     * @returns {string}
+     */
+    reset() {
+        this.state.reset();
+        this.view.reset();
+        return toKociemba(this.state.getState());
+    }
+
+    /**
+     * @param {string} kociembaState
+     * @returns {boolean}
+     */
+    setState(kociembaState) {
+        const state = fromKociemba(kociembaState);
+        if (state) {
+            this.state.setState(state);
+            this.view.setState(state);
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * @returns {string}
+     */
+    getState() {
+        return toKociemba(this.state.getState());
+    }
+
+    /**
+     * @param {CubeType} cubeType
+     * @returns {string}
+     */
+    setType(cubeType) {
+        if (!Object.values(CubeTypes).includes(cubeType)) {
+            throw new Error(`Invalid cube type: ${cubeType}`);
+        }
+        this.state = new RubiksCubeState(cubeType);
+        this.view.setType(cubeType);
+        return toKociemba(this.state.getState());
+    }
+}

package/src/{three → rubiksCube3D}/centerPiece.js

@@ -1,9 +1,10 @@
 // @ts-check
-import { BoxGeometry, ExtrudeGeometry, Mesh, MeshBasicMaterial, Object3D } from 'three';
+import { BoxGeometry, ExtrudeGeometry, Mesh, MeshBasicMaterial, MeshStandardMaterial, Object3D, PlaneGeometry, SRGBColorSpace, TextureLoader } from 'three';
 import { SVGLoader } from 'three/examples/jsm/Addons.js';
 import { Sticker } from './sticker';
+/** @import {Vector3Like} from 'three' */
 
-/** @typedef {{ positon: import('three').Vector3Like, rotation: import('three').Vector3Like }} CenterPieceUserData */
+/** @typedef {{ positon: Vector3Like, rotation: Vector3Like }} CenterPieceUserData */
 
 export class CenterPiece extends Object3D {
     constructor() {
@@ -18,11 +19,45 @@ export class CenterPiece extends Object3D {
         this.frontSticker.position.set(0, 0, 0.5);
         this.frontSticker.rotation.set(0, 0, 0);
         this.add(this.frontSticker);
+
+        /** @type {Mesh<PlaneGeometry, MeshStandardMaterial> | null} */
+        this.logo = null;
     }
 
     get stickers() {
         return [this.frontSticker];
     }
+
+    /**
+     * @param {string} logoPath
+     */
+    addLogo(logoPath) {
+        this.removeLogo();
+        const material = new MeshStandardMaterial({
+            transparent: true,
+            color: 'white',
+            metalness: 0,
+            roughness: 0.4,
+        });
+        const mesh = new Mesh(new PlaneGeometry(0.9, 0.9), material);
+        mesh.position.set(0, 0, 0.54);
+        this.logo = mesh;
+        this.add(mesh);
+        const texture = new TextureLoader().load(logoPath, (texture) => {
+            texture.colorSpace = SRGBColorSpace;
+            material.map = texture;
+            material.needsUpdate = true;
+            texture.anisotropy = 16;
+        });
+    }
+
+    removeLogo() {
+        if (!this.logo) return;
+        this.remove(this.logo);
+        this.logo.material.map?.dispose();
+        this.logo.material.dispose();
+        this.logo = null;
+    }
 }
 
 const loader = new SVGLoader();

package/src/{three → rubiksCube3D}/cornerPiece.js

@@ -1,9 +1,23 @@
 /// @ts-check
-import { BoxGeometry, ExtrudeGeometry, Material, Mesh, MeshBasicMaterial, Object3D } from 'three';
+import {
+    BoxGeometry,
+    ExtrudeGeometry,
+    Material,
+    Mesh,
+    MeshBasicMaterial,
+    MeshStandardMaterial,
+    Object3D,
+    PlaneGeometry,
+    SRGBColorSpace,
+    TextureLoader,
+} from 'three';
 import { Sticker } from './sticker';
 import { SVGLoader } from 'three/examples/jsm/Addons.js';
+import { Faces } from '../core';
+/** @import {Vector3Like} from 'three' */
+/** @import {Face} from "../core" */
 
-/** @typedef {{ positon: import('three').Vector3Like, rotation: import('three').Vector3Like }} CornerPieceUserData */
+/** @typedef {{ positon: Vector3Like, rotation: Vector3Like }} CornerPieceUserData */
 /**
  * @param {Material} frontMaterial
  * @param {Material} rightMaterial
@@ -39,6 +53,46 @@ export class CornerPiece extends Object3D {
     get stickers() {
         return [this.frontSticker, this.rightSticker, this.topSticker];
     }
+
+    /**
+     * @param {Face} face
+     * @param {string} logoPath
+     */
+    addLogo(face, logoPath) {
+        this.removeLogo();
+        const material = new MeshStandardMaterial({
+            transparent: true,
+            color: 'white',
+            metalness: 0,
+            roughness: 0.4,
+        });
+        const mesh = new Mesh(new PlaneGeometry(0.9, 0.9), material);
+        if (face === Faces.U) {
+            mesh.position.set(0, 0.54, 0);
+            mesh.rotation.set(-Math.PI / 2, 0, -Math.PI / 2);
+        } else if (face === Faces.F) {
+            mesh.position.set(0, 0, 0.54);
+        } else if (face === Faces.R) {
+            mesh.position.set(0.54, 0, 0);
+            mesh.rotation.set(Math.PI / 2, Math.PI / 2, 0);
+        }
+        this.logo = mesh;
+        this.add(mesh);
+        const texture = new TextureLoader().load(logoPath, (texture) => {
+            texture.colorSpace = SRGBColorSpace;
+            material.map = texture;
+            material.needsUpdate = true;
+            texture.anisotropy = 16;
+        });
+    }
+
+    removeLogo() {
+        if (!this.logo) return;
+        this.remove(this.logo);
+        this.logo.material.map?.dispose();
+        this.logo.material.dispose();
+        this.logo = null;
+    }
 }
 
 const loader = new SVGLoader();

package/src/rubiksCube3D/cubeConfig.js

@@ -0,0 +1,87 @@
+// @ts-check
+import { CubeTypes, Faces } from '../core';
+/** @import {CubeType, Face} from '../core' */
+/** @import {ColorRepresentation} from 'three' */
+
+/**
+ * @typedef CubeConfig
+ * @property {number[]} layers
+ * @property {number} pieceSize
+ * @property {number} coreSize
+ * @property {number} outerLayerMultiplier
+ */
+
+/**
+ * @param {CubeType} cubeType
+ * @return {CubeConfig}
+ */
+export function getCubeConfig(cubeType) {
+    switch (cubeType) {
+        case CubeTypes.Two:
+            return {
+                layers: [-1, 1],
+                pieceSize: 2,
+                coreSize: 1.7,
+                outerLayerMultiplier: 1,
+            };
+            break;
+        case CubeTypes.Three:
+            return {
+                layers: [-1, 0, 1],
+                pieceSize: 1,
+                coreSize: 1.32,
+                outerLayerMultiplier: 1,
+            };
+        case CubeTypes.Four:
+            return {
+                layers: [-1, -1 / 3, 1 / 3, 1],
+                pieceSize: 2 / 3,
+                coreSize: 1.25,
+                outerLayerMultiplier: 1.1,
+            };
+        case CubeTypes.Five:
+            return {
+                layers: [-1, -1 / 2, 0, 1 / 2, 1],
+                pieceSize: 1 / 2,
+                coreSize: 1.2,
+                outerLayerMultiplier: 1.2,
+            };
+        case CubeTypes.Six:
+            return {
+                layers: [-1, -3 / 5, -1 / 5, 1 / 5, 3 / 5, 1],
+                pieceSize: 2 / 5,
+                coreSize: 1.18,
+                outerLayerMultiplier: 1.3,
+            };
+        case CubeTypes.Seven:
+            return {
+                layers: [-1, -2 / 3, -1 / 3, 0, 1 / 3, 2 / 3, 1],
+                pieceSize: 1 / 3,
+                coreSize: 1.16,
+                outerLayerMultiplier: 1.35,
+            };
+        default:
+            throw new Error(`Unsupported cube type: ${cubeType}`);
+    }
+}
+
+export const FaceColors = {
+    [Faces.B]: 'blue',
+    [Faces.D]: 'yellow',
+    [Faces.F]: '#2cbf13',
+    [Faces.L]: '#fc9a05',
+    [Faces.R]: 'red',
+    [Faces.U]: 'white',
+};
+
+/**
+ * @param {ColorRepresentation} color
+ * @return {Face}
+ * */
+export const ColorToFace = (color) => {
+    const face = Object.values(Faces).find((face) => FaceColors[face] === color);
+    if (!face) {
+        throw new Error(`Invalid color: ${color}`);
+    }
+    return face;
+};

package/src/rubiksCube3D/cubeSettings.js

@@ -0,0 +1,30 @@
+// @ts-check
+import { CubeTypes } from '../core';
+/** @import {CubeType} from '../core' */
+
+/**
+ * @typedef RubiksCube3DSettingsOptions
+ * @property {CubeType} [cubeType]
+ * @property {number} [pieceGap]
+ * @property {number} [animationSpeedMs]
+ * @property {gsap.EaseString | gsap.EaseFunction} [animationStyle]
+ * @property {string | null} [logo]
+ */
+
+export default class RubiksCube3DSettings {
+    /**
+     * @param {RubiksCube3DSettingsOptions} [options]
+     */
+    constructor(options = {}) {
+        /** @type {CubeType} */
+        this.cubeType = options.cubeType ?? CubeTypes.Three;
+        /** @type {number} */
+        this.pieceGap = options.pieceGap ?? 1.04;
+        /** @type {number} */
+        this.animationSpeedMs = options.animationSpeedMs ?? 150;
+        /** @type {gsap.EaseString | gsap.EaseFunction} */
+        this.animationStyle = options.animationStyle ?? 'sine';
+        /** @type {string | null} */
+        this.logo = options.logo ?? null;
+    }
+}

package/src/{three → rubiksCube3D}/edgePiece.js

@@ -2,8 +2,9 @@
 import { BoxGeometry, ExtrudeGeometry, Mesh, MeshBasicMaterial, Object3D } from 'three';
 import { SVGLoader } from 'three/examples/jsm/Addons.js';
 import { Sticker } from './sticker';
+/** @import {Vector3Like} from 'three' */
 
-/** @typedef {{ positon: import('three').Vector3Like, rotation: import('three').Vector3Like }} EdgePieceUserData*/
+/** @typedef {{ positon: Vector3Like, rotation: Vector3Like }} EdgePieceUserData*/
 
 export class EdgePiece extends Object3D {
     constructor() {

package/src/rubiksCube3D/index.js

@@ -0,0 +1,3 @@
+import RubiksCube3D from './rubiksCube3D';
+import RubiksCube3DSettings from './cubeSettings';
+export { RubiksCube3D, RubiksCube3DSettings };