CPU 3D Rubik CLI Lab

Educational CPU-rendered Rubik cube prototype.

Features:

• pure Python 3D math and software rasterization
• PyQt6 window only displays CPU framebuffer
• Rubik cube face turns with keyboard
• agent CLI over Unix socket
• LLM-safe CLI for text-state solving experiments
• headless control tests

Install

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

System package note: PyQt6 must work on your desktop session.

Run app

python3 cpu3d_cube.py

Keyboard:

• WASD / arrows — rotate view
• Q / E — roll view
• 1 — L
• 2 — U
• 3 — R
• 4 — F
• 5 — B
• 6 — D
• Shift + 1..6 — inverse move
• 7 — reverse mode on/off
• 8 — undo one recorded move
• 9 — scramble
• 0 — reset
• Esc — quit

Agent CLI

General CLI. Useful for automation and demos.

python3 rubik_cli.py find
python3 rubik_cli.py ping
python3 rubik_cli.py status
python3 rubik_cli.py state
python3 rubik_cli.py key 1 2 3
python3 rubik_cli.py seq "R U R' U'"
python3 rubik_cli.py hold d 0.5
python3 rubik_cli.py scramble
python3 rubik_cli.py solve
python3 rubik_cli.py reset

LLM-safe CLI

Restricted CLI for honest LLM solving tests.

Allowed:

python3 rubik_llm_cli.py state
python3 rubik_llm_cli.py move R
python3 rubik_llm_cli.py move "R'"
python3 rubik_llm_cli.py seq R U "R'" "U'"
python3 rubik_llm_cli.py check

Not exposed:

• reset
• scramble
• solve/undo
• history
• internal state

Move mapping:

• L U R F B D
• suffix ' for inverse
• suffix 2 for double turn

Phone-key mapping inside app/general CLI:

• 1=L
• 2=U
• 3=R
• 4=F
• 5=B
• 6=D

See llm_rubik_manual.md for state format and test protocol.

Tests

QT_QPA_PLATFORM=offscreen python3 test_controls.py

Expected:

controls ok

Architecture

• cpu3d_cube.py — PyQt6 app, CPU renderer, Rubik model, Unix socket control server
• rubik_cli.py — full agent CLI, socket-first, xdotool fallback
• rubik_llm_cli.py — restricted CLI for LLM experiments
• test_controls.py — headless smoke tests
• llm_rubik_manual.md — fair-test protocol

Rendering path:

1. cubie stickers as 3D quads
2. optional animated layer rotation
3. camera rotation
4. perspective projection
5. painter's algorithm
6. scanline quad fill into low-res framebuffer
7. PyQt6 scales framebuffer to window

Notes

This is a desktop teaching prototype, not a phone build. The math/rendering approach can be ported to Java ME with fixed-point math, lookup sin/cos tables, and low-resolution drawing.

License

MIT