Metadata-Version: 2.5
Name: itchy
Version: 0.2.0
Summary: Typed Python game authoring and native Scratch project generation
Project-URL: Homepage, https://github.com/vivainio/itchy
Project-URL: Documentation, https://vivainio.github.io/itchy/
Project-URL: Repository, https://github.com/vivainio/itchy
Project-URL: Issues, https://github.com/vivainio/itchy/issues
Keywords: compiler,education,games,scratch
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Education
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# itchy

Write typed Python games, generate native Scratch blocks, and export self-contained `.sb3` projects.

Install with [uv](https://docs.astral.sh/uv/) and Python 3.12 or newer:

```sh
uv tool install itchy
mkdir my-game
cd my-game
itchy init
itchy run
```

`itchy init` creates a starter with two sprite modules, a stage, shared variable/list/message modules, SVG costumes, and project configuration in an empty directory. Edit the sprite modules to create your game; its comments link to the **[itchy book](https://vivainio.github.io/itchy/)**. `itchy run` prepares the Scratch runtime and opens your game in a local browser. The first run needs internet access to install runtime dependencies.

To translate a Scratch project into Python, run `itchy import my-game.sb3 [directory]`. This creates readable Python using itchy's purpose-built builders where available, copies costumes and sounds to `assets/`, and records unresolved source blocks and remaining generic fallbacks in `IMPORT_NOTES.md`. Custom blocks are reconstructed as Python `Procedure` objects. Run `itchy build` to export a new `.sb3` from the Python source.

```sh
itchy run --no-open       # Serve without opening a browser
itchy run --port 4400     # Choose a port
itchy build               # Export dist/game.sb3 and a shareable browser preview
```

Open an exported `.sb3` in Scratch with **File → Load from your computer**. Generated projects use standard Scratch blocks; Scratch website import is not yet automatically verified.

For development of itchy itself:

```sh
git clone https://github.com/vivainio/itchy.git
cd itchy
uv sync
source .venv/bin/activate
itchy check
itchy test --browser
```

The book's Markdown sources are in [`docs/`](docs/), with navigation and theme in [`zensical.toml`](zensical.toml).

Keep local Scratch test projects as `test-apps/*.sb3` (the entire directory is
gitignored). Run `uv run python scripts/rebuild_test_apps.py` to delete and
recreate each matching `test-apps/<name>-python/` directory, run `ty check`
against the checkout's environment, then build its
`dist/game.sb3` and browser preview. The source `.sb3` files are preserved;
edits in the generated Python directories are discarded.
