RubicCube

This program implements a Rubik’s Cube simulator, rendering all six faces of a 3×3×3 cube on screen using user-defined graphics characters (UDGs) stored in arrays. The cube’s state is encoded in a 6×14 string array `a$`, where the first nine columns hold cubie colors per face and columns 10–14 store adjacency data for rotation logic. Clockwise and counter-clockwise face rotations are handled by subroutines at lines 1020 and 1150, which manipulate the state array and optionally animate the affected cubies via the display routine at line 800. The program supports saving and loading named cube states to tape as a string array, and includes a move-history string `m$` that records each rotation to allow an “unscramble” playback feature. A companion machine code block is loaded at `USR “a”` (the UDG base address) via a separate `CODE` file, providing the custom cubie graphics used throughout the display.

---

Program Analysis

Program Structure

The program is organized into well-separated subroutines with a clear initialization and main-loop flow. Execution starts at line 10 which jumps to line 30 (past the tape LOAD at line 20, which is only reached when re-run via SAVE "RubicCube" LINE 20). The high-level flow is:

1. Lines 30–110: Screen setup and data initialization (border/paper/ink, cube state array, coordinate table, shape arrays)
2. Lines 120–160: Display instructions and enter main loop
3. Lines 170–340: Option menu (fresh cube, unscramble, save to tape)
4. Lines 350–700: Initialization subroutine — builds a$(), u(), b$(), d() arrays from DATA
5. Lines 710–790: Full cube redraw subroutine
6. Lines 800–910: Partial redraw subroutine (affected faces only)
7. Lines 920–1010: Main keypress dispatch loop
8. Lines 1020–1140: Counter-clockwise rotation (key “r”)
9. Lines 1150–1270: Clockwise rotation (key “t”)
10. Lines 1280–1320: Keypress wait routine (flush then wait)
11. Lines 1330–1390: Copy current edge cubies into c$() buffer
12. Lines 1400–1490: Face selection display
13. Lines 1500–1560: Highlight selected face center (XOR overlay)
14. Lines 1570–1630: Start menu (play/scramble/load)
15. Lines 1640–1730: Scramble routine
16. Lines 1740–1800: Load cube from tape
17. Lines 1810–1850: Move history recorder
18. Lines 1860–1990: Unscramble playback engine
19. Lines 2000–2010: SAVE commands for program and machine code

Data Representation

The cube state is stored in a$(6,14), a 6×14 string array. Each row represents one face; columns 1–9 hold single-character strings encoding the color (as a digit 2–7, matching INK values) of each cubie on that face. Columns 10–14 hold adjacency face indices used during rotation to identify which neighboring faces are affected.

The screen coordinates for all 54 visible cubie positions are stored in u(54,2), a numeric array populated from DATA at lines 510–560. Each entry gives the PRINT AT row and column for that cubie’s top-left corner. Cubies are displayed as 2×2 character blocks using UDGs defined in the machine code file.

The d(4,3) array (lines 660–680) maps, for each of the four edge groups around a face, the three cubie positions within the adjacent face that are affected by a rotation.

Machine Code Usage

Line 20 loads a machine code block named "rubiccubeC" to address USR "a", which is the base address of the UDG table (character 144). This installs custom 2×2 cubie graphics (UDGs \a through \p at minimum) used in b$(). Line 2010 saves this block back to tape. The BASIC program itself never calls USR as a function; the machine code is purely graphical data, not executable subroutines.

UDG and Display Technique

Each cubie face is rendered as a 2×2 block of UDG characters. The four UDGs per shape variant are stored in b$(6,4) at lines 580–640. Faces 1 and 3 share b$(1) (UDGs \a\b\c\d), faces 2 and 4 share b$(2) (UDGs \i\j\k\l), and faces 5 and 6 share b$(5) (UDGs \e\f\g\h), reflecting the three visible orientations of the isometric cube projection.

The selected face is highlighted using OVER 1 (XOR mode) at lines 1520–1540 and 1460–1470, printing UDGs \m\n\o\p over the center cubie to create a highlight effect without permanently altering the cell colors. The same technique clears the highlight by reprinting in the same mode.

Rotation Algorithm

Both rotation subroutines (lines 1020 and 1150) follow the same pattern:

1. Call line 1810 to record the move in m$
2. Call line 1330 to snapshot the eight edge cubies of the four adjacent faces into c$(4,3)
3. Rotate the face’s own nine cubies in a$(k, TO 8) by string-slicing and reassignment (lines 1040–1050 for CCW, 1170–1180 for CW)
4. Cycle the edge cubie colors around the four adjacent faces using the offset index x (±1 mod 4)
5. Redraw only the affected cubies via line 800 (skipped when hide=1 during scrambling)

The face ring rotation for CW (line 1090) uses x=s+1 cycling 1→2→3→4→1, and CCW (line 1200) uses x=s-1 cycling 4→3→2→1→4.

Move History and Unscramble

The move history is recorded in the string variable m$. Each move is prepended (not appended) as a two-character sequence: face number (as a digit) and move type (“r” or “t”). Line 1820 implements compression: if the same face is turned again in the same direction, the previous record is consumed rather than duplicated — this is a partial move-cancellation optimization. The unscramble routine at line 1860 reads moves from the front of m$ and plays back the opposite rotation, stepping through the history in reverse order. During playback, pressing “h” halts and “r” returns control immediately.

Key BASIC Idioms

• SGN PI is used throughout as a constant value of 1 (since SGN(3.14159…) = 1), avoiding the storage of a numeric literal in FOR loop initializers — a common Sinclair BASIC memory-saving idiom.
• PI TO 4 used as a slice index evaluates to 3 TO 4 since PI truncates to 3 in integer slice contexts.
• VAL a$(f,e) converts a single stored digit character back to a number for use as an INK color or array index.
• STR$ (c+1) is used to store numeric values as single characters in string arrays.
• The keypress routine at lines 1280–1320 uses the standard flush-then-wait pattern: spin while INKEY$ is non-empty, then spin while empty, ensuring a clean single keypress.

Notable Anomaly: Variable Name Collision

Lines 740, 840, and 880 use u(Z,2) with capital Z in the second coordinate lookup, while the loop variable is lowercase z. In Sinclair BASIC, variable names are case-sensitive for string variables but numeric variable names are single letters and case is normalized — both z and Z refer to the same variable. This is not a bug but may appear confusing.

Line 1190/1210 Redundancy

In the clockwise rotation subroutine, line 1190 declares FOR t=SGN PI TO 3 but this loop variable t is immediately re-declared at line 1210 with FOR t=SGN PI TO 3 again inside the FOR s loop. The first FOR t at line 1190 is effectively dead code — it sets up a loop that is never iterated because line 1200’s IF x=0 assignment and line 1210’s re-declaration supersede it. This appears to be a copy-paste artifact from the CCW routine structure at lines 1190–1210 and does not affect correctness.

Scramble and Tape Storage

The scramble routine (lines 1640–1730) performs 7 random face rotations with hide=1 to suppress screen updates during computation, then redraws the full cube at the end. Tape save (lines 280–320) stores the move history in a temporary g$() array and the cube state in a$() as two separate named SAVE operations. Loading (lines 1740–1800) reverses this, restoring both arrays.