standards

Cubing Standard #3: KPuzzle (DRAFT)

Status: DRAFT
Version: 2018-09-06
Author: Lucas Garron
Prescriptive or descriptive: prescriptive (this standard attempts to describe new conventions)

KPuzzle is a JSON format for specifying twisty puzzles based on how pieces are permuted and oriented. The format is adapted from KSolve, with a few notable differences in the details (see section 3.3).

3.1 Puzzle Definition

The definition of a puzzle defines mainly which pieces it consists of, what state is considered solved, and what moves can be performed on those pieces (and how). In order to make this as practical as possibly, pieces are divided into orbits, and each piece is described using a position and an orientation. This is in contrast to a simple representation where all facelets are represented using a single permutation (although KPuzzle can be used for such representations).

3.1.1 Example

{
  "name": "3×3×3",
  "orbits": [
    {
      "orbitName": "EDGES",
      "numPieces": 12,
      "numOrientations": 2
    },
    {
      "orbitName": "CORNERS",
      "numPieces": 8,
      "numOrientations": 3
    },
    {
      "orbitName": "CENTERS",
      "numPieces": 6,
      "numOrientations": 4
    }
  ],
  "defaultPattern": {
    "EDGES": {
      "pieces": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
      "orientation": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
    },
    "CORNERS": {
      "pieces": [0, 1, 2, 3, 4, 5, 6, 7],
      "orientation": [0, 0, 0, 0, 0, 0, 0, 0]
    },
    "CENTERS": {
      "pieces": [0, 1, 2, 3, 4, 5],
      "orientation": [0, 0, 0, 0, 0, 0],
      "orientationMod": [1, 1, 1, 1, 1, 1]
    }
  },
  "moves": {
    "U": {
      "EDGES": {
        "permutation": [1, 2, 3, 0, 4, 5, 6, 7, 8, 9, 10, 11],
        "orientationDelta": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
      },
      "CORNERS": {
        "permutation": [1, 2, 3, 0, 4, 5, 6, 7],
        "orientationDelta": [0, 0, 0, 0, 0, 0, 0, 0]
      },
      "CENTERS": {
        "permutation": [0, 1, 2, 3, 4, 5],
        "orientationDelta": [1, 0, 0, 0, 0, 0]
      }
    },
    // …
  },
  "derivedMoves": {
    "E": "Uw' U",
    // …
  }
}

3.1.2 Structure

Here is a specification of the KPuzzle Definition structure in JSON, roughly in TypeScript format (adapted from kpuzzle.js):

export type KPatternData = Record<string, KPatternOrbitData>;
export interface KPatternOrbitData {
  pieces: number[];
  orientation: number[];
  orientationMod?: number[];
}

export type KTransformationData = Record<string, KTransformationOrbitData>;
export interface KTransformationOrbitData {
  permutation: number[];
  orientationDelta: number[];
}

export interface KPuzzleOrbitDefinition {
  orbitName: string;
  numPieces: number;
  numOrientations: number;
}

export interface KPuzzleDefinition {
  name: string;
  orbits: KPuzzleOrbitDefinition[];
  defaultPattern: KPatternData;
  moves: Record<string, KTransformationData>;
  derivedMoves?: Record<string, string>;
}

3.1.3 Validation

For a definition to be valid, the following must hold:

Let:

Then:

Notes:

3.3 Comparison with KSolve

The KPuzzle format is inspired by KSolve, but has the following differences:

- KPuzzle Definition KSolve Definition
Format JSON Text
Permutations 0-indexed 1-indexed
Orientations By slot (“post-permutation”) By pieces (“pre-permutation”)
Features For now: orbits, moves Orbits, moves, puzzle name, solved state, comments, derived moves (some versions), forbidden pairs/groups (some versions), bandaged pieces (some versions)

TODO