A modern desktop timer for 3×3 Rubik's Cube solves, built with Python & CustomTkinter.

Simple. Fast. Offline.

---

Table of Contents

• Quick Start
• Overview
• Features
• Changelog
• Installation
• Running
• Project Structure
• Data Storage
• Development
• Requirements
• Contributing
• Security
• License

---

Quick Start

30 seconds to your first solve:

# Option 1: One-command install (requires Python 3.10+)
pip install git+https://github.com/L3gitFoxy/3x3_timer.git && 3x3_timer

# Option 2: Run directly (no install)
git clone https://github.com/L3gitFoxy/3x3_timer.git
cd 3x3_timer
python run.py

# Option 3: Double-click (Windows)
run.bat

On first launch, a welcome dialog explains the timer flow. Press ANY KEY to start inspection, then follow the on-screen prompts.

---

Overview

3x3 Timer is a modern desktop timer for recording Rubik's Cube solves with a sleek CustomTkinter dark-theme UI.

Solve history is stored locally, making the application completely offline with no external services or accounts required.

---

Features

• Modern UI — CustomTkinter dark theme with rounded widgets, hover effects, and dynamic font scaling
• High-precision solve timer with inspection (15s) & grace period (3s)
• WCA-compliant scramble generator (20 random moves, no parallel-face sequences per WCA 4b3)
• Inline scramble display — scramble always visible, no reveal/hide pattern
• Isometric 3D cube visualizer — step through scrambles with arrow keys
• Solve time graph — line chart with best/worst/average markers in the times window
• Local solve history with scramble tracking and persistent JSON storage
• Ao5 / Ao12 / Ao100 — sliding-window averages calculated automatically
• CSV export — export all solve times to CSV for external analysis
• Responsive layout — window resizes proportionally, timer font scales
• Cross-platform (Windows, macOS, Linux)
• First-run welcome dialog — explains the timer flow for new users
• One-click launchers — run.bat (Windows) and run.sh (macOS/Linux) auto-create virtual environments
• No internet connection required
• No external database
• Lightweight multi-file modular application

---

Installation & Running

One-command install (requires Python 3.10+)

pip install git+https://github.com/L3gitFoxy/3x3_timer.git && 3x3_timer

Or install, then run whenever:

pip install git+https://github.com/L3gitFoxy/3x3_timer.git
3x3_timer

Run directly without installing

git clone https://github.com/L3gitFoxy/3x3_timer.git
cd 3x3_timer
python run.py

One-click launchers (auto-create virtual environment)

Windows: Double-click run.bat
macOS/Linux: Run ./run.sh in the terminal

These scripts automatically create a Python virtual environment, install dependencies, and launch the app — no manual setup required.

Install with pipx (recommended for isolation)

pipx install git+https://github.com/L3gitFoxy/3x3_timer.git
3x3_timer

pipx installs the app in an isolated environment so it doesn't interfere with other Python packages.

---

Project Structure

3x3_timer/
│
├── src/
│   ├── __init__.py          # Package marker
│   ├── scramble.py          # Cube simulation & WCA scramble generation
│   ├── timer.py             # Pure timer logic & state machine
│   ├── storage.py           # JSON persistence & validation
│   ├── ui.py                # CustomTkinter graphical interface
│   └── visualizer.py        # Isometric 3D cube visualizer
├── tests/
│   ├── __init__.py          # Test suite marker
│   ├── test_timer.py        # Timer state machine tests (20 tests)
│   ├── test_scramble.py     # Scramble generation tests (22 tests)
│   └── test_storage.py      # JSON persistence tests (23 tests)
├── data/
│   └── times.json           # Solve history (gitignored)
├── .github/workflows/
│   └── ci.yml               # CI pipeline (lint, type-check, test)
├── .pre-commit-config.yaml  # Git hooks (ruff, mypy, formatting)
├── .gitignore
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── SECURITY.md
├── pyproject.toml           # Project config & tool settings
├── run.bat                  # Windows one-click launcher
├── run.sh                   # Unix one-click launcher
└── run.py                   # Entry point

---

Data Storage

Solve times are stored locally in data/times.json.

No cloud services, analytics, or user accounts are used.

---

Development

Setup

# Clone the repo
git clone https://github.com/L3gitFoxy/3x3_timer.git
cd 3x3_timer

# Install with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Run tests

pytest --cov=src

Lint & format

ruff check src/ tests/
ruff format src/ tests/

Type check

mypy src/ tests/

Pre-commit hooks

The project uses pre-commit to automatically run ruff (lint + format) and mypy before every commit. After installing dev dependencies, run:

pre-commit install

---

Requirements

• Python 3.10 or newer
• CustomTkinter >= 5.2.2 (installed automatically via pip)

---

Contributing

See CONTRIBUTING.md.

---

Security

See SECURITY.md.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.