A high-performance, cross-platform Rubik's Cube simulator and solver built in Rust. The application combines a mathematically rigorous cube state engine with a real-time 3D renderer, delivering smooth piece-by-piece rotation animations and an asynchronous Kociemba two-phase solver that never blocks the UI thread.
Whether you want to explore cube theory, visualize solutions step-by-step, or simply play with a virtual cube, this project provides a robust, production-grade foundation.
- 54-Facelet State Representation — A deterministic, integer-based internal model that eliminates floating-point drift and hardware-dependent anomalies. Every state transition is a pure permutation.
- Standard Move Notation — Full support for the 18 HTM (Half-Turn Metric) moves:
U,D,F,B,L,Rwith clockwise, counter-clockwise, and 180° variants. - Scrambler — Generates valid random scramble sequences with configurable length, avoiding consecutive same-face moves.
- Orbital Camera — Fully controllable 360° camera with smooth zoom and pan, powered by Bevy's ECS architecture.
- Smooth Animations — Per-cubelet rotation animations with configurable duration, using quaternion-based interpolation for artifact-free motion.
- Sticker Rendering — Individual sticker quads with a physically accurate sRGB color palette matching official WCA standards.
- Kociemba Two-Phase Algorithm — Integrated via the
kewbcrate, running on a dedicated thread with an 8 MB stack to prevent overflow on Windows. - Asynchronous Execution — Solving runs in a background thread with a channel-based result pipeline, keeping the UI fully responsive.
- Cached Data Tables — The solver's pruning table is generated once and cached to the platform's standard cache directory (
XDG_CACHE_HOMEon Linux,~/.cacheon macOS,%LOCALAPPDATA%on Windows).
- Real-Time Status — Color-coded indicators for
SOLVED,UNSOLVED,CALCULATING..., andSOLVING...states. - Solve Statistics — Tracks solve count, last solution length and duration, and running averages (steps, time, and throughput).
- Compiles natively on Linux, macOS, and Windows with no platform-specific dependencies beyond the standard Rust toolchain.
- Rust 1.85+ (Edition 2024) — Install via rustup
# Clone the repository
git clone https://github.com/GiorgiKavtaradze-prog/Rubik.git
cd Rubik
# Run in release mode (recommended for optimal solver performance)
cargo run --release
# Or build a release binary
cargo build --releaseNote: The first run will generate the Kociemba pruning table, which may take several minutes. The table is cached for subsequent runs.
The graphics feature is optional. You can build the core engine and solver without the Bevy rendering dependency:
cargo build --no-default-features
cargo test --no-default-features| Action | Input |
|---|---|
| Orbit / Rotate | Left Click + Drag |
| Zoom | Scroll Wheel |
Use the keyboard to rotate faces using standard Rubik's notation:
| Key | Move | With Shift |
|---|---|---|
U |
Up face — Clockwise | Up face — Counter-Clockwise |
D |
Down face — Clockwise | Down face — Counter-Clockwise |
F |
Front face — Clockwise | Front face — Counter-Clockwise |
B |
Back face — Clockwise | Back face — Counter-Clockwise |
R |
Right face — Clockwise | Right face — Counter-Clockwise |
L |
Left face — Clockwise | Left face — Counter-Clockwise |
| Key | Action |
|---|---|
S |
Scramble — Applies a 20-move random scramble with animation |
Space |
Solve — Triggers the Kociemba solver and plays the solution animation |
src/
├── main.rs # Bevy application entry point, ECS systems, and event loop
├── lib.rs # Library crate root with feature-gated modules
├── cube/ # Core cube state engine
│ ├── cubie.rs # 54-facelet Cube struct with permutation logic
│ ├── moves.rs # Move and Face types with standard notation
│ ├── state.rs # Facelets representation for rendering
│ └── scrambler.rs # Random scramble sequence generator
├── render/ # 3D visualization layer (Bevy)
│ ├── cube3d.rs # Cubelet and sticker mesh spawning
│ └── animation.rs # Rotation animation state machine
├── solver/ # Solving algorithms
│ ├── kociemba_solver.rs # Kewb-based two-phase solver with caching
│ ├── stats.rs # Solve statistics tracking
│ └── idas.rs # (Deprecated) IDA* solver for shallow scrambles
└── ui/ # Heads-up display
└── hud.rs # Status, stats, and help text rendering
- Pure Permutation Model — The cube state is represented as a
[u8; 54]array. All moves are deterministic permutations, ensuring reproducibility across platforms and runs. - ECS Architecture — The Bevy engine uses an Entity-Component-System pattern, with cubelets as entities and transforms/animations as components.
- Thread-Isolated Solver — The Kociemba solver runs on a dedicated thread with an explicit 8 MB stack, communicating results back via a
std::sync::mpscchannel polled each frame. - Feature Flags — The
graphicsfeature gates all Bevy-dependent code, allowing headless testing of the core engine and solver.
# Run all tests (including integration tests)
cargo test
# Run tests without graphics dependencies
cargo test --no-default-features
# Run with output
cargo test -- --nocaptureThe test suite includes:
- Identity verification — Four sequential turns of any face return to the solved state.
- Inverse move validation — Applying the inverse of a scramble sequence restores the cube.
- Solver integration — The Kociemba solver produces valid solutions for random scrambles.
This project is licensed under the MIT License — see the LICENSE file for details.
Contributions are welcome! Please feel free to submit issues or pull requests.
- Fork the repository
- Create a feature branch (
git checkout -b feat/your-feature) - Commit your changes (
git commit -m 'Add your feature') - Push to the branch (
git push origin feat/your-feature) - Open a pull request
Made with ❤️ and Rust.