Metadata-Version: 2.4
Name: twistypuzzle-gui
Version: 0.1.1
Classifier: Environment :: X11 Applications
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
Classifier: Topic :: Games/Entertainment :: Puzzle Games
Classifier: Typing :: Typed
Requires-Dist: twistypuzzle==0.1.1
Summary: Desktop interface for the twistypuzzle simulator
Keywords: twisty-puzzle,rubik,gui,slint,desktop
Author-email: Misagh Soltani <msoltani@email.sc.edu>
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/misaghsoltani/TwistyPuzzle
Project-URL: Issues, https://github.com/misaghsoltani/TwistyPuzzle/issues
Project-URL: Source, https://github.com/misaghsoltani/TwistyPuzzle

# twistypuzzle-gui

The desktop interface for [`twistypuzzle`](https://pypi.org/project/twistypuzzle/): a graphical interface rendering via the simulator's CPU software rasterizer, independent of external GPU or browser runtimes.

```bash
pip install "twistypuzzle[gui]"
twistypuzzle-gui
```

Drag rotates the camera, clicking an arrow executes a layer turn, and scroll zooms. Keyboard shortcuts: Space scrambles, `R` resets, `U` undoes.

## Command-Line Interface

`twistypuzzle-gui` provides both an interactive graphical interface and command-line execution. It initializes the specified puzzle at the requested configuration, while information flags display data and exit without spawning a window.

```bash
twistypuzzle-gui "Rubik's Cube (3x3x3)"          # a cataloged puzzle, by name
twistypuzzle-gui '?shell=C$1&cut=C$1/3'          # arbitrary puzzle recipe query
twistypuzzle-gui Megaminx --scramble 20 --seed 7 # initialize with scramble
twistypuzzle-gui --moves "A B2' C" --theme dark  # apply move sequence
twistypuzzle-gui --list                          # list all cataloged puzzles
twistypuzzle-gui --help                          # complete command options
```

| Option | Description |
| --- | --- |
| `[PUZZLE]`, `-p`, `--puzzle` | A cataloged puzzle by name, or a recipe query string. Anything beginning with `?` is parsed as a recipe. |
| `-r`, `--recipe` | Explicit recipe query string. |
| `-s`, `--scramble`, `--seed` | Pseudo-random walk scramble with deterministic seed. |
| `-m`, `--moves` | Apply a written sequence, such as `"A B2' C"`. |
| `--depth`, `--no-animate` | Depth for the Scramble button, and optional animation toggle. |
| `--yaw`, `--pitch`, `--distance` | Initial camera orientation and distance. |
| `--no-arrows`, `--no-edges` | Toggle rendering of turn arrows and piece edges. |
| `--theme`, `--size` | `dark`, `light`, or `system`, and window dimensions in logical pixels. |
| `-l`, `--list`, `--polyhedra` | Print the catalog or polyhedron codes, then exit. |
| `-V`, `--version`, `-h`, `--help` | Print version or help information, then exit. |

Invalid command-line invocations return an error message with exit code 2.

## Python Integration

The wheel installs the executable as `twistypuzzle-gui`, and the `twistypuzzle_gui` module forwards arguments to the underlying executable, allowing programmatic invocation from Python scripts or notebooks:

```python
import twistypuzzle_gui

twistypuzzle_gui.launch("Megaminx", "--scramble", "12")  # blocks until closed
twistypuzzle_gui.launch("Megaminx", wait=False)  # asynchronous execution
print(twistypuzzle_gui.capture("--list"))  # capture stdout from command-line query flags
```

`python -m twistypuzzle_gui [OPTIONS] [PUZZLE]` passes through command arguments.

The desktop interface operates as an independent binary or via the optional `[gui]` extra, decoupling windowing toolkit dependencies from headless simulator workflows.

