mesh-forge

Generate optimised, mobile-ready 3D game models from a prompt or a reference image — using cheap, small AI models.

Installs as a skill for Claude Code, GitHub Copilot CLI, and Cursor.

npx mesh-forge-skill
npx mesh-forge-skill verify

Then just ask:

make me a low-poly treasure chest that opens

The idea

An LLM cannot produce good mesh data at any price — ask one for vertices and you get garbage. But it can reliably produce a tiny parametric spec against a fixed catalog:

{ "recipe": "chest", "palette": ["#8B5A2B", "#C9A227"], "clips": ["open", "close"] }

That's ~40 tokens. A deterministic Blender pipeline turns it into geometry, repairs it, and enforces every budget. The hard part lives in the library and the validators, not in the model — which is exactly why small, cheap models work here.

ask the user  →  tiny JSON spec  →  Blender builds  →  auto-repair  →  validate  →  .glb
                 ↑ the only step
                   that costs tokens

Most failure modes are caught and silently repaired by free deterministic code, so a weaker model's sloppier spec still lands inside budget without a retry.

What you get

Every asset is a single .glb:

• 1 draw call, 1 material, no textures — vertex colours only
• ≤1500 triangles (props) / ≤3500 (characters)
• ≤150 KB / ≤400 KB, Draco-compressed
• Correct real-world scale in metres, Y-up, origin at the base, sitting on the ground
• Optional skeleton, skinning, and animation clips

Drops straight into Three.js, Babylon, Unity, Godot, or an h5-game-builder game's 3D-assets/ folder.

It asks before it builds

The skill never guesses anything that changes how the model looks. It asks — in plain language, with options — then reads the spec back to you before building a single polygon, and shows you a render before finalising.

A stout wooden chest about knee-height, dark walnut with brass banding, lightly worn, with a lid that opens. Sound right?

Prefer no questions? Say "you pick" and it uses documented defaults, then prints every assumption it made.

Catalog

| Group | Recipes | |---|---| | Containers | crate barrel chest† | | Nature | rock tree | | Pickups | coin‡ gem‡ potion | | Structure | fence platform sign door† | | Characters | humanoid — rigged, skinned, animated |

† opens ‡ spins

Clips: idle walk run jump land hit die · open close creak · spin bob pulse

Rigging actually works

Because the pipeline generates the body itself, it knows where every joint is — bones are placed exactly, never inferred from geometry. Parts bind rigidly to one bone each, which is the correct look for chunky flat-shaded characters, and animations come from a curated clip library that retargets across body proportions automatically.

You never author animation curves. You pick names.

Reference images

python3 scripts/ref3d.py extract ref.png      # sample exact palette + proportions
python3 scripts/refmatch.py compare ref.png qa/front.png   # colour gate
python3 scripts/ref3d.py   compare ref.png qa/front.png    # silhouette gate

Colours are sampled from the image and used verbatim. Both gates must pass before the skill will claim a match.

Honest limit: a parametric catalog matches palette, proportion, and silhouette. It does not reproduce an arbitrary image exactly. When a reference is outside what the catalog can express, the skill says so and names the closest recipe rather than quietly shipping a near-miss.

Requirements

• Blender 4.2 LTS or newer — the geometry engine. Runs entirely in the background; you never open or learn it. npx mesh-forge-skill verify detects it and prints guided per-platform setup if it's missing.
• Python 3.8+ — any version; we use Blender's own bundled interpreter for geometry, so pip install bpy is never needed.
• Optional: npm i -g gltfpack for meshopt compression on animated models.

No API keys. No cloud services. No model weights. Everything runs locally.

CLI

bash scripts/doctor.sh                                     # check/guide setup
python3 scripts/forge.py specs/crate.json --out out.glb     # build
python3 scripts/validate.py out.glb --kind prop             # budget gates
python3 scripts/render_sheet.py out.glb --out qa/sheet.png  # contact sheet
bash scripts/selftest.sh                                    # regression suite

Open viewer.html?src=out.glb to inspect the result in three.js — the engine games actually ship with, and therefore the check that counts.

Adding recipes

See references/recipes.md. Add a catalog entry to recipes.json and a builder to scripts/recipes_build.py. Prefer enums over free numbers — enums are what let a small model succeed.

License

MIT