flix

0.75.3

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

def canDraw(n: Int32): Bool§ Source

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.

def convention(n: Int32): String§ Source

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.

def draw(n: Int32, state: FramedState, color: Bool): Result[String, String]§ Source

The net for orbits, or why there isn't one.

def fromFacelets(n: Int32, facelets: Vector[Int32]): Result[String, FramedState]§ Source

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.

def toFacelets(n: Int32, state: FramedState): Result[String, Vector[Int32]]§ Source

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.

def writtenFacelets(n: Int32): Option[Vector[Int32]]§ Source

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.