Effigy

Game-ready 3D assets and 2D sprites from a picture or a sentence, made on your own GPU.
Generate, clean, retopologize, texture, rig, animate and export, offline, on one 16 GB NVIDIA card.
New in 0.2.0: an AMD Radeon RX 9070 runs the Fast chain too.

Set it up · Manual · Capabilities · How it works · How-tos · Under the hood · Agents · Status · Development

_{Sixteen characters generated from concept images and put through the character chain. The blue dots are the 52 joints Effigy placed on its own; twelve of the sixteen needed no correction (bench).}

_{The Double Dragon move set on the bench viking, as 15-colour pixel art: 21 moves, 382 frames, from the 3D character to a Godot sprite in under a minute (how-to, bench).}

_{The optional detail pass: each pair is before | after; rows are front, three-quarter, back and a close-up (bench).}

The workflow is a line of stages. Solid ones run for every asset; dashed ones are optional and mostly for characters.

flowchart LR
  R[Reference<br><sub>prompt → brief → concepts,<br>or your image</sub>] --> G[Generate<br><sub>Fast or Faithful</sub>]
  G --> C[Clean] --> S[Simplify<br><sub>tri or quad</sub>] --> U[Unwrap] --> B[Bake<br><sub>PBR + normal + AO</sub>]
  B -.-> F[Face<br><sub>from the image</sub>] -.-> D[Detail<br><sub>Tile redraw</sub>] -.-> P[Parts]
  P -.-> RG[Rig] -.-> SK[Skin] -.-> A[Animate<br><sub>clips, text, video</sub>]
  B --> CH[Check] --> E[Export<br><sub>Godot, Unreal, Unity,<br>web, OBJ, print</sub>]
  A -.-> CH

Each stage is a Python module in steps/ that runs as its own process in the environment its model needs, reads one version folder and writes the next. The backend never imports torch: it owns the library, the job queue, the GPU lock and the Blender link, and streams progress to the browser.

flowchart TB
  UI[Browser<br><sub>React + three.js</sub>] <-->|fetch, SSE| API[server/<br><sub>FastAPI · GPU lock · library · jobs</sub>]
  AG[Agent<br><sub>Claude Code, Codex, Cursor…</sub>] -->|MCP| API
  API -->|one process per step| ST[steps/&lt;name&gt;.py<br><sub>.venv-ml · .venv-skin · .venv-kimodo · .venv-parts · .venv-gemx</sub>]
  API -->|headless| BL[Blender 5.2.2<br><sub>exports, rig checks</sub>]
  API <-->|localhost socket| LIVE[Your Blender<br><sub>live link</sub>]
  ST --> LIB[(library/&lt;asset&gt;/&lt;NNN_step&gt;/<br><sub>files + meta.json</sub>)]
  BL --> LIB

Measured on the reference machine (RTX 5080 Laptop, 16 GB VRAM, 32 GB RAM); every number comes from a bench document under docs/bench/.

Every model, tool and dataset is listed in licenses.yaml and shown on the app's Licences page. All of them allow commercial use of what they produce; three carry an attribution (DINOv3, Llama 3, and a courtesy credit for the CC0 Mesh2Motion clips) that the export writes into CREDITS.txt. You choose what to download: props only, characters, characters with motion, or everything (60 to 141 GB).

What the policy rules out and why (non-commercial weights, region-restricted licences, models trained on data you can't ship) is in docs/PLAN.md §6.

Install = download the zip from Releases, unzip and double-click run.bat. It downloads Python, PyTorch, Blender and the models you pick into its own folder; nothing is installed system-wide, and uninstalling is deleting the folder. It writes run.log next to itself (which GPU it found, and on AMD the install's output). To update, unpack the newest zip into the same folder: your library, models, Python and Blender stay. The step-by-step guide, including the Hugging Face login for the gated models, is SETUP.md. From a git checkout, run.bat (or run.sh) does the same.

The effigy MCP server (mcp/effigy_server.py) gives any MCP client the whole workflow as tools:

Setup → Connect an agent prints the configuration for Claude Code, Claude Desktop, Codex, Cursor and Gemini CLI, with absolute paths: use that, not the repo's .mcp.json, which is relative and serves only a Claude Code session started inside the checkout. The API answers only local requests, so the agent runs on the machine the app runs on. A typical session: import a zip, look at it, clean and simplify it, validate, export into a folder for Godot; jobs are bounded and the agent polls job_status like the UI does.

Batch from the command line: with the app running, uv run python -m tools.bench --preset game-prop --set <folder of images> --export godot --to <folder> --out <file>.csv runs the preset over every image, exports each result and copies it into <folder>/<asset>_godot/, one CSV row per image (seconds and VRAM per step, the checks, the export folder). A run that stops midway is not resumed: run it again on the images that are left (every image becomes a new asset, nothing is overwritten).

Effigy is young (started October 2026) and has been exercised on one machine, plus a contributor's AMD card for the Fast chain. What's in the benches under docs/bench/ is real and measured; what isn't there hasn't been run. Known limits:

• Windows first; Linux from source only. No macOS (no CUDA).
• AMD: the RX 9070 / 9070 XT only (its kernel wheels are built for gfx1201) and the Fast chain only; the rest of the app still needs an NVIDIA card.
• Engine imports were checked headless for Godot 4.7 and Unreal 5.8; the Unity export is written to Unity's conventions but has not been import-checked yet. The 2D sprites were checked in Godot 4.7; Unreal's Paper2D import needs the editor and is not checked yet.
• The automatic skeleton fit is right on about three of four characters; the editor covers the rest. Creature fits depend on a clean mesh (touching legs or a fused snout fail a skin check).
• The brief step is template-based, no LLM in the loop. The detail pass can invent detail (a per-view keep/drop is open).
• An experimental Hunyuan3D engine is designed but not built; if it ever is, its outputs are fenced as restricted (its licence excludes the EU, UK and South Korea) and never reach a preset.

Needs uv and Node 22. run.bat / run.sh syncs the Python environments, downloads the pinned Blender and gltfpack on first run, builds the UI once and serves it on http://127.0.0.1:8000 (another port: Setup, App address, or EFFIGY_PORT).

uv sync --frozen                                   # .venv: backend, tests, lint (Python 3.12)
uv run pytest -q && uv run ruff check . && uv run ruff format --check .
UV_PROJECT_ENVIRONMENT=.venv-ml uv sync --frozen --group ml       # the ML steps (torch 2.8 cu128)
UV_PROJECT_ENVIRONMENT=.venv-ml uv run --frozen --group ml pytest -q   # the ML suite (CPU; GPU tests need EFFIGY_GPU_TESTS=1)
cd ui && npm ci && npm run build && npx playwright test            # the UI and its browser tests
uv run python -m server.blender_install            # pinned Blender into blender/
python tools/package.py                            # the Windows portable zip into dist/

Environment variables (never committed): EFFIGY_MODELS and EFFIGY_LIBRARY move the two big folders; EFFIGY_BLENDER and EFFIGY_GLTFPACK point at existing installs; EFFIGY_BLENDER_MCP_PRO_DIR and BLENDER_MCP_PRO_LICENSE are for the live link through Blender MCP Pro (the free blender-mcp add-on works too).

How the project is run: one milestone per branch and PR (the list is in docs/IMPLEMENTATION.md §4), acceptance checks in the PR, the numbers recorded in docs/bench/; contributors start at CONTRIBUTING.md. Contracts between steps (file names, frames, units, meta.json) are frozen in docs/IMPLEMENTATION.md §3; coding agents start there. CI workflows run on request only.

MIT (see LICENSE), except blender_ops/, which is GPL-3.0-or-later because it runs inside Blender. Models, tools and datasets keep their own licences, listed in licenses.yaml; Effigy's own code and the assets you make with it are yours.