🎲 Rubik's Cube Simulator

An interactive 3D Rubik's Cube simulator built with Three.js, featuring realistic animations, intuitive controls, and an intelligent solver.

✨ Features

🎮 Interactive 3D Visualization

• Realistic 3D rendering using Three.js with smooth animations
• Orbit controls for rotating and viewing the cube from any angle
• High-quality materials with Phong shading for realistic plastic appearance
• Face labels on center pieces for easy orientation (R, L, U, D, F, B)
• Beveled edges for a premium look

🎲 Random Scrambling

• Intelligent scramble algorithm that generates random valid moves
• Configurable difficulty (default: 25 moves)
• Avoids redundant moves (no consecutive moves on same face/axis)
• Displays scramble sequence so you can recreate or practice
• Smooth animations for all rotations (300ms per move)

⚡ Command Execution System

• Standard notation support:
  • R, L, U, D, F, B - clockwise face rotations
  • R', L', U', D', F', B' - counterclockwise rotations
  • R2, L2, U2, D2, F2, B2 - double (180°) rotations
• Sequence execution - enter multiple moves separated by spaces
• Real-time feedback with status messages
• Example commands: R U R' U', F2 B2 U D', R U2 R' U'

🧩 Intelligent Solver

• Automatic solving with step-by-step breakdown
• Layer-by-layer method using beginner-friendly algorithms:
  1. White Cross - Solve the top cross
  2. White Corners - Complete the first layer
  3. Middle Layer - Position middle edge pieces
  4. Yellow Cross - Create the last layer cross
  5. Yellow Corners Position - Position last layer corners
  6. Yellow Corners Orient - Orient last layer corners
  7. Yellow Edges - Complete the puzzle
• Move count display - see total moves needed
• Visual execution - watch the solution unfold
• Completion status - clear feedback when solved

🎨 Beautiful User Interface

• Modern, clean design with intuitive controls
• Color-coded buttons:
  • 🟠 Scramble (Orange) - Mix up the cube
  • 🔵 Solve (Blue) - Generate and execute solution
  • 🔴 Reset (Red) - Return to solved state
  • 🟢 Execute (Green) - Run custom commands
• Interactive input field with Enter key support
• Comprehensive notation guide built into the interface
• Scrollable solution panel for viewing detailed steps
• Responsive layout that adapts to different screen sizes
• How to Use section with emoji indicators for quick reference

🔄 Additional Features

• Reset functionality - instantly return to solved state
• State checking - automatically detects if cube is already solved
• Animation queue - prevents conflicting operations
• Error prevention - validates moves before execution
• Console logging for debugging and monitoring

🚀 Getting Started

Installation

1. Clone the repository:

git clone https://github.com/gyagp/rubiks-cube-threejs.git
cd rubiks-cube-threejs

2. Open index.html in your web browser:

# On Windows
start index.html

# On macOS
open index.html

# On Linux
xdg-open index.html

Or use a local server:

# Using Python 3
python -m http.server 8000

# Using Node.js (with http-server)
npx http-server

Usage

1. Scramble the Cube

   • Click the "Scramble" button to randomly mix the cube
   • The scramble sequence will be displayed in the solution panel

2. Execute Custom Moves

   • Type moves in the input field (e.g., R U R' U')
   • Press Enter or click "Execute"
   • Watch the cube perform your moves

3. Solve the Cube

   • Click "Solve" to generate a step-by-step solution
   • The solution will be displayed and automatically executed
   • View the breakdown of each solving phase

4. Reset

   • Click "Reset" to return the cube to its solved state

🎨 Color Scheme

Standard Western Rubik's Cube color scheme (opposite faces):

• ⬜ White (Top/Up) ↔ 🟨 Yellow (Bottom/Down)
• 🟩 Green (Front) ↔ 🟦 Blue (Back)
• 🟥 Red (Right) ↔ 🟧 Orange (Left)

Initial orientation: White on top, Green facing you

📖 Notation Guide

Notation	Meaning
R	Rotate right face clockwise (Red)
L	Rotate left face clockwise (Orange)
U	Rotate upper face clockwise (White)
D	Rotate down face clockwise (Yellow)
F	Rotate front face clockwise (Green)
B	Rotate back face clockwise (Blue)
R'	Rotate right face counterclockwise
U2	Rotate upper face 180° (double turn)

🏗️ Project Structure

rubiks-cube-threejs/
├── index.html          # Main HTML file
├── css/
│   └── style.css      # Styling and layout
├── js/
│   ├── main.js        # Application entry point
│   ├── cube.js        # Cube logic and state management
│   ├── solver.js      # Solving algorithms
│   ├── renderer.js    # Three.js scene and rendering
│   └── controls.js    # UI event handlers
└── README.md          # This file

🛠️ Technologies Used

• Three.js (r128) - 3D graphics library
• OrbitControls - Camera control for 3D navigation
• Vanilla JavaScript - No framework dependencies
• HTML5 Canvas - Rendering target
• CSS3 - Modern styling

🎯 Features in Detail

Cube State Management

• Internal state representation using color arrays
• Each face tracked with 9 stickers (3x3 grid)
• Real-time synchronization between visual and logical states

Animation System

• Smooth 300ms animations per move
• Rotation groups for precise cubie movement
• Quaternion-based rotations for accuracy
• Animation queue prevents conflicts

Solver Algorithm

• Implements beginner's method (layer-by-layer)
• Step-by-step breakdown for learning
• Move optimization to reduce sequence length
• Validates cube state before solving

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📝 License

This project is open source and available under the MIT License.

👨‍💻 Author

gyagp

🙏 Acknowledgments

• Built with Three.js
• Inspired by classic Rubik's Cube solving methods
• Generated and enhanced with AI assistance

---

Enjoy solving! 🎲✨