The armature handbook

You block the shot. The model shoots it.

A video model can produce motion, light and life that no renderer can. It cannot be told who is on screen and where they are standing. armature supplies exactly that: a canonical character mesh is staged and animated in headless Blender, and the render becomes a per-frame control sequence the video model works inside — so AI-generated video carries one persistent main character whose position and pose are known every frame.

armature is image-to-video with a GLB instead of an image. Everything spatial is authored — character, pose, camera, staging, blocking — and the model paints life over it. The deliverable is footage: film, cutscenes, character performance, any shot at all. A game is one consumer of that footage, not the boundary of the tool.

The previz scene is ground truth. The video model paints life over it.

Read this part first

The founding thesis is no longer untested. Fourteen experiments have closed since 2026-08-10, and the arc has been through a repo-wide audit — called by the Director, recorded in docs/audit-first-arc.md — whose finding is stated plainly rather than buried: the first arc bought clean measurements of the mechanism and zero frames of the product, and the work now runs under a binding trajectory rule because of it. v0.2.1 — released 2026-08-15 — made the toolkit installable: armature_core ships to PyPI as armature-studio and to npm as @mcptoolshop/armature-studio, published from a tag by OIDC with no long-lived token anywhere. Hard gates green and translations landed before that tag, as before it.

v0.3.0 puts a gate in front of the money. Cloud generation costs real credits and spent credits have no undo, so the bound used to be a sentence in a spec honoured by whoever read it. It is now a check that runs inside the tools that author a spend — see the spend gate below.

Install

pip install armature-studio

npm install -g @mcptoolshop/armature-studio   # the same command, as a launcher

armature check

What installs is armature_core — the gates, the framing and turnaround solvers, the shot-spec contract, the channel maths and the payload builders — every one of which imports under a plain CPython. The rendering scripts are deliberately not console entry points: they run inside Blender’s own interpreter (blender -b -P tools/render_turnaround.py -- …), where a script on your Python could not import bpy at all, and shipping one would be a promise the package cannot keep. The npm package is a launcher, not a port — a second copy of a threshold in a second language is how a threshold drifts.

	Measured, as of 2026-08-18
Experiments closed	14 (one more withdrawn un-run on a falsified premise) — the control arc · rig repair and skeleton approval · the first painted shot · the clean-chain baseline · densified driving · the no-control route’s instructive hard fail · the free route’s first held world · the composed route’s identity verdict (E13, its whole dispatch–halt–repair–run arc inside one date) · the LoRA scene-lever priced live (E14 — the character holds on technically_color, fails on the photo-real pair; zero partner credits)
Routes	the driven route (rig-rendered pose → Animate; proven at shot level, parked — licence-clear for its unpark) · the free route (authored start frame → camera tier at the 6.0 / uni_pc baseline; LoRA scene-lever measured live — E14) · the composed route, graduated by E13: identity-locked, model-decided cinematography from authored references, worlds steered by what the references carry
What a control sequence governs	where the figure is, at what scale, when it moves, and authored subject motion — 85.0° against 0.062°
The division of labour	control owns the outline; the reference owns surface, material and costume
Identity	holds at the Director’s eye, three ways — driven (E08), unanchored (E11 wave 1), and now through a hosted human-trained tier fed nothing but authored references (E13, both arms, both seeds)
Worlds	hold when handed (E12) — and on the hosted tier, the reference’s own ground steers the model-decided world and dominates seed chaos (E13; mechanism attribution honestly open at four generations)

Everything on this site is measured, cited to a numbered experiment, or explicitly marked open. A page that implies a capability nobody has measured is the same defect as a report with a placeholder shaped like evidence — the repo’s method exists to catch that defect, so its own public surface has to survive it.

The spend gate (v0.3.0)

Every generation on a cloud tier costs credits, and spent credits have no compensator — there is no undo, no refund, no rollback. Until v0.3.0 the bound on that was a line in each experiment’s spec, honoured by whichever seat read it. That is a document discipline, and this repo’s whole method exists because document disciplines fail quietly.

Gate CANON makes it mechanical. A subject’s canon is a machine-readable statement of what that character is, keyed on surface — and a surface with no occupant is recorded as a hole, not left absent, because an element list cannot show you what it forgot. Before a payload is written, the gate checks it both ways: that the submission covers the canon, and that everything in the submission is canon. The second direction is the one that catches things — a prompt naming a garment the character does not own reads perfectly well to a human.

Three details matter more than the feature:

• It fires before the output directory exists. Nothing in this repository submits to a cloud tier — the payload builders write files and a session submits them — so the irreversible step this tree owns is writing a payload. The gate lives inside the seven builders that author one, and a refusal leaves no directory behind to be mistaken later for work that happened.
• It raises; it is not an assert. assert is deleted by -O, so the suite runs a second time under -O in CI to prove the gate still fires.
• The escape cannot be worn by a subject that has canon. --no-canon on a character with a ratified canon file is refused as a checkbox; with no subject named at all it is refused as a skip flag; and a canon file whose every occupant is unratified is refused outright — because a check that cannot fail is not a check.

What it does not do is judge whether the figure is the right character. That is canon and the Director’s to rule; no metric here approximates it. The gate checks that a spend can name its subject, which is a different and answerable question.

Where armature sits

armature is downstream of facet, a sibling repo that turns a styled 2D concept into a textured 3D asset. facet cuts and paints the figure; armature stages and performs it. armature consumes facet’s canonical assets and never writes into its tree — and the two repos share one record engine (record-index), so each side’s evidence trail is queryable by the other.

It inherits facet’s discipline too, described on the method page and paid for the hard way.

What armature is not

Named because each is a plausible-sounding drift that would eat the project:

• Not limited to games. Cutscenes, movies, character poses and movement — anything image-to-video can make, made with a scene you own instead of a still. The scope has been shrunk twice and corrected twice; describing armature by a single use-case is the drift signature.
• Not a video editor or NLE. It produces shots. Assembly, grading and sound live elsewhere.
• Not an animation suite. Blender is the animation tool. armature stages and renders.
• Not a character creator. facet makes the asset; armature consumes it.
• Not a model. No training a video model from scratch. Per-character identity adapters are a measured question, not a founding assumption.
• Not a real-time system. Batch, headless, recorded.

The rest of this handbook

• The thesis — why control sequences rendered from geometry, and what the measured evidence actually says.
• Method — three seats, spec → report → ruling, and why the discipline exists.
• The license gate — no non-commercial models anywhere, the verified map, and the traps it caught.
• Roadmap — the arc as planned, the arc as run, and what governs now.

The canonical copies of everything summarized here live in the repo: README · CLAUDE.md · the audit · license map · roadmap. Where this handbook and the repo disagree, the repo is right — it is what the specs cite.