Orbit64.Net
Draws a decoded cube as a net, and reads one back out of its facelets.
A token carries every movable piece and, on an odd cube, the fixed-center frame. This module applies that frame while crossing the facelet boundary.
This is the only module in the package that knows where a cube's pieces and
facelets sit. State ranking is pure arithmetic in n; Orbit64.Move names
faces and layer depths but carries no slot geometry. A picture needs to know
which slot sits where, so this module supplies a convention and convention
names it.
One set of tables serves both directions. toFacelets writes a state out as
stickers and fromFacelets reads one back in, which is what lets a project
carrying a cube engine of its own both consume and produce tokens without
ever restating the slot convention -- the one thing it could not restate
correctly without copying these tables.
Every table below is derived from cube geometry alone. No other project's
puzzle definition is read, which keeps this Apache-2.0 package clear of the
GPL sources that describe the same shapes. The derivation takes three
inputs -- a cube is n^3 cubies, a face turn rotates a layer, and a facelet is
face * n * n + row * n + col over U R F D L B -- and the rest follows:
corners the standard URF UFL ULB UBR DFR DLF DBL DRB midges the standard UR UF UL UB DR DF DL DB FR FL BL BR wings by the facelet index of the piece's reference sticker centers by facelet index, each orbit separately
Orientation counts clockwise seen from outside: for a corner from its U or D facelet, for a midge from U or D where it has one and F or B otherwise. A wing carries no orientation, and its reference sticker is the one in the first chirality class -- a wing cannot be flipped in place, so its 48 stickers fall into two orbits of 24, and that picks the reference without anyone choosing.
Ordering wings and centers by facelet index makes slot order a consequence
of the facelet layout rather than a second thing to agree on. It also makes
a center's color index its face index, so a solved cube is
0 0 0 0 1 1 1 1 ... with no lookup in between.
The 3x3x3 tables come out as the ones in wide use. That is not borrowing: given the standard facelet numbering and the standard piece names there is exactly one right answer, and deriving it from geometry reproduces those values bit for bit.
One caveat applies at every size: the picture assumes whoever produced the
token numbered their slots the way convention(n) says. A token does not
say, and the checked-in test vectors cannot settle it -- relabeling slots
and pieces by any bijection conjugates every permutation, and conjugation
preserves cycle structure, permutation parity and the orientation sums, so
no property of the arrays tells one labeling from another.
The 6x6x6 and 7x7x7 use the same geometric rules as the smaller cubes.
Definitions
Whether this module has a slot convention for an n x n x n.
Separate from draw because "there is no convention for a 6x6x6" and
"these orbits are not a cube" are different answers, and a caller that
wants to know which without building a state should not have to guess
from n.
The name of the slot convention draw assumes at size n.
A token stores ordinals and no geometry, so a picture is only correct if its producer numbered slots the way this reads them. Naming the assumption is the difference between a silently wrong picture and a disagreement someone can trace.
The net for orbits, or why there isn't one.
The orbits facelets describes, or why it describes no cube.
The exact inverse of toFacelets, and the direction a project with a
cube engine of its own needs in order to produce a token rather than
merely draw one. Both directions read the same private tables, so an
adapter never has to restate this package's slot convention -- the one
thing it could not restate correctly without copying it.
Facelets carry colors and no slot numbers, so this recovers the state
as convention(n) numbers it. A project whose own slot order differs
still gets the same cube, described in Orbit64's terms, which is exactly
what makes the facelet layer the place two such projects can meet.
On an odd cube the fixed centers select the stored frame. The reader restores the canonical facelet orientation before it reads coordinates, then returns both those coordinates and that frame.
Facelets that no sequence of turns can reach are refused with a reason: a twist or flip sum off its modulus, a color count off four, and, on an odd cube, corner and midge permutations of different parity.
The cube's stickers, as 6 * n * n face indices.
Facelet face * n * n + row * n + col, faces U R F D L B numbered 0
to 5, row-major within a face -- the layout flix-cube's BigCube and
cube-solvers' Facelets both use, which is what makes this the layer
those projects and this one can meet at. Slot orders differ between
implementations and always will; sticker colors do not.
Subject to the same convention draw names, and the same caveat: this
says what the state looks like if its producer numbered slots the way
convention(n) says. It is a rendering, not a proof of agreement.
The net for orbits, or None for a size this module cannot draw or a
state that is not a cube.
color false gives plain letters, for pipes and for NO_COLOR.
Every facelet index the tables for size n write to, in no order.
These tables are hand-derived, and the failure they invite is a
duplicated or omitted index -- which a scramble fixture can miss, since
a doubly-written facelet still holds a plausible color. A caller that
wants to check them can count instead: this should hold 6 * n * n
entries, all distinct. None for a size with no tables, and for the
2x2x2, which borrows the 3x3x3's.