Metadata-Version: 2.4
Name: gummy-snake
Version: 0.8.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Artistic Software
Classifier: Topic :: Multimedia :: Graphics
Requires-Dist: opencv-python-headless>=4.13.0.92 ; extra == 'media'
Requires-Dist: numpy>=2.4.6 ; extra == 'numpy'
Provides-Extra: media
Provides-Extra: numpy
License-File: license.txt
Summary: A playful Python toolkit for creative coding and small games.
Keywords: creative-coding,games,graphics,python,sketches
License-Expression: LGPL-2.1-only
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Gummy Snake

[![PyPI](https://img.shields.io/pypi/v/gummy-snake.svg)](https://pypi.org/project/gummy-snake/)
[![Python Versions](https://img.shields.io/pypi/pyversions/gummy-snake.svg)](https://pypi.org/project/gummy-snake/)
[![License: LGPL-2.1](https://img.shields.io/badge/License-LGPL--2.1-blue.svg)](license.txt)
[![Downloads](https://img.shields.io/pypi/dm/gummy-snake.svg)](https://pypi.org/project/gummy-snake/)

Gummy Snake is a playful Python toolkit for creative coding and small games. It
is for people who want to sketch with code: draw shapes, animate motion, react
to input, load sprites, play with pixels, and build visual toys without first
building a full app.

The public API is Python-first. Function names use `snake_case`, sketches are
ordinary Python files, and drawing, export, pixels, text, images, native
interactive windows, and ECS storage/execution are powered by packaged Rust
runtime components. On desktop builds, native windows and input use the
SDL3-backed runtime. The Rust canvas owns the hot renderer state used to
construct draw commands, including the current style, transform stack,
image/text state, and GPU command batches. It also owns the mutable sketch
context state for canvas lifecycle fields, timing, loop/redraw flags, input
snapshots, and in-progress shape buffers. The Rust ECS owns entity/component,
tag, resource, event, query, schedule, spatial-index, and compiled physical-plan
state; Python constructs typed logical plans and keeps the public sketch API
friendly.

## Install

```sh
pip install gummy-snake
```

Published wheels include the required Rust `gummy_canvas` canvas runtime, which
also exposes the packaged Rust ECS bridge. Source or editable installs must build
that PyO3 module; there is no Python renderer or Python ECS execution fallback
for runtime-owned behavior. Local development builds compile SDL3 from
source/static through Rust when native interactive support is enabled, so no
separate system SDL3 install is normally required.

Install optional media helpers when you need camera or video frame sources:

```sh
pip install "gummy-snake[media]"
```

## First Sketch

Create a file named `circle_sketch.py`:

```python
import gummysnake as gs


@gs.setup
def setup() -> None:
    gs.create_canvas(400, 300)
    gs.no_stroke()


@gs.draw
def draw() -> None:
    gs.background(245)
    gs.fill(255, 90, 90)
    gs.circle(200, 150, 100)


gs.run()
```

Run it:

```sh
python circle_sketch.py
```

For repeatable scripts, use a bounded headless render:

```python
gs.run(headless=True, max_frames=1)
```

Callbacks can also be `async def`, which is useful with async-compatible asset
helpers:

```python
image = None


@gs.preload
async def preload() -> None:
    global image
    image = await gs.load_image_async("sprite.png")
```

## What You Can Make

- 2D drawings with shapes, curves, color, transforms, and blend modes.
- Animated sketches using the familiar `setup()` and `draw()` lifecycle.
- Decorator-based sketches, async-compatible callbacks, and object-oriented
  `Sketch` subclasses.
- Image and pixel experiments, including canvas export.
- Text, font measurement, and accessibility descriptions.
- Interactive sketches with SDL3-backed native windows, mouse, keyboard, and
  touch state when native window support is available.
- WEBGL-style 3D sketches with primitives, lights, materials, models, textures,
  and shader objects. Built-in model and primitive draws use retained Rust/GPU
  buffers, GPU transforms/projection/depth, and built-in material shaders when
  GPU drawing is available.
- Data-oriented simulations and games with the Rust-accelerated ECS: dataclass
  components/resources, typed tags/events, decorated systems, deterministic
  system ordering, grouped joins, spatial relations, and Rust physical execution
  before every `draw()` call.
- Dense 2D scenes that rely on internal mixed primitive, line, sprite, and
  text batching rather than one Python-to-Rust call per draw.
- Small games and visual toys using the examples as starting points.

Loaded images, models/meshes, and sounds keep Rust-managed asset handles behind
friendly Python wrappers. This is intentional for performance: bulk asset bytes,
geometry arrays, parsing, export, and metadata extraction should stay in the
Rust canvas runtime so sketches avoid repeated Python object materialization and
per-element loops. Normal `load_image(); image(...)` sprite drawing can stay on
the fast renderer path, model export can use Rust-owned geometry without first
creating Python `Vec3` objects, and built-in WEBGL model draws can reuse
retained GPU vertex/index buffers while the GPU handles transform, projection,
depth testing, texture sampling, and material lighting. Loaded sounds keep their
bytes and duration metadata in `CanvasSound` until user code asks for Python
bytes.
Image-local resize, mask, filter, crop/copy, and alpha compositing delegate
bulk byte work to the Rust canvas runtime while keeping the Python `Image`
API and version semantics.

ECS component and resource schemas are declared with Python dataclasses. Default
Python field types map to Rust storage columns, and `typing.Annotated` with
`gummysnake.ecs.types` lets sketches request narrower or vector/list storage
such as `UInt16`, `Float32`, `Vec3F32`, or `List(Float64)`. Registered systems
are ordinary decorated Python functions that return lazy `ecs.Action` trees; the
plan is serialized to Rust, optimized into a physical plan, cached, and executed
against Rust-owned columns. Python UDFs marked with `@ecs.udf` are the explicit
escape hatch for side effects or external APIs and are the only ECS plan nodes
that execute Python at runtime.

For pixel effects, `load_pixels()` returns `gummysnake.core.pixels.PixelBuffer`,
a mutable list-like RGBA byte buffer that tracks dirty regions;
`load_pixel_bytes()` provides a bytes readback path; and `update_pixels()`
accepts lists, `PixelBuffer`, and buffer-like inputs such as `bytes`,
`bytearray`, and `memoryview`. Buffer-like uploads use the Rust canvas
buffer-protocol path without an intermediate Python `bytes(...)` copy, exact
no-op byte uploads are skipped, and dirty row-aligned `PixelBuffer` changes can
upload as smaller Rust regions. Small canvas `get()` and `set()` region
operations use Rust region calls instead of reconstructing the full canvas as a
Python image.
For dense drawing loops, `gs.fast()` returns a frame-local facade that keeps
public style/transform state while reducing global-mode dispatch overhead.
Fill-only rectangles, triangles, circles, axis-aligned ellipses, compatible line
runs, and mixed stroked/fill primitive groups can batch into compact Rust
commands with per-record style and transform data. Supported primitive batches
use procedural GPU instance paths where possible; static unchanged command
streams can be retained and reused; unsupported transforms fall back to the
general vertex path without changing public API behavior. Sprite-heavy loops can
batch through the Rust image path with per-sprite transforms, source rectangles,
tint, sampling, and blend state, including an internal atlas path for ordered
draws from a small texture set.
Text-heavy overlays can use `text_batch()` and `text_widths()` to submit many
labels or measurements with fewer Python calls while staying on the Rust-owned
text path. The renderer keeps `text_width()`, ascent/descent, and
`text_bounds()` consistent with the current style used for drawing, and it mixes
GPU glyph-atlas text with batched cached line-texture atlas fallback internally
when that is needed to preserve ordered output around intervening shapes or
images.
ECS runs after frame timing/input state is updated and before plugin
`before_draw` hooks and user `draw()`. Use `gs.add_system(system, order=...)`,
`before=[...]`, `after=[...]`, or named system sets to make execution order
explicit. `do_in_order()` observes serial read-after-write order;
`do_in_parallel()` is for independent snapshot-style actions. Strict mode
(`gs.configure_ecs(strict=True)`) rejects ambiguous duplicate writes, while
non-strict mode remains deterministic with last-write-wins warnings that can be
suppressed via `warn_on_ambiguity=False`.

Opt-in `enable_performance_diagnostics()` counters can identify readback, pixel
conversion, upload, direct model/shape draw, primitive/image batch size and
flush shape, GPU vertex-buffer, texture cache, GPU blend/region-effect passes,
glyphon-backed text drawing, cached-text atlas fallback, and CPU compositing
fallback paths. Use `gs.ecs_diagnostics()` for ECS counters such as physical
plan compiles/runs, rows scanned, fields written, UDF calls, ambiguity warnings,
event queues, and spatial index candidate/exact rows.
HiDPI/Retina rendering keeps sketch coordinates logical while physical pixel
buffers and GPU vertices are scaled by `pixel_density()`.

## Learn More

- [Getting started](docs/getting_started/index.md)
- [Examples](examples/README.md)
- [API reference](docs/reference/index.md), including the [ECS reference](docs/reference/ecs.md)
- [Contributor docs](docs/contribute/index.md), including the [ECS architecture](docs/contribute/ecs_architecture.md)

## For Contributors

This repository uses `uv` for Python commands:

```sh
uv sync --dev
uv run ruff check .
uv run mypy src
uv run pytest
uv run python scripts/source_size_audit.py
uv run python scripts/structure_audit.py
```

The canvas runtime is a required PyO3 module for development/source installs and
also exposes the Rust ECS bridge:

```sh
uvx maturin develop --manifest-path crates/gummy_canvas/Cargo.toml --features extension-module
```

Use `--release` for benchmark/performance comparisons; a debug extension build
can make ECS and rendering benchmarks look dramatically slower.

The refactored Python package is split by responsibility: user-facing wrapper
functions live in topic modules under `src/gummysnake/api/` (for example
`lifecycle.py`, `input.py`, `images.py`, `pixels.py`, `text.py`, `models.py`,
`shaders.py`, `sound.py`, `media.py`, and `three_d.py`), `SketchContext` mixins
live in `src/gummysnake/context_mixins/`, lifecycle code and object-mode facade
groups live in `src/gummysnake/sketch/`, enum-backed constants live in
`src/gummysnake/constants/`, and thin canvas backend/renderer facades delegate to
`src/gummysnake/backend/canvas_runtime/host/` and
`src/gummysnake/backend/canvas_runtime/renderer/`. The ECS public API and logical
plan builders live in `src/gummysnake/ecs/`, while canonical storage and physical
execution live in `crates/gummy_ecs` and are exposed through the `gummy_canvas`
PyO3 module. The renderer internals are grouped around bridge calls, lifecycle,
counters, caches, payload builders, and primitive/image/text/pixel drawing.
Shared test fakes live in `tests/helpers/`, fixtures live in `tests/fixtures/`,
and generated example output stays under the
gitignored `examples/output/` tree. The native desktop runtime itself lives in
`crates/gummy_canvas`, owns sketch context state, canvas draw state, command
construction, cache/dirty-state helpers, and GPU render-pass batching, and uses
SDL3 for windowing, resizing, and input event collection. Python keeps the
public API, callbacks, plugin hooks, and friendly wrapper objects.

The contributor documentation explains the architecture, lifecycle, testing
workflow, and release shape in more detail:

- [Contributor guide](docs/contribute/index.md)
- [Architecture](docs/contribute/architecture.md)
- [Backend and renderer boundaries](docs/contribute/backend_renderer.md)
- [Runtime model](docs/contribute/runtime.md)
- [Runtime diagnostics](docs/contribute/runtime_diagnostics.md)
- [ECS architecture](docs/contribute/ecs_architecture.md)
- [ECS debugging and performance triage](docs/contribute/ecs_debugging.md)
- [Build capabilities](docs/contribute/build_capabilities.md)
- [API performance policy](docs/contribute/api_performance_policy.md)
- [Text renderer decision](docs/contribute/text_renderer_decision.md)
- [Testing and CI](docs/contribute/testing.md)

Performance benchmarks are opt-in:

```sh
uv run pytest tests/benchmark/test_canvas_backend_perf.py --run-benchmarks
uv run pytest tests/benchmark/test_api_overhead_perf.py --run-benchmarks
uv run pytest tests/benchmark/test_image_pipeline_perf.py --run-benchmarks
uv run pytest tests/benchmark/test_model_export_perf.py --run-benchmarks
uv run pytest tests/benchmark/test_webgl_3d_perf.py --run-benchmarks
uv run pytest tests/benchmark/test_ecs_perf.py --run-benchmarks
uv run pytest tests/benchmark/test_ecs_spatial_perf.py --run-benchmarks
```

Canvas backend benchmark scenarios measure native interactive presentation and
are expected to average at least 240 FPS. Headless/offscreen numbers are useful
for export diagnostics, but they are not the runtime performance acceptance
metric. The canvas benchmark payload includes renderer metrics for draw counts,
primitive/image batch records, flushes, largest coalesced batch size, vertex
uploads, texture uploads/reuse, text cache hits, pixel readbacks/uploads, GPU
region effects, and presented/rendered frame counts. WEBGL frame-style benchmark
scenarios use the same FPS floor.
High-count primitive and sprite stress variants keep explicit 60 FPS gates for
10k stress scenes, and the high-count primitive gate covers 10k, 50k, and 100k
static retained-batch scenes behind `--run-high-count-benchmarks`.
Model export benchmarks use a memory budget for streaming OBJ/STL output.
Machine-specific baseline snapshots live in `tests/benchmark/baselines/`; keep
captured values as measured and note both the required 240 FPS floor and the
higher recovered-variant margin target when applicable.

Long-running resource lifecycle checks are also opt-in:

```sh
uv run pytest tests/stress --run-stress -q -s
```

## Compatibility

Gummy Snake keeps the sketch lifecycle familiar, but it is not a browser port.
It does not include DOM helpers, browser-only APIs, JavaScript aliases, or a
Pillow/Pyglet/Python renderer fallback. Unsupported features raise explicit
package errors so sketches fail clearly.

