Stage Gen

Stage Gen is a general asset generation SDK and authoring toolkit. Build your own pipeline from GNode nodes, reusable components and bounded recipes, then inspect its outputs in the optional web-based run viewer. Your application decides how assets become a game, animation, tool or other experience.

Iron Petal Unit, one of the example games built with Stage Gen assets.

The product accepts caller-owned Python pipeline definitions and explicit input, output and cache directories. TOML may describe the assets of a particular recipe; there is no universal gameplay document required by the public SDK.

This repository houses two separately owned products: Stage Gen, the main asset product described here, and the Godot example project, a maintained consumer project with its own games, runtime packages, templates and tools. Godot demonstrates ways to use Stage Gen; its gameplay architecture can evolve within that project without becoming part of the asset SDK's contract. The Godot project charter defines that continuing boundary.

3D SD characters

Explore the 3D character workflow and inspect textured, rigged chibi models:

• 3D character guide: the brief-to-rig workflow, setup, supported profile and current limits.
• Example GLBs and review notes: Nami — bunny hood and Riko — pink sweater.

The reference-led examples are development results that needed rig cleanup, beyond the guide's narrower supported profile. Their GLBs include rig-check clips and a cheer; the Samba motion shown in demos is applied separately. New generation uses local Python, Blender and your own paid-provider keys.

Movie sprites

Looping body motion with separately controlled eyes and mouth: Yuzu blinks, Riko winks, and both demonstrate A/O mouth shapes in this twelve-second preview. The characters are composited over an Afterlight background.

Use the supported movie sprite workflow to generate and finish transparent body loops, then pass the resulting first-frame canonical to the existing facial repaint pipeline. It exports standard videos, PNGs and metadata; the consuming application owns playback. See the preview details.

Start with a local asset pipeline

Python 3.12 or newer is required. From this checkout:

uv sync --frozen
uv run stage-gen --help
uv run python src/stage_gen/recipes/looping_parallax/examples/supplied_layers/make_inputs.py /tmp/parallax-inputs
uv run stage-gen pipeline plan src/stage_gen/recipes/looping_parallax/examples/supplied_layers/pipeline.py --input /tmp/parallax-inputs
uv run stage-gen pipeline run src/stage_gen/recipes/looping_parallax/examples/supplied_layers/pipeline.py --input /tmp/parallax-inputs --output /tmp/parallax-run --cache-dir /tmp/parallax-cache
uv run stage-gen pipeline inspect /tmp/parallax-run

Use a new output directory for each run. The example uses supplied, procedurally authored layers and makes no provider calls. It produces repeating images, placement metadata and a preview. Layer extraction from a final reference image is a separate generation step and is not implemented by this example.

Author your own definition with stage_gen.pipeline.define, then use plan, run and inspect from Python or the CLI. Plan a subset with --target NODE_ID. Outputs retain trace, projection, validated cache entries and portable provenance. Read the SDK guide and recipe example.

Planning is offline. Provider nodes require explicit --live or allow_provider_calls=True and an author-configured service. The SDK injects services at the application boundary; credentials never belong in inputs or viewer code. The existing universe and storefront recipes also expose explicit --dry-run commands for deterministic fake operations. See provider setup.

Inspect outputs and consume assets

The web viewer reads completed or running output directories. Generic media and metadata stay inspectable without a built-in recipe identity; bounded inspectors can understand parallax or animation metadata.

Godot consumers live under godot. The asset consumer template shows a local preparation script and GDScript loading an explicit asset. Games own their scenes, controls, combat, narrative binding and asset-to-game wiring. The optional Scenario framework and its independent compiler belong to that Godot project. Games invoke authored sequences and grant presentation capabilities while retaining their world and input policy; Stage Gen does not require a scenario or gameplay contract.

Each example game owns its inputs, preparation script and Godot project. Install the optional game tooling when preparing those games:

uv sync --frozen --group games
uv run --group games python godot/games/bellweather/pipeline/prepare.py

Concept Studio is an optional application in apps/concept_studio. Install it with uv sync --group apps. Its concept workflow has its own workspace and is not a mandatory phase of asset generation.

Repository and checks

Start with the directory preview, architecture, documentation index, and contribution guide. The product gate does not need Bun or Godot:

uv run python scripts/check.py

Verification defines separate product, viewer, Godot, game, application and documentation gates, plus the aggregate gate. Source code licensing is distinct from asset rights; see media publication.