standards

KPuzzle Definition (DRAFT)

Version: 2018-09-06
Author: Lucas Garron

Overview

A KPuzzle Definition is a JSON object that specifies a twisty puzzle, adapted from KSolve. The formats are interoperable, with notable differences in the details:

- 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)

This document currently errs on the side of a limited specification for now, with plans to extend it with more features in the future.

Example

{
  orbits: {
    "EDGE":   {"numPieces": 12, "orientations": 2},
    "CORNER": {"numPieces": 8,  "orientations": 3},
    "CENTER": {"numPieces": 6,  "orientations": 4}
  },
  moves: {
    "U": {
      "EDGE":   {"permutation": [3, 0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 11], "orientation": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]},
      "CORNER": {"permutation": [1, 2, 3, 0, 4, 5, 6, 7], "orientation": [0, 0, 0, 0, 0, 0, 0, 0]},
      "CENTER": {"permutation": [0, 1, 2, 3, 4, 5], "orientation": [1, 0, 0, 0, 0, 0]}
    },
    "F": {
      "EDGE":   {"permutation": [9, 1, 2, 3, 8, 5, 6, 7, 0, 4, 10, 11], "orientation": [1, 0, 0, 0, 1, 0, 0, 0, 1, 1, 0, 0]},
      "CORNER": {"permutation": [3, 1, 2, 5, 0, 4, 6, 7], "orientation": [1, 0, 0, 2, 2, 1, 0, 0]},
      "CENTER": {"permutation": [0, 1, 2, 3, 4, 5], "orientation": [0, 0, 1, 0, 0, 0]}
    },
    ...
  }
}

Specification

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

// TODO: Convert to something like JSON Schema?

// TODO: Rename to `perm` and `ori` to save space for serialized representations?
interface OrbitTransformation {
  permutation: number[]
  orientation: number[]
}

interface Transformation {
  [key: string/* orbit name */]: OrbitTransformation
}

interface OrbitDefinition {
  numPieces: number
  orientations: number
}

interface KPuzzleDefinition {
  orbits: {[key: string/* orbit name */]: OrbitDefinition}
  moves: {[key: string/* move name */]: Transformation}
}

Validation

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

Let:

Then:

Notes:

TODO