Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs: describe additive effect generation and playback
Soohong Kim99ade7a01c9d
diff --git a/docs/README.md b/docs/README.mdindex 548753b..b7e8988 100644--- a/docs/README.md+++ b/docs/README.md@@ -55,6 +55,7 @@ grouping is derived from `sprite_gen/_modules.py`, the one taxonomy table.|---|---|| [user-workflow.md](user-workflow.md) | Two conversation flows, access checks, optional curation and saved defaults || [atlas-workflow.md](atlas-workflow.md) | Execution of GPT row sprites through the existing extraction pipeline |+| [Effects](effects.md) | `pixel-draw --kind effect`, `video-frames --alpha-mode brightness`, `video-loop --cycle lifetime` |## Contract & structurediff --git a/docs/effects.md b/docs/effects.mdnew file mode 100644index 0000000..9deec58--- /dev/null+++ b/docs/effects.md@@ -0,0 +1,77 @@+# Effects++`sprite-gen` creates non-looping additive visual effects (bursts, flashes, impacts) using pixel drawing or video workflows.++## Pixel Effects++Claude draws pixel grids (8–48 px) using palette brightness steps:++```bash+sprite-gen pixel-draw --kind effect --subject 'a small orange fire burst' \+ --size 16 --frames birth,peak,decay,gone --candidates 1 --out-dir fire+```++- **Frames**: 2–8 frames (default: `birth,peak,decay,gone`; other kinds retain at most four). Empty frames are allowed if content changes and at least one frame is visible.+- **Constraints**: No fixed height, feet, or stray spark checks. Origin is centered across all frames.+- **Outputs**: Generates `effect.strip.png`, `effect.strip.json` (mapped in `report.json`), preview, and individual frames.+- **Dark Smoke**: Dark occluding smoke is not additive light; use `sprite`, `icon`, or chroma modes for normal blending.++## Video Pipeline++1. **Prepare canvas**:+ ```bash+ sprite-gen video-canvas --still effect.png --state effect --out canvas.png+ ```+ Accepts RGBA or artwork on black. Retains canvas dimensions and center, composites alpha over black, and writes empty black `canvas.end.png`. Framing overrides are disabled for effects.++2. **Generate prompt**:+ ```bash+ sprite-gen video-prompt --direction front --state effect --character 'A fiery explosion' > prompt.txt+ ```++3. **Generate video**:+ ```bash+ sprite-gen video --image canvas.png --last-frame canvas.end.png \+ --prompt-file prompt.txt --duration 3 --resolution 480p --out clip.mp4+ ```+ `canvas.end.png` can be passed alone without `--image` for text-driven content. Standard provider billing applies.++4. **Extract frames**:+ ```bash+ sprite-gen video-frames --clip clip.mp4 --out-dir frames --alpha-mode brightness+ ```++5. **Extract lifetime sequence**:+ ```bash+ sprite-gen video-loop --frames-dir frames/keyed --fps 24 --state effect \+ --cycle lifetime --out-dir result --name fire+ ```+ Replace `24` with the FPS from `frames/frames.report.json`. State `effect` automatically selects `lifetime`. An empty ending is required; incomplete clips fail without return-to-start conditions and never convert into periodic loops. No particle cleanup or edge failure checks occur. Origin is fixed across all frames; brightest and darkest motion changes are preserved in PNG/WebP.++Automate all stages using `video-set`:+```bash+sprite-gen video-set --base front=effect.png --states effect \+ --out-dir result --character 'A fiery explosion'+```+No per-direction variations are needed; rotate a single front effect at runtime.++## Brightness Alpha & Rendering++Calculates alpha as $a = \max(R, G, B) / 255$. Unpremultiplied color is $U = C / a$ (where $C$ is source-on-black, $0$ when $a = 0$). Output additive rendering in 0–255 units is:+$$\text{output} = \min(255, B + a \cdot U)$$+This preserves saturated colors and faint glows without double-multiplying brightness. There is no threshold: black disappears, dark smoke is faint and cannot occlude, and light saturates to white over pure white backgrounds. Use normal or chroma modes for opaque dark smoke (chroma defaults unchanged).++GIF cannot represent partial transparency, providing only a preview of emission against black with limited alpha. Use PNG or WebP with additive blending for true alpha.++## Metadata++Shared attributes:+- `loop: false`, `hold_last: false`, `blend: add`+- `end_frame`: final delivered strip index+- `anchor`: canvas center (relative to crop in video)++Pipeline differences:+- **Pixel**: `events: []`+- **Video**: `kind: lifetime`, `events: [{frame: <int>, name: "motion_peak"}]`, and `source_cut.samples` naming source frames.++GIF and WebP play once and retain the empty endpoint. Strips can subsample while retaining both endpoints.diff --git a/tests/video/test_effect.py b/tests/video/test_effect.pyindex 6de603b..63e16df 100644--- a/tests/video/test_effect.py+++ b/tests/video/test_effect.py@@ -114,3 +114,32 @@ def test_lifetime_cut_keeps_dim_edge_spark_and_terminal_sample(tmp_path):def test_lifetime_refuses_an_end_with_even_one_dim_pixel(tmp_path):with pytest.raises(SystemExit, match="empty"):cut(lifetime_frames(tmp_path, fade=False), tmp_path / "out", cycle_mode="lifetime")+++def test_video_set_routes_effect_through_black_pin_and_shared_cut(tmp_path, monkeypatch):+ keyed = lifetime_frames(tmp_path)+ raw = tmp_path / "raw"+ raw.mkdir()+ for src in sorted(keyed.glob("*.png")):+ rgba = np.array(Image.open(src)).astype(float)+ Image.fromarray(np.rint(rgba[:, :, :3] * rgba[:, :, 3:] / 255).astype(np.uint8)).save(raw / src.name)+ base = raw / "frame-010.png"+ captured = {}+ def runner(image, prompt, clip, report, **kwargs):+ assert "no effects" not in prompt and "black" in prompt+ assert Image.open(kwargs["last_frame"]).getextrema() == ((0, 0), (0, 0), (0, 0))+ assert kwargs["last_frame"] != image+ captured["pinned"] = True+ clip.write_bytes(b"synthetic")+ return 0+ monkeypatch.setattr(frames, "probe", lambda _: {"stream_index": 0, "fps": 24})+ monkeypatch.setattr(frames, "extract", lambda *a: sorted(raw.glob("*.png")))+ def forbidden(*a, **kw):+ pytest.fail("effects must not trigger facing analysis or chroma cleanup")+ monkeypatch.setattr(batch.facing_mod, "prepare_still", forbidden)+ monkeypatch.setattr(frames, "cutout", forbidden)+ result = batch.run_item(item="side-effect", direction="side", state="effect", base=base,+ root=tmp_path / "batch", character="A spark", duration=3, resolution="480p",+ key="auto", force=False, gap=0, video_runner=runner)+ assert captured["pinned"] and result["ok"], result+ assert result["loop"]["kind"] == "lifetime"