Amadeus-SpriteForge

Local asset review and behavior graph editing for sprite animation. Import existing PNG frames, inspect clips and seams, edit a graph, and export a runtime-only character pack for Amadeus.

Status: source alpha, 0.1.0. Generation services and the Amadeus application runtime are separate. 中文说明

Reviewer screenshots

Direct KTX2 playback alongside the creator's saved node layout. This example uses a separately supplied character pack; the repository's runnable examples use geometric sprites.

Expanded behavior graph

Editable example included in the repository

Try the example

Python 3.10 or newer is required. Reference checks use Windows and Python 3.12.

git clone https://github.com/Code-Amadeus/Amadeus-SpriteForge.git
cd Amadeus-SpriteForge
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install ".[qa]"
.\.venv\Scripts\spriteforge.exe init workspace --demo
.\.venv\Scripts\spriteforge.exe review --workspace workspace

On Linux/macOS use .venv/bin/python and .venv/bin/spriteforge. Those platforms need their own verification; a configured CI job is not completed platform evidence.

Commands below use spriteforge for readability. Activate this virtual environment, or replace it with .\.venv\Scripts\spriteforge.exe on Windows and .venv/bin/spriteforge on Linux/macOS. Node.js is only needed to develop/test the UI.

The editor opens at http://127.0.0.1:7788. Use --port 8788 or --no-browser to configure startup. The base installation (pip install -e .) has no third-party Python runtime dependencies. The qa extra adds OpenCV and NumPy for image analysis.

The demo is original geometric artwork generated by spriteforge.demo; it includes weighted automatic edges and a zero-weight manual edge. No character pack is needed.

Direct KTX2 review

spriteforge review --workspace examples/runtime-minimal
spriteforge review --workspace path/to/character-pack

A directory with runtime_manifest.json opens as a read-only runtime pack. Its indexed KTX2 frames are decoded and rendered directly in the browser. PixiJS, the Basis loader and WASM transcoder are bundled. Viewing needs no PNG originals, toktx, Node.js or CDN connection; a WebGL-capable browser is required.

The verified encoding is Amadeus UASTC KTX2, not every KTX2 variant. Playback, frame stepping, graph inspection and exact node-clip preview are available. The renderer bounds its texture cache. Editing and PNG QA remain in the authoring workspace.

Graph view preserves the creator's saved coordinates and curved wiring. Export writes a separate <pack-name>.graph-layout.json beside the runtime directory; keep it alongside the pack for graph viewing. An existing pack can also use its original authoring graph explicitly:

spriteforge review --workspace path/to/character-pack --layout path/to/authoring/graph_config.json

The layout is matched by exact node ID and label and supplies only coordinates; runtime edges and playback remain authoritative. A pack without saved layout still plays clips but shows a missing-layout message instead of inventing a default layout. Use Fit graph, wheel or +/- zoom, empty-space dragging, and Expand to inspect large graphs. Viewing never rewrites coordinates or runtime package data.

Existing assets

spriteforge init workspace
spriteforge import --workspace workspace --source path/to/frames --name my-character
spriteforge review --workspace workspace

Import copies PNG files and their directory layout into workspace/projects/. Existing projects are not overwritten. You can also open an existing authoring workspace directly. Review saves graph_config.json in that selected directory; use a copy when evaluating migration.

Select an actual frame folder from the source list. Processed variants are separate folders; export does not substitute interpolation or alpha versions. The player supports queues, frame stepping and optional seam QA. The Graph tab supports nodes, directed edges, root selection, weights, validation, saving and exact node-clip preview.

Each node binds a frame root, phase, interval and loop mode. flat means PNGs directly in root; in, loop, and out select explicit subdirectories. Filenames are sorted lexicographically, so zero-pad numeric filenames.

One root is required. Positive edge weights are normalized during traversal; zero is manual. Save validates topology and selected frames before atomically replacing the graph. An empty new workspace is an unfinished draft until valid nodes are added.

Amadeus export

Install KTX-Software separately. toktx is needed only for export and is not bundled. The reference export uses KTX-Software 4.4.2 and its UASTC KTX2 encoder.

spriteforge validate-graph --workspace workspace
spriteforge export-amadeus --workspace workspace --output exports/demo-v1 --id demo --display-name "Demo" --version 1.0.0 --toktx path/to/toktx.exe
spriteforge validate-pack exports/demo-v1

Export reads the same frame list and timing as node preview, encodes textures, strips authoring fields, validates the staged package, then publishes the local directory. Existing exports are not overwritten. The result implements amadeus.spriteforge.character-pack.v1:

runtime_manifest.json
graph_config.json
spriteforge_mouth_config.json
textures/**/*.ktx2

The first exporter handles body clips without mouth overlays. An existing workspace with mouth expressions/profiles stops export with an explanation. --no-mouth explicitly exports body clips only. The editor retains authoring mouth-overlay preview and Copy JSON tuning; this is not proof of Amadeus mouth-runtime equivalence.

Amadeus still owns semantic aliases, speech transitions, post-speech holds and presentation priority. Node preview plays a selected clip, not a whole TTS turn. See architecture and authoring.

Checks

Contributors should install the development extra first; see CONTRIBUTING.md.

python -m pip install -e ".[qa,dev]"
python -m pytest
node --check src/spriteforge/web/review.js

Tests cover topology, path containment, rejected saves, HTTP endpoints, preview bindings, import and export consistency. Encoder unit tests use a stub; actual encoding is checked separately. tools/browser_smoke.cjs exercises a running editor with Playwright. See validation evidence.

Scope and license

This foundation excludes generation services, private artwork, model weights, personal configurations, the wallpaper scenario editor and the full Amadeus renderer. Scenario graphs use a separate contract and need a separate migration.

Project code and generated demo: AGPL-3.0-only, consistent with the adapted Amadeus code. Bundled browser dependencies retain their MIT/Apache licenses; see LICENSE, NOTICE.md, and third-party notices. Imported user media retains its own license. KTX-Software is installed separately for export.