Why animsmith

What animsmith is, why it exists, and what it is worth to your team.

This page is for someone deciding whether to adopt animsmith — a lead evaluating tools, a producer weighing pipeline changes, an engineer asked "should we use this?". If you already use animsmith and want reference material, start from all pages instead.

What animsmith is

animsmith validates, measures, reports, and prepares skeletal animation clips for game-engine import and runtime use.

Concretely: point it at a glTF/GLB or FBX export and it answers — before engine import, in seconds, with frame- and bone-level detail — questions that otherwise wait for a playtest: Does the loop pop? Do the feet slide? Does the measured root-motion speed match what the character controller expects? Did this re-export silently change the motion? It works from the command line, from CI via stable exit codes and versioned JSON, or from Rust as a library — and it repairs the mechanical problems that are provably safe to fix.

Why it exists

Every game team answers "is this clip game-ready?" by hand today: a tech artist scrubbing a timeline, a reviewer squinting at a playblast, a bug report from playtest. Nothing open-source does game-semantics clip validation. Format validators stop at spec conformance — a run cycle whose feet skate across the ground is perfectly valid glTF; the validator has no concept of a foot, a loop, or root motion. Engine importers do see content problems, but they see them late, inside editor workflows, after import-time conversion has already reshaped the data — and every studio re-derives its custom import checks from scratch. Academic motion-metric code lives in ML-evaluation repos, not artist tools.

animsmith is the missing layer in between: a content quality gate and repair assistant for animation clips — the linter and test suite counterpart to engine import inspectors, packaged as a standalone Rust library and CLI: glTF/GLB native, FBX ingested for DCC exports, engine-agnostic, with machine-readable output for CI. It gives animation teams the same repeatable, reviewable, CI-friendly confidence that code teams expect from tests and linters.

What "game-ready" means

"Game-ready" is staged evidence, not a stamp — a clip is ready for a consumer, and the last stages of readiness belong to that consumer. The readiness ladder is the canonical definition; it stages the evidence from file-ready data to shipped acceptance. What animsmith contributes splits three ways:

• Validated generically, on every file: the data is mechanically sound — finite values, unit rotations, monotonic key times, sane durations, no accidental scale animation or export bloat — and the losslessly repairable defects are repaired.
• Validated against your declarations: the semantic contracts only you can state — loops, in-place policy, speed pins, required bones, blend sets — declared in a project config, resolved through a rig profile, with missing prerequisites recorded as typed, nonblocking coverage gaps rather than guessed.
• Consumer-owned: importer and blend-graph behavior, controller feel, artistic quality, and shipping sign-off. animsmith's reports and measurements are evidence for that review, not a substitute for it — no standalone tool can certify behavior inside a runtime it has never seen.

What game-ready means covers the measurable ground symptom by symptom: the runtime failure you see when a declared contract is violated, the mechanics behind it, and the check, repair, and config that address it.

What it is worth, by role

Artists and animators get actionable frame- and bone-level reports instead of "the import looked wrong": which clip, which bone, which frame, and a fix hint that maps to a DCC action — trim frames, freeze scale, rename bones, fix the rest pose. animsmith lint export.fbx runs seconds after export, while the DCC session is still open.

Technical animators codify engine and rig assumptions once — loop flags, speed pins, blend rings, rig profiles — in a project config, then batch-validate whole libraries against it instead of re-checking every delivery by hand.

Gameplay engineers stop debugging capsule, root-motion, and foot-slide problems after import. Root travel, stride, and gait phase become measured numbers checked against declared tolerances, and CI gates catch a drifted re-export before it reaches a playtest.

Producers and pipeline owners turn outsourced-asset acceptance into measurable requirements: a machine-readable acceptance contract that both sides can run, fewer review round-trips, and asset state that is visible in a report rather than in someone's head.

Tool engineers build on a Rust library and a versioned JSON envelope with published schemas, instead of scraping engine import logs — the same checks the CLI runs, inside your own pipeline.

What animsmith is not

animsmith is not a converter, an animation editor, or a DCC replacement. It converts FBX exports to glTF as pipeline plumbing and applies byte-surgical repairs whose correctness its own checks can verify, but artistic transformation — retargeting, motion editing, re-authoring — is DCC work and stays out of scope. It also does not replace glTF-Validator or engine importers: it sits between them, checking the content semantics the format validator cannot see, earlier and more repeatably than the engine can.

Where to go next

Convinced, or curious? The what game-ready means covers each failure mode in depth — mechanics, check, repair, config — and everything else, from install to runnable workflows, is routed from the all pages.

What game-ready means

What animsmith checks for, and why exported clips fail at runtime.

A skeletal animation clip can pass every format validator and still break the game it ships in: the loop pops, the character glides, feet skate through blends, a limb stays T-posed. Those are not file-format errors — the file is spec-conformant — they are content problems that only surface after the slowest step of the pipeline: engine import, a bake, a playtest.

This page defines what "game-ready" means here. The readiness ladder below stages the evidence from file-ready data to shipped acceptance and says who owns each level. The checks, repairs and config surfaces themselves live in the symptom index, which routes every runtime symptom — and the narrower presentations of one — to the page that walks it, and carries every registered check id in one table.

Each symptom has its own page under symptoms: what you see in the engine, what AnimSmith measured, the finding, the repair, and the precise contract one click down. If you want runnable commands, use the examples cookbook; if you want the current per-check reference for IDs, default findings, prerequisites, config keys, coverage gaps, and remediation boundaries, see the built-in check reference; if you want the reasoning behind the tool itself — why it exists and what it is worth to your team — see why animsmith.

A valid file is not a usable clip

Format validators — Khronos glTF-Validator being the canonical one — check spec conformance: accessor validity, buffer bounds, quaternion norms at the container level. They have no concept of a loop, a gait, or root motion. A clip whose walk cycle was cut a quarter-stride short is perfectly valid glTF; it will also visibly pop every second of gameplay.

The characteristics below fall into two groups, and animsmith treats them differently:

• Mechanical characteristics hold for every clip, with no knowledge of your project: finite values, monotonic key times, unit quaternions, consistent durations.
• Semantic characteristics are contracts only you can declare: this clip loops, this one is authored in place, these four form a blend ring — declared in a project config and resolved through a rig profile.

These two groups are the first two levels of the readiness ladder, which states what animsmith does about each.

Two loops benefit. The artist inner loop — animsmith lint export.fbx seconds after a DCC export catches "the loop pops" or "wrong rig" while the DCC session is still open, instead of after import and bake. And the CI gate — the same checks with machine-readable output and stable exit codes hold every committed asset to the contract, so a re-export can't silently drift.

The readiness ladder

"Game-ready" is not one property a tool can certify, because most of it is relative to a consumer: your engine, your controllers, your bar for quality. It is a ladder of evidence, and each level has a different owner. animsmith's job is to make the early levels checked and repeatable, make the declared middle measurable, and say plainly what it did not evaluate — not to stamp the whole ladder.

1. File-ready — the data is parseable, finite, and mechanically valid: no NaN/Inf, monotonic key times, unit quaternions, sane durations, clean track hygiene. This is animsmith's primary generic coverage: the mechanical checks (nan, time-monotonic, quat-norm, quat-flip, duration-sanity, scale-keys, non-uniform-scale, constant-track) run on every file with no configuration. The narrower constant-nonunit-scale policy signal is registered but opt-in. fix repairs the two losslessly repairable defect classes (quat-norm, quat-flip).

2. Clip-ready — the clip honors what you declared about it: loop closure, duration and frame grid, in-place vs root-motion policy, required bone motion, structural rig presence, bind-pose consistency. Strong, config-backed coverage where a check exists: fps, loop-seam, in-place, root-motion-speed, foot-slide, missing-bones, required-bones, frozen-bone, and bind-pose judge exactly the expectations you declare — and the checks that need rig roles report a typed coverage gap instead of guessing when a role cannot be resolved. One member is heuristic: foot-slide ships as a warning (see feet slide within one clip).

3. Set-ready — clips that blend or sync together are compatible as a set. Generic measurement and checking where implemented: gait-group holds a declared directional blend ring to a shared stride phase, sync-group checks same-time timing surfaces, and time-complement explains pairs whose stride phase aligns materially better under reflected time. measure supplies the per-clip numbers, and animsmith diff catches drift between revisions. Set compatibility beyond the implemented checks is yours to review.

4. Rig and use prerequisites — which bones play which roles on the target rig, which bones must exist, which bones a clip must animate, and what each clip is for. A shared boundary: you supply the meaning (a rig profile or [rig.roles], [rig] required_bones, animates_bones, per-clip expectations), and animsmith resolves roles against the skeleton, checks the declarations, and reports the resolved roles it used. Nothing at this level can be inferred from the file alone.

5. Runtime integration — importer behavior, blend-graph topology, animation target IDs, masks, sync and reset behavior, and the poses your engine actually evaluates. Consumer-owned: animsmith's exact Bevy 0.19.0 profiles can predict the canonical Animation{i} source-animation selector and, in the current revision 3 slice, negative animation/channel gate outcomes. It does not run the engine, prove runtime asset existence, or validate graph wiring, target survival, or positive playback. A dropped source row is prediction evidence, not a content finding; when both gates allow loading, runtime survival is required-unavailable. Its measurements come from its own documented sampling model — a model of engine samplers, not a reproduction of yours.

6. Gameplay, artistic, and production acceptance — controller feel and timing, readability, visual quality, provenance, reproducibility, shipping sign-off. Consumer-owned: reports and measurements inform the review; people make the call.

A clean run is evidence, and evidence has scope: it covers the checks that ran, on the file that ran, against the contract you declared. Only an actual animsmith run on the actual file establishes that evidence — nothing transfers from vendor previews, other files in the pack, or another export's report. And where generic validation touches a later level, it supplies prerequisites or evidence for that level, never blanket certification of it: a mechanically pristine, contract-clean clip can still be rejected by your importer, your blend graph, or your art director.

Reading a lint run

One animsmith lint run answers five independent questions. Keep them separate when you automate on the output:

• Was the check active? The full catalog is selected by default; --select narrows the selected set, and [checks.<id>] severity = "off" disables a check. A built-in opt-in check stays disabled until its severity is set to "note", "warn", or "error". Final JSON still records inactive checks without executing them.
• Did it apply here? Contract-aware checks judge only declared expectations. With no loop = true clip in the config, loop-seam has nothing to judge and is recorded as not_applicable.
• Was the work evaluated? When declared work exists but a prerequisite or measurement is missing, the check reports a typed coverage gap. A check can also complete part of its work: gait-group still validates declared ring members when unresolved roles keep it from measuring phase, then reports member existence as completed and phase coherence as a gap. Engine prediction work uses a separate required_prediction_unavailable facet; unlike an ordinary coverage gap, it makes lint exit 1 and cannot be suppressed with severity or --allow.
• What did the evaluated work find? Content findings at note, warning, or error severity, carrying clip, bone, time, and measured-vs-expected context.
• What blocks? Gate policy is yours, not animsmith's verdict: exit 1 on error findings, --deny-warnings to promote warnings, per-check severity overrides, and presentation-only --allow in text or Markdown. Coverage gaps never fail a run, while required-unavailable engine prediction work does. Exit 0 means no failing findings and no required prediction work remains unavailable; it still does not imply ordinary gap completeness. A gate that requires full coverage must inspect gaps too.

There is deliberately no single "pass" state: a run can complete with warnings, and it can evaluate some declared work while skipping the rest. See machine-readable output for the current v19 representation. It models selection, configuration, applicability, and evaluation independently, keeps content findings separate from typed gaps, and records completed work scopes. This is evidence about animsmith's checks, not runtime certification; stricter completeness policy belongs to the consuming pipeline.

Each clip symptom the levels above describe has a page of its own under symptoms, whose one table routes it to the checks that measure it, the repair, the config surface, and who owns the fix; the three runtime problems that are not about a clip are answered on that index itself.

Why animsmith exists

The positioning case — what animsmith is, why nothing else fills this role, and what it is worth to each role on a team — lives in why animsmith.

Everything else — the symptom pages themselves, runnable workflows, pipeline scenarios, the CLI reference, embedding, and the dated engine survey behind this page's contract — is routed from all pages.

Install

AnimSmith is one binary. Pick the route that fits your machine, then confirm it runs.

Prebuilt binary

Download the archive for your platform from the latest GitHub release. The archive names for each platform are listed in the CLI reference. Each archive ships with a matching .sha256 file, so you can verify the download before unpacking it:

$ sha256sum -c animsmith-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz.sha256
$ tar -xzf animsmith-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz

Put the animsmith binary somewhere on your PATH.

Cargo

With a Rust toolchain installed:

$ cargo install animsmith

The default build includes FBX input and HTML reports. For a pure-Rust, glTF-only binary with no C build step:

$ cargo install animsmith --no-default-features

That build omits report, convert, and assemble; everything else works.

Check it

$ animsmith --version   # exits 0

Rust pipelines

If you would rather call the checks from your own Rust code than shell out to the binary, start with the embedding guide; the crates are on crates.io and documented on docs.rs.

The project README is the same install summary in the form crates.io and GitHub show, plus a condensed check and configuration reference.

Next: first lint in 60 seconds.

First lint in 60 seconds

Two synthetic clips from this repository are enough to see what a finding looks like, repair one, and watch a declared contract catch a popped loop. The commands run from a checkout of the repository. With an installed binary and no checkout, download the files they name from examples/assets/ and examples/walk.animsmith.toml and adjust the paths.

1. Lint a clip that flickers

Mechanical checks need no configuration. This clip carries one non-unit rotation key and one hemisphere flip, the two representation defects that make a pose flicker or spin the long way round:

$ animsmith lint examples/assets/clip-dirty.glb
examples/assets/clip-dirty.glb:
  error[quat-norm] clip 'swing' bone 'spine' @0.500s: non-unit rotation key (worst at key 2) (measured 1.0500, expected 1.0000)
  warning[quat-flip] clip 'swing' bone 'spine' @0.750s: 2 hemisphere flip(s) between adjacent rotation keys (first between keys 2 and 3) — engines without neighborhood correction will spin the long way (measured 2.0000)
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: swing): only 1 usable first-frame rotation track(s); at least three are required
1 error(s), 1 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 1

Every finding names the check, the clip, the bone and the time, then the measured value against the expected one. The coverage line is not a finding: a check that lacked the evidence it needs (here, at least three rotation tracks) says so instead of guessing, and never fails the run.

2. Repair what is mechanically safe

Both defects are lossless to repair, so fix can do it. --dry-run reports the pending repairs and exits 1 without writing anything; -o writes the repaired copy.

$ animsmith fix examples/assets/clip-dirty.glb --dry-run
  would fix[quat-norm] clip 'swing' bone 'spine': 1 key(s) unit-normalized
1 key(s) would be fixed across 1 track(s) -> no output written
  would fix[quat-flip] clip 'swing' bone 'spine': 1 key(s) hemisphere-normalized
1 key(s) would be fixed across 1 track(s) -> no output written   # exits 1

$ animsmith fix examples/assets/clip-dirty.glb -o fixed.glb
  fixed[quat-norm] clip 'swing' bone 'spine': 1 key(s) unit-normalized
1 key(s) fixed across 1 track(s) -> fixed.glb
  fixed[quat-flip] clip 'swing' bone 'spine': 1 key(s) hemisphere-normalized
1 key(s) fixed across 1 track(s) -> fixed.glb   # exits 0

$ animsmith lint fixed.glb
fixed.glb:
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: swing): only 1 usable first-frame rotation track(s); at least three are required
0 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 0

The repair changes only the bytes of the keys it names; meshes, skins and every other accessor pass through byte-identical, and animsmith diff reports no measurement moved.

3. Lint against a contract

Whether a clip loops is your knowledge, not the file's. Without a declaration, this walk cycle lints clean:

$ animsmith lint examples/assets/walk-dirty.glb
examples/assets/walk-dirty.glb:
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: walk): only 0 usable first-frame rotation track(s); at least three are required
0 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 0

Declare it as a loop through a project config and the seam checks arm:

$ animsmith --config examples/walk.animsmith.toml lint examples/assets/walk-dirty.glb
examples/assets/walk-dirty.glb:
  error[loop-closure] clip 'walk' bone 'foot_r' @1.000s: loop does not close in position: bone 'foot_r' is 0.1581 m from its first-frame model-space position (cap 0.0100 m) (measured 0.1581, expected 0.0100)
  error[loop-seam] clip 'walk' @1.000s: loop seam pops: wrap discontinuity is 6.82× the neighbouring in-clip step (cap 1.60) — the clip does not close its cycle (measured 6.8152, expected 1.6000)
  error[loop-seam-vel] clip 'walk' bone 'foot_r' @1.000s: loop velocity changes at the seam: bone 'foot_r' differs by 0.7972 m/s between the incoming and outgoing model-space velocities (cap 0.1000 m/s) (measured 0.7972, expected 0.1000)
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: walk): only 0 usable first-frame rotation track(s); at least three are required
3 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 1

The clip was cut a quarter-cycle short, so the right foot is 16 cm from where the loop needs it to be. The config file is short and commented; most of the loop caps it sets are the defaults, and it says where it departs from them — a stricter 0.5 degree per-clip rotation cap (default 1.0) and a 1.6 loop-seam ratio (default 1.5). Which parts of such a contract you can declare on your own, and which need the game developer, is who writes what.

4. Read the exit code

0 means no failing findings (warnings, notes and coverage gaps may remain), 1 means failing findings, 2 means an operator error such as a missing file. --deny-warnings promotes warnings to failures for a stricter gate.

Next: your first report shows the same findings as skeleton playback and charts. When something specific looks wrong in the engine, start from the symptoms.

Your first report

A finding tells you which clip, bone and frame are wrong. The HTML report shows you: it plays back the exact pose-grid frames the checks judged, with foot and root trails, metric charts, and a findings list that scrubs the viewer to the judged frame when you click it. One file, no server, no dependencies; attach it to a pull request or send it to whoever owns the fix.

The commands below run from a checkout of the repository; the clips are the same synthetic samples used in first lint.

Render the report

$ animsmith --config examples/walk.animsmith.toml report examples/assets/walk-dirty.glb -o report.html
wrote report.html (1 clip(s), 3 finding(s), 0.1 MB)   # exits 0

Open report.html in a browser. This is the same report, embedded here and scrubbed to the first finding:

Open it full size. Drag to orbit, use the wheel to zoom, and click a finding to jump to its frame. When the file holds more than one clip, the with control plays a second one beside the first at the same normalized phase, with both source times labelled — a presentation mapping between two timelines, not a retime. With a pair selected, enable illustrative blend for an optional third pane and a continuous weight slider. This engine-agnostic presentation interpolates sampled local transforms and runs forward kinematics; it adds no measured finding or runtime evidence. See the blend contract. The source charts share a playhead with the 3D view, and each chart caption says what to look for in it — derived from what your configuration declares for that clip and what the checks judged, not from an assumption about what the clip is. A clip declared loop = true is told its curves should end where they began; one that pins speed_mps with animation-owned travel is told the root should keep travelling at that speed, with no claim about the shape it travels; a clip that declares neither is told so, and named the checks that judged it. A root path is also marked where the track starts (a hollow circle) and where it ends (a filled square), and the caption states how far apart the two are. A configuration that declares a [gait_groups.<name>] blend ring adds one further figure per group, drawing every member's left-minus-right foot height on one shared stride-phase axis with the declared tolerance as a band; that figure stays on screen whichever member you select, because comparing them is what it is for.

Compare before and after

When a clip has been repaired or re-exported, render both versions into one comparison report. The pair below is a synthetic gait with a seam and a sliding foot on the left, and the corrected clip on the right:

$ animsmith --config examples/report-comparison.animsmith.toml report \
    examples/assets/report-comparison-before.glb \
    --compare-after examples/assets/report-comparison-after.glb \
    --before-clip acceptance-matrix --after-clip acceptance-matrix \
    -o comparison.html
wrote comparison.html (1 clip(s), 5 finding(s), 0.1 MB)   # exits 0

Open the comparison. Press play beside the shared phase to run both sides together, or scrub it by hand. Tick Overlay after on before beside it to draw the two skeletons in one pane — the before solid, the after dashed over it — at those same frames. The judged poses come first, then the shared root trajectory — fitted to its own panel, with a scale bar in the corner and the magnification against the role-trajectory panels in its caption, so a two-centimetre sway is legible and still reads as two centimetres — and then each side's trails and gait. The gait panel shades the sampled stance intervals, and every panel's caption says what to look for in it.

Share evidence without sharing the asset

The report embeds the sampled pose grid, which is the motion itself. When the clip is licensed or confidential, render an evidence-only report: findings, coverage gaps, engine predictions and charts stay, the poses are omitted, and the file is safe to attach to a vendor ticket.

$ animsmith --config examples/walk.animsmith.toml report examples/assets/walk-dirty.glb -o evidence.html --evidence-only
wrote evidence.html (1 clip(s), 3 finding(s), 0.1 MB)   # exits 0

Where next

• Something specific looks wrong in the engine: start from the symptoms.
• You want this in your export loop or CI: for artists or for game developers.
• You want the full flag list: the CLI reference.

Mixamo to game-ready: an end-to-end tutorial

Take one free Mixamo download through the whole pipeline: download, convert to glTF, inspect the rig, lint, fix what is mechanically fixable, and grow a project contract config from the results.

This is the bring-your-own-asset counterpart to the examples cookbook: the cookbook runs against small assets committed to this repo, while this tutorial runs against a real marketplace rig you download yourself. Each step links to the page that owns its why rather than re-explaining — what game-ready means for everything the checks judge, and the pipeline scenario guide for acquiring and handling the raw asset.

The complete key, default, and precedence reference for the contract used below is the configuration reference.

About the transcripts. The command output in this tutorial is real, captured from a small generated rig that carries the same mixamorig:* bone names, the same nine profile roles, and the same mixamo.com take name as a real download (this repo does not ship Mixamo's own files — see the asset policy). Your download will show many more bones — fingers, twist joints — and possibly more findings; the roles, the commands, and the behavior are the same. Excerpts marked real download were captured once (July 2026) from Mixamo's default Walking; unlike the stand-in transcripts they are not regenerated by this repo's tests, so treat their exact numbers as a snapshot.

Build requirements. convert (step 2) ships in the default install — it sits behind the fbx feature, which is enabled unless you opted out. If you installed with --no-default-features, use the default build for this one step (see feature flags). Everything from step 3 on works in any build.

1. Download a clip from Mixamo

Mixamo is free with an Adobe ID, and Adobe documents its animations as royalty-free for personal and commercial projects — see Adobe's Mixamo FAQ for the current terms. That covers using the assets in your project; it does not clearly permit redistributing the downloaded files, so keep them out of public repos and do not commit them here.

1. Sign in and pick any character.
2. Search the animations for Walking and select a walk cycle.
3. Check the In Place option. Mixamo's default walks travel through the world; In Place keeps the hips over the origin, which is the shape most capsule-driven character controllers expect. (If your game uses root motion, download without In Place — step 6 shows how the contract differs.)
4. Download as FBX Binary with skin. The skin is optional for linting, but keeping it lets report render the mesh later.

We recommend keeping the downloaded FBX as your immutable raw source and treating every animsmith output as a derived artifact — the pipeline scenario guide explains that raw-vs-generated split.

2. Convert to glTF

$ animsmith convert Walking.fbx -o walking.glb    # real download
wrote walking.glb (70 node(s), 1 clip(s), 2 mesh(es) / 28374 position(s), 2 material(s)); dropped 1 clip(s) with no writable tracks

(Counts vary by character. This download contains a second take named Take 001 with zero tracks and keys. Conversion omits that empty take, writes the animated mixamo.com clip, and reports the omission. The licensed download is not committed here.)

animsmith lints FBX directly, so conversion is not required to run checks — but glTF/GLB is the native format for the rest of the pipeline (fix, transform, and diff operate on glTF), and a convert-once step gives later commands a stable baseline to compare against. A conversion that succeeds proves the container is well-formed, not that the motion is usable — a valid file is not a usable clip — which is what steps 4–6 judge.

3. Inspect the rig

$ animsmith inspect walking.glb
walking.glb
rig profile: mixamo (9 roles)
  hips         -> mixamorig:Hips (exact)
  spine        -> mixamorig:Spine (exact)
  head         -> mixamorig:Head (exact)
  left_foot    -> mixamorig:LeftFoot (exact)
  right_foot   -> mixamorig:RightFoot (exact)
  left_toe     -> mixamorig:LeftToeBase (exact)
  right_toe    -> mixamorig:RightToeBase (exact)
  left_hand    -> mixamorig:LeftHand (exact)
  right_hand   -> mixamorig:RightHand (exact)
skeleton: 9 bones
  mixamorig:Hips
    mixamorig:LeftFoot
      mixamorig:LeftToeBase
    mixamorig:RightFoot
      mixamorig:RightToeBase
    mixamorig:Spine
      mixamorig:Head
      mixamorig:LeftHand
      mixamorig:RightHand
materials: 0
mesh instances: 0
clips: 1
  mixamo.com: 1.000s, 2 tracks, 33 keys max

These are the same nine roles a real download resolves; your skeleton list will just be longer. From the real download (abridged):

$ animsmith inspect walking.glb                   # real download
walking.glb
rig profile: mixamo (9 roles)
  ...the same nine-role table as above...
skeleton: 70 bones
  <fbx-root>
    mixamorig:Hips [skinned]
      mixamorig:Spine [skinned]
        ...
materials: 2
  ...the exact quoted source material names...
mesh instances: 2
  node "<first mesh node name>"
    ...mesh, skin, and primitive/material context...
  node "<second mesh node name>"
    ...mesh, skin, and primitive/material context...
clips: 1
  mixamo.com: 1.033s, 156 tracks, 32 keys max

The extra bones — fingers, twist joints, end markers — carry no role, and the two mesh nodes ride along for report playback.

Two things to read off this output:

• The mixamo profile resolved without any config. Mixamo is a built-in rig profile: it binds the semantic roles from Mixamo's mixamorig:* bone names, which is what arms the role-based checks in step 6. Without a resolved rig, those checks skip rather than guess (see the symptom index).
• The clip is named mixamo.com. Mixamo names every export's animation take mixamo.com, and animsmith uses the take name as the clip name. Your contract config must address the clip by this name.

The mixamo profile has no Root role. Mixamo rigs have no dedicated root bone — mixamorig:Hips is the top of the hierarchy, and any root motion is baked into it. animsmith therefore judges in-place and root-motion-speed on the Hips track for Mixamo rigs: travel measurements still work, but they describe hip movement, not a separate locomotion root. If your engine workflow retargets hip motion onto a dedicated root bone (a common Unreal step), that happens downstream in your DCC or importer — lint the export you actually ship to the engine.

4. Lint the mechanical checks

$ animsmith lint walking.glb
walking.glb:
  coverage[bind-pose] first_frame_rest_delta 'mixamo.com': insufficient_rotation_evidence: ...
0 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s)

With no config, expectation-driven checks are not applicable. Mechanical checks still evaluate, as does bind-pose; this analytic fixture has no rotation tracks, so bind-pose records a nonblocking coverage gap rather than claiming a clean evaluation. Findings like constant-track notes are normal on a marketplace rig. From the real download (abridged):

$ animsmith lint walking.glb                      # real download
walking.glb:
  warning[scale-keys] clip 'mixamo.com' bone 'mixamorig:Hips': scale animation present ...
  note[constant-track] clip 'mixamo.com' bone 'mixamorig:Spine': translation track has 2 keys but never moves — export bloat
  ...
0 error(s), 1 warning(s), 103 note(s), 1 coverage gap(s)

Of the clip's 156 tracks, 103 never move — pure export bloat — and the hips carry a scale track worth checking before retargeting. Nothing here is broken motion; the serious mechanical defects — flicker-inducing quaternion problems — tend to creep in later, after the asset has been through your DCC, a retargeter, or an exporter plugin.

5. Fix what is mechanically fixable

$ animsmith fix walking.glb --dry-run
0 key(s) would be fixed across 0 track(s) -> no output written
0 key(s) would be fixed across 0 track(s) -> no output written

(One summary line per default repair — quat-norm, then quat-flip.) fix applies only repairs that are provably lossless: quat-norm and quat-flip, the representation defects behind the pose flickers, spins, or explodes. That makes it safe to run unconditionally; on a clean export it is a no-op, as here. When a re-export does pick up defects:

$ animsmith fix walking.glb -o walking-fixed.glb
$ animsmith lint walking-fixed.glb
$ animsmith diff walking.glb walking-fixed.glb

The re-lint proves the findings are gone; the diff proves the repair moved no measured motion. The cookbook's repair section shows the full transcript of that loop on a committed dirty asset.

6. Grow the contract config

The mechanical checks passing does not make the clip game-ready — a walk whose loop pops or whose feet skate is mechanically pristine (see a valid file is not a usable clip). The semantic checks need your expectations declared. Start from what measure reports. The shortened JSON below is illustrative; capture and retain the exact numbers from your own downloaded asset rather than treating these sample values as vendor evidence:

$ animsmith measure --format json walking.glb
{
  "schema_version": 19,
  "schema": "urn:animsmith:schema:output:19",
  "tool": { "name": "animsmith", "version": "0.14.0",
            "source": { "revision": null, "dirty": null } },
  "command": "measure",
  "summary": { "files": 1 },
  "files": [
    {
      "path": "walking.glb",
      "input": {
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "bytes": 123456
      },
      "rig": { "profile": "mixamo", "resolution_outcome": "resolved",
        "resolved_roles": { "hips": "mixamorig:Hips", "spine": "mixamorig:Spine",
          "left_foot": "mixamorig:LeftFoot", "right_foot": "mixamorig:RightFoot" },
        "resolved_role_policies": { "hips": "exact", "spine": "exact",
          "left_foot": "exact", "right_foot": "exact" } },
      "measurements": {
        "schema_version": 18,
        "schema": "urn:animsmith:schema:measurements:18",
        "clips": { "mixamo.com": {
          "duration_s": 1.0, "frame_count": 33,
          "animated_bones": ["mixamorig:Hips", "mixamorig:LeftFoot", "mixamorig:RightFoot"],
          "bone_channels": [
            { "bone_index": 0, "bone_name": "mixamorig:Hips",
              "availability": "measured",
              "properties": ["translation", "rotation"] },
            { "bone_index": 1, "bone_name": "mixamorig:LeftFoot",
              "availability": "measured",
              "properties": ["translation"] },
            { "bone_index": 2, "bone_name": "mixamorig:RightFoot",
              "availability": "measured",
              "properties": ["translation"] }
          ],
          "bone_rotation_range_deg": { "mixamorig:Hips": 3.2 },
          "loop_continuity": { "bones": [
            { "bone_index": 0, "bone_name": "mixamorig:Hips",
              "position_delta_m": 0.0, "rotation_delta_deg": 0.0,
              "seam_velocity_delta_mps": 0.0,
              "seam_angular_velocity_delta_degps": 0.0 },
            { "bone_index": 1, "bone_name": "mixamorig:LeftFoot",
              "position_delta_m": 3.7e-17, "rotation_delta_deg": 0.0,
              "seam_velocity_delta_mps": 0.0,
              "seam_angular_velocity_delta_degps": 0.0 },
            { "bone_index": 2, "bone_name": "mixamorig:RightFoot",
              "position_delta_m": 3.7e-17, "rotation_delta_deg": 0.0,
              "seam_velocity_delta_mps": 0.0,
              "seam_angular_velocity_delta_degps": 0.0 }
          ] },
          "loop_continuity_availability": "measured",
          "loop_endpoint_mode_availability": "not_applicable",
          "frame_grid_availability": "not_applicable",
          "loop_seam_ratio": 1.2e-15,
          "loop_seam_ratio_availability": "measured",
          "gait": { "phase": 0.75, "phase_availability": "measured", "lr_amplitude_m": 0.2 },
          "gait_availability": "measured",
          "root_trajectory": {
            "bone_index": 0, "bone_name": "mixamorig:Hips",
            "source_role": "hips_fallback",
            "translation": {
              "horizontal_displacement_x_m": 0.0,
              "horizontal_displacement_z_m": 0.0,
              "horizontal_travel_m": 0.0,
              "vertical_displacement_m": 0.0,
              "vertical_min_displacement_m": 0.0,
              "vertical_max_displacement_m": 0.0
            },
            "translation_availability": "measured",
            "yaw": {
              "heading_axis": "positive_z", "net_yaw_deg": 0.0,
              "unwrapped_yaw_deg": 0.0, "yaw_travel_deg": 0.0
            },
            "yaw_availability": "measured"
          },
          "root_trajectory_availability": "measured",
          "speed_mps": 0.0,
          "speed_mps_availability": "measured"
        } },
        "mesh_definitions": [],
        "node_instances": [],
        "scenes": [],
        "skeleton_source_coverage": "unavailable",
        "skeleton_nodes": [],
        "skins": [],
        "material_resource_coverage": "complete",
        "material_definitions": [],
        "textures": [],
        "images": []
      }
    }
  ]
}

(Abridged — all nine roles resolve; head, toes, and hands are elided here.) The numbers become the contract: near-zero per-bone loop deltas and loop_seam_ratio say the cycle closes in pose, velocity, and locomotion phase; speed_mps of zero confirms the In Place download, and the gait numbers seed a blend-ring group once you have more than one direction. Declare what must stay true by saving this as animsmith.toml next to your clip — animsmith auto-loads it from the working directory:

[rig]
profile = "mixamo"

[clips."mixamo.com"]
loop = true
movement_owner_xz = "gameplay"

[checks.loop-seam]
max_ratio = 1.6

[checks.loop-closure]
max_position_delta_m = 0.01
max_rotation_delta_deg = 1.0

[checks.loop-seam-vel]
max_velocity_delta_mps = 0.1

[checks.loop-seam-rot]
max_angular_velocity_delta_degps = 5.0

The same contract is committed as examples/mixamo.animsmith.toml for reference (from a repo checkout, pass it with --config examples/mixamo.animsmith.toml instead of saving a local copy). It pins the profile rather than trusting auto-detection, declares the clip a loop (arming the loop checks) and gives XZ movement to gameplay (arming in-place, judged on the Hips track per the callout above). Every key, glob pattern, and severity override is documented in the configuration reference.

Lint against the contract:

$ animsmith lint walking.glb
walking.glb:
  coverage[bind-pose] first_frame_rest_delta 'mixamo.com': insufficient_rotation_evidence: ...
0 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s)   # exits 0

And this is what a violation looks like — the same contract against a copy whose cycle was cut short, the classic popped loop:

$ animsmith lint walking-popped.glb
walking-popped.glb:
  error[loop-closure] clip 'mixamo.com' bone 'mixamorig:RightFoot' @1.000s:
    loop does not close in position (measured 0.1581, expected 0.0100)
  error[loop-seam] clip 'mixamo.com' @1.000s: loop seam pops: wrap discontinuity
    is 6.82× the neighbouring in-clip step (cap 1.60) — the clip does not
    close its cycle (measured 6.8152, expected 1.6000)
  error[loop-seam-vel] clip 'mixamo.com' bone 'mixamorig:RightFoot' @1.000s:
    loop velocity changes at the seam (measured 0.7972, expected 0.1000)
3 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s)   # exits 1

The contract also catches downloading the wrong variant. The real download above is Mixamo's default Walking — the traveling one — and under this In Place contract it fails exactly as it should:

$ animsmith lint walking.glb                      # real download
walking.glb:
  error[in-place] clip 'mixamo.com': declared in-place but the root travels
    at 1.79 m/s — the character will glide at runtime (measured 1.7857,
    expected 0.0000)
  ...

For a root-motion download like that one, give XZ ownership to the animation and add a speed pin, using the speed_mps that measure reported as the starting value:

[clips."mixamo.com"]
loop = true
movement_owner_xz = "animation"
speed_mps = { value = 1.8, tolerance = 0.15 }

Older configs may spell XZ gameplay/animation ownership as in_place = true or false. That alias remains supported, but one selector entry cannot declare both in_place and movement_owner_xz.

Under that contract the real download passes the loop and speed pins and surfaces genuine content findings instead (abridged):

$ animsmith lint walking.glb                      # real download
walking.glb:
  warning[foot-slide] clip 'mixamo.com' bone 'mixamorig:LeftFoot' @0.333s:
    left foot skates during stance: speed deviates 0.52 m/s from the
    expected 0.00 m/s (cap 0.30) — foot plants will slip at runtime ...
  warning[foot-slide] clip 'mixamo.com' bone 'mixamorig:RightFoot' @0.833s: ...
0 error(s), 3 warning(s), 103 note(s), 0 coverage gap(s)   # exits 0

Whether that stance drift is acceptable for your game is exactly the kind of decision the contract records — tighten the cap, accept it with --allow, or send the clip back for cleanup (see feet slide within one clip).

From here the contract grows with your project: rename clips as you import more animations, add [clips."run_*"] globs, speed pins, and gait_groups blend rings as the locomotion set fills out — the cookbook's project contract section and the worked character.animsmith.toml show that full shape. Commit animsmith.toml next to your assets and every bare animsmith lint — local or in CI — enforces it.

Where to go next

What game-ready means explains every failure mode these checks catch; everything else — the cookbook, the CLI reference, embedding — is routed from all pages.

Symptoms

Start from what you see in the engine, not from a check id. One row per symptom: what it looks like, the checks that measure it, the repair, the config surface, who owns the fix, and the page that walks it. Each page opens with the runtime symptom, shows what AnimSmith measured on a synthetic clip, and keeps the precise contract one click down; the built-in check reference and the configuration reference remain the exact authorities.

Where the repair column says re-export, that is deliberate: AnimSmith rewrites a clip only in ways whose within-clip correctness its own checks can verify. Those are the lossless quaternion repairs and the bounded mechanical edits — slice, hold-extend, in-place gait anchor, duplicate-loop-endpoint removal, constant-track pruning and FBX-to-glTF conversion — while artistic transformation stays DCC work, for the reason in what animsmith is not. A clean run on any row here is also still scoped evidence: runtime integration caveats apply after it, including the sparse transition coverage a blend or transition set is judged on.

The table above carries every registered check id, including the narrower presentations of a symptom that no page of its own owns. The readiness ladder stages what a clean run on any of these pages is evidence for.

Whichever row you follow, capture the current lint --format json result, and when the motion itself is contested, the offline report or a before/after diff. A current, repository-safe diagnostic pair is:

# workflow-exit: 0
$ANIMSMITH --config "$CONFIG_DIR/report-comparison.animsmith.toml" report \
    "$ASSET_DIR/report-comparison-before.glb" \
    --compare-after "$ASSET_DIR/report-comparison-after.glb" \
    --before-clip acceptance-matrix --after-clip acceptance-matrix \
    -o "$WORK_DIR/symptom-comparison.html"

It shows a deliberately defective loop and stance trail; it is diagnostic evidence, not an engine or artistic acceptance result.

Not about the clip

Three runtime problems produce no content finding, so none of them has a row above. Each is answered by reading the run itself and then by the project that consumes the asset.

A loader error or an AnimSmith refusal. Read stderr and the command's exit code, then inspect engine-track-support, engine-addressability, input identity, and coverage facets. Correct a bad path, config, or supported source fact; do not reinterpret a refusal. Engine feature and import settings belong to the engine project. The gate closes on a successful rerun with complete applicable source evidence, plus engine-observed load evidence where the route requires it — for Bevy, the revision-3 lint command in the intake workflow.

A clip exists but cannot be addressed in-engine. Inspect generate addressability source rows, selector and index evidence, the dependency closure, and the engine profile's coverage state. Regenerate an application manifest after a source-order change; application name policy, loaded handles, targets, and graph wiring are engine code. The gate closes when the source inventory is complete and the target project records a resolved runtime asset, selector, target, and playback.

Animations vanish in Bevy with no lint error. No content finding exists, because the loader's bevy_animation feature or its load_animations setting dropped them; the Bevy profile's revision-3 gate predicts exactly that negative outcome. The gate closes in the Bevy project that loads the asset, not in a lint run.

The exact fields, severities, prerequisites, and configuration keys stay authoritative in the built-in check reference and the configuration reference. If evidence identifies a vendor or source delivery defect, return the source and its evidence; if it identifies runtime or artistic uncertainty, keep the project-owned gate open.

The pose flickers, spins, or explodes

A joint snaps the long way round between two keys, a limb jitters for a frame, or the whole character turns into visual noise.

Checks: nan · quat-norm · quat-flip · time-monotonic

Why it happens

Rotation is stored as quaternions, and engines are stricter about the maths than exporters are. A key that is not unit length skews skinning, two adjacent keys on opposite hemispheres make an engine interpolate the long way round, and one non-finite float poisons every pose that interpolates through it. Nothing here is an artistic decision — it is the representation of the rotation, which is why these are the checks that need no configuration at all.

What AnimSmith measures

The synthetic clip below carries one non-unit rotation key and one sign-flipped key on the same bone; everything else is the clean clip.glb. The report names both, with the frame each was judged at.

Both defects are in the representation rather than the pose. AnimSmith normalizes every rotation key it samples, and a quaternion and its negation are the same rotation, so the judged frames below play back as the clean swing — the findings list is what marks the two defective keys. That is the point: an engine that does not normalize, or that slerps without neighborhood correction, is the one that flickers.

Open the interactive report to scrub the exact keys the checks judged.

What the finding looks like

$ animsmith lint examples/assets/clip-dirty.glb
examples/assets/clip-dirty.glb:
  error[quat-norm] clip 'swing' bone 'spine' @0.500s: non-unit rotation key (worst at key 2) (measured 1.0500, expected 1.0000)
  warning[quat-flip] clip 'swing' bone 'spine' @0.750s: 2 hemisphere flip(s) between adjacent rotation keys (first between keys 2 and 3) — engines without neighborhood correction will spin the long way (measured 2.0000)
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: swing): only 1 usable first-frame rotation track(s); at least three are required
1 error(s), 1 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 1

Both defects are lossless to repair, so this is the one symptom family AnimSmith fixes for you. --dry-run reports the pending repairs and writes nothing:

$ animsmith fix examples/assets/clip-dirty.glb --dry-run
  would fix[quat-norm] clip 'swing' bone 'spine': 1 key(s) unit-normalized
1 key(s) would be fixed across 1 track(s) -> no output written
  would fix[quat-flip] clip 'swing' bone 'spine': 1 key(s) hemisphere-normalized
1 key(s) would be fixed across 1 track(s) -> no output written   # exits 1

$ animsmith fix examples/assets/clip-dirty.glb -o fixed.glb
  fixed[quat-norm] clip 'swing' bone 'spine': 1 key(s) unit-normalized
1 key(s) fixed across 1 track(s) -> fixed.glb
  fixed[quat-flip] clip 'swing' bone 'spine': 1 key(s) hemisphere-normalized
1 key(s) fixed across 1 track(s) -> fixed.glb   # exits 0

$ animsmith lint fixed.glb
fixed.glb:
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: swing): only 1 usable first-frame rotation track(s); at least three are required
0 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 0

What AnimSmith can do

The comparison below is that repair, run by the generator that renders this page: the before side is clip-dirty.glb and the after side is the file animsmith fix wrote from it, not a hand-authored clean copy of the clip. Each side prints its own SHA-256 above the pose, which is what pins the after side to that output — the document records both inputs by content identity and carries no path.

Open the interactive comparison and press play beside the shared phase to run both sides together, or tick Overlay after on before to draw the two skeletons in one pane — the before solid, the after dashed over it.

The findings list is what changed: the non-unit key and the hemisphere flip on the before side, and nothing on the after side. The two pose panels play the same swing, for the reason above — both defects were in the representation, and AnimSmith normalizes every rotation key it samples — which is also why diff reports no measurement moved. No rig role resolves on this three-bone chain, so the trajectory and gait panels report their evidence unavailable: the findings and the two identities are what this comparison has to show.

What to do

1. Non-unit or flipped rotation keys. Run animsmith fix. The repair is byte-surgical: meshes, skins, materials and textures pass through byte-identical, and animsmith diff reports no measurement moved.
2. A NaN or Inf anywhere. There is no safe automatic repair for a value that carries no information. Find the step that produced it — a divide in a constraint, a bad bake, a corrupted transfer — and re-export.
3. Non-monotonic or late key times. Fix the retiming or export range in the DCC. A first key that starts late is its own hazard: the engine clamp-holds an unauthored pose for the gap.

Who fixes it: AnimSmith repairs the representation, and the DCC owns the data. fix closes the two quaternion classes; a non-finite value, a broken timeline or a bad bake goes back to the export that produced it. The gate closes when the repaired copy re-lints clean and its diff against the original shows no measurement moved.

Config

These checks are mechanical: they run on every file with no configuration. Configuration only changes how hard they fail — promote the hemisphere warning for a project whose runtime slerps without neighborhood correction:

[checks.quat-flip]
severity = "error"

The clip is the wrong length or freezes at the end

A limb stops dead a fraction of a second before the rest of the body, or a clip that should be one second long plays a frame short in the engine.

Checks: duration-sanity · fps

Why it happens

A clip's duration is not one number in the file: it is whatever its longest channel reaches, and an engine clamp-holds every channel that ends earlier. A partial export, a slice that dropped one bone's tail keys, or a retiming step that drifted off the frame grid all leave a file that looks valid and plays wrong. The length a clip is supposed to be is project knowledge, so AnimSmith checks the mechanical part always and the declared part only once you pin it.

What AnimSmith measures

The synthetic walk below has one left-ankle rotation channel that stops at 0.75 s while both translation channels run to 1.0 s. The report's judged frame is the moment the short channel starts being held.

Open the interactive report to scrub the frames after the ankle stops.

What the finding looks like

The spread is mechanical, so no configuration is needed to see it:

$ animsmith lint examples/assets/walk-short-channel.glb
examples/assets/walk-short-channel.glb:
  warning[duration-sanity] clip 'walk_short_channel': channels end at different times (0.750s..1.000s) — shorter channels will be clamp-held (measured 0.2500, expected 0.0000)
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: walk_short_channel): only 1 usable first-frame rotation track(s); at least three are required
0 error(s), 1 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 0

The other half of this symptom — a clip whose channels agree but whose length no longer matches the manifest — has no mechanical signature at all. Only a declared duration_s (and fps for the frame grid) turns it into a finding.

What to do

1. Channels ending at different times. The export dropped part of a channel. Re-export the full range; duration-sanity reports the spread, it does not resample the clip.
2. A declared length that is missed. Pin duration_s for the clip and let the check report the measured and expected seconds. The tolerance absorbs harmless exporter rounding, not a wrong authored range.
3. Keys off the frame grid. Declare fps and fix the retiming step that drifted. Unreal, for example, documents that animations with non-whole end frames do not import correctly.
4. When the input is deliberately being edited. animsmith transform --slice cuts a window on the frame grid and retimes it to start at zero, and --hold-extend appends a linear hold of the final pose for charge and block poses. See editing a clip.

Who fixes it: the pipeline. A partial export or a drifted retime is repaired where it was produced — a re-export, or an explicit transform when the cut itself is the intended edit. The gate closes when the clip's channels agree, its declared duration and frame grid are met, and the engine plays the whole range.

Config

[clips.walk_short_channel]
# The authored range. Linting reports a missed pin; it never resamples.
duration_s = { value = 1.0, tolerance = 0.02 }
# The grid the clip was authored on, so `fps` can check that its keys stay
# on that grid and that it spans a whole number of frames.
fps = 32.0

The loop pops

Every time the cycle wraps, the character jumps or hitches for one frame.

Checks: loop-closure · loop-seam-vel · loop-seam-rot · loop-seam · duplicate-loop-endpoint

Why it happens

A looping clip needs the pose and the motion to be continuous across the wrap. An export range that ends a frame early, an unbaked cycle modifier, or copied endpoint keys with mismatched tangents all leave a gap that the engine crosses in a single frame. A pose gap is a visible jump; a velocity gap is a hitch or pulse once per cycle.

What AnimSmith measures

The synthetic walk below was cut a quarter-cycle short. Foot height relative to the hips no longer returns to its first-frame value, so the loop cannot close.

walk.glb is the clean control this fixture was cut from, not a repair of walk-dirty.glb: it is there to show what the closed contract looks like. AnimSmith does not re-author the endpoint pose.

Open the interactive report to scrub the exact frames the checks judged; the findings list on the right jumps the viewer to the seam.

What the finding looks like

$ animsmith --config examples/walk.animsmith.toml lint examples/assets/walk-dirty.glb
examples/assets/walk-dirty.glb:
  error[loop-closure] clip 'walk' bone 'foot_r' @1.000s: loop does not close in position: bone 'foot_r' is 0.1581 m from its first-frame model-space position (cap 0.0100 m) (measured 0.1581, expected 0.0100)
  error[loop-seam] clip 'walk' @1.000s: loop seam pops: wrap discontinuity is 6.82× the neighbouring in-clip step (cap 1.60) — the clip does not close its cycle (measured 6.8152, expected 1.6000)
  error[loop-seam-vel] clip 'walk' bone 'foot_r' @1.000s: loop velocity changes at the seam: bone 'foot_r' differs by 0.7972 m/s between the incoming and outgoing model-space velocities (cap 0.1000 m/s) (measured 0.7972, expected 0.1000)
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: walk): only 0 usable first-frame rotation track(s); at least three are required
3 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 1

The closed cycle passes the same contract. What remains is the fourth, narrower warning: this export repeats frame 0 at the authored endpoint.

$ animsmith --config examples/walk.animsmith.toml lint examples/assets/walk.glb
examples/assets/walk.glb:
  warning[duplicate-loop-endpoint] clip 'walk' @1.000s: declared loop repeats its first pose at the authored endpoint: 1 redundant closing key(s) per track; ...
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: walk): only 0 usable first-frame rotation track(s); at least three are required
0 error(s), 1 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 0

What to do

1. Nonzero position or rotation delta. Fix the export range or the endpoint pose in the DCC, then re-export. AnimSmith does not re-author poses.
2. Zero pose delta, high velocity delta. Match the endpoint tangents on both sides of the seam in the DCC.
3. Only a duplicated final frame. When duplicate-loop-endpoint warns, animsmith transform --drop-duplicate-loop-endpoint turns the clip into an open cycle losslessly. Read the loop contract against loop_endpoint_mode afterwards: loop-closure compares a repeated final sample with frame 0, so an open cycle intentionally does not keep it green.

Who fixes it: the artist, in the DCC. Only a strict redundant endpoint can be removed mechanically; pose, tangent and contact repair is DCC work, and loop policy (which clips loop, how strict the caps are) is a project decision recorded in the config. The gate closes when the declared closure and seam checks pass and the loop plays cleanly in the target engine's graph.

Config

Declare the clip as a loop; the caps below are the defaults, shown so you can tighten or loosen them per project.

[clips.walk]
loop = true

[checks.loop-closure]
max_position_delta_m = 0.01
max_rotation_delta_deg = 1.0

[checks.loop-seam-vel]
max_velocity_delta_mps = 0.1

[checks.loop-seam-rot]
max_angular_velocity_delta_degps = 5.0

The character glides or runs in place

The character slides across the floor without its feet driving the motion, or it pumps its legs and never leaves the spot.

Checks: in-place · root-motion-speed

Why it happens

Exactly one thing should move the character horizontally: the controller, or the clip's own root motion. Both is a glide; neither is running in place. The file cannot tell you which was intended — a treadmill cycle and a travelling cycle are both valid glTF — so this symptom only becomes checkable once the project declares who owns each movement component.

What AnimSmith measures

The two synthetic cycles below are the same walk. One keeps its root under the character; the other carries the hips 1.2 m forward over the same second. The root-path figure is measured from the file, so a declared contract can be held against it.

Open the interactive report to read the measured trajectory beside the finding.

What the finding looks like

Declare that gameplay owns horizontal travel and the baked 1.2 m becomes a glide:

$ animsmith --config examples/walk-travel-in-place.animsmith.toml lint examples/assets/walk-travel.glb
examples/assets/walk-travel.glb:
  error[in-place] clip 'walk_travel': declared in-place but the root travels at 1.20 m/s — the character will glide at runtime (measured 1.2000, expected 0.0000)
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: walk_travel): only 0 usable first-frame rotation track(s); at least three are required
1 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 1

The same file, the same measured 1.2 m/s. Declare that the animation owns the travel and pin the speed the controller was built around, and the finding changes to a stale pin:

$ animsmith --config examples/walk-travel-root-motion.animsmith.toml lint examples/assets/walk-travel.glb
examples/assets/walk-travel.glb:
  error[root-motion-speed] clip 'walk_travel': measured root-motion speed 1.20 m/s disagrees with the declared 1.00 ± 0.10 m/s — playback scaled by this pin will slide or moonwalk (measured 1.2000, expected 1.0000)
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: walk_travel): only 0 usable first-frame rotation track(s); at least three are required
1 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 1

With no declaration at all the same file is silent. The measurement is always available; the contract is what makes it a finding.

What to do

1. Decide ownership per component, once. XZ, Y and yaw are independent. Declare each as "gameplay" (the controller owns it) or "animation" (extracted root motion owns it), and configure the importer and controller to match.
2. Get the ground truth before pinning a speed. Run animsmith measure and read the measured horizontal root speed; a pin copied from a design document is the usual cause of a stale root-motion-speed.
3. Re-export when the file disagrees with the decision. AnimSmith does not convert root motion to in-place motion, and transform --gait-anchor refuses accumulating root translation precisely so it cannot be misused for that.

Who fixes it: gameplay decides ownership and the artist re-exports. AnimSmith reports the disagreement between the declaration and the measurement, and has no automatic movement-policy repair. The gate closes when the declaration and the measurements agree and an engine trial proves exactly one — not zero, not two — movement producer per component.

Config

[rig]
# `in-place` and `root-motion-speed` need a resolvable root; both fall back
# to the hips role when the rig has no dedicated root bone.
profile = "auto"

# A treadmill cycle: the controller owns horizontal travel.
[clips.walk_travel]
movement_owner_xz = "gameplay"

# Or a travelling cycle, pinned to the speed the controller expects:
#
# [clips.walk_travel]
# movement_owner_xz = "animation"
# speed_mps = { value = 1.2, tolerance = 0.1 }

Feet skate when clips blend

Each locomotion clip looks clean on its own, but the moment the runtime crossfades between two of them the feet skate, stutter or pop.

Checks: gait-group · sync-group · time-complement

Why it happens

A directional set — run forward, back, left, right — is blended at runtime, and a blend is only seamless when every member is at the same point in its stride. If one cycle's left foot plants at the top of the loop and another's plants a quarter cycle later, every mix of the two puts the feet somewhere neither clip authored. Nothing in a single clip is wrong; the incompatibility only exists between them, which is why it survives per-clip review.

What AnimSmith measures

The synthetic ring below holds four clips built from one analytic gait, with run_left entered a quarter of the way into that gait. The stride anchor is measured from the left-minus-right foot height relative to the hips, so the shift is visible as the same curve starting at a different point.

The report draws one figure per declared gait group. Every member is on the same normalized source-phase axis and none of them is shifted onto another: aligning them would draw one curve four times and hide the very thing the group is checked for. run_forward, run_backward and run_right share one gait, so their curves coincide and their stride-anchor marks land together at 0.75; run_left runs a quarter cycle earlier and its mark sits at 0.50. The shaded band is the declared 0.15 cap either side of the circular mean of the measured anchors, and run_left is the anchor outside it. No member is nominated as the reference: the check judges the set's spread, so the figure names the members whose anchors fall outside the band and leaves the choice of which one to re-anchor to the project.

Open the interactive report to play the two members together at one phase; the with selector pairs any two members, and both source times are labelled because the pairing is a presentation mapping between two timelines rather than a retime. Enable illustrative blend and move the weight slider to inspect a third pose computed from their sampled local transforms. The source panes keep the judged frames; the third pane is engine-agnostic presentation and adds no measured finding. It does not model your engine's masks, controller, root-motion policy or contact handling. Check the result in the intended runtime; zoom out if an interior pose extends beyond the source-based camera fit.

What the finding looks like

$ animsmith --config examples/run-ring.animsmith.toml lint examples/assets/run-ring.glb
examples/assets/run-ring.glb:
  error[gait-group]: gait group 'run-ring': stride-anchor phases spread by 0.20 cycle (cap 0.15) — directional blends between these clips will skate or pop. Measured: [run_forward=0.75, run_backward=0.75, run_left=0.50, run_right=0.75] (measured 0.1988, expected 0.1500)
  coverage[bind-pose] insufficient_rotation_evidence ×4 (scopes: first_frame_rest_delta; subjects: run_backward, run_forward, run_left, run_right): only 0 usable first-frame rotation track(s); at least three are required
1 error(s), 0 warning(s), 0 note(s), 4 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 1

The finding is group-level, not per-clip: it names the ring, prints every member's measured anchor, and identifies the one that disagrees. Linted without the config the same file is silent — a blend ring is a runtime intent, not something four clips reveal on their own.

What to do

1. Declare the ring before you debug it. [gait_groups.<name>] is what arms the check. Until the set exists in the config, its coherence is unverified rather than verified-clean.
2. Re-anchor an explicitly in-place cycle. animsmith transform --gait-anchor rotates a cyclic clip in time so its stride anchor lands at t=0. Selecting it declares the clip in-place, and it refuses accumulating root translation or yaw.
3. Use runtime phase offsets for root motion. A travelling cycle keeps its trajectory; align the members in the blend graph instead of rewriting the clip.
4. Check the timing surfaces too. [sync_groups.<name>] holds same-time members to a shared duration, frame grid and endpoint convention, and the optional time_complement diagnostic warns when a pair aligns materially better under reflected time.

Who fixes it: the technical animator declares the ring, and the DCC or the blend graph fixes the disagreement. AnimSmith can re-anchor an eligible in-place cycle and nothing else — mask topology, contact events and graph timing are project work. The gate closes when the declared ring lints clean and a playback capture covers the transitions and contacts on the intended character.

Config

[rig]
# The stride anchor is measured from left-minus-right foot height relative to
# the hips, so the group needs hips plus both foot roles.
profile = "auto"

[gait_groups.run-ring]
clips = ["run_forward", "run_backward", "run_left", "run_right"]
# Cycle fraction: members spread wider than this skate or pop when the runtime
# crossfades between them.
max_gait_phase_spread = 0.15
# Members with less left/right alternation than this are excluded as noise.
min_lr_amplitude_m = 0.03

[sync_groups.run-ring]
clips = ["run_forward", "run_backward", "run_left", "run_right"]
max_duration_delta_s = 0.001
max_frame_count_delta = 0
max_fps_delta = 0.01

[sync_groups.run-ring.time_complement]
min_reflected_time_advantage = 0.25
min_lr_amplitude_m = 0.03

Feet slide within a clip

A planted foot drifts along the ground during stance, so the character looks like it is skating.

Checks: foot-slide

Why it happens

During stance the foot must move consistently with the clip's declared travel: at speed_mps relative to the character for an in-place clip, or planted in the world for a root-motion clip. Retargeting, resampling, a wrong speed pin, or hand-keyed contacts break that relationship, and runtime IK and blend band-aids exist to hide the result.

What AnimSmith measures

The synthetic gait below has a left foot that skates during stance. The report samples stance intervals with the run's contact threshold and shades them, so the slide is visible as foot motion inside a shaded interval.

Open the interactive report to scrub the exact frames the checks judged; it opens on the first of the two foot-slide findings. This clip declares a loop and a speed_mps pin, so the gait panel's caption says its curves should end where they began and that the shaded bands are the stance intervals foot-slide judged: a foot that moves horizontally inside its band is the slide.

What the finding looks like

$ animsmith --config examples/report-comparison.animsmith.toml lint examples/assets/report-comparison-before.glb
examples/assets/report-comparison-before.glb:
  error[loop-closure] clip 'acceptance-matrix' bone 'left_foot' @1.000s: loop does not close in position: bone 'left_foot' is 0.4000 m from its first-frame model-space position (cap 0.0100 m) (measured 0.4000, expected 0.0100)
  error[loop-seam-vel] clip 'acceptance-matrix' bone 'left_foot' @1.000s: loop velocity changes at the seam: bone 'left_foot' differs by 1.3416 m/s between the incoming and outgoing model-space velocities (cap 0.1000 m/s) (measured 1.3416, expected 0.1000)
  warning[foot-slide] clip 'acceptance-matrix' bone 'left_foot' @0.250s: left foot skates during stance: speed deviates 0.72 m/s from the expected 1.00 m/s (cap 0.30) — foot plants will slip at runtime (measured 0.7200, expected 0.3000)
  warning[foot-slide] clip 'acceptance-matrix' bone 'right_foot' @1.000s: right foot skates during stance: speed deviates 0.88 m/s from the expected 1.00 m/s (cap 0.30) — foot plants will slip at runtime (measured 0.8800, expected 0.3000)
  note[constant-track] clip 'acceptance-matrix' bone 'hand': rotation track has 5 keys but never moves — export bloat
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: acceptance-matrix): only 1 usable first-frame rotation track(s); at least three are required
2 error(s), 2 warning(s), 1 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 1

What the repair looks like

The after clip below is an authored repair: both sides come from this repository's fixture generator, and the after side is the same gait with those defects repaired. It is not the output of an AnimSmith transform, because AnimSmith does not re-author contacts.

Open the interactive comparison to see the two side by side; press play beside the shared phase to run them together, or tick Overlay after on before to put the two skeletons in one pane. The skeleton and the root path are the same on both sides, so what the panels show is the stance repair.

What AnimSmith itself does here is the measuring and one narrow transform: it reports the slide with the stance intervals it judged, and transform --gait-anchor can rotate an eligible in-place cycle's phase to choose a better stride cut. Anchoring changes which frame the cycle starts on, not how fast a planted foot travels, so it does not repair this finding. Contact cleanup stays DCC work.

What to do

1. Check the speed pin first. Run animsmith measure on the clip and compare the measured horizontal root speed with the declared speed_mps; a stale pin produces a slide finding on a clean clip.
2. Re-author the contacts in the DCC. Plant the stance foot (or move it at the declared speed for an in-place cycle), then re-export and re-lint.
3. Do not paper over it with runtime IK before the source is clean; the check is there so the band-aid stays optional.

Who fixes it: the artist. AnimSmith can report the slide and, for an eligible in-place gait, re-anchor the cycle, but contact cleanup and blend timing are DCC and runtime work. The gate closes when the clip re-lints clean under the declared contract and stance behaves in the actual blend.

Config

[rig]
roles = { root = "root", hips = "hips", left_foot = "left_foot", right_foot = "right_foot" }

[clips.acceptance-matrix]
loop = true
speed_mps = { value = 1.0, tolerance = 0.1 }
movement_owner_xz = "gameplay"

[checks.foot-slide]
contact_height_m = 0.03
max_slide_mps = 0.3

A limb is T-posed, or a bone never moves

One arm hangs out sideways while the rest of the body animates, a socket is missing on the target rig, or the whole character deforms as if it were authored on somebody else's skeleton.

Checks: missing-bones · required-bones · frozen-bone · bind-pose

Why it happens

A bone can fail in four ways that all look alike in the engine: it is absent from the skeleton, it is present but carries no keys, it carries keys that never move it, or it moves relative to a bind pose that was not this rig's. A presence-only check passes the third case, and a motion-only check passes a socket that is meant to be static. What separates them is a declaration: which bones the clip is supposed to animate, and which must simply exist.

What AnimSmith measures

The synthetic walk below is declared to animate both arms. arm_l is keyed at five identical values, and arm_r never reached the file at all. The report plays back the exact frames the checks judged, so the still arm is visible in the pose grid rather than inferred from the message.

Open the interactive report to scrub the cycle and watch the left arm stay where it started; it opens on the frozen-bone finding that names it.

What the finding looks like

$ animsmith --config examples/walk-frozen-arm.animsmith.toml lint examples/assets/walk-frozen-arm.glb
examples/assets/walk-frozen-arm.glb:
  error[missing-bones] clip 'walk_frozen_arm' bone 'arm_r': required bone does not exist in the skeleton
  error[frozen-bone] clip 'walk_frozen_arm' bone 'arm_l': required bone rotates only 0.00° over the clip (floor 1.00°) — frozen/T-posed limb or a wrong-source slice (measured 0.0000, expected 1.0000)
  note[constant-track] clip 'walk_frozen_arm' bone 'arm_l': rotation track has 5 keys but never moves — export bloat
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: walk_frozen_arm): only 1 usable first-frame rotation track(s); at least three are required
2 error(s), 0 warning(s), 1 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 1

Without the declaration only the mechanical note survives. Nothing in the file says the arms were supposed to move, so nothing in the file can be wrong about it:

$ animsmith lint examples/assets/walk-frozen-arm.glb
examples/assets/walk-frozen-arm.glb:
  note[constant-track] clip 'walk_frozen_arm' bone 'arm_l': rotation track has 5 keys but never moves — export bloat
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: walk_frozen_arm): only 1 usable first-frame rotation track(s); at least three are required
0 error(s), 0 warning(s), 1 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 0

What to do

1. Declare what the clip must animate. animates_bones turns a silently static limb into a failing gate. It matches bone names, not rig roles, so it needs no profile.
2. Declare what must merely exist. Sockets, IK targets and mask bones are intentionally static, so they belong in [rig] required_bones rather than in a per-clip motion rule.
3. Missing bone: repair the source rig. AnimSmith does not create bones, rename an export, or retarget a rig. Fix the export skeleton in the DCC and re-export.
4. Keyed but frozen: find the slice that dropped it. A masked-out channel, a wrong-source slice, or a bake that never ran leaves keys that go nowhere.
5. Wide bind deviation: check which rig it was authored against. A clip whose first frame is far from this skeleton's rest pose was almost certainly authored against a different bind and will deform incorrectly when retargeted onto this one.

Who fixes it: the artist repairs the source rig. AnimSmith reports structural absence, declared motion that never happened, and a first frame far from rest; target binding, Avatar/Skeleton setup and masks are engine work. The gate closes when a re-export meets the structural contract and the required bones visibly move on the target character.

Config

# Bones this clip must animate. Both checks match names, not roles.
[clips.walk_frozen_arm]
animates_bones = ["arm_l", "arm_r"]

[rig]
# Bones that must exist even though nothing is expected to move them.
required_bones = ["root", "weapon_socket", "ik_hand_l"]

[checks.frozen-bone]
# Real motion moves required bones tens of degrees; the default floor catches
# a truly static bone without flagging subtle idle sway.
min_rotation_deg = 1.0

Files disagree about skeleton or clip identity

Two deliveries that were supposed to be the same character import as different skeletons, or a report says Take 001 and nobody can tell which of the thirty files in the pack it came from.

Commands: animsmith inspect · animsmith collection lint

Why it happens

Marketplace packs commonly ship one clip per file and reuse an embedded take name such as Take 001 across every one of them, so a clip's display name is not an identifier. Skeletons drift the same way: two exports of "the same" rig can differ in hierarchy or rest signature and stop being exact-skeleton interchangeable. Both are properties of a set of files, and AnimSmith's ordinary checks resolve clips inside one loaded document — so this symptom is answered by retaining identity, not by a check firing.

What AnimSmith measures

There is no chart here, because the evidence is identity rather than motion. inspect reports the exact skeleton and the embedded clip names of one physical file, and a collection manifest binds each (file, clip) pair to a logical id that survives the display name.

The repository's own collection-boundary fixtures are shaped like the marketplace case: walk-a.gltf and walk-b.gltf are distinct physical files with identical bytes and the same embedded name.

$ animsmith inspect crates/animsmith/testdata/collection-spike/source/walk-a.gltf
crates/animsmith/testdata/collection-spike/source/walk-a.gltf
rig profile: none detected
skeleton: 1 bones
  root
materials: 0
mesh instances: 0
clips: 1
  Take 001: 0.000s, 0 tracks, 0 keys max   # exits 0

$ animsmith inspect crates/animsmith/testdata/collection-spike/source/walk-b.gltf
crates/animsmith/testdata/collection-spike/source/walk-b.gltf
rig profile: none detected
skeleton: 1 bones
  root
materials: 0
mesh instances: 0
clips: 1
  Take 001: 0.000s, 0 tracks, 0 keys max   # exits 0

Two files, one name. A third file in the same set carries Take 001 and Take 002, so even the take index is only meaningful together with its file:

$ animsmith inspect crates/animsmith/testdata/collection-spike/source/multi.gltf
crates/animsmith/testdata/collection-spike/source/multi.gltf
rig profile: none detected
skeleton: 1 bones
  root
materials: 0
mesh instances: 0
clips: 2
  Take 001: 0.000s, 0 tracks, 0 keys max
  Take 002: 0.000s, 0 tracks, 0 keys max   # exits 0

What the evidence looks like

A collection manifest is what turns those rows into stable identities: each source keeps its safe locator and expected digest, and each logical clip names the source plus the exact take index and embedded name it came from.

[[sources]]
key = "walk-a"
path = "walk-a.gltf"
config = "fixture.animsmith.toml"
expected_sha256 = "277f55812602cc560dbb432dede43bb145b3caa6cb90493675442a8f5499f044"

[[clips]]
id = "com.example.collection-spike/locomotion/walk-a"
source = "walk-a"
take_index = 0
take_name = "Take 001"

animsmith collection lint runs every declared source and emits that retained binding as machine-readable evidence — the source digest, the config basis, the observed takes, and the runtime sets that cross file boundaries. The fixture set above is the worked example, and collection contracts is the reference.

What to do

1. Record the physical file, not the display name. A runtime-set member must preserve the exact source path plus the embedded clip name and index. Normalized display names are not reproducible identifiers.
2. Reconcile the pack's own list separately. State it as a separate fact when a bundled animation list uses different spelling, casing, or ranges from the files; do not silently rename to make them match.
3. Do not force a skeleton reference. A copied-avatar or skeleton-reference hierarchy mismatch means the referenced mapping is not evidence for that file. Use a compatible individual asset, or obtain an authoritative re-export.
4. Keep retargeting a separate decision. An engine humanoid or retarget profile may still make two hierarchies compatible, but only after every required chain maps and the target character's deformation, transitions, masks, sockets and root ownership pass in the intended runtime.

Who fixes it: the pack owner and the pipeline that ingests it. AnimSmith retains identity and reports what each file actually contains; it does not merge, rename, or infer set membership, and it does not retarget. The gate closes when the recorded source-to-target mapping is complete and the target character plays the intended clips with visual evidence.

Config

Identity lives in the collection manifest rather than in animsmith.toml. Every source keeps its own document-local config, so declaring a set never changes what a single file means:

schema = "urn:animsmith:schema:collection-manifest:1"
schema_version = 1
collection_id = "com.example.collection-spike"
input_root = "source"

[[runtime_sets]]
id = "com.example.collection-spike/sets/cross-file-gait"
kind = "gait-group"
members = [
  "com.example.collection-spike/locomotion/walk-a",
  "com.example.collection-spike/locomotion/walk-b",
]

The file is bloated, or the retargeter chokes

Clips are far larger than the motion in them justifies, a retargeter or importer mangles a character it should handle, or a weapon parented to a socket imports at the wrong size.

Checks: constant-track · scale-keys · non-uniform-scale · rest-world-scale · constant-nonunit-scale

Why it happens

"Key everything" exports and baked control rigs write channels that store hundreds of identical values, and every one of them still costs storage and work in every blend the runtime evaluates. Animated and non-uniform scale come from the same place — a constraint bake, a unit conversion, an unapplied object transform — and are the curves retargeters and physics are least consistent about. None of this is invalid, which is exactly why it accumulates: the file plays, so nobody looks.

What AnimSmith measures

The synthetic walk below stretches its pelvis to 1.2 on Y and back, and carries a five-key weapon_socket translation channel that never moves. The report separates the two facts: temporal scale variation, unequal axes, and redundant data are three different findings about the same file.

Open the interactive report to read the three findings against the frames they were judged at.

What the finding looks like

These checks are mechanical, so they run with no configuration:

$ animsmith lint examples/assets/walk-scaled.glb
examples/assets/walk-scaled.glb:
  warning[scale-keys] clip 'walk_scaled' bone 'pelvis': scale animation present — verify it is intentional; many rigs and retargeters mishandle animated scale
  warning[non-uniform-scale] clip 'walk_scaled' bone 'pelvis' @0.500s: non-uniform scale present — verify it is intentional; many rigs and retargeters mishandle non-uniform scale
  note[constant-track] clip 'walk_scaled' bone 'weapon_socket': translation track has 5 keys but never moves — export bloat
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: walk_scaled): only 0 usable first-frame rotation track(s); at least three are required
0 error(s), 2 warning(s), 1 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 0

The note is the only removable one. transform --prune-constant-tracks names every channel it removes, with its original track index:

$ animsmith transform examples/assets/walk-scaled.glb -o compact.glb --prune-constant-tracks
  constant-track removed 'walk_scaled': track index 3 bone 'weapon_socket' translation Linear 5 key(s)
wrote compact.glb (4 node(s), 1 clip(s), 0 mesh(es) / 0 position(s), 0 material(s))   # exits 0

$ animsmith lint compact.glb
compact.glb:
  warning[scale-keys] clip 'walk_scaled' bone 'pelvis': scale animation present — verify it is intentional; many rigs and retargeters mishandle animated scale
  warning[non-uniform-scale] clip 'walk_scaled' bone 'pelvis' @0.500s: non-uniform scale present — verify it is intentional; many rigs and retargeters mishandle non-uniform scale
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; subjects: walk_scaled): only 0 usable first-frame rotation track(s); at least three are required
0 error(s), 2 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), 0 required-unavailable prediction facet(s)   # exits 0

The two scale warnings survive on purpose. Animated scale is authored content, not bloat, and removing it is not a mechanical decision.

What to do

1. Review transition coverage before pruning. Removing a constant channel keeps that clip's standalone pose but makes its (bone, property) coverage sparse. Leave tracks intact when a runtime transition does not explicitly reset the omitted property.
2. Decide whether the scale motion is intentional. Squash-and-stretch, a visibility trick and a gameplay deformation are all legitimate; a constraint bake, a unit-conversion curve and an unapplied object scale are not. Inspect the curve in the DCC's Graph Editor and remove or rebake only the unwanted channel.
3. Check what a socket actually inherits. A node's local scale is not its effective scale. Declare the attachment nodes your runtime contract cares about in [runtime_nodes] selectors and let rest-world-scale report the inherited factor.
4. Fix the source, then verify the export. Re-export, re-lint, and preview in the target engine; the desired end state is that deliberate scale motion remains and accidental curves are gone.

Who fixes it: the artist or the exporter settings. AnimSmith can remove provably constant multi-key tracks and nothing else — it does not judge a non-rest constant pin, rewrite cubic tangents, flatten skeletal scale into geometry, or decide whether an effect is artistically correct. The gate closes when a source recheck plus the target engine's own scale, attachment and visual observation agree.

Config

# Shared attachment/socket/IK policy. Each exact name or `*` glob must resolve
# to exactly one source node; a miss or multiple matches is a coverage gap.
[runtime_nodes]
selectors = ["weapon_socket", "ik_*_target"]

[checks.rest-world-scale]
expected_uniform_scale = 1.0
uniform_scale_tolerance = 0.0001

# Opt into a unit-scale policy only when the project expects unit scale in
# animation channels.
[checks.constant-nonunit-scale]
severity = "note" # or "warn" / "error" for your project

For artists: from export to handoff

Where you are: Artist export → Contract → Developer intake → CI gate → Engine check

You have exported a clip, or cleaned one up, and somebody downstream has to trust it. This page is the order to do that in: keep the file you exported from, check what you actually shipped, make only the changes a tool can prove, and hand over the evidence with the asset instead of a verbal "it's fine".

It keeps the original immutable, makes mechanical changes reviewable, and leaves artistic approval where it belongs. For the meaning of the stages, start with why AnimSmith and the readiness ladder. When something already looks wrong in the engine, start from the symptoms instead and come back here to hand it off.

Outcome and boundary

AnimSmith can inspect source facts, measure and compare motion, evaluate a declared contract, safely repair two quaternion representations, and perform bounded mechanical transforms. It can also produce an offline HTML report. It does not decide whether a performance, retarget, contact, controller, or visual result is acceptable in a game. A clean lint result is scoped evidence, not a blanket “game-ready” verdict.

Keep these artifacts separate:

The broader storage split and its ownership rationale are in the pipeline guide.

Work the candidate, not the source

The commands below are executable examples. $ANIMSMITH, $ASSET_DIR, $CONFIG_DIR, and $WORK_DIR are placeholders supplied by your checkout or automation: the repository test binds them to the current binary, checked-in self-authored fixtures, committed configs, and a disposable output directory. The first comment gives the command's expected exit status; an exit of 1 can be expected evidence that a candidate materially differs.

1. Inventory the untouched baseline. Run inspect and measure before changing the file. Keep the JSON measurement output with the baseline.

   # workflow-exit: 0
   $ANIMSMITH inspect "$ASSET_DIR/report-comparison-before.glb"
   $ANIMSMITH measure --format json "$ASSET_DIR/report-comparison-before.glb"
   

2. Declare only project facts. Add loop, movement-owner, speed, rig-role, required-bone, and set membership declarations only after the team agrees they are true — who writes what says which of those you can settle alone and which need the game developer. The configuration reference owns every key and precedence rule; the contract-config cookbook is the runnable starting shape.

3. Lint and report the baseline. Treat a finding as a precise work order: its check id, measured value, subject, and coverage state say what was and was not evaluated. The built-in check reference owns the check contracts and the machine-output reference owns the JSON fields. Use the existing self-authored comparison pair when a reviewer needs a judged frame, skeleton, root/foot trails, or charts.

   # workflow-exit: 0
   $ANIMSMITH --config "$CONFIG_DIR/report-comparison.animsmith.toml" report \
       "$ASSET_DIR/report-comparison-before.glb" \
       --compare-after "$ASSET_DIR/report-comparison-after.glb" \
       --before-clip acceptance-matrix --after-clip acceptance-matrix \
       -o "$WORK_DIR/author-comparison.html"
   

4. Choose the right remedy. fix can losslessly normalize finite quaternions and correct quaternion hemisphere continuity. transform can make its explicitly bounded slice, hold, gait-anchor, duplicate-endpoint, or constant-track operation. Use the editing cookbook for those operations. Retargeting, pose/contact cleanup, motion redesign, and an intentional scale change remain DCC work; then export a new candidate. Importer settings and controller behavior remain engine/project work. A source delivery defect or missing contractual clip goes back to the vendor/source owner.

   Handed over: the finding as a work order, and a new candidate export back — the immutable source never moves. That round trip is the mocap cleanup gate.

5. Diff the candidate against the accepted baseline. A binary rewrite is not review evidence. Compare the measured effects and hand off the output with the candidate.

   # workflow-exit: 1
   $ANIMSMITH diff "$ASSET_DIR/report-comparison-before.glb" \
       "$ASSET_DIR/report-comparison-after.glb"
   

6. Hand off exact evidence. Include input identity, committed config, AnimSmith version, command, lint JSON (including coverage gaps), diff, and any generated report. State the remaining engine, gameplay, and visual gates instead of converting unknowns into a pass.

   Handed over: the candidate plus that evidence bundle, to whoever accepts it — the receiving side runs the same contract, which is what outsourced-asset acceptance makes a two-sided gate rather than a request.

When to stop and route

Next step

Use the symptom index for a symptom-first route, or hand the candidate to the game-developer intake workflow for the engine-observed gates.

For game developers: from pack to engine gate

Where you are: Artist export → Contract → Developer intake → CI gate → Engine check

A pack has landed, and somebody has to say whether it can ship in your game. This page is the order to find out in: inventory what the delivery really contains, pin the engine you are judging it against, settle who moves the character, gather the source evidence, and then close the question in the project itself.

It begins with source evidence and ends with an observed engine gate; AnimSmith predictions are useful prerequisites, not engine execution. When one clip already misbehaves, the symptoms pages route it faster than a full intake pass.

Intake path

1. Inventory the actual delivery. Keep source files immutable. Inspect every physical file, record logical clip names separately from file names, and classify the real runtime sets: locomotion rings, transitions, attacks, masked overlays, contacts, and interaction chains. A collection manifest can retain that physical-to-logical binding; see collection contracts.

   Handed over: the untouched delivery, with its licence and vendor metadata, into an immutable raw location — marketplace-pack intake is the sorting pass that follows, and raw vs transformed artifact storage is where each artifact lives.

2. Choose the engine tuple before interpreting an engine check. An engine profile identifies one documented importer boundary. It does not select a skeleton, create a controller, retarget clips, or replace target-engine testing. Use the configuration reference for the profile schema and the maintained engine page for the exact tuple.

3. Make movement ownership explicit. For each locomotion clip, decide whether gameplay/controller code or extracted animation owns XZ, Y, and yaw movement. This is one of the surfaces only your project can settle; who writes what has the rest. Declare that contract, then inspect in-place, root-motion-speed, and any applicable engine prediction. Do not apply extracted root motion and controller movement twice, or omit both.

4. Run source evidence before conversion. lint and report establish file and declared-contract evidence; measure exposes the facts used in a disagreement. The built-in check reference and output reference are canonical for those records. Convert or assemble only when the target boundary needs it, and retain the conversion/assembly evidence beside the derived artifact.

5. Exercise the target project. Load the exact emitted artifact, play each intended clip, test skeleton/retarget mapping, blend/transition timing, masks and contacts, root-motion application, target lookup, and a visual gameplay scene. This is the gate that establishes engine-observed evidence.

   Handed over: the exact emitted artifact and its evidence, to the project that will ship it. Once it is accepted there, every later re-export is judged by CI gating on animation changes against this same contract.

Worked path: Bevy 0.19.0, profile revision 3

The executable examples use the placeholder convention from the animation-author workflow. $FBX_FIXTURE is an authorized self-authored FBX input and $BEVY_CONFIG is the exact TOML fence below, materialized by automation before the command runs.

This path is exact only for bevy / revision 3 / 0.19.0 / gltf-asset-loader. It applies to glTF JSON or GLB, not FBX. Preserve an FBX source, then convert the candidate at the format boundary before applying a Bevy profile:

# workflow-exit: 0
$ANIMSMITH convert "$FBX_FIXTURE" -o "$WORK_DIR/candidate.glb"

The conversion is source-to-GLB evidence, not a Bevy import. Then use the versioned configuration below; it is also committed as examples/bevy-v3.animsmith.toml.

[engine]
profile = "bevy"
profile_revision = 3
engine_version = "0.19.0"
importer = "gltf-asset-loader"

[engine.settings]
extension_handler_environment = "bare_empty"
bevy_animation_feature = true
load_animations = true

Run the source-side gate and generate the neutral addressability inventory:

# workflow-exit: 1
$ANIMSMITH --config "$BEVY_CONFIG" lint \
    --select engine-track-support "$ASSET_DIR/walk.glb" --format json

# workflow-exit: 0
$ANIMSMITH generate addressability "$ASSET_DIR/walk.glb"

The profile's engine-track-support prediction can prove only negative loader gate outcomes from the declared feature/settings and bounded source animation/channel inventory. If both gates allow loading, the correct result is required-unavailable runtime survival: AnimSmith does not run Bevy, read back a Bevy import, or prove that an asset, target, graph, or playback survived. Likewise, addressability records source animation indices and canonical selector evidence; it does not prove a live handle resolves in an application. The Bevy profile guide owns the precise rule and coverage boundary.

Close the Bevy gate in the project that will ship the asset:

• load candidate.glb through the selected application path and record the loaded asset/animation evidence;
• resolve the expected typed selector and verify the target mapping after the project's own scene root, names, and spawned hierarchy are present;
• create and exercise the application-owned AnimationPlayer, graph/state transitions, masks, and reset policy;
• make one explicit decision about each root-motion component, then test it against controller/physics movement so it is neither double-applied nor missing; and
• capture a visual gameplay trial for clip playback, blending, contacts, attachments, and scale.

Those are project-owned runtime and visual gates. Their recorded observations, not a prediction facet, are the evidence that closes them.

Other engine routes

Use the maintained profile page for each narrower route; do not copy settings from a different project or version.

Close the intake decision

Keep four results separate: source mechanics, declared contract, engine observation, and gameplay/artistic acceptance. A pack can be usable for a prototype while a blend, retarget, mask/contact, or visual gate remains open; record the owner and the exact missing evidence. For commercial evidence that already exists, use the commercial-pack evaluation guide instead of treating a report as an approval for a different project.

Declaring the contract: who writes what

Where you are: Artist export → Contract → Developer intake → CI gate → Engine check

animsmith.toml is where a team writes down what a clip is supposed to do. Mechanical checks need none of it — they run on any file. Everything else waits for a declaration: with no loop = true, the seam checks have nothing to judge and record themselves as not applicable, and a check that needs a rig role it cannot resolve reports a typed coverage gap instead of guessing.

So the question this page answers is not what the keys mean — the configuration reference is the exhaustive authority for that — but who is allowed to write each one. Some surfaces are facts of the export and an animator can declare them alone. Some are decisions only the game can make, and an animator who guesses at them writes a contract that fails for the wrong reason. The rest have to be agreed once and then committed beside the assets, like code.

The surfaces, and who owns each

"Owner" is who decides the value, not who types it: the file itself is committed once, reviewed like code, and read by everyone.

Two rules follow from that table. An artist can go a long way alone: a rig profile, loop, fps and animates_bones already arm the checks that catch a popped seam, a short channel and a frozen arm. But movement_owner_*, speed_mps and the blend groups are the game's decisions — declared without the game developer, they measure the clip against a guess.

Nothing is inferred from omission. Leaving loop out does not declare the clip non-cyclic; it declares nothing, and the loop checks stay not applicable. Ownership is the same: each movement axis is independent, and an omitted one is never assumed.

A complete minimal contract

This is examples/walk.animsmith.toml, the committed contract for the sample walk cycle in first lint in 60 seconds — the smallest file that makes the semantic checks fire:

# A runnable contract for the committed `walk.glb` / `walk-dirty.glb`
# example rigs — the smallest config that makes the semantic checks fire.
#
#   animsmith lint --config examples/walk.animsmith.toml examples/assets/walk.glb
#
# See examples/character.animsmith.toml for the full game-character shape
# (locomotion rings, speed pins, per-check overrides).

[rig]
# The rig's bone names (pelvis / foot_l / foot_r) resolve the built-in
# ue-mannequin profile, so "auto" binds hips + feet with no inline map.
profile = "auto"

[clips.walk]
# Declaring the clip as a loop arms role-free per-bone C0/C1 checks plus the
# locomotion-specific feet-relative-to-hips loop-seam check.
loop = true
# Gameplay owns horizontal travel (the clip is a treadmill cycle), so
# `in-place` expects no measured XZ root travel.
movement_owner_xz = "gameplay"
# A per-clip cap can be stricter than a project-wide loop default. Omitted
# dimensions continue to inherit their global caps.
max_loop_rotation_delta_deg = 0.5

[checks.loop-seam]
# Fail a wrap discontinuity more than 1.6× the in-clip stride step.
max_ratio = 1.6

[checks.loop-closure]
# Model-space endpoint pose caps. Inherited root travel may require a larger
# position cap (or disabling this check) for extracted root-motion clips.
max_position_delta_m = 0.01
max_rotation_delta_deg = 1.0

[checks.loop-seam-vel]
# Fail when incoming/outgoing model-space linear velocity differs by >0.1 m/s.
max_velocity_delta_mps = 0.1

[checks.loop-seam-rot]
# Fail when shortest-path model-space angular velocity differs by >5 deg/s.
max_angular_velocity_delta_degps = 5.0

# The same three caps can live in a `[clips."name_*"]` glob. They do not
# configure angular seam velocity, which is outside these overrides.

Run it against the committed clip and the loop checks pass; run it against the same clip cut a quarter-cycle short and they fail with the measured distance. The examples cookbook walks that pair, and examples/character.animsmith.toml grows the same shape to a full character with rings, speed pins and per-check overrides.

Where to go next

The configuration reference owns every key, default, unit and precedence rule; the built-in check reference owns what each declaration arms. When a declaration turns out to be wrong rather than missing, the symptom index routes what you see in the engine to the page that walks it.

Raw asset to game-ready pipeline

Where you are: Artist export → Contract → Developer intake → CI gate → Engine check

Where animsmith fits in an animation asset pipeline.

This guide is the process-level companion to what game-ready means and the examples cookbook. That page defines the readiness ladder and explains why a check fires; the cookbook gives runnable command transcripts. This page shows how teams place those commands in the larger path from raw source animation to engine-facing, reviewable, CI-gated assets.

Which scenario belongs to which handoff

Every handoff the two reader workflows name lands in one of the scenarios below. Start from the row that matches the artifact currently moving:

The common shape:

1. Acquire the source asset.
2. Preserve the raw source and provenance.
3. Parse and inspect the file.
4. Segment long takes into named clips.
5. Decide root-motion policy per clip.
6. Retarget, conform, or clean up in DCC tools.
7. Validate motion semantics.
8. Optimize the exported data.
9. Export engine-facing artifacts.
10. Gate and report changes in CI.

animsmith does not replace DCC work, engine importers, or a team's contract format. It gives the pipeline a repeatable measurement and linting step around them: inspect for inventory, measure for raw numbers, lint for the declared contract, fix for safe repairs, transform for mechanical edits, convert for FBX/glTF handoff, diff for regression checks, and report for review artifacts.

Pipeline map

Bevy animation gate

When the target is Bevy 0.19.0's stock gltf-asset-loader, the current profile revision 3 adds a deliberately narrow gate after source inspection. engine-track-support binds raw animation rows and independent per-animation channel coverage from the same load to the resolved bevy_animation_feature and load_animations settings. The compiled feature gate wins when the two settings disagree. A complete inventory reports only negative dropped-row outcomes; a complete empty inventory is not applicable.

Partial or unavailable inventory reports exactly one subjectless, unsuppressible required-unavailable facet and no retained-prefix prediction, including bounded N+1 overflow. If both gates allow loading, the result is instead required-unavailable runtime-survival evidence: the pipeline must still exercise the actual Bevy application. This slice has no extension/construct coverage, no positive runtime-survival claim, and no content finding for a dropped row. Current output-v19 carries its immutable V5 provenance unchanged; output-v17 and output-v16 remain historical readers, and rev1/rev2 with output-v15 remain preserved for existing consumers.

Shared contract config

Every scenario below becomes much more useful once the team commits an animsmith.toml next to the asset set. The exact tolerances belong to your project, and the config is where the team records facts such as which clips loop, who owns each clip's XZ/Y/yaw movement, what speed a locomotion clip promises, which bones must move, and which clips form a directional blend set. animsmith checks those facts against the measured asset. It records typed, nonblocking coverage gaps when rig roles cannot be resolved, rather than guessing.

Keep the process guide focused on where the contract is used. For the canonical config shape, use the project contract config cookbook, the committed examples/character.animsmith.toml, and the configuration reference.

Cookbook routing

This guide keeps the pipeline shape here and the runnable transcripts in the command-owned references:

Scenario: marketplace-pack intake

Marketplace packs usually arrive as many clips with inconsistent naming, export settings, skeletons, and quality. The intake goal is to sort the pack into "usable now", "needs cleanup", and "reject or replace" before artists build gameplay on top of it — and to record what each verdict is based on.

Intake evidence comes from running animsmith on the actual delivered files. Vendor preview media and partial sample downloads cannot establish raw loop boundaries, complete blend-set compatibility, exact rig and channel behavior, or how a clip will integrate in your runtime. Treat vendor claims as context, keep them distinct from run-backed findings in the intake notes, and preserve open unknowns instead of rounding them to "fine".

Store the downloaded source in a raw, immutable location with its license and vendor metadata. Convert FBX assets into the format your pipeline uses, inspect representative files, measure the pack, then lint the batch before adding stricter project contract expectations. Use the conversion and reporting recipe for conversion and reports, the first CLI gate recipe for inventory and batch linting, and the project contract recipe once clip names and policies settle.

When physical files, repeated take names, and runtime sets are declared in a collection manifest, retain the collection lint JSON and render a local collection dashboard from that exact output. The dashboard is a current-state inventory: it keeps unavailable and incomplete rows visible and can link separately generated offline per-asset reports. Keep those reports and the raw assets outside source control when they contain licensed material. Do not use the dashboard as a quality score or an engine/artistic/gameplay acceptance decision. Its versioned machine authority is urn:animsmith:schema:collection-dashboard:1. Observed physical takes remain visible under their source even when no logical clip declaration binds them; their evidence contributes to the unfiltered summary without creating a logical identity. Source-level findings and subjectless required_prediction_unavailable facets without one exact witness remain counted once at source scope rather than being guessed onto a take or logical clip row.

Record intake as a coverage matrix over the representative files rather than one verdict per file: what was evaluated and clean, what was evaluated and produced findings, and what was not evaluated — because no expectations are declared yet, because a rig role did not resolve (the result carries a typed coverage gap), or because a check was disabled. Not-evaluated cells are neither pass nor fail; they stay visible until the contract grows to cover them or the team accepts them:

Use the first pass to catch obvious importer hazards: non-finite values, quaternion problems, inconsistent durations, scale keys, constant tracks, missing required bones, loop pops, wrong in-place/root-motion policy, and gait-phase drift in blend sets. When a finding requires artistic judgment, treat it as a DCC cleanup ticket instead of trying to auto-fix motion.

Scenario: mocap cleanup gate

Mocap data often moves through capture, solve, cleanup, retarget, slice, and export steps. The risk is subtle drift: the cleaned clip looks better, but a loop seam, stride phase, speed pin, or required-bone motion changed without anyone noticing.

Measure the raw solve before cleanup. Use transform only for mechanical edits such as slicing, hold extension, or gait anchoring, then measure and lint before and after DCC cleanup with the same config. Compare the cleaned output against the pre-cleanup or last accepted revision with diff. Use the first CLI gate recipe for measurement and linting, the editing recipe for mechanical transform work, and the project contract recipe for semantic checks.

diff is the key review step: it catches meaningful changes in the measurements animators and gameplay programmers care about, rather than asking reviewers to compare binary assets or trust a re-export.

Scenario: outsourced-asset acceptance

Outsourced animation acceptance works best when the vendor receives a machine-readable contract instead of a vague "make it game-ready" request. animsmith can be the acceptance gate both sides run locally.

Recommended contract package:

• The target skeleton or rig profile expectations.
• The committed animsmith.toml.
• A naming table for required clips.
• Required source and engine-facing artifact paths.
• The named cookbook recipe or wrapper script the vendor and the receiving team will run.

Use exit codes as the automation boundary:

Exit 0 does not assert that every declared check evaluated. A delivery whose rig the profile cannot resolve records role-dependent work as coverage gaps and still exits 0, so an acceptance gate should also review gaps and the resolved rig roles in the JSON output before accepting. Required-unavailable engine prediction work is distinct from those ordinary gaps: it exits 1 and cannot be suppressed by severity or --allow.

Use the project contract recipe for the shared animsmith.toml, then pair the first CLI gate recipe with the machine-readable output reference for JSON lint output and exit-code gating.

For review, attach the JSON output to the ticket and generate an HTML report for clips with contested findings. The structured output makes it clear whether rejection came from a semantic contract failure such as a popped loop or from a mechanical problem such as bad quaternion keys.

If your acceptance system is already written in Rust, embed the check catalog instead of shelling out. Load with animsmith-gltf or animsmith-fbx, build Config from your own contract format, and map Finding severities to your vendor workflow. The embedding guide shows the API boundary.

Scenario: CI gating on animation changes

CI should answer two questions on every asset change: does the new asset still meet the declared contract, and did any important measurement move?

Run lint on changed clips with the project config, compare changed clips against the previous accepted revision with diff, publish human-readable review artifacts, and gate on process exit rather than by scraping text. Use JSON for automation, Markdown and HTML for humans. Use the first CLI gate recipe for CI lint, the project contract recipe for config-backed checks, the conversion and reporting recipe for report, and the machine-readable output reference for JSON and Markdown outputs.

--deny-warnings is a project policy choice. Many teams start by gating only errors, then promote warnings once the back catalog is clean. Severity overrides in [checks.<id>] let a team make that transition one check at a time without losing visibility.

Scenario: raw vs transformed artifact storage

A reliable pipeline treats raw source and engine-facing outputs as different artifacts with different ownership.

Use this split:

This separation keeps fix and transform honest. Quaternion repairs, frame slicing, hold extension, gait anchoring, and conversion are mechanical steps whose results can be rechecked. Retargeting, pose edits, contact cleanup, and motion redesign remain DCC work, then re-enter the pipeline through measure, lint, and diff.

Where to go next

What game-ready means explains the runtime symptoms behind each check, and the examples cookbook turns the stages above into runnable commands. Everything else — embedding, the JSON envelope, the dated source research behind this process model — is routed from the all pages.

Engine profiles

• Unity 6000.3 profile guide — Configure the exact Unity Generic/Humanoid profiles, importer advice, root-motion choices, and scale boundary.
• Unreal Engine 5.8 profile guide — Map FBX animation, Skeleton, frame, unit, root-motion, and scale concerns to AnimSmith evidence without inventing importer settings.
• Godot 4.7 profile guide — Plan scene import, retargeting, animation slicing, root scale, and the current profile's explicit prediction boundary.
• Bevy 0.19.0 profile guide — Generate exact Animation{i} selector evidence and keep runtime loading, graph, target, and scale responsibilities explicit.
• glTF and generic runtime guide — Use the engine-neutral contract for custom runtimes, glTF units, source identity, scale repair, and downstream validation.

Unity 6000.3 animation profile

Use this page when FBX animation will be imported by Unity 6.3 LTS. AnimSmith has a current Unity Generic root-motion profile plus the preserved Humanoid profile:

These are importer contracts, not claims that every Unity 6000.3 project uses the same rig, controller, physics setup, or root-motion policy. Both accept FBX only. Revision 2 is the exact Generic contract used by the engine-root-motion prediction; revision 1 remains readable for historical advice artifacts. An engine profile never changes AnimSmith measurements.

What Unity expects

Unity's Rig tab maps a Generic rig through a chosen root node and a Humanoid rig through an Avatar. Its Animation tab defines clip ranges, loops, and whether rotation, vertical position, and XZ position are baked into the pose or extracted as root motion. A clean source therefore still needs an intentional rig type, Avatar/root selection, clip cuts, movement ownership, and controller setup.

The Model tab documents three separate scale influences: source-file scale, Scale Factor, and Transform scale. The preserved revision-1 advice profile models Convert Units and Bake Axis Conversion; Generic revision 2 deliberately does not claim either setting. It models only the closed animation/root-motion controls listed below, not Scale Factor, Avatar construction, or the imported hierarchy that Unity ultimately creates.

AnimSmith checks and thresholds

The ordinary mechanical and contract-aware catalog runs unchanged under either Unity profile. The most importer-sensitive rows are:

The current Unity-only check is engine-root-motion, and it is applicable only for the exact Generic revision-2 tuple, an FBX source, and declared movement ownership. engine-addressability remains a Bevy-only rule. The separate generate import-advice contract still projects only settings declared under the historical revision-1 Unity advice profile.

The ownership line is explicit: #267 provides the parent/rest-world/bind scale measurements, #268 provides the selected-node rest-world-scale finding, and #155 provides the Unity importer suggestion document. Static placement baking (#224) and skinned rest/bind reparameterization (#269) are different repair domains.

Configure the exact importer contract

Every applicable revision-2 setting is required; the profile does not invent a default. The exact Generic root-motion tuple is:

[engine]
profile = "unity-generic"
profile_revision = 2
engine_version = "6000.3"
importer = "fbx-model-importer"

[engine.settings]
animation_type = "generic"
avatar_setup = "create_from_this_model"
import_animation = true
root_motion_source = "Reference/Root"

[clips."*".engine_settings]
root_rotation = "extract"
root_position_y = "bake"
root_position_xz = "extract"

[runtime_nodes]
selectors = ["weapon_socket", "ik_*_target"]

[checks.rest-world-scale]
expected_uniform_scale = 1.0
uniform_scale_tolerance = 0.0001

For Humanoid, select the preserved unity-humanoid revision-1 profile and omit root_motion_source; that setting is not applicable to the Humanoid profile. Generic revision 2 freezes animation_type = "generic", avatar_setup = "create_from_this_model", and import_animation = true; other values are rejected. The three clip-scoped bake or extract choices are required for every actual Generic clip. The example above is a prediction configuration, not a Unity project file.

Root-motion prediction

engine-root-motion compares one declared movement owner with one materialized Unity clip setting for each declared axis: horizontal_xz uses root_position_xz, vertical_y uses root_position_y, and yaw uses root_rotation. bake means baked_into_pose; extract means stored_as_root_motion. Gameplay ownership is compatible with baking, while animation ownership is compatible with extraction. A conflict is an ordinary error finding with a prediction_scope, not a rewritten measurement or an automatic fix.

The check's lifecycle is explicit. A selected, enabled, applicable check emits one available facet per clip/axis when all evidence is present. Its machine result is RootMotionRouting with project_owner, importer_disposition, and compatibility. A clip with no declared axis is not applicable for that axis. Missing raw-path coverage, incomplete project intent, duplicate/overflowed settings, a missing or ambiguous source path, a path that does not identify the resolved Root role, or unavailable axis-specific trajectory evidence emits a required_prediction_unavailable facet instead. Required-unavailable work is not a content finding, cannot be suppressed with --allow, makes the check not_evaluated when all work is unavailable (or partial when mixed), and makes lint exit 1.

Project-intent construction is bounded at each retained source/declaration prefix plus one overflow witness. An unmapped declaration tail is therefore not silently treated as ownerless: NPlusOne intent work makes the exact profile unavailable and produces one atomic summary. A complete, exhaustively observed source/intent inventory with no declared owner remains genuinely not applicable; path evidence is required once declared work exists.

The source path must resolve to the explicitly resolved Root role. This rule does not use the consumer-neutral Hips fallback: a resolved Hips role cannot stand in for a missing Root. Root trajectory measurements may be unavailable for an individual axis, but their numeric magnitude is never an applicability or routing threshold. A zero-travel clip and a travelling clip use the same ownership/setting comparison when their required measurement availability is measured.

Closed raw FBX path evidence

root_motion_source is a case-sensitive, byte-exact relative transform path. The V1 grammar uses / as its only separator and has no escaping or Unicode normalization. Paths must have nonempty segments; leading/trailing /, //, . and .. segments, backslashes, control or Unicode format characters are rejected. A segment is at most 1,024 UTF-8 bytes, a complete path at most 4,096 bytes, and a path at most 256 segments.

The FBX loader projects this path inventory from the same input bytes through a raw-preserving ufbx load. Original source node identities, parent chains, and names are retained; the implicit ufbx root and generated geometry/scale helper nodes remain evidence but cannot satisfy a configured path. Complete coverage is required to prove NoMatch; incomplete or unavailable coverage produces CoverageIncomplete, never a guessed absence. This is raw-source evidence, not a claim that Unity executed the import.

Generate the bounded advice document with the historical advice profile using:

animsmith --config unity.animsmith.toml generate import-advice character.fbx

The result maps the declared values to Unity importer properties. It does not assert that Unity imported successfully or that the imported motion matches the source visually. The root-motion prediction likewise performs no Unity editor execution, imported-asset readback, runtime playback, or engine certification. Repository and CI evidence for this slice uses only self-authored synthetic FBX fixtures; commercial animation packs are not fixtures or uploaded artifacts.

Common failures and fixes

Scale and unit workflow

Unity documents one imported world unit as one metre for its physics-oriented scale convention. That does not mean every file should be multiplied until its root Transform reads one: source units, importer conversion, and inherited bone scale are separate domains. An inherited bone scale also multiplies descendant socket, attachment, IK, and collision-anchor offsets, authored animation translations, and measured root travel.

• If every represented length is wrong, use DCC unit correction or the supported glTF/GLB scale whole-document operation before producing the Unity FBX. FBX whole-document scaling is not supported.
• If world geometry is already correct but one skinned hierarchy carries a compensating uniform scale, use the explicit scale rest-bind design. FBX input is re-encoded to a proved GLB, so a downstream FBX requirement still needs a deliberate DCC/export step.
• convert --bake-static-mesh-transforms is for static, unskinned placement. It is not a substitute for skinned rest/bind reparameterization.

Before: a hand socket inherits scale 0.01, so a unit-sized prop or IK offset is scaled unexpectedly. After a successful rest/bind operation: the measured world geometry and joint trajectories are preserved while the selected hierarchy is reparameterized to the declared factor. Still verify Avatar mapping, attachments, collision anchors, root motion, compression, blending, and a player build in Unity. See Scaling safely for the exact write set and proof boundary.

Unreal Engine 5.8 animation profile

Use this page for the exact AnimSmith tuple unreal / revision 1 / 5.8 / fbx-importer. V1 accepts FBX only.

What Unreal expects

Unreal imports skeletal motion as Animation Sequence assets tied to a Skeleton. The FBX animation pipeline documents FBX 2020.2 and requires an existing compatible Skeleton for an animation-only import. The Animation Sequences guide also documents frame ranges, sample rates, custom attributes, bone-name and hierarchy matching, and the requirement that animation end frames be whole.

The frozen profile knows that Unreal uses a left-handed, Z-up basis with +X forward and a centimetre distance unit. It also knows that the importer exposes unit and axis conversion controls. Those facts do not prove the exact imported hierarchy, conversion result, or runtime root-motion policy.

AnimSmith checks and thresholds

The normal check catalog is engine-neutral. Prioritize:

For the frozen Unreal revision 1 / 5.8 / fbx-importer profile, engine-clip-boundary evaluates each retained FBX animation stack against the documented whole-end-frame requirement. The FBX adapter retains the parser-resolved absolute KTime end coordinate and exact frame period; the format-neutral core records that evidence without converting it through seconds or decimal FPS. A complete selected range whose end coordinate is off that integer lattice is a finding. Missing, partial, or unavailable timing evidence is a required-unavailable facet, never a guessed frame number. This bounded check does not predict Animation Length, Frame Import Range, resampling, compression, root-motion, or any other Unreal import setting.

engine-addressability remains Bevy-only.

Scale evidence and policy stay separated: #267 owns the measured scale domains and #268 owns the selected-node finding. The #155 advice contract reports an honest refusal for this profile. Static placement baking #224 does not replace the skinned rest/bind design #269.

Configure the profile

[engine]
profile = "unreal"
profile_revision = 1
engine_version = "5.8"
importer = "fbx-importer"

[clips."locomotion_*"]
loop = true
movement_owner_xz = "animation"
max_loop_position_delta_m = 0.01
max_loop_rotation_delta_deg = 1.0

Unreal revision 1 has no materialized setting vocabulary. Supplying [engine.settings] or clip engine settings is an error. generate import-advice returns the typed profile_settings_unmodeled refusal rather than inventing Convert Scene Unit, frame ranges, sample rates, or root-motion settings.

Revision 2 import advice

The exact revision-2 advice tuple is unreal / 2 / 5.8 / fbx-importer. It accepts FBX only and has one required document setting. There is no safe profile default, so the setting must be explicit:

[engine]
profile = "unreal"
profile_revision = 2
engine_version = "5.8"
importer = "fbx-importer"

[engine.settings]
sample_rate = "default_30"       # or "source_determined"
# sample_rate = "custom_hz(60)"   # 1..48000

The closed sample-rate domain is default_30, source_determined, or custom_hz(n) with n from 1 through 48,000. The unreal_fbx_import_data projection in urn:animsmith:schema:engine-import-advice:2 projection emits bUseDefaultSampleRate=true for default_30; the other two forms emit false and a CustomSampleRate value (0 for source_determined, otherwise the explicit hertz). No frame range, unit conversion, skeleton, compression, root-motion, or runtime result is inferred. The advice is a same-load projection of the declared setting, not an Unreal import execution or certification.

Common failures and fixes

Scale and unit workflow

Unreal's units guide uses centimetres for distance by default, while AnimSmith measurements are normalized to metres. Compare physical quantities, not the raw number printed in two different unit systems. The FBX import option Convert Scene Unit converts source units to centimetres. Inherited bone scale also multiplies descendant sockets, attachments, IK and collision anchors, animation translations, and root-motion distance.

Use scale whole-document only for self-contained glTF/GLB whose entire represented length domain is wrong. Use scale rest-bind when world geometry is correct but a selected skinned hierarchy carries a compensating uniform scale; narrow FBX rest/bind produces GLB. Use static transform baking only for unskinned placement. None of these operations chooses Unreal Skeleton, retarget, root-motion extraction, socket, IK, collision, or compression policy.

Before: a weapon socket inherits 100 while the mesh is visually compensated. After rest/bind: the proved world geometry and trajectories are unchanged and the selected hierarchy is canonicalized. Unreal import, socket attachment, physics asset, root motion, retargeting, and runtime playback still require engine validation. See Scaling safely.

Godot 4.7 animation profile

Use this page for godot / revision 1 / 4.7 / resource-importer-scene. The frozen profile accepts glTF JSON, GLB, and FBX. That is AnimSmith's evidence boundary, not a complete list of formats Godot can import.

What Godot expects

Godot's scene importer turns a source scene into Godot nodes and resources. Its advanced settings can slice animation timelines, optimize tracks, save animations externally, and configure subresources. Retargeting 3D skeletons depends on a BoneMap, compatible hierarchy, and aligned rest poses; matching bone names alone is not enough.

Godot documents a right-handed, Y-up, metre-oriented 3D convention. Its nodes/root_scale defaults to 1.0; nodes/apply_root_scale decides whether that value is applied into descendants, meshes, animations, and bones or left on the root node. AnimSmith revision 1 does not model either setting or predict the resulting imported hierarchy.

AnimSmith checks and thresholds

All ordinary checks remain engine-neutral. The most relevant are:

engine-addressability is Bevy-only. Godot has no engine-specific prediction check in V1.

The measured parent/rest-world/bind domains come from #267, while #268 owns the selected-node finding. The #155 advice contract refuses rather than inventing Godot settings. Static placement baking #224 and the skinned rest/bind design #269 solve different transform problems.

Configure the profile

[engine]
profile = "godot"
profile_revision = 1
engine_version = "4.7"
importer = "resource-importer-scene"

[runtime_nodes]
selectors = ["weapon_socket", "ik_*_target"]

[checks.rest-world-scale]
expected_uniform_scale = 1.0
uniform_scale_tolerance = 0.0001

Godot revision 1 has no setting descriptors. Any engine setting is rejected, and generate import-advice emits profile_settings_unmodeled. Configure timeline slices, root scale, animation optimization, external animation files, BoneMap, and root-motion behavior in Godot or the source DCC.

Revision 2 import advice

The exact revision-2 advice tuple is godot / 2 / 4.7 / resource-importer-scene. It accepts only glTF JSON and GLB for this document-level projection. The closed document setting vocabulary is:

[engine]
profile = "godot"
profile_revision = 2
engine_version = "4.7"
importer = "resource-importer-scene"

[engine.settings]
animation_fps = 30       # positive integer; 1..120
animation_trimming = false

animation_fps defaults to the verified profile value 30 when omitted and animation_trimming defaults to false; explicit values retain their explicit_config origin in the advice. The JSON prediction projects exactly animation/fps and animation/trimming under the godot_params projection kind in urn:animsmith:schema:engine-import-advice:2. It does not emit root scale, optimization, external-animation, BoneMap, timeline-slice, or runtime playback conclusions. Values are proposed importer parameters derived from same-load evidence, not a Godot import execution or certification.

Common failures and fixes

Scale and unit workflow

Godot's 3D introduction states that 3D uses metres and recommends authoring at the correct scale because post-import scaling can create precision problems. Keep three decisions separate:

• Whole-file unit correction changes every represented length and is supported by scale whole-document only for self-contained glTF/GLB.
• Skinned rest/bind reparameterization preserves world geometry while removing one declared compensating hierarchy scale; glTF/GLB and the narrow FBX-to-GLB path are supported.
• nodes/root_scale is a Godot importer choice. AnimSmith does not emit it.

An inherited bone scale multiplies descendant sockets, attachments, IK and collision anchors, animation translations, and root-motion distance no matter which layer introduced the compensation.

Static transform baking fixes only supported unskinned placement. It cannot repair a Skeleton3D/BoneMap contract. After any source rewrite, retest attachments, IK, collision shapes, retarget pose, root motion, animation slices, and runtime playback in Godot. See Scaling safely.

Bevy 0.19.0 animation profile

Use this page for the exact bevy / 0.19.0 / gltf-asset-loader profiles. Revision 1 owns animation-label addressability. Revision 2 owns the unit/effective-scale prediction substrate and its version-pinned load settings. Revision 3 is the current slice for animation/channel gate support and the separately versioned rich addressability-rule bundle. All three accept glTF JSON and GLB only; none applies to a later Bevy release.

What Bevy expects

Bevy loads glTF subassets through typed labels. In 0.19.0, GltfAssetLabel::Animation(index) formats as Animation{index}. An animation name is separate optional metadata, not part of that typed selector. Runtime playback still requires the relevant animation feature/settings, loaded assets, an AnimationPlayer, targets, and an animation graph or equivalent application setup.

The frozen profile also records that animation target ids are derived from name paths. Revision 3's separately versioned rich addressability bundle emits bounded predictions for those paths, named-map winners, scene/skin labels, and the optional default-scene route. It does not emit graph templates, extension support, or proof that a runtime asset exists.

AnimSmith checks and thresholds

The rest of the check catalog is unchanged by the profile.

For scale, #267 owns the measurement domains and #268 owns the selected-node finding. The #155 import-advice work has no Bevy payload. Static placement baking #224 and skinned rest/bind reparameterization #269 remain separate from selector generation.

Configure and generate selectors

[engine]
profile = "bevy"
profile_revision = 1
engine_version = "0.19.0"
importer = "gltf-asset-loader"

[runtime_nodes]
selectors = ["weapon_socket", "ik_*_target"]

[checks.rest-world-scale]
expected_uniform_scale = 1.0
uniform_scale_tolerance = 0.0001

animsmith --config bevy.animsmith.toml lint --select engine-addressability character.glb
animsmith --config bevy.animsmith.toml generate addressability character.glb

The standalone addressability inventory retains source animation/channel indices, optional names, raw targets/accessors, and dependency closure. The optional Bevy section uses the same existing check. Named, unnamed, and duplicate-named animations remain distinct because source index is the authority. The selector can change when animation array order changes.

Bevy revision 1 has no settings vocabulary, so [engine.settings] and clip engine settings are invalid. generate import-advice is not a Bevy settings generator.

For unit/effective-scale prediction, select revision 2 and declare the two required environment facts. Defaults are retained with their origin; list them explicitly only when the load differs:

[engine]
profile = "bevy"
profile_revision = 2
engine_version = "0.19.0"
importer = "gltf-asset-loader"

[engine.settings]
extension_handler_environment = "bare_empty" # or "bevy_pbr_stock_0_19"
bevy_animation_feature = true
rotate_scene_entity = false # default
rotate_meshes = false       # default
load_meshes = "nonempty"    # default; or "empty"
load_animations = true      # default

[runtime_nodes]
selectors = ["weapon_socket", "ik_*_target"]

animsmith --config examples/bevy-v2.animsmith.toml lint \
  --select engine-unit-scale character.glb --format json

The handler environment is closed to an empty registry or exactly Bevy 0.19's stock PBR handler. Arbitrary application handlers are not approximated. With load_meshes = "empty", the rule reports each otherwise-created primitive child as suppressed while retaining the source-node entity semantics.

Revision 3: animation/channel gate support

Revision 3 preserves the revision-2 Bevy tuple and adds the narrow engine-track-support check. The only new settings are the document-scoped bevy_animation_feature and load_animations, each recorded with its explicit/default origin:

[engine]
profile = "bevy"
profile_revision = 3
engine_version = "0.19.0"
importer = "gltf-asset-loader"

[engine.settings]
extension_handler_environment = "bare_empty" # or "bevy_pbr_stock_0_19"
bevy_animation_feature = true
load_animations = true

The compiled bevy_animation feature gate has precedence over load_animations. A disabled feature gate therefore predicts a negative drop even when load_animations = true; with the feature enabled, a false load_animations setting predicts the corresponding loader drop. These are negative importer outcomes, not content findings. If both gates allow loading, the result is a stable required-unavailable runtime-survival state because AnimSmith does not execute Bevy or inspect its runtime asset.

The rule inventories raw source animation rows and independent per-animation channel rows from the same load. Complete-empty source animation inventory is not applicable. Partial or unavailable animation/channel coverage emits exactly one subjectless, unsuppressible inventory required_prediction_unavailable facet and no retained-prefix prediction; bounded N+1 evidence is therefore distinguishable from a complete result. Extensions, unsupported constructs, target survival, graph wiring, and other positive runtime claims remain outside revision 3. Current output-v19 carries its immutable V5 provenance unchanged; the output-v17 and output-v16 readers and the revision-2/V4 output-v15 reader remain preserved.

Revision 3 rich addressability

The rich standalone contract is the immutable urn:animsmith:schema:gltf-addressability:2; see gltf-addressability-v2.schema.json. It is selected only for the exact revision-3 tuple and preserves the V1 gltf-animation-addressability:1 inventory as a nested animation domain. The adapter runs one engine-addressability evaluation and does not create a second lifecycle.

The separately versioned authority pins Bevy tag v0.19.0, commit c6f634ca9f406d68ba5109d921247b654cb42c10, bevy_gltf 0.19.0, locked gltf 1.4.1, and the label, loader, node-path, AnimationTargetId, feature, and root Cargo.lock sources. The isolated readback probe's committed lock is the graph authority: every Bevy 0.19 release crate in that lock is 0.19.0 (independently-versioned helpers such as bevy_mikktspace retain their own version); its lock guard rejects internal Bevy patch drift. It requires explicit target pointer width (bits32 or bits64) because Bevy hashes path segment lengths using the target pointer width; AnimSmith never uses the host width. Missing bevy_animation or disabled load_animations is typed unavailable, not runtime success.

Scene{i} is emitted for every declared source scene. Gltf.default_scene is only a route to the selected existing Scene{i}: there is no DefaultScene label and no fabricated Scene0. Every source skin eagerly gets Skin{i}/InverseBindMatrices, including unreferenced skins, with Bevy's identity fallback when inverse-bind data is absent. Skin{i} is created when any source node references it during the all-source-node construction pass; source skin indices, never collected-vector position, are authoritative. Explicit skin.skeleton remains source evidence only because Bevy ignores it; scene-instantiated SkinnedMesh attachment is outside this static slice.

Named scene/animation/skin maps are separate from typed labels and are source-order last-write-wins; skin winners follow lazily created skins in first-reference order. Target rows are per unique source animation target node with contributing animation/channel identities. Authored names or GltfNode{source_index} fallbacks form the path, excluding the scene world-root. A target path/UUID is published only when complete hierarchy, reachability, closure, feature/settings, and collision evidence exists.

The report carries an independent target_coverage projection alongside the retained target rows. It is complete when the unique-target domain is exhaustively represented by complete raw node/scene/path and animation/channel evidence, including an empty domain; incomplete evidence makes it required_unavailable. It also becomes required_unavailable with target_domain_truncated when more than 4,096 targets exist, or with projection_bounds_exceeded when a new rich projection exceeds its aggregate structural/text budget.

Each new rich projection scene/node/skin/attachment/path/target/map domain is capped at 4,096 rows, with aggregate projection structural references at 65,536 and dynamic projection text at 1 MiB. The sealed V1 animation inventory and CheckEvaluation scopes retain their own bounds. One name/path segment is capped at 1,024 UTF-8 bytes, a path at 4,096 bytes and 256 segments, and a report at 256 MiB. The explicit target-coverage projection reports target_domain_truncated at the target row ceiling and projection_bounds_exceeded for other rich-projection budget exhaustion; readback rejects N+1 collections and contradictory states. This is prediction evidence only and does not certify Bevy loading, spawning, target survival, graph wiring, or playback.

If the shared check's core per-file facet budget would be exceeded, V2 exposes one subjectless engine-addressability:facet-budget scope with facet_budget_exceeded rather than a misleading retained-facet prefix. This is compaction within the same check lifecycle, not an additional check.

Common failures and fixes

Scale and unit workflow

glTF defines all linear distances in metres. Revision 2 proves that one glTF metre-valued length reaches one Bevy world-space length unit with no loader scale conversion; it deliberately does not claim a universal application, physics, or gameplay metre convention. Treat the format mapping and the application's world convention as two separate authorities. Inherited scale still multiplies descendant attachment, IK, and collision offsets, authored animation translations, and root travel in the composed transform hierarchy.

Use scale whole-document only when every represented glTF length is wrong. Use scale rest-bind when geometry is already correct and one skinned hierarchy carries a declared compensating uniform scale. Use static transform baking only for unskinned placement. None of these operations proves Bevy scene spawning, target-id paths, attachment behavior, physics/collision scale, root motion, animation-graph wiring, or visual playback.

Before: a selected weapon node has a world affine classification that includes uniform factor 0.01. After rest/bind: AnimSmith proves preserved geometry and joint trajectories under the reparameterized hierarchy. Then load the emitted asset in the exact Bevy application, validate the caller-owned WorldAssetRoot and ancestors that are outside importer output, resolve the typed label, attach the prop, and exercise the graph and physics setup. See Scaling safely.

glTF and generic runtime profile

Use this page when glTF/GLB is consumed by a custom runtime or when no frozen engine tuple matches the actual consumer. This is intentionally not a sixth V1 engine profile. Leave [engine] absent and use AnimSmith's engine-neutral measurements, checks, transforms, and evidence.

What the format guarantees

The glTF 2.0 specification defines a right-handed, Y-up coordinate system and metres for linear distances. Animation sampler input is time in seconds and must be finite, non-negative, and strictly increasing; channels target node translation, rotation, scale, or morph weights. Names are optional and not guaranteed unique. The runtime still chooses scene selection, asset addressability, graph/controller behavior, root-motion extraction, blending, events, masks, physics, and error handling.

AnimSmith checks and thresholds

No engine-specific check applies without a profile. The engine-neutral catalog still provides exact source contracts:

Use the complete check catalog for structural rig, duration, FPS, gait, sync, foot-slide, and bind-pose contracts. Do not select engine-addressability; it is defined only for the exact Bevy tuple.

The scale-domain measurements are the engine-neutral output of #267, and the selected-node policy is #268. The profile-specific advice work in #155 does not invent a generic importer. Static placement baking #224 and skinned rest/bind reparameterization #269 remain distinct repair contracts.

Configure the runtime contract

Declare only what the project actually knows:

[rig]
profile = "humanoid"

[runtime_nodes]
selectors = ["weapon_socket", "ik_*_target"]

[checks.rest-world-scale]
expected_uniform_scale = 1.0
uniform_scale_tolerance = 0.0001

[clips."locomotion_*"]
loop = true
movement_owner_xz = "gameplay"
speed_mps = { value = 3.0, tolerance = 0.2 }

There is no fallback or nearest engine profile. Adding a made-up [engine] tuple is an operator error, not a way to label a custom runtime.

Common failures and fixes

Scale and unit workflow

If an exporter wrote centimetre-valued numbers into a format that defines metres, the whole asset is physically wrong: a factor 0.01 whole-document conversion is the relevant operation when the supported-source boundary is met. If the mesh is already the correct world size but a skeleton root carries 0.01 with compensating descendants, whole-document conversion is wrong; use the explicit rest/bind operation instead. That inherited scale also multiplies descendant socket, attachment, IK, and collision-anchor offsets, animation translations, and root-motion distance.

Static transform baking moves supported unskinned placement into geometry. It does not repair a skinned hierarchy. Rest/bind reparameterization covers the accepted skinned design and preserves its stated world-space invariants. The runtime still owns sockets, attachments, IK, collision anchors, root motion, graph behavior, extensions, rendering, physics, and visual acceptance. See Scaling safely and the static asset workflow.

animsmith examples

A cookbook of runnable workflows. Each section is a self-contained task you can copy into your own project — several double as CI/acceptance gates. Each workflow addresses a runtime failure described in what game-ready means, which explains why the checks behind these commands exist. For the larger process that turns raw source assets into engine-facing outputs, see the pipeline scenario guide.

Commands that reference examples/assets/ run against small assets committed there, so you can follow along from a source checkout with no downloads; the assets are procedurally generated (see their README for provenance and how to regenerate them). The conversion and reporting section operates on assets you supply, using placeholder filenames — export.fbx, old.glb — for your own exports and baselines.

For complete contract semantics, see the configuration reference.

Console transcripts are real command output, with long finding messages elided as .... JSON envelopes are abridged illustrative projections with placeholder digests, byte counts, and build provenance; capture those identity fields from your own run. Exit-code annotations remain # comments.

Running the commands

Examples use the installed CLI form, animsmith <command>. From a source checkout, prefix each command with cargo run -p animsmith --:

animsmith lint examples/assets/clip.glb
cargo run -p animsmith -- lint examples/assets/clip.glb   # source checkout

Two examples need the default build's feature-gated commands (report, convert); they are marked default features only. Everything else works in the pure-Rust --no-default-features build too.

Exit codes

Every example relies on the same convention, so scripts can gate on it:

1. A first CLI gate

When a clip enters CI, the first question is not just whether the file parses — it is whether the motion is safe to ship. A gate built from inspect, measure, and lint catches the gap described in a valid file is not a usable clip: valid containers can still hide content problems that only show up after import, bake, or playtest. inspect summarizes structure; measure reports metrics without judgment; lint runs the checks and sets the exit code.

$ animsmith inspect examples/assets/clip.glb
examples/assets/clip.glb
rig profile: none detected
skeleton: 3 bones
  root
    spine
      chest
materials: 0
mesh instances: 0
clips: 1
  swing: 1.000s, 1 tracks, 5 keys max

$ animsmith lint examples/assets/clip.glb
examples/assets/clip.glb:
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; ...
0 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), ...   # exits 0

A defective asset produces findings and a non-zero exit:

$ animsmith lint examples/assets/clip-dirty.glb
examples/assets/clip-dirty.glb:
  error[quat-norm] clip 'swing' bone 'spine' @0.500s: non-unit rotation key ...
  warning[quat-flip] clip 'swing' bone 'spine' @0.750s: 2 hemisphere flip(s) ...
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; ...
1 error(s), 1 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), ...   # exits 1

Warnings alone keep the exit code at 0. Use --deny-warnings when CI should fail on warnings too:

$ animsmith lint --deny-warnings examples/assets/clip-dirty.glb   # exits 1

For machine consumption, --format json emits the current v19 result envelope (see output.md). This jq projection keeps the example short while showing where retained/promotion evidence, content findings, and independently versioned measurement evidence live:

$ animsmith lint --format json examples/assets/clip-dirty.glb | jq \
    '{schema_version, schema, command,
      prediction_facets: .summary.prediction_facets,
      prediction_provenance: .files[0].prediction_provenance,
      input: .files[0].input,
      check: (.files[0].checks[] | select(.check_id == "quat-norm") |
        {check_id, selection, configuration, applicability, evaluation, findings}),
      measurements: (.files[0].measurements | {schema_version, schema})}'
{
  "schema_version": 19,
  "schema": "urn:animsmith:schema:output:19",
  "command": "lint",
  "prediction_facets": {
    "available": 0,
    "required_prediction_unavailable": 0
  },
  "prediction_provenance": null,
  "input": {
    "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "bytes": 123456
  },
  "check": {
    "check_id": "quat-norm",
    "selection": "selected",
    "configuration": "enabled",
    "applicability": "applicable",
    "evaluation": "complete",
    "findings": [
      { "check_id": "quat-norm", "severity": "error", "clip": "swing",
        "bone": "spine", "time_s": 0.5, "measured": 1.05, "expected": 1.0,
        "message": "non-unit rotation key (worst at key 2)" }
    ]
  },
  "measurements": {
    "schema_version": 18,
    "schema": "urn:animsmith:schema:measurements:18"
  }
}

As a CI gate

Lint every clip and fail the job on any error (add --deny-warnings to also fail on warnings):

# .github/workflows/animate.yml
- run: cargo install animsmith --no-default-features
- run: animsmith lint --deny-warnings clips/*.glb

The step's exit code is the gate: 1 fails the job, 0 passes it.

2. Repairing an asset

Use repair when a clip plays as a sudden flicker, spin, or explosion, but the authored motion is still recoverable. The symptoms in the pose flickers, spins, or explodes are often quaternion representation problems, so fix --dry-run lets a gate report the exact lossless repairs before writing anything.

quat-norm and quat-flip are not just checks — they are lossless, idempotent repairs. fix --dry-run is the check mode: it reports what it would repair and exits 1 if anything is pending, writing nothing.

$ animsmith fix examples/assets/clip-dirty.glb --dry-run
  would fix[quat-norm] clip 'swing' bone 'spine': 1 key(s) unit-normalized
1 key(s) would be fixed across 1 track(s) -> no output written
  would fix[quat-flip] clip 'swing' bone 'spine': 1 key(s) hemisphere-normalized
1 key(s) would be fixed across 1 track(s) -> no output written   # exits 1

Write the repaired asset with -o (or --in-place), then confirm it lints clean:

$ animsmith fix examples/assets/clip-dirty.glb -o fixed.glb
  fixed[quat-norm] clip 'swing' bone 'spine': 1 key(s) unit-normalized
1 key(s) fixed across 1 track(s) -> fixed.glb
  fixed[quat-flip] clip 'swing' bone 'spine': 1 key(s) hemisphere-normalized
1 key(s) fixed across 1 track(s) -> fixed.glb

$ animsmith lint fixed.glb
fixed.glb:
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; ...
0 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), ...   # exits 0

Because the repairs are lossless, diff confirms no measurement moved — the fix changed representation, not motion:

$ animsmith diff examples/assets/clip-dirty.glb fixed.glb
no significant movement
0 significant change(s)                      # exits 0

Pin an exact repair set with --repair id[,id] (animsmith fix --help lists the ids). Repairs that cannot be applied byte-surgically — data-URI .gltf buffers, cubic tracks, quantized rotations — are reported as skipped[...] and do not fail the check. Gate on lint when detection alone should fail CI.

3. Editing a clip

Use editing when the animation content is right but the pipeline cut is wrong: a capture has junk at the head, a one-shot needs a final hold, or a loop's stride anchor lands in the wrong place. Those are the cases in the clip is the wrong length or freezes at the end and the loop pops, where a mechanical transform can make the clip conform without touching geometry.

transform applies mechanical pipeline edits — slice a window, hold the final pose, re-anchor a gait cycle, remove an eligible duplicate loop endpoint, or prune provably constant multi-key tracks. Geometry passes through unchanged.

Slice a sub-window (retimed to start at 0):

$ animsmith transform examples/assets/clip.glb -o sliced.glb --slice 0.5:1.0
  sliced 'swing' to [0.5:1]s (3 keys max)
wrote sliced.glb (3 node(s), 1 clip(s), 0 mesh(es) / 0 position(s), 0 material(s))

$ animsmith diff examples/assets/clip.glb sliced.glb
  swing duration_s: moved 1.0000 -> 0.5000
  swing frame_count: moved 5.0000 -> 3.0000
  swing loop_continuity.bones[1].rotation_delta_deg: moved 22.9183 -> 11.4592
  swing loop_continuity.bones[2].position_delta_m: moved 0.1987 -> 0.0998
  swing loop_continuity.bones[2].rotation_delta_deg: moved 22.9183 -> 11.4592
  swing loop_continuity.bones[2].seam_velocity_delta_mps: moved 0.0598 -> 0.0200
  swing bone_rotation_range_deg[spine]: moved 22.9183 -> 11.4591
7 significant change(s)                       # exits 1

Extend the final pose (useful for hold frames at the end of a one-shot):

$ animsmith transform examples/assets/clip.glb -o held.glb --hold-extend 0.5
  hold-extended 'swing' by 0.5s
wrote held.glb (3 node(s), 1 clip(s), 0 mesh(es) / 0 position(s), 0 material(s))

Other transforms: --gait-anchor rotates a cyclic clip so its stride anchor lands at t=0. It is an explicit in-place declaration and needs resolvable Root (or Hips fallback), Hips, and feet roles; accumulating root translation/yaw refuses without writing the output or emitting buffered success stdout. Every nonconstant selected trajectory channel must contain exactly one key at each --fps whole-frame sample over the clip duration; sparse, differently framed, duplicate-time, or off-grid evidence and duplicate (bone, property) channels refuse. Declared frames × skeleton bones, declared frames × tracks, and maximum authored keys × skeleton bones are each capped at 1,000,000 samples. Retain root motion or use runtime phase offsets instead. --fps N sets the grid used for retiming. See cli.md for the full flag list.

For a loop exported with frame 0 copied again at the inclusive final frame, use --drop-duplicate-loop-endpoint only after the default warning identifies the strict authored-key case:

$ animsmith transform cycle.glb -o cycle-open.glb --drop-duplicate-loop-endpoint

The transform removes the same closing key count from every channel and re-pins the duration; it does not repair a stationary hold, root-travel/nonclosing clip, mismatched timelines, endpoint tangents, or retargeting damage. The open cycle is for engines that wrap over duration, so its inclusive loop-closure result is expected to change.

For exported clips with redundant “key everything” or baked-control channels, start with the default constant-track note, inspect the DCC/engine result, then make the explicit mechanical edit:

$ animsmith lint exported.glb --select constant-track
$ animsmith transform exported.glb -o compact.glb --prune-constant-tracks
  constant-track removed 'idle': track index 3 bone 'control' scale Linear 90 key(s)

The transform keeps a deterministic text record for every removal and every candidate it declines, including the source track index. It leaves an animates_bones target in place so the declared motion contract can still be checked; it does not protect [rig] required_bones, which only declares that the skeleton must contain a name. Re-lint and preview compact.glb in the target engine before replacing the export.

4. A project contract config

Use a contract config when the failure depends on what your game expects, not on file validity alone. The character glides or runs in place, feet skate when clips blend, and feet slide within one clip all need declared locomotion or blend assumptions before animsmith can judge them.

Mechanical checks run with no config. Contract-aware checks run only for the expectations you declare. duplicate-loop-endpoint, loop-closure, loop-seam-vel, and loop-seam-rot need only loop = true; role-dependent checks such as loop-seam, gait-group, root-motion-speed, in-place, and foot-slide also need resolvable rig roles. Without those roles they report a typed coverage gap rather than guess, so a config that pins a [rig] profile (or inline [rig.roles]) is what makes them fire.

sync-group is role-independent: use it for same-time or absolute-sync blend sets, where compatible duration, longest-channel key count, validated declared FPS grid, and loop endpoint mode matter. Each group declares non-negative duration, key-count, and FPS spread tolerances; incompatible findings retain a machine-readable row for every configured member.

The optional nested time_complement policy activates the separate warning-level time-complement check for every unordered pair in that sync group. It uses the already measured left-minus-right foot-height gait phase, so it needs resolvable hips plus left and right foot/toe roles. The exact-zero signal has no phase subject even when min_lr_amplitude_m = 0; positive near-idle or noisy phase evidence below that floor is also excluded. Among the remaining pairs, a warning appears only when reflected-time similarity beats same-time similarity by more than min_reflected_time_advantage. The finding's member rows retain both scores, their advantage, each phase, and each amplitude.

examples/assets/walk.glb is a committed rig for this: a hips + two-foot skeleton with a one-second walk cycle. Its bone names resolve a built-in profile, so inspect binds the rig with no config at all:

$ animsmith inspect examples/assets/walk.glb
examples/assets/walk.glb
rig profile: ue-mannequin (3 roles)
  hips         -> pelvis (exact)
  left_foot    -> foot_l (exact)
  right_foot   -> foot_r (exact)
skeleton: 3 bones
  pelvis
    foot_l
    foot_r
materials: 0
mesh instances: 0
clips: 1
  walk: 1.000s, 2 tracks, 33 keys max

measure reports the semantic metrics the checks judge — per-bone C0 pose closure and C1 seam velocity, the feet-relative loop-seam ratio (≈ 0 here, since this cycle returns its feet exactly), gait phase, L/R foot amplitude, and sampled Hips-fallback trajectory. This fixture's pelvis stays fixed, so all trajectory values are zero while the selected source remains explicit:

$ animsmith measure --format json examples/assets/walk.glb
{
  "schema_version": 19,
  "schema": "urn:animsmith:schema:output:19",
  "tool": { "name": "animsmith", "version": "0.14.0",
            "source": { "revision": null, "dirty": null } },
  "command": "measure",
  "summary": { "files": 1 },
  "files": [
    {
      "path": "examples/assets/walk.glb",
      "input": {
        "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "bytes": 123456
      },
      "rig": { "profile": "ue-mannequin", "resolution_outcome": "coverage",
        "resolved_roles": { "hips": "pelvis", "left_foot": "foot_l", "right_foot": "foot_r" },
        "resolved_role_policies": { "hips": "exact", "left_foot": "exact", "right_foot": "exact" } },
      "measurements": {
        "schema_version": 18,
        "schema": "urn:animsmith:schema:measurements:18",
        "clips": { "walk": {
          "duration_s": 1.0, "frame_count": 33,
          "animated_bones": ["foot_l", "foot_r"],
          "bone_channels": [
            { "bone_index": 1, "bone_name": "foot_l",
              "properties": ["translation"] },
            { "bone_index": 2, "bone_name": "foot_r",
              "properties": ["translation"] }
          ],
          "bone_rotation_range_deg": {},
          "loop_continuity": { "bones": [
            { "bone_index": 0, "bone_name": "pelvis",
              "availability": "measured",
              "position_delta_m": 0.0, "rotation_delta_deg": 0.0,
              "seam_velocity_delta_mps": 0.0,
              "seam_angular_velocity_delta_degps": 0.0 },
            { "bone_index": 1, "bone_name": "foot_l",
              "availability": "measured",
              "position_delta_m": 3.7e-17, "rotation_delta_deg": 0.0,
              "seam_velocity_delta_mps": 0.0,
              "seam_angular_velocity_delta_degps": 0.0 },
            { "bone_index": 2, "bone_name": "foot_r",
              "availability": "measured",
              "position_delta_m": 3.7e-17, "rotation_delta_deg": 0.0,
              "seam_velocity_delta_mps": 0.0,
              "seam_angular_velocity_delta_degps": 0.0 }
          ] },
          "loop_continuity_availability": "measured",
          "loop_endpoint_mode_availability": "not_applicable",
          "frame_grid_availability": "not_applicable",
          "loop_seam_ratio": 1.2e-15,
          "loop_seam_ratio_availability": "measured",
          "gait": { "phase": 0.75, "phase_availability": "measured", "lr_amplitude_m": 0.2 },
          "gait_availability": "measured",
          "root_trajectory": {
            "bone_index": 0, "bone_name": "pelvis",
            "source_role": "hips_fallback",
            "translation": {
              "horizontal_displacement_x_m": 0.0,
              "horizontal_displacement_z_m": 0.0,
              "horizontal_travel_m": 0.0,
              "vertical_displacement_m": 0.0,
              "vertical_min_displacement_m": 0.0,
              "vertical_max_displacement_m": 0.0
            },
            "translation_availability": "measured",
            "yaw": {
              "heading_axis": "positive_z", "net_yaw_deg": 0.0,
              "unwrapped_yaw_deg": 0.0, "yaw_travel_deg": 0.0
            },
            "yaw_availability": "measured"
          },
          "root_trajectory_availability": "measured",
          "speed_mps": 0.0,
          "speed_mps_availability": "measured"
        } },
        "mesh_definitions": [],
        "node_instances": [],
        "scenes": [],
        "skeleton_source_coverage": "unavailable",
        "skeleton_nodes": [],
        "skins": [],
        "material_resource_coverage": "complete",
        "material_definitions": [],
        "textures": [],
        "images": []
      }
    }
  ]
}

examples/walk.animsmith.toml is the contract: it declares the clip a loop (which arms the loop checks) and in-place, and caps their tolerances. Against the clean rig every semantic check passes, and the run exits 0. The one warning is not a defect in the motion: a cycle whose last key repeats its first is a representation an engine can trim, which editing a clip covers with transform --drop-duplicate-loop-endpoint.

$ animsmith lint --config examples/walk.animsmith.toml examples/assets/walk.glb
examples/assets/walk.glb:
  warning[duplicate-loop-endpoint] clip 'walk' @1.000s: declared loop repeats its first pose ...
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; ...
0 error(s), 1 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), ...   # exits 0

examples/assets/walk-dirty.glb is the same rig with the clip cut a quarter-cycle short, so the feet never return to their first-frame pose — the classic popped loop seam. The same contract catches it:

$ animsmith lint --config examples/walk.animsmith.toml examples/assets/walk-dirty.glb
examples/assets/walk-dirty.glb:
  error[loop-closure] clip 'walk' bone 'foot_r' @1.000s: loop does not close in position: ...
  error[loop-seam] clip 'walk' @1.000s: loop seam pops: wrap discontinuity is 6.82× ...
  error[loop-seam-vel] clip 'walk' bone 'foot_r' @1.000s: loop velocity changes at the seam: ...
  coverage[bind-pose] insufficient_rotation_evidence ×1 (scopes: first_frame_rest_delta; ...
3 error(s), 0 warning(s), 0 note(s), 1 coverage gap(s), 0 available prediction facet(s), ...   # exits 1

The contract is load-bearing: a bare animsmith lint examples/assets/walk-dirty.glb (no config) reports no findings — with no loop = true declared, the three loop checks are explicitly not applicable. Semantic checks enforce your declared expectations, not a guess.

walk-dirty.glb is one of a set. examples/assets/ commits one mutation of this same walk per runtime symptom — a channel that ends early, a clip that travels, a blend ring whose members disagree, a frozen arm, an animated non-uniform scale — each alongside the contract config that arms its checks. The asset table lists what every fixture fires and which config to pass.

Keeping the exported rig shape stable

animates_bones is deliberately per clip: it says that a named bone must exist and carry animation keys in that take. That is the right contract for a swinging arm or a locomotion root, but it is too strict for a static weapon socket, an IK target, a retargeting mask bone, or another runtime attachment point. Put those structural requirements on the rig instead:

[rig]
profile = "auto"
required_bones = ["root", "weapon_socket", "ik_hand_l"]

required-bones checks only that each declared name identifies exactly one bone in the input skeleton. A present-but-static bone is clean; a missing name is an error. Duplicate skeleton names are ambiguous rather than silently matched, and an export with no skeleton cannot satisfy the contract. This is also useful for a static mesh or a take with no clips: the structural check does not need animation data to run.

It is not a repair tool. AnimSmith does not add sockets, rename a duplicate, retarget a rig, or decide which bones your engine needs; fix the source rig or its export in the DCC, then lint it again. Use [clips.<name>] animates_bones = [...] when the same bones must move in a particular clip, and frozen-bone when keyed rotation is required to exceed a meaningful motion floor.

Presence and transform policy are separate. To require a runtime-facing node to inherit a unit effective rest scale, select it explicitly:

[runtime_nodes]
selectors = ["weapon_socket", "ik_*_target"]

[checks.rest-world-scale]
expected_uniform_scale = 1.0
uniform_scale_tolerance = 0.0001

An exact name or * glob must match exactly one source node. A miss or multiple matches produces explicit coverage instead of guessing. The finding's node path includes source indices and ancestors, so a local scale of 1 can still be traced to a non-unit effective scale inherited from a parent. This does not inspect animation scale keys, infer units from geometry, or rescale the file. The legacy [checks.rest-world-scale].node_selectors spelling is an alias; declaring it together with [runtime_nodes] is a configuration error.

Scaling up to a full character

examples/character.animsmith.toml is the full game-character shape the small walk contract grows into:

[rig]
profile = "auto"            # or mixamo / ue-mannequin / humanoid

[checks.loop-seam]
max_ratio = 1.6             # per-check tuning
[checks.loop-closure]
max_position_delta_m = 0.01
max_rotation_delta_deg = 1.0
[checks.loop-seam-vel]
max_velocity_delta_mps = 0.1
[checks.loop-seam-rot]
max_angular_velocity_delta_degps = 5.0
[runtime_nodes]
selectors = ["weapon_socket", "ik_*_target"]
[checks.rest-world-scale]
expected_uniform_scale = 1.0
uniform_scale_tolerance = 0.0001
[checks.frozen-bone]
min_rotation_deg = 0.5
[checks.quat-flip]
severity = "note"           # demote while an upstream fix lands

[clips."run_*"]             # glob: every run clip loops
loop = true
movement_owner_xz = "animation" # extracted root motion owns horizontal travel
movement_owner_y = "gameplay"   # controller owns vertical motion
movement_owner_yaw = "animation"
max_loop_position_delta_m = 0.04  # per-family pose/velocity seam caps
max_loop_rotation_delta_deg = 2.0
max_loop_velocity_delta_mps = 0.2
max_loop_angular_velocity_delta_degps = 200.0
[clips.run_forward]
max_loop_rotation_delta_deg = 0.5 # exact entry wins for this dimension
duration_s = { value = 1.033, tolerance = 0.02 } # authored clip-length contract
speed_mps = { value = 3.1, tolerance = 0.25 }   # root-motion contract

[gait_groups.run-ring]      # a directional blend ring
clips = ["run_forward", "run_backward", "run_left", "run_right"]
max_gait_phase_spread = 0.15   # members must stride in phase
min_lr_amplitude_m = 0.03      # exclude near-idle members

[sync_groups.run-ring]
clips = ["run_forward", "run_backward", "run_left", "run_right"]
max_duration_delta_s = 0.001
max_frame_count_delta = 0
max_fps_delta = 0.01

[sync_groups.run-ring.time_complement]
min_reflected_time_advantage = 0.25 # reflected score must beat same-time score
min_lr_amplitude_m = 0.03           # skip low-confidence gait signals

A gait_groups block is the payoff for a real character: it holds every clip in a directional blend ring to the same stride phase, so runtime blends between them don't skate. animsmith.toml is auto-loaded from the working directory, so committing one next to your assets makes every bare animsmith lint enforce the contract.

Movement ownership is independent on XZ, Y, and yaw. Each field is either "gameplay" (the entity/controller owns that component) or "animation" (extracted root motion owns it); omitted axes stay absent. in_place = true and false remain compatibility aliases for XZ gameplay and animation, respectively, but one selector entry cannot use both in_place and movement_owner_xz. Exact/glob layers normalize the alias before applying the usual field-by-field precedence.

The four role-free loop-continuity caps (max_loop_position_delta_m, max_loop_rotation_delta_deg, max_loop_velocity_delta_mps, and max_loop_angular_velocity_delta_degps) refine the corresponding global check caps in a [clips.<exact-name>] entry or [clips."glob_*"] family. An exact name wins over matching globs and an omitted field keeps its inherited cap. This is useful when root-motion runs need a different position allowance but idles must stay tightly closed. All four values must be finite and non-negative.

Predicting a Bevy animation selector

The small bevy.animsmith.toml profile selects Bevy 0.19.0's exact glTF loader contract. Its first production prediction maps each completely inventoried source animation index to the canonical typed subasset label spelling Animation{index}:

$ animsmith --config examples/bevy.animsmith.toml lint \
    --select engine-addressability examples/assets/walk.glb

The available facet's subject is the predicted display label, such as Animation0. Names do not control this selector: unnamed animations work, and duplicate names remain distinct indices. This predicts the selector spelling, not that Bevy loaded the file, retained its targets, or wired it into an animation graph. Incomplete source-animation inventory produces a blocking required_prediction_unavailable facet instead of guessing from the retained prefix. Prediction provenance v1 separately caps actual clip settings at 4,096, so a 4,097-clip file is a bounded operator error rather than a truncated prediction; issue #485 owns a future overflow representation.

Revision 2 uses bevy-v2.animsmith.toml for the unit/effective-scale rule. The example selects the closed empty-handler environment, declares the compiled animation feature, and demonstrates shared runtime-node selectors:

$ animsmith --config examples/bevy-v2.animsmith.toml lint \
    --select engine-unit-scale examples/assets/walk.glb --format json

The available file result is an exact 1:1 glTF-metre to Bevy world-length-unit mapping, not a claim that arbitrary application world state uses metres. Scene, primitive-child, and selected-node facets remain distinct; incomplete evidence is blocking rather than inferred.

Revision 3 is the current example in bevy-v3.animsmith.toml. It selects the narrow engine-track-support gate-support prediction:

$ animsmith --config examples/bevy-v3.animsmith.toml lint \
    --select engine-track-support examples/assets/walk.glb --format json

The prediction binds raw animation rows and independent per-animation channel coverage from the same load. The compiled bevy_animation feature gate takes precedence over load_animations; a disabled gate yields only negative dropped animation/channel outcomes, never a content finding. If both gates allow loading, runtime survival is required-unavailable because this contract does not run Bevy. Complete-empty inventory is not applicable; partial or unavailable inventory yields one subjectless, unsuppressible inventory facet and no retained-prefix prediction, including bounded N+1 overflow. Extensions, other animation constructs, and positive runtime survival are outside this slice. V5 provenance remains immutable inside the current output-v19 envelope; output-v17, output-v16, the rev1/rev2 profiles, and output-v15 contracts remain preserved.

Generate a reusable engine-neutral inventory as canonical JSON without a profile:

$ animsmith generate addressability examples/assets/walk.glb \
    > walk.addressability.json

Select the exact profile to add the unchanged Bevy evaluation to the same document; the neutral inventory and its identity stay unchanged:

$ animsmith --config examples/bevy.animsmith.toml generate addressability \
    examples/assets/walk.glb --format markdown

The inventory keeps source animation and channel indices, optional source names, raw targets and accessors, and dependency-closure identity. It does not infer scenes, skins, named-map winners, target UUIDs, extension support, or successful runtime loading.

The richer exact-Bevy path is a separate V2 contract, urn:animsmith:schema:gltf-addressability:2; see gltf-addressability-v2.schema.json. It retains bounded same-load scene, node, skin, attachment, root-to-node path, default-scene, named-map, and unique-target evidence while preserving this V1 animation inventory. Complete empty coverage proves absence; partial prefixes and unavailable domains do not. Explicit skin.skeleton is retained as source evidence, not inferred into a Bevy root, and scene-instantiated SkinnedMesh attachment is not claimed.

The V2 adapter is pinned to Bevy 0.19.0 revision 3 and commit c6f634ca9f406d68ba5109d921247b654cb42c10 (bevy_gltf 0.19.0, locked gltf 1.4.1, and root Cargo.lock). It reuses one engine-addressability lifecycle and the existing Animation{i} primitive. Scene{i} is emitted for every declared scene, and Gltf.default_scene routes only to an existing scene; there is no DefaultScene label or fabricated Scene0. Bevy eagerly emits Skin{i}/InverseBindMatrices for every source skin, including unreferenced skins, and emits Skin{i} when any source node references it. Named maps are separate source-order last-write-wins projections.

Exact target UUIDs require explicitly selecting 32- or 64-bit target pointer width because Bevy hashes segment lengths using the target pointer width; AnimSmith never infers width from the host. Missing feature/settings, incomplete or unreachable targets, multiple paths, and path/UUID collisions are typed required_unavailable, not guessed. target_coverage distinguishes complete (including empty) target coverage from incomplete raw/animation evidence and target_domain_truncated; other rich projection budget failures use projection_bounds_exceeded. Each V2 domain is capped at 4,096 rows, references at 65,536, path segments at 1,024 bytes and 256 segments, retained text at 1 MiB, and reports at 256 MiB. This remains prediction evidence only, not runtime-load, spawning, target-survival, graph, or playback evidence.

Predicting Unity Generic root motion

Select an exact engine profile and fully materialize every required importer setting before generating advice. For Unity Generic, for example:

[engine]
profile = "unity-generic"
profile_revision = 2
engine_version = "6000.3"
importer = "fbx-model-importer"

[engine.settings]
animation_type = "generic"
avatar_setup = "create_from_this_model"
import_animation = true
root_motion_source = "Reference/Root"

[clips."*"]
loop = true
movement_owner_xz = "animation"

[clips."*".engine_settings]
root_rotation = "extract"
root_position_y = "bake"
root_position_xz = "extract"

$ animsmith --config unity.animsmith.toml lint \
    --select engine-root-motion export.fbx

The current Generic revision-2 lint prediction compares the three declared movement-owner axes with the three bake | extract clip settings. bake means baked_into_pose; extract means stored_as_root_motion. It requires a case-sensitive, byte-exact Reference/Root path to the explicitly resolved Root role and never uses Hips as a fallback. The path grammar has no escaping or Unicode normalization, rejects empty/reserved/control/format segments, and limits segments, paths, and depth to 1,024 bytes, 4,096 bytes, and 256 segments. Raw path evidence is projected from the same FBX bytes; the implicit root and generated helpers cannot match.

An available facet records a typed routing result; a conflict is an error finding. Missing path, Root, intent, settings, raw inventory, or measured translation/yaw availability is required_prediction_unavailable, not a content finding, and exits 1. Measurement magnitude does not affect routing: zero and nonzero travel use the same comparison. This is prediction evidence only—no Unity editor execution, imported-asset readback, runtime playback, or engine certification occurs. The contract uses prediction provenance V6 and output V19; historical output V9 and other readers remain immutable. The checked-in/CI FBX inputs for this slice are self-authored synthetic fixtures.

Generating engine import advice

The separate historical revision-1 advice profile remains the route for projecting Convert Units, Bake Axis Conversion, Generic Root Motion Source, and the three ModelImporterClipAnimation.lockRoot* booleans. Use a revision-1 Unity advice config for this command:

$ animsmith --config unity-advice.animsmith.toml generate import-advice export.fbx \
    > export.import-advice.json

Unreal 5.8 and Godot 4.7 revision 1 deliberately exit 1 with profile_settings_unmodeled; their frozen profiles do not yet define importer settings. That command does not guess frame ranges, sample rates, unit conversion, or root-motion behavior.

Revision 2 provides the narrow document-setting projection for the exact Godot and Unreal tuples:

# Godot 4.7 / revision 2 / resource-importer-scene (glTF JSON or GLB)
[engine]
profile = "godot"
profile_revision = 2
engine_version = "4.7"
importer = "resource-importer-scene"

[engine.settings]
animation_fps = 30
animation_trimming = false

Godot's only projected keys are animation/fps (1..120, default 30) and animation/trimming (default false). Unreal 5.8 / revision 2 / fbx-importer accepts FBX and requires one explicit document setting:

[engine]
profile = "unreal"
profile_revision = 2
engine_version = "5.8"
importer = "fbx-importer"

[engine.settings]
sample_rate = "default_30" # or "source_determined" / "custom_hz(60)"

The V2 JSON contract is urn:animsmith:schema:engine-import-advice:2. It contains one available native import-setting projection or one typed refusal; it does not claim importer execution, frame ranges, units, skeleton/retargeting, compression, root motion, runtime behavior, or project-file changes.

Steering a run without a config

You can also shape a run from the command line. --select restricts the run set, --allow suppresses findings, and [checks.<id>] severity (including "off") reshapes how hard each check fails:

$ animsmith lint --select quat-norm examples/assets/clip-dirty.glb   # only quat-norm
$ animsmith lint --allow quat-flip examples/assets/clip-dirty.glb    # hide quat-flip

Demote a check while an upstream fix is pending (a [checks.quat-flip] severity = "note" override turns the warning into a note):

$ cat demote.toml
[checks.quat-flip]
severity = "note"

$ animsmith lint --config demote.toml examples/assets/clip-dirty.glb
  error[quat-norm] clip 'swing' bone 'spine' @0.500s: non-unit rotation key ...
  note[quat-flip] clip 'swing' bone 'spine' @0.750s: 2 hemisphere flip(s) ...
1 error(s), 0 warning(s), 1 note(s), 1 coverage gap(s), 0 available prediction facet(s), ...   # exits 1

See the configuration reference for the full key reference.

5. Converting exports and generating reports (default features only)

Use this workflow when a DCC or marketplace export reaches your importer but brings bloated constant tracks, stray scale keys, or a rig the retargeter cannot trust. That is the hygiene side of the file is bloated, or the retargeter chokes and the rig-contract side of a limb is T-posed, or a bone never moves: convert to glTF, measure/lint/report, then compare against the previous asset before committing the migration.

convert normalizes an FBX (or glTF) export into a clean glTF, and report renders a self-contained HTML report with skeleton playback and metric charts. Both are in the default build; a --no-default-features binary omits them. report --evidence-only writes the same findings, coverage gaps and engine predictions without the sampled pose grid — keeping the charts in a single-clip report, though not in a comparison, whose panels are drawn from that grid — for sharing evidence where the clip itself cannot travel.

$ animsmith convert export.fbx -o clip.glb
$ animsmith measure clip.glb
$ animsmith report clip.glb -o report.html
$ animsmith diff old.glb clip.glb

The repository also carries a byte-checked, self-authored visual-comparison pair. It exercises the report's acceptance context without a commercial or private source asset:

$ animsmith --config examples/report-comparison.animsmith.toml report \
    examples/assets/report-comparison-before.glb \
    --compare-after examples/assets/report-comparison-after.glb \
    --before-clip acceptance-matrix --after-clip acceptance-matrix \
    -o comparison.html

In comparison.html, select the before-side loop finding to see the exact first and last judged poses overlaid with the affected bone highlighted. The trajectory panels disclose root, hips, and bilateral-foot trails; the gait panel shades the typed foot-slide stance intervals and names the selected role. The combined root chart uses one metres scale and distinct before/after legends. The before-side constant-track row is explicitly structural evidence: its quaternion keys can be removed while the sampled poses look unchanged. Neither the fixture nor the report certifies artistic, gameplay, importer, or engine acceptance.

cargo run -p animsmith --example gen_example_assets regenerates both inputs. The example_assets_match_generator_output integration test rebuilds every committed example and compares its bytes, so CI catches hand edits or generator drift.

When one authoritative skinned base and its animation takes live in separate files, use the versioned character-assembly.toml recipe instead. assemble produces one GLB and evidence pair; source-package extraction and project publication stay outside animsmith.

The example uses current recipe v7 without its optional rest/bind operation. For glTF/GLB or inventory-complete normalized/baked FBX assembly, add [rest_bind_scale] with the required exact root_node_name and expected_factor fields. The base must resolve that name to one source node and exactly one non-empty skin whose every joint is that node or a descendant. Every distinct FBX clip is projected to its normalized skeleton and takes. A glTF/GLB clip retains its existing successful full rest/bind or meshless track-only path; its clip-track gate additionally admits only failures in unused geometry, deformation, material, or bind domains while retaining framing, dependency, raw-coverage, named-skeleton, and animation accessor/layout safety. The basis proof covers the selected base skin joints, exact root, their named ancestry, and actual track targets; unreferenced base-only geometry descendants need not appear in the clip. Every input passes basis compatibility before remapping.

$ animsmith assemble examples/character-assembly.toml \
    -o character.glb --evidence character.assembly.json

Getting a test asset

We do not ship third-party assets. To try this on a real rig:

• Mixamo — free with an Adobe ID and royalty-free for personal and commercial use. Download a character + animation as FBX, then convert it. Mixamo is also a built-in rig profile, so [rig] profile = "mixamo" resolves its roles for the semantic checks. Check Adobe's current terms before redistributing any downloaded asset; the safe path is to keep them out of your repo. The Mixamo tutorial takes one download end-to-end, from this convert step through a contract config.
• CC0 / public-domain sources for assets you want to commit.
• Or generate your own — see the asset generator this repo uses for its own fixtures.

6. Embedding animsmith as a library gate

Use embedding when the team already has an importer or build pipeline and wants animsmith's checks as a library step instead of a separate shell command. The pipeline-library use case is the payoff in why animsmith: load your asset once, map your own contract into Config, and surface findings in the same gate that owns the rest of your asset rules.

Pipelines can skip the CLI and drive the check catalog directly: load a document, resolve rig roles, build a Config from your own contract format, measure, run the checks, and map findings to your gate.

The runnable walkthrough is crates/animsmith/examples/embed.rs, paired with embedding.md:

$ cargo run -p animsmith --example embed

It exits 1 on purpose — the example declares a deliberately wrong expectation to demonstrate a failing gate, not an accidental error.

Feature matrix

Asset policy

Assets committed to this repo are procedurally generated or CC0, with provenance recorded. Third-party assets (Mixamo and similar) are used via documented download steps, not checked-in bytes or download scripts, unless their terms clearly permit redistribution.

Advanced workflows

• Static asset workflow guide — Diagnose bounds and transform domains, preserve normal maps, bake supported static placement, attach explicit textures, and understand what still needs engine validation.
• Scaling glTF safely — Choose whole-document unit conversion or rest/bind reparameterization, understand the exact-source rewrite/proof transaction, and interpret its support boundary.
• Material texture recipes — Attach explicit BaseColor, normal, metallic-roughness, and occlusion images during conversion with deterministic resizing and provenance evidence.
• Multi-source character assembly — Combine an authoritative skinned base with exact takes and timeline windows from separate inputs, producing one deterministic GLB plus evidence.
• Collection contract extensions — Read the contact-fragment, foot-cycle planner, and transition-family contracts, including strict manifest and contact-evidence bindings.

Static assets: bounds, transforms, and textures

This guide is for artists, technical artists, engine integrators, and build engineers handing a prop or environment asset from a DCC tool to a game. It explains four questions that look similar in a viewport but need different answers in an asset pipeline:

1. Which bounding box are we measuring?
2. Is placement stored in mesh vertices or in a node hierarchy?
3. Did the normal map survive conversion as a normal map?
4. Should missing texture links be preserved, repaired declaratively, or sent back to the artist?

animsmith reports or performs only the part it can prove. It does not certify an engine's import settings, generate artistic material content, or replace a runtime smoke test.

Start with the handoff problem

Which bounding box do you mean?

A mesh definition contains reusable vertex data. A node places an instance of that mesh into a hierarchy. A scene chooses root nodes and therefore a set of instances. The glTF scene and node model and its transformation rules make those identities separate: a mesh's global transform comes from the node that references it, and a child inherits its parents' transforms.

That gives one asset several valid axis-aligned bounding boxes (AABBs):

For example, a unit cube can have a mesh-local box from (0, 0, 0) to (1, 1, 1), while a node with scale 2 and translation 10 along X has a static node-world box from (10, 0, 0) to (12, 2, 2). Neither result is wrong. Using the first as a placed-world bound, or the second as a reusable mesh bound, is the bug.

geometry_centroid is a separate mesh-local fact: it is the arithmetic mean of finite decoded base POSITION rows, not the center of geometry_aabb. An asymmetric mesh can therefore have a centroid away from its box center. It is useful for checking authored pivots or coarse placement assumptions, but it is not a center of mass, surface-area-weighted center, collision origin, or a runtime placement guarantee.

For indexed geometry, each stored POSITION contributes once even when the index stream references it repeatedly; for unindexed geometry, each stored position contributes once. Empty or wholly non-finite geometry has no centroid. animsmith reports this evidence but does not move the pivot, recenter the mesh, or bake transforms as part of measure.

animsmith measure prop.glb
animsmith measure prop.glb --format json > prop.measure.json

Why the distinction matters

• Artists can tell whether unexpected size comes from modeled geometry or an unapplied object/parent transform.
• Engine integrators can choose the domain their importer, preview camera, culling system, or placement code actually consumes.
• Pipeline developers can compare the same source identities across re-exports instead of joining records by non-unique display names.

An unavailable box is not an empty or zero-sized box. Skinned deformation, non-finite transforms, or a definition without finite positions produce an explicit unavailability reason. Scene records also expose excluded instance counts, so a partial static union cannot masquerade as complete coverage.

These are default/rest source-asset measurements. They deliberately exclude animation, skin and morph deformation, runtime component transforms, engine-generated collision, and camera- or frame-dependent bounds. Validate those in the consuming engine.

Inventory material and image handoffs

Before treating a missing detail as an engine-shader problem, inspect the source material graph:

animsmith measure prop.glb --format json > prop.measure.json

For glTF/GLB, the nested measurement data records source-order material definitions and their semantic bindings, then texture-to-image references and image metadata. That exposes, for example, a normal slot that points to the same image as BaseColor, a texture shared by several materials, a linked external image, or an image whose declared MIME disagrees with the container found in its bytes. Successful image inspection reports decoded width, height, channel count, and color type. It does not decide whether a BaseColor texture is authored well, whether a normal map has the intended convention, or whether an engine importer will choose the right settings.

An unavailable image is explicit rather than silently omitted: it has an unavailability reason and no decoded metadata. A malformed PNG/JPEG may still identify its container, but is not repaired. Other loaders can report material_resource_coverage: "unavailable"; do not equate that with an empty material table. This inventory is source evidence only. It neither resizes or transcodes images nor makes a later writer or conversion recipe authoritative for every original resource. Keep the raw handoff asset when byte-level source provenance matters.

Preserve normal maps as data, not color

A tangent-space normal map stores direction vectors in RGB texels. It changes lighting without changing the mesh silhouette; Unity's normal-map introduction shows why a low-poly surface can retain grooves, rivets, and other fine detail. Blender likewise documents that a tangent-space Normal Map node expects matching UVs and non-color image data.

Ordinary full-scene conversion preserves available linked or embedded PNG/JPEG base-color and normal images. A glTF normal texture keeps its normalTexture.scale; an FBX normal map uses glTF's default scale because the ordinary FBX material does not expose the same scalar. The glTF material model defines the normal slot and scale separately from the sRGB BaseColor slot.

animsmith convert source.fbx -o source.glb

Expected result: a material that had a discoverable normal image still has a normal texture after conversion, and converting or transforming the glTF again does not silently replace it with the BaseColor image or discard its strength. If the original bytes already satisfy the operation, they pass through without being decoded and re-encoded.

What preservation does not fix

animsmith does not decide whether an image is artistically correct, convert a height map into a normal map, flip an engine-specific green-channel convention, generate missing tangents, or configure the engine's texture importer. For example, Unity still requires the texture to be imported as a normal map and documents its expected Y+ convention. A model can therefore contain the right glTF material link and still look wrong under engine-specific import or shader settings.

Bake static placement into geometry

Use --bake-static-mesh-transforms when a static consumer needs final placement in mesh-local vertices beneath identity nodes. A common example is a prop modeled under rotated or scaled helper objects: it looks right in the DCC and a hierarchy-aware viewer, but a consumer that extracts only the mesh definition gets the unplaced shape.

animsmith convert prop.fbx -o prop-baked.glb \
  --bake-static-mesh-transforms

The operation accumulates the accepted rest hierarchy into positions, applies the inverse-transpose transform to normals and normalizes them, then emits a canonical identity root with identity mesh children. It retains indices, UVs, supported material assignments, BaseColor textures, and normal textures. convert --format json records the source identity, applied world matrix, determinant, and output identity for each baked instance.

Conceptually, this is the exchange-format counterpart of applying object transforms in a DCC. Blender's Apply transforms documentation explains the artist-side operation: transfer the current object transform into its data while keeping the visible result in place. animsmith's operation is intentionally narrower and fail-closed.

Rejection is part of the contract

The bake exits with an asset refusal (1) and writes no output instead of guessing when the source cannot be transformed without violating its preservation promises. The CLI reference owns the exact acceptance and rejection list.

It is not a general scene flattener. It does not bake skins or animation, duplicate shared instances, repair winding, preserve artistic pivots or helper hierarchies, choose a project-specific forward axis, or generate collision. Use the DCC or an engine-aware asset build step when one of those changes is intentional.

Attach textures with a recipe

Use --material-texture-recipe when the source material names are trustworthy but image links are missing, non-portable, or subject to a project size cap. Do not add a recipe merely because conversion supports one: ordinary conversion already preserves texture links it can discover.

animsmith convert prop.fbx -o prop.glb \
  --material-texture-recipe recipes/prop-materials.toml

A typical bad handoff has a material named surface, an artist-approved BaseColor image and tangent-space normal image beside the source, but an FBX whose external paths point to another workstation. A recipe maps the exact, case-sensitive source material name to those two images. If either path, image, or material match is invalid, the whole conversion fails before output.

The successful result has one explicit BaseColor/normal pair for every recipe entry. Images within max_dimension keep their original bytes and MIME type. Larger images use deterministic, role-aware processing: BaseColor is treated as color, while a normal map is treated as vector data and renormalized. Conversion evidence records every consumed and emitted image.

The recipe does not generate textures, invent material matches, pack ORM maps, add unsupported PBR slots, repair UVs or tangents, change normal-map handedness, or judge artistic quality. See the material texture recipe reference for the exact TOML schema, containment policy, limits, and processing contract.

Verify the result in layers

One successful conversion is evidence about the asset operation, not proof of the whole runtime presentation. Keep the raw source immutable and verify each layer explicitly:

# 1. Record source bounds and identities.
animsmith measure prop.fbx --format json > prop.before.json

# 2. Convert with only the operations your handoff requires.
animsmith convert prop.fbx -o prop.glb \
  --bake-static-mesh-transforms \
  --material-texture-recipe recipes/prop-materials.toml \
  --format json > prop.conversion.json

# 3. Measure the written artifact, not only the source.
animsmith measure prop.glb --format json > prop.after.json

Then inspect the written artifact in the target engine:

• confirm size, forward/up orientation, pivot expectations, and hierarchy;
• confirm the shader uses BaseColor and normal textures in the intended slots;
• confirm the normal texture's import type and channel convention;
• exercise runtime culling, LODs, collision, lighting, and instancing;
• retain the conversion evidence beside the derived artifact so automation can explain how it was produced.

That final engine pass stays necessary because animsmith does not know the consumer's shaders, import presets, physics scale, collision generation, or runtime placement policy.

Scaling safely

animsmith scale is an evidence-emitting producer for two different scale operations. glTF/GLB supports both; the narrow FBX boundary supports only rest/bind and always emits a new GLB. Neither operation guesses units or scale policy from geometry, names, or asset categories.

Use the CLI reference for the exact command grammar and machine-readable output for the scale-evidence v4/v5 schemas. This guide owns the operator workflow and the boundary between the two operations.

Choose the operation

These operations are not interchangeable. A rest/bind cleanup must not be selected merely because a character appears too large or small, and a unit conversion must not be used to remove an inherited scale from one hierarchy.

Whole-document conversion takes one finite positive --factor. Rest/bind requires all three declarations: a raw source-skin index, a raw source-root node index, and the finite positive factor expected at that root. Use animsmith measure source.glb to list authored source-node and source-skin indices; neither selector is a normalized bone id or mesh-instance ordinal.

animsmith scale whole-document source.glb -o metres.glb \
  --factor 0.01 --evidence metres.scale.json

animsmith scale rest-bind source.glb -o canonical.glb \
  --source-skin-index 0 --source-root-node-index 3 \
  --expected-factor 0.01 --evidence canonical.scale.json

There is no in-place mode, plan file, animsmith.toml key, implicit first skin/root, or per-run tolerance override. Input, artifact, and evidence paths must be three distinct files. For narrow FBX rest-bind, neither destination may name a safe dependency key retained by the same-load closure, and a symlink-refused dependency or terminal closure-budget stop prevents publication. glTF/GLB artifacts keep the input container; narrow FBX rest-bind emits a new .glb.

What one run proves

One invocation performs one ordered transaction:

1. Parse the source and build a complete capability inventory.
2. Compile one format-neutral ScalePlan containing the exact topology, payload shape, field ownership, and proof claims for that source.
3. For glTF/GLB, apply that plan directly to source JSON and buffer bytes; the normalized model writer is not used. Narrow FBX rest-bind first writes a private normalized GLB, then applies the plan and proof to that GLB.
4. Reload the exact emitted bytes and run the independent normalized core proof plus the raw artifact proof. The artifact proof also reruns the writer and requires deterministic bytes.
5. Stage the artifact/evidence pair, read the staged artifact back, and require its digest to match the bytes that were proved before promoting both files.

A reported refusal publishes neither file and restores any prior pair. The two destinations require two renames, so a process killed between them has the crash window documented in machine-readable output. Proof is not run again after staging: digest equality binds the already-proved bytes to the published file.

The current fixed tolerance identity is appendix-d-v6. It is recorded in scale evidence together with each evaluated residual and both observed-factor witness fields. Rest/bind derives those witnesses independently from the raw source projection and normalized skeleton; whole-document conversion records the declared factor in both because that operation has no source factor to measure. There is no runtime alias for an older policy and no per-run tolerance knob.

Write sets and preservation

Whole-document conversion rewrites represented lengths: node TRS translations and matrix translation columns, mesh POSITION, translation animation values and cubic tangents, raw glTF morph-target POSITION deltas, inverse-bind translation columns, and corresponding accessor bounds. Rotation, scale, normals, UVs, static and animated morph weights, key times, and other dimensionless payloads remain outside the write set. Static JSON morph weights retain their numeric values; animated weight accessor payloads remain byte-exact.

Rest/bind reparameterization derives every multiplier from the selected raw topology. It rewrites the necessary node-local translation/scale or matrix components, translation and scale animation payload, and affected inverse binds. Mesh positions and the already-correct world geometry remain unchanged.

At factor one, whole-document conversion plans no semantic writes. See the scale output contract for the exact artifact-preservation and evidence-field semantics at that boundary.

Supported source boundary

Scale accepts self-contained glTF/GLB for both operations. A .gltf source with an external buffer or image is refused rather than partially converted. Raw preflight also refuses any source domain the current model and artifact proof cannot preserve completely. Whole-document conversion admits only raw glTF POSITION morph-target deltas with dimensionless static/animated weights; NORMAL, TANGENT, sparse/interleaved scale-bearing accessors, unsafe aliases, and every morph payload under rest/bind reparameterization remain refused. It also refuses cameras and lights, along with GPU instancing, unregistered extensions, extras, non-triangle primitives, secondary skin-influence sets, unsafe accessor layouts, and animation targeting a matrix-authored node. The rejection record contains the complete typed violation inventory.

Do not read the core model's static unprojected-connector rows as a current glTF capability. The glTF loader projects every accepted node today, and the raw writer has no connector-bridge implementation; that path is outside the supported source boundary.

With the default FBX feature, scale rest-bind source.fbx -o canonical.glb accepts only the inventory-complete normalized subset. It requires the same explicit skin/root/factor declarations, stages a private normalized GLB, maps both selectors by exact unique named identity, then uses the existing raw GLB rewrite/reload/proof path. The same-load gate admits exact marker, LOD-group, stereo-camera, camera-switcher, and display-layer typed lists because none can supply rest/bind state to that bridge, plus shader/binding-table metadata. Display layers contribute only node membership and editor visibility/freeze/color state; they do not alter projected nodes. It admits a BindPose only when it covers every joint of each skin it touches and its converted rows are finite, unambiguous, and agree with the converted cluster bind or node rest-world matrix already consumed by the bridge; a source without a Pose remains valid. The raw aggregate still counts all admitted rows. Residual unmodeled typed lists fail closed with exact nonzero kind counts. The same-load gate may also admit enumerated scale-invariant conversion fidelity—omitted authored vertex/face/edge metadata, influence projection with complete effective coverage, triangulation, and exact-bit welding—without removing any inventory evidence. Missing influence coverage, omitted point/line or mesh geometry, unsupported skinning/deformers, incomplete binds or normals, and unclassified payload remain blockers. It records the full FBX inventory and staged GLB digest in scale-evidence v5. The published artifact is a re-encoded GLB: no raw FBX byte, object-property, marker/camera/display-layer behavior, or authored-curve-key preservation is claimed. FBX whole-document conversion remains refused. Character assembly likewise does not silently apply either scale operation. Its existing bind-pose canonicalization remains a distinct, explicit recipe operation. Morph support intentionally remains a raw glTF whole-document capability; it does not add morphs to the shared normalized model or enable rest/bind morph reparameterization.

Outcomes and evidence

The CLI reference owns exit-status semantics, and the output reference owns the scale-evidence v4/v5 wire contract and publication outcomes. In brief, --format json prints the same record that a successful run writes to --evidence; a refused run prints its rejection record but never writes the evidence destination because there is no artifact/evidence pair to publish. The record carries no timestamp; declared paths remain as entered, and identical inputs and arguments produce byte-identical evidence.

Embedding the same contract

Rust pipelines use animsmith_core::scale for planning and normalized proof, and animsmith-gltf for raw preflight, exact-source rewrite, reload, and artifact proof. Pass one compiled plan through rewrite_scale_plan; do not substitute the fixture-only analytic reference builder for a format writer. See the embedding guide and the crate rustdoc for exact type and error contracts. Appendix D in DESIGN.md is the normative algebra and preservation decision; the calibration notes record how the fixed proof policy is measured.

Material Texture Recipes

animsmith convert --material-texture-recipe <PATH> attaches explicit BaseColor, normal, metallic-roughness, and occlusion images to named source materials. It is for assets whose material links are incomplete or need a reproducible texture-size policy. The recipe is declarative: it does not generate artistic content.

animsmith convert input.fbx -o output.glb \
  --material-texture-recipe recipes/materials.toml

Recipe format

Recipes are TOML documents with immutable identity urn:animsmith:schema:material-texture-recipe:1. The retrievable JSON Schema is material-texture-recipe-v1.schema.json.

schema_version = 1
schema = "urn:animsmith:schema:material-texture-recipe:1"
texture_root = "textures"
max_dimension = 1024

[[materials]]
name = "surface"
base_color = "surface-base.png"
normal = "surface-normal.jpg"
metallic_roughness = "surface-metallic-roughness.png"
occlusion = "surface-occlusion.png"

materials is a list. Each entry requires one exact source-material name, one base_color path, and one normal path. metallic_roughness and occlusion are optional paths for their corresponding glTF PBR slots. Names are matched exactly, case-sensitively. A duplicate recipe name is an operator error because the recipe is intrinsically ambiguous. A valid recipe name that matches no source material, a source material omitted from the recipe, or an ambiguous source material is an asset-property refusal (exit 1): it describes the recipe's fit to the loaded asset rather than invalid syntax. Every declared entry must be used; a recipe cannot partially apply and succeed. Unknown recipe fields are rejected instead of ignored.

Run animsmith inspect <input> first and copy names from its top-level materials section; its quoted names use TOML-compatible escapes and can be copied directly into a recipe. The mesh instances section shows which material each primitive references. Ambiguous source names are marked and must be corrected in the authoring tool before a recipe can target them; inspect does not rename or merge materials.

max_dimension is required and must be from 1 through 4096. It bounds both the requested output size and accepted source dimensions. Source image files are limited to 64 MiB. Only PNG and JPEG files are accepted; their type is determined from file magic, not a filename extension.

Paths and containment

All paths are interpreted relative to the recipe file. Empty, absolute, drive-prefixed, and backslash spellings are rejected for consistent cross-platform behavior. texture_root is optional. When it is set, it too is recipe-relative and is a containment root: the converter canonicalizes the root and every image path and rejects traversal or symlink resolution outside the root. Missing paths, non-regular files, and escaped paths are operator errors. Without texture_root, ordinary recipe-relative resolution applies, including explicit .. components, and no containment root is declared.

Deterministic processing

The converter processes entries in source-material order and image slots in BaseColor-then-normal-then-metallic-roughness-then-occlusion order. Recipe declaration order does not affect the artifact or evidence. If an image already fits max_dimension, it is a no-op: its original encoded bytes and MIME type are preserved. A resized image is emitted as PNG RGBA8.

BaseColor resizing converts sRGB into linear light, premultiplies alpha, uses Lanczos3 filtering, then converts back to sRGB. Normal resizing decodes tangent-space vectors, uses Triangle filtering, and renormalizes vectors before encoding. Metallic-roughness and occlusion maps use linear-channel Triangle filtering: they are not treated as sRGB color or tangent-space vectors. For resized output, the pinned encoder uses Best compression and NoFilter. Producer evidence names the pinned primary packages image 0.25.10, png 0.18.1, and zune-jpeg 0.5.15; Cargo.lock pins their full dependency closure. Given the same supported-platform inputs, recipe, and tool version, this policy produces deterministic output bytes.

Evidence

With --format json, conversion evidence records the recipe path and root, the declared dimension cap, the locked processor identity, every consumed image, and every emitted texture. Records are ordered as described above. See machine-readable output for the versioned evidence contract.

Multi-source character assembly

animsmith assemble combines one authoritative skinned base with animation takes from separate FBX or glTF inputs. Use it when a delivery spreads clips across individual files or long master timelines but the runtime needs one GLB.

animsmith assemble character-assembly.toml \
  -o character.glb \
  --evidence character.assembly.json

The command is available in default builds with the fbx feature. It always writes a GLB and versioned JSON evidence as one publication pair. It prepares both files before replacing either destination and restores prior outputs if the second replacement fails.

This rollback contract covers every error returned by the command. No portable filesystem primitive can make two independently named destinations power-loss-atomic, so after abrupt process or machine termination the consumer must verify the evidence artifact digest before publication.

Boundary

Assembly owns format-generic scene, skin, animation, material, and GLB work. The consuming project still owns source-package extraction, gameplay naming and acceptance policy, cache/generation policy, provenance beyond assembly evidence, and publication. DCC automation is outside this command.

Recipe

Start from examples/character-assembly.toml:

schema_version = 7
schema = "urn:animsmith:schema:character-assembly-recipe:7"
input_root = "inputs"
base_input = "base-character.fbx"
mesh_instances = ["character-mesh"]
remove_nodes = ["sword-placeholder"]
complete_tracks = true
canonicalize_skin = true
ground_and_center = true
prune_constant_tracks = false
fps = 30.0

# Optional for glTF/GLB and the inventory-complete FBX subset; the exact root
# name and factor are required together.
# [rest_bind_scale]
# root_node_name = "root"
# expected_factor = 0.01

[[clips]]
name = "idle"
input = "idle.fbx"
take = "Take 001"
frame_window = [1, 61]
drop_closing_endpoint = true
strip_bones = ["motion-root"]

All input paths are relative to input_root, which is itself relative to the recipe. Absolute paths, parent traversal, symlink components, and paths that escape the canonical root are rejected. Output paths are command arguments so the recipe remains relocatable.

The input root is an operator-controlled snapshot: do not mutate or replace its entries concurrently with assembly. Symlink checks and reads are separate portable filesystem operations, so the command does not claim to defend against an actor racing the input tree while it runs.

Discover exact recipe names

Inspect the base before writing the recipe:

animsmith inspect inputs/base-character.fbx

Copy the quoted name after node in the mesh instances section exactly into mesh_instances; quoted names use TOML-compatible escapes. Each entry also shows its source node, referenced mesh, skinned status, and the material used by every primitive. The top-level materials section lists the exact, case-sensitive names required by a material texture recipe. Duplicate skeleton node or material names are marked ambiguous; assembly and material recipe validation reject ambiguous authored names instead of guessing. Multiple mesh instances attached to one uniquely named node are not ambiguous and are selected together. inspect only reports the authored scene—it does not rename nodes or materials, merge duplicates, or repair the asset.

The base supplies the authoritative skeleton, rest pose, meshes, skins, materials, and textures. mesh_instances names the exact base nodes whose mesh instances survive; omitting it retains every instance. An explicit node name must be unique; every mesh instance attached to that selected node survives. Unreferenced mesh and material definitions are pruned. For a recipe-v7 FBX base, assembly resolves this selection once against the captured FBX node names and carries the selected scene through its private GLB scale stage. Any holder names generated by that private serialization are not a second recipe namespace. When rest_bind_scale is enabled, an explicit selection that retains no skinned base instance refuses as an asset-recipe-mismatch at the selection boundary; its diagnostic names the recipe selection rather than the private staging artifact.

Each [[clips]] entry selects one exact source take, renames it, and remaps its tracks to the base skeleton by exact unique bone name. Missing referenced bones and ambiguous names fail rather than retarget motion. An entry may then apply:

• frame_window = [START, END]: one-based, inclusive source frame endpoints at fps, or time_window = [START, END] in seconds;
• drop_closing_endpoint = true: remove one final key from every channel;
• hold_frames = N: duplicate the final pose after N / fps seconds;
• gait_anchor = true: explicitly declare an in-place cyclic gait and run the measured gait-anchor transform using the selected animsmith.toml rig configuration. Assembly refuses before publication when the Root role (or Hips fallback) has missing/non-finite trajectory evidence, more than 1 cm of horizontal endpoint displacement, or more than 1° of yaw accumulation; no interior step is subtracted as an allowance. Every nonconstant channel the operation would rotate must contain exactly one key at each declared fps whole-frame sample over the clip duration, at the exact representable f32 key / fps time and period endpoint. Sparse, differently framed, duplicate-time, or off-grid evidence refuses, as do duplicate (bone, property) channels (including constant channels). Exact admitted f32 key times drive verification, and an integer-index permutation performs the rewrite; exempt constant tracks cannot influence its period or shift. The complete skeleton, resolved roles, and track shapes are validated first; declared frames × skeleton bones, declared frames × tracks, and maximum authored keys × skeleton bones are independently bounded at an inclusive 1,000,000 samples. Yaw uses f64 first/final headings plus counted full-turn crossings. At sample zero it chooses the local +Z, +Y, or +X basis axis with the greatest finite horizontal projection, in that deterministic tie order, and retains it for the entire proof. This supports different source-axis conventions without allowing a later axis switch to hide yaw; loss of the selected horizontal projection refuses. Error does not grow with segment count; four f32 successors at the inclusive 1 cm/1° caps cover only authored endpoint translation/quaternion quantization;
• strip_bones = [...]: remove every TRS track for named base bones.

Optional rest/bind scale canonicalization

Recipe v7 can opt into the accepted rest/bind scale operation with one top-level block:

[rest_bind_scale]
root_node_name = "root"
expected_factor = 0.01

The block has no defaults: the exact normalized root-node name and finite positive expected factor are both required. In the captured base, the name must resolve to exactly one source node and exactly one non-empty source skin whose every joint is that node or its descendant. Every distinct FBX clip-only input uses the track-only case described below. A glTF/GLB clip retains its existing successful full rest/bind or meshless track-only path; role-specific admission additionally selects the track-only path when only geometry, material, deformation, or bind obligations that assembly never consumes would fail. Framing, parser, topology, dependency, raw-coverage, named-skeleton, and animation accessor/layout checks remain strict. Missing or repeated names and zero or multiple applicable base skins fail closed. Leading or trailing whitespace is invalid rather than silently trimmed; internal whitespace remains exact. No source-array index is reused across files. Recipe v7 accepts glTF/GLB and the narrow FBX subset admitted by the existing normalized/baked rest-bind capability boundary. That boundary requires a complete ufbx inventory for the normalized metre/Y-up hierarchy, derived bind evidence, rebuilt geometry, and baked animation. Its same-load gate may admit enumerated scale-invariant conversion fidelity, including omitted authored vertex/face/edge metadata, influence projection with complete effective coverage, triangulation, and exact-bit welding, while retaining every inventory fact. Incomplete source-skeleton projection, unclassified payload, missing effective influences or geometry, incomplete bind evidence, residual unmodeled source elements or extensions, incomplete resource/construct coverage, or an incompatible basis fails closed. The source-aware gate may admit user-defined properties and bounded external texture/video declarations because neither supplies rest/bind state to the normalized GLB bridge. It also admits exactly ufbx's marker, LOD-group, stereo-camera, camera-switcher, and display-layer typed lists: they cannot supply hierarchy transforms, skin binds, tracks, or geometry to that bridge. Display layers contribute only node membership and editor visibility/freeze/color state; they do not alter projected nodes. The gate admits shader/binding-table metadata on the same basis. A BindPose is admitted only when it covers every joint of each skin it touches and its converted rows are finite, unambiguous, and agree with the converted cluster bind or node rest-world matrix already consumed by the bridge; no Pose remains required. Those elements remain counted in the raw aggregate, while every residual unmodeled typed list fails closed and is named by kind and count in the refusal. Rooted capture retains supported linked texture bytes through the normalized artifact, and neither publication destination may name one of the safe source-relative dependency keys retained by that same-load closure, including a key whose capture was unavailable or refused. The command stops before publication when a retained key was refused as symlink-mediated rather than resolving through the link, or when the closure resource budget leaves a declaration tail unchecked. The frozen v7 evidence retains declaration counts in its capability inventory; same-load raw facts and closure remain loader-side rather than being added to that wire record. Admission does not claim raw FBX object-property, marker, camera, material, or texture-assignment preservation. A refusal identifies the exact failed source fact, semantic domain, or inventory counter. Nothing is inferred from filenames, bounds, character height, inverse-bind magnitudes, or source units. Recipe v6 remains immutable with its explicit source indices; recipes v4/v5 remain immutable and continue to reject FBX when rest_bind_scale is active.

Recipe v7 retains recipe v6's composition with canonicalize_skin, ground_and_center, and remove_nodes. It captures and validates the raw inputs first, applies the same mesh selection and canonical assembly transforms to the staged candidate and an independently source-rebased reference, then maps selectors by names and ordered selected joint topology after any index changes. It serializes the staged candidate, performs the raw rest-bind rewrite last, reloads those exact bytes once for proof, and atomically publishes only after the final clips match the rebased reference. Recipe v4 remains immutable and continues to reject that combination.

Before any clip keys are remapped or copied, assembly captures and validates the exact bytes of the base and every separately supplied clip. Each input must agree on the selected domain and factor, named parent topology, target local rest matrices and orientations, helper-node layout, and coordinate convention. Each input's own target paths and plan-owned effective factors are validated and fingerprinted; distinct clips need not contain identical target paths. A matching digest alone is not compatibility evidence. Topology, orientation, helper-layout, basis, selector, or factor disagreement rejects the complete operation before publication. Topology, resolved names, and the declared factor compare exactly. V7 compares the exact resolved root and ordered selected-skin joint names plus the named source/helper parent paths; format-local skin/node numbers remain per-input evidence. Each input's selector identity is derived from its accepted plan and source document; a declared/resolved disagreement rejects the operation. V6 retains exact raw-selector comparison. Rest translations, scales, and matrices use the named Appendix D tolerance policy, while quaternion orientation uses shortest-path angular distance, so equivalent q/-q spellings do not become false incompatibilities.

For a compatible clip, translation values and both translation tangents of a CUBICSPLINE track are rebased in the source basis before exact-name remapping. Assembly reuses the same validated scale request, compiled write-set, raw glTF rewrite, tolerance policy, and paired proof residuals as animsmith scale. The assembled artifact is serialized, reloaded from its exact staged bytes, and proved once before the artifact/evidence pair can be published.

complete_tracks = true fills absent TRS channels from the base rest pose for the union of selected skin joints and nodes targeted by any emitted clip. Per-clip strip_bones entries stay excluded. Rotation key values are unit-normalized and made hemisphere-consistent without changing cubic tangent sign relationships. When FBX scale staging produces an independent reference skeleton, completion targets are carried by exact unique bone name and resolved separately in each skeleton; numeric bone IDs are document-local. Each skeleton's own node-removal closure is excluded before completion.

canonicalize_skin = true bakes each skin's common geometry-to-world transform into positions and normals and rewrites inverse binds consistently. ground_and_center = true additionally places the bind-pose geometry on Y=0 and centers it in X/Z while translating skeleton roots and root-translation animation tracks by the same offset. Inconsistent skin transforms, singular normal transforms, or shared mesh definitions that require incompatible bakes are rejected.

prune_constant_tracks = true removes tracks that the existing core constant- track predicate proves constant, after completion, quaternion cleanup, and all other assembly transforms. This is all-property pruning: it can remove completion-generated (bone, property) coverage when the completed value is constant, so it may undo part of complete_tracks = true. The carve-out uses the effective output clip's animates_bones exact names; it never uses required_bones, so declared motion evidence is preserved without retaining unrelated tracks. For an independent scale reference, authoritative prune decisions and the final clip proof are projected by exact unique bone name and channel property rather than by document-local bone or track indices. The canonical example leaves pruning disabled; opt in only after reviewing the completed clip and the consumer's transition behavior. A consumer that does not explicitly reset an omitted property during a transition can retain the outgoing clip's value, so leave pruning disabled where dense transition coverage matters until property-scoped selection is available (see #401). Set it to false or omit it to retain every otherwise eligible track.

remove_nodes = [...] selects exact, case-sensitive names from the post-canonicalization base skeleton and removes each selected node together with its complete descendant subtree. Every name must resolve exactly once; an absent or ambiguous name fails rather than being skipped. Overlapping ancestor and descendant selections are allowed and their union is removed once, in original parent-before-child node order. Selecting the entire skeleton is refused. Surviving descendants are never reparented because every descendant of a removed node belongs to the removal closure.

Removal is planned before track completion, and closure nodes are excluded from completion targets. The structural projection is applied only after clip processing and constant-track pruning. It is refused if a final track still targets the closure, if a skinned mesh instance is attached to it, or if a selected node remains referenced by a skin joint or complete source-skin identity. For an FBX input with rest_bind_scale, an unskinned mesh instance attached inside the declared closure is excluded from the private normalized scale stage and removed with that closure. The same instance still blocks scale when its node is not declared for removal. This is the only attachment reference consumed implicitly; per-clip strip_bones and constant-track pruning remain necessary to make an animated decorative subtree removable. The effective clip's animates_bones configuration still protects named tracks from pruning, so a protected surviving track causes removal to fail. [rig] required_bones is a lint presence policy, not a node-removal selector or protection list.

Errors are deterministic and no output is published on any refusal. A valid recipe that does not fit loaded asset facts is a typed asset refusal (exit 1); JSON mode emits producer-refusal:1, while text mode reports the same stable kind on stderr. Recipe syntax/schema/value, input/path, and publication failures are operator errors (exit 2) and emit no stdout. Recipe schema and value validation precede input loading. After the base's selected mesh and canonicalization steps, selectors and their descendant closure are resolved deterministically and the whole-skeleton rule is checked. After all clip transforms, every surviving track, mesh attachment, skin reference, and complete source-skin fact is checked before the hierarchy is changed. The reported refusal identifies the offending stored record; traversal order is an implementation detail rather than a wire contract.

Accepted projection preserves the original order and parent links of every surviving node, remaps all surviving node references through one stable map, and clears optional source-native skeleton projection because it can no longer describe the authored source completely. Node removal performs no mesh, material, or texture garbage collection. Outside the bounded FBX scale composition above, a mesh instance inside the closure is refused. The earlier explicit mesh_instances selection and its existing resource pruning remain the only assembly resource-garbage-collection pass. Evidence counts an unskinned instance consumed by declared node removal in transforms.removed_mesh_instances and omits its node name from retained_mesh_instances.

An optional material_texture_recipe reuses the exact material-name recipe boundary described in Material texture recipes, including BaseColor, normal, metallic-roughness, and occlusion slots.

The normative current recipe schema is character-assembly-recipe-v7.schema.json. Recipe v1 through v6 remain immutable historical contracts. Migrate a v6 rest/bind recipe by changing its identity to v7 and replacing both source-index fields with root_node_name. Omitting the block remains ordinary assembly behavior; v3 continues to reject the block as unknown.

Evidence and determinism

The current evidence identity is urn:animsmith:schema:character-assembly-evidence:7. It records the effective recipe, recipe and input SHA-256 digests, the selected configuration file's declared path and digest (or an explicit built-in-defaults marker), selected takes and windows, exact source/base bone remap names and indices, and track operation counts, start/end/delta facts for named translation tracks removed by strip_bones, mesh selection, canonicalization flags, tool identity, and the final artifact digest and counts. When pruning is enabled, each clip records the exact removed tracks in pruned_constant_tracks: the index in the completed, normalized output clip immediately before pruning (retaining its pre-prune authored order), exact bone name and bone_index in the post-canonicalization/pre-node-removal skeleton, TRS property, interpolation, and key count. bone_remaps.base_index uses that same pre-removal coordinate space. Consumers derive a surviving final index by subtracting earlier transforms.removed_nodes[].original_node_index entries; a pruned track whose node is later removed intentionally has no final-artifact node index. The array is empty when pruning is disabled or no track is removed. The top-level transforms.removed_nodes array records every projected node exactly once in original pre-removal node order: its exact name, original node index, nullable original parent index, and whether the recipe selected it directly rather than through an ancestor. It is empty when remove_nodes is omitted or empty. See character-assembly-evidence-v7.schema.json.

When rest_bind_scale is active, v7 pins each exact base/clip input digest and its versioned basis fingerprint, the declared root name, each input's resolved root name/source-node index, the source-skin index for full rest/bind inputs, and the effective staged selectors after canonicalization/removal, the factor, every compatibility result, and the shared final-artifact scale proof. The staged-source digest and exact emitted-byte read-back digest make the two serialization boundaries explicit; the read-back digest equals the published artifact identity on every accepted run. Each input records application = rest-bind with fingerprint contract urn:animsmith:character-assembly-scale-basis:1, or application = skinless-clip-tracks with urn:animsmith:character-assembly-skinless-clip-scale-basis:1, so consumers never infer the applied domain or version from the digest. The operation record also carries the sibling residual_comparison_counts record pairing every shared maximum residual to its comparison count by the same stable field name. These records let a consumer verify that assembly validated and transformed every participating input before remapping and that proof consumed the exact bytes subsequently published.

V7 constructs an explicit animation-only projection for each distinct FBX clip-only input and for each glTF/GLB clip admitted to the track-only path. The projection retains complete source-skeleton node coverage and every normalized take, while excluding source meshes, mesh instances, materials, skins, and inverse-bind state that cannot contribute to assembly. The captured input digest and source-projection evidence still describe the unmodified source, including unsupported FBX deformation or glTF bind payload. For glTF/GLB, the role-specific raw gate excludes only obligations wholly owned by those projected domains; malformed animation accessors, matrix-target animation, unsafe dependencies, and incomplete raw construct coverage still refuse. The clip projection's exact named root, every joint in the selected base skin, and the named ancestors connecting that rig domain must match the accepted skinned base basis in normalized topology. Rest translation, rotation, and scale remain strict independently for every node/property that any take omits; a component may differ only when every take explicitly authors that named channel, so assembly never falls back to the differing clip rest. Each actual clip track target and its named ancestors join that compatibility domain, and the target must belong to the base plan's affected closure. Base-only geometry and attachment descendants do not become clip requirements merely because the base plan rewrites them. The base plan supplies each named translation/scale target factor; cubic-spline in/value/out triplets are rebased together. A skinless base still refuses, as does any clip projection with incomplete source coverage, an incompatible named basis, or a track outside the base scale domain. Bind matrices are neither synthesized nor claimed for the track-only row. The retained skinless-clip-tracks label names the projected operation domain, not a requirement that the captured source was skinless. The exact final assembled artifact remains covered by the shared skinned-base rewrite and proof. Independently serialized animation-only FBX clip projections are compared under that proof's Appendix-D numeric tolerance; full rest/bind inputs retain exact pre-remap oracle comparison.

Each v7 scale-input row also identifies the captured container and its source projection. raw-gltf records authored-curve and raw-span preservation. normalized-baked-fbx explicitly records both as false, embeds the complete FBX capability inventory, and binds the private normalized GLB stage by digest and byte count. When declared node removal consumes an unskinned instance, that private stage excludes the instance while the raw input digest and capability inventory remain unchanged. This stage is not a second public artifact or evidence chain: assembly still serializes, rewrites, reloads, proves, digest-checks, and atomically publishes one final GLB/evidence pair.

Evidence v1 through v6 remain immutable historical contracts; v1 does not describe pruning, v1 and v2 do not describe structural node removal, and none of them describe rest/bind scale compatibility. Consumers migrating from v2 or v3 must verify removed_nodes against the effective recipe and output hierarchy rather than inferring removal from track evidence or lint configuration.

Given identical recipe bytes, input and config bytes, tool build, paths, and platform, repeated runs emit byte-identical GLB and evidence. Evidence keeps operator-declared paths rather than leaking canonical host paths.

Collection contract extensions

This document records versioned extensions to the file-scoped collection decision in DESIGN.md Appendix F. Contact-fragment V1 includes its strict standalone and manifest-selected producer/CLI/publication boundary. The directional-speed policy/evaluation V1 is a separate ordered 0.6.0 slice with one JSON-only evaluator command. The contact-transform result and foot-cycle map planner are format-neutral contracts; animation rewriting, collection publication, and runtime systems remain separate work.

Directional-speed policy V1 (#552, ordered slice)

The strict collection-directional-speed-policy:1 reader is an ordered, manifest-bound declaration for the directional-speed evaluator. It is a separate TOML envelope: it does not add fields to collection-manifest V1, revise collection-output V2, or infer membership from filenames or paths. animsmith collection evaluate-directional-speed --policy POLICY.toml --evidence COLLECTION-OUTPUT.json --format json binds its raw bounded inputs to the typed reader, strict current collection-output V3 adapter, pure evaluator, and immutable result. There is no output file, text/Markdown, subset, or inference mode; publication remains a consumer responsibility.

The envelope repeats the exact manifest identity (collection_id plus {sha256, bytes}), one directional-blend runtime_set_id, and every existing logical member exactly once in manifest order. Each member has one nonzero, unique semantic [x, z] coordinate. source_basis.x and source_basis.z are orientation witnesses for raw collection-output V3 +X/+Z endpoint displacement in that semantic plane; their magnitudes are nonsemantic, and the evaluator uses unit axes for heading. They must be finite, bounded, nonzero, and perpendicular. diagonal_behavior is closed and applies to unit-input/base targets: for coordinate c, preserve uses gain g(c) = hypot(c) while normalize uses g(c) = 1. Thus uniform expected speed is base * g(c), authored expected speed is the member's base speed_mps * g(c), and ratios compare expected_measured_ratio_i_to_ref = declared_expected_ratio_i * g(c_i) / g(c_ref), with the reference declaration fixed at 1.0. Direction comparison is unaffected by this gain.

The declaration also carries finite bounded direction_tolerance_deg in the inclusive range 0..=180 degrees. The pure evaluator normalizes raw endpoint displacement before source-basis projection and uses published speed_mps for magnitude (not travel). Its immutable result binds raw policy and evidence InputIdentity values and retains a manifest-ordered row for every member: policy coordinate, raw evidence, projected heading, comparison values, tolerances, deviations, and pass/violation outcome. Incomplete root travel, zero endpoint, zero ratio reference, and numeric range are typed not-evaluated outcomes, never implicit passes, failures, or subsets.

uniform requires uniform_speed_mps and speed_tolerance_mps; authored requires each member's speed_mps plus speed_tolerance_mps; and ratios requires a declared reference_member, each member's expected_ratio, and a dimensionless ratio_tolerance. Mode-inapplicable fields are rejected. The strict reader rejects parse/declaration failures including unknown or duplicate fields, unknown tokens, malformed identities, duplicate member ids or coordinates, invalid coordinates or basis, nonfinite/out-of-range values, and N+1 members before retaining them. Separate binding validation rejects stale manifest identity, wrong runtime-set id or kind, and missing, extra, or reordered member sequences. No licensed asset data belongs in this declaration or its tests.

Foot-cycle parameterization V1 (#18, planner slice)

urn:animsmith:schema:foot-cycle-parameterization:1 is a strict bounded TOML declaration for one existing collection-manifest gait-group. It repeats the exact manifest identity, runtime-set id, exact ordered members, one explicit reference member, one safe contact-fragment path per member, finite positive minimum/maximum segment slopes whose inclusive interval contains 1.0, and one safe future output-directory path. The reference owns canonical contact-boundary phases. Membership, ordering, contact paths, and reference ownership are never inferred from filenames or clip names.

schema = "urn:animsmith:schema:foot-cycle-parameterization:1"
schema_version = 1
runtime_set_id = "com.example/sets/walk"
reference_member = "com.example/walk-forward"
output_directory = "generated/walk-aligned"
minimum_segment_slope = 0.5
maximum_segment_slope = 2.0

[proof]
max_gait_phase_spread = 0.08
min_lr_amplitude_m = 0.05
max_contact_boundary_phase_error = 0.01

[manifest]
schema = "urn:animsmith:schema:collection-manifest:1"
schema_version = 1
collection_id = "com.example"

[manifest.input]
sha256 = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
bytes = 1234

[[members]]
id = "com.example/walk-forward"
contact_fragment = "contacts/walk-forward.json"

[[members]]
id = "com.example/walk-right"
contact_fragment = "contacts/walk-right.json"

The reader is closed and bounded at 8 MiB and 4,096 members. Planning admits at most 16,384 contact events and 32 MiB of canonical contact-fragment bytes across the whole declared ring, so independent per-fragment limits cannot multiply into unbounded retained topology or canonicalization work. Exact supplied byte counts are preflighted before canonicalization; a false count is then caught by exact canonical byte-count and digest comparison on the first such row. Safe locators use the same lexical relative-path contract as collection manifests. It rejects unknown fields, unsupported identities/versions, unsafe or duplicate paths, duplicate/missing members, an absent reference, invalid manifest identities, and invalid slope ranges. The required closed [proof] table declares finite max_gait_phase_spread and max_contact_boundary_phase_error values in the inclusive range [0, 0.5] plus a finite non-negative min_lr_amplitude_m. These exact values are bound by the parameterization byte identity and retained in the plan; V1 has no defaults, gait-group/config lookup, filename inference, or cross-member policy merge. The published foot-cycle-parameterization-v1.schema.json describes the decoded TOML shape. Host canonicalization, symlink/alias detection, and the guarantee that output_directory is a previously absent sibling generation destination are enforced by the private source-preparation adapter described below; this parser performs no filesystem I/O.

The pure core planner additionally requires each supplied sidecar byte identity to equal its canonical contact-fragment:1 identity and its collection clip witness to equal the manifest's exact logical/source/take-index/take-name row. Each member also supplies independently measured typed Root/Hips evidence bound to the fragment's exact artifact, dependency closure, and collection clip source/take witness. Cross-wired or stale measurements refuse before their values are used. A missing, ambiguous, malformed, or non-finite witness refuses. Evidence retains signed endpoint X/Z displacement and signed accumulated unwrapped yaw. The unchanged admission derives horizontal displacement with binary64 hypot(X, Z) and uses absolute yaw; values above 0.01 m or 1 degree refuse, and both thresholds are inclusive. The planner consumes and retains those facts but does not sample an animation asset itself. V1 recognizes exactly AnimSmith's contact-support-detector:1 extension and validates its closed algorithm, sampling, frame-cap, threshold, and selected left/right foot-or-toe role provenance. Every member must carry the exact same finite non-negative contact_height_m binary64 value because that policy determines the compared window boundaries. Other extensions refuse because no operation-specific transform handler has run.

The private CLI-crate preparation adapter now bounded-reads the exact manifest and parameterization, resolves the exact member-reachable source/config subset in canonical manifest source-key order plus every declared contact fragment and absent output directory under its declaration root, and rejects symlinks, canonical collisions, and (where the platform exposes file identity) hardlink aliases before source parsing. It first validates the pure exact runtime-set binding, then loads only its member-reachable manifest sources/configs in manifest order; unrelated source rows do not gate this scoped operation. It captures each distinct canonical config once and shares that immutable normalized snapshot and explicit byte identity across its sources for later proof without a control-file reread. Distinct retained config snapshots share an inclusive 32 MiB invocation ceiling; repeated use of the same canonical config is counted and captured once. It requires complete dependency-closure identity and exact raw take index/name witnesses, counts primary, every retained external dependency identity, and normalized document semantic payload against per-source and invocation byte ceilings. Each loaded document passes strict structural shape validation before sampling or candidate work. The adapter then preflights both frames * bones pose cells and frames * tracks sampling work for every selected member and admits the complete multi-member totals against the inclusive one-million-cell/work ceiling before constructing the first metric grid. The prepared in-memory collection retains those exact source pose-cell and sample-evaluation totals so a later output proof can share one invocation budget without resampling or rereading controls. After planning, it runs the core clip-candidate preflight for every member and checks invocation-wide candidate-key, retained-value, exact candidate-storage-byte (including name), and work totals before constructing the first candidate. It then derives Root/Hips endpoint X/Z hypot and absolute unwrapped yaw through the existing metric grid/role/trajectory authority, and cross-checks every returned plan binding and duration before calling time_warp_clip_v1. Any refusal drops the whole in-memory batch and creates no output or partial result.

Preparation deliberately stops contact transformation at a typed continuation. It validates and reconstructs the closed stance-detector payload through the operation-specific core handler, but a fresh output artifact identity and its dependency closure do not exist until the candidate document is serialized. Only that later serialization step may supply those exact identities and call transform_contact_fragment_v1; preparation does not hash an in-memory Clip, claim a generated artifact identity, serialize, reread/prove, or publish. No user-visible command is added by this slice. A freshly serialized exact-copy candidate may truthfully retain the input content identity; freshness comes from capturing the serialization result, not from requiring unequal digests.

Each member must contain complete positive left/right support windows, each with exactly one same-side marker. Fragment rows stay physically linear: windows are partitioned by side, and same-side runs must be strictly disjoint (even touching same-side runs refuse). When one side has both a first run starting at 0 and a distinct last run ending at 1, those two physical rows form one logical cyclic stance. Their artificial seam edges are omitted from topology correspondence, while both windows and both markers remain in the transformed fragment. A single full-cycle [0,1] stance refuses. Opposite-side windows may overlap or touch. After seam coalescing, both sides must have the same nonzero logical-run count and their onsets must alternate around the cycle.

The planner derives true logical onsets/releases in deterministic cyclic chronological order, including a fixed kind order for simultaneous phases. It rotates only the correspondence sequence to a true left-support onset; it does not rotate numeric clip phases. Therefore the reference boundary phase remains its authored normalized phase and a member that would require moving phase zero, including incompatible wrap/non-wrap correspondence, refuses as non-monotone.

Independent output proof first requires the expected and freshly detected (side, edge) sequence in absolute phase-zero chronological order to match. It then compares those phase-zero-paired boundary phases with circular numeric distance, but a complete left/right role swap is a topology failure even at the maximum allowed boundary-error tolerance.

For matching signatures, corresponding source onsets/releases map to the reference phases. Simultaneous source boundaries are admitted only when all corresponding reference boundaries are simultaneous at one phase, and vice versa. Identical (source, output) pairs collapse to one map knot; a group split on either axis refuses. (0,0) and (1,1) are then included in that same deduplication, so the planner preflights the 4,096-point contact-transform cap from the retained knots rather than raw boundary rows. Every resulting segment must be finite, strictly increasing, continuous, and within the inclusive declared slope range. The planner returns one duration-preserving ContactTransformOperationV1::TimeWarp plus exact ContactTransformBindingV1 per member.

The separate pure time_warp_clip_v1 seam consumes one such member plan only after its caller has selected and bound the corresponding loaded clip. It strictly validates track-local clip/track shape; because this seam has no skeleton input, its host must already have bound every track bone index to the selected, validated skeleton. Fixed aggregate name-byte, track, authored/generated key/value, and work caps refuse before candidate allocation; candidate storage has a derived public upper bound from those admitted rows. LINEAR tracks map every authored key and insert interior map-knot samples; STEP tracks map only authored breakpoints. A map knot and an authored key that are the same instant in the emitted binary32 domain — equal, or one representable place apart, since that domain holds nothing between them — are one emitted key: it keeps the authored time and the authored value and carries the control point's own output, because the control point is the definition of the map at that instant. FootCycleClipWarpKnotV1 is the one definition of that question and time_warp_rows_v1 the one answer to which keys a track emits and in what order; the independent output proof consumes those rows for the sequence alone and derives every expected time and value itself, a knot's own times included. Regression tests freeze those rows and independently perturb producer output times for both knot-bearing row kinds and source times for inserted knots. A coalesced row always retains its authored value: its source time is unused metadata after row selection, and perturbing it alone does not invalidate the correct candidate. That holds for a track's own first and last authored key too: the span test is inclusive of one place on either side, so which side of a rounding step the reconstructed instant lands on does not decide whether that key takes its control point's output. Where two authored keys are one place apart, a knot binds to the key it is bit-equal to rather than the key it is merely beside, and both keys are retained. The one exception is a map knot that is the same instant as a source endpoint, 0 or the duration: the map's exact endpoint rows define the output there and a candidate retains those two instants as themselves, so such a knot contributes nothing. Two knots that name one instant refuse: each is compared against both instants of the knot before it, its own resolved source time and the instant it named, because a knot that coalesced into an authored key answers to a time one place from its own. Distinct output instants that collide after binary32 narrowing refuse too. One-key CUBICSPLINE tracks are retained, and multi-key cubic tracks are retained only for bit-exact constant values with zero tangents. The value caps are the shape-derived three-values-per-cubic-key maxima, so malformed N+1 storage refuses at shape or key bounds before it can become a separate valid value-only case.

Neither pure seam transforms contact fragments, derives root measurements, binds the selected asset to the plan, serializes output artifacts, proves reread results, or publishes a generation directory; those remain later #18 transaction seams described below.

Foot-cycle generation V1 (#18)

The public producer is deliberately one collection command with no destination override:

animsmith collection transform-foot-cycle COLLECTION.toml \
  --parameterization FOOT-CYCLE.toml --format json

The parameterization's output_directory is resolved relative to that document and must name a previously absent directory below an existing safe parent. The command is available in the glTF-only build; .fbx sources remain available only when the fbx feature is enabled. Every admitted source, including .gltf, is emitted as a self-contained GLB.

For N members, the generation has exactly 3N+1 files in parameterization member order:

members/000000/artifact.glb
members/000000/contact-fragment.json
members/000000/evidence.json
...
aggregate-evidence.json

Logical ids and source keys are evidence fields, never filesystem names. The member evidence identity is urn:animsmith:schema:foot-cycle-member-evidence:1; it binds exact manifest and parameterization inputs, source artifact/config/complete closure, output artifact/complete closure, transformed and independently redetected contact identities, canonical operation identity, declared proof policy, and reread proof residuals. The aggregate identity is urn:animsmith:schema:foot-cycle-aggregate-evidence:1; it repeats the control bindings and policy, preserves ordered member paths and identities, and records checked 3N+1, component bytes, exact total, retained GLB bytes, and source/output/combined metric work. See foot-cycle-member-evidence-v1.schema.json and foot-cycle-aggregate-evidence-v1.schema.json.

All GLBs, canonical transformed fragments, member evidence, and aggregate evidence share one 256 MiB retained/staged cap in addition to their stricter component limits. Every candidate, contact transform, independent reread proof, and bounded serialization finishes before the first filesystem write. The publisher flushes the fixed file set beneath one sibling temporary directory and performs one no-replace directory rename. It does not replace an existing generation or claim power-loss, network-filesystem, or abandoned-temp cleanup guarantees.

Success exits 0 and writes the exact published aggregate-evidence.json bytes to stdout only after publication. A broken stdout is diagnosed best effort and cannot undo or relabel the generation. Asset/capability/map/contact/proof refusal exits 1 with one producer-refusal:1 JSON record and no destination. Malformed or stale controls and bindings, unsafe paths or aliases, I/O, serialization, or publication/race failures exit 2 with empty stdout and no published destination.

Contact fragments (#147)

The contact-fragment V1 identity is urn:animsmith:schema:contact-fragment:1. AnimSmith 0.6.0 ships #152's format-neutral strict core reader, bounded canonicalization seam, and strict one-clip producer. generate contact-fragment includes a manifest-selected collection form that reloads the declared source rather than reading collection-output evidence. Transforms and runtime systems remain out of scope.

It is an importable envelope that can be merged into a host's one authoritative measured sidecar. It binds contact facts to the exact primary source bytes and complete versioned dependency closure, plus producer/tool version and an unambiguous clip reference. artifact is the existing primary InputIdentity; dependency_closure_identity is the existing complete DependencyClosureIdentityV1 rather than the full output-v10 closure record. Both serialize as {sha256, bytes}: sha256 makes the algorithm and digest explicit rather than adding separate algorithm and digest fields. Partial or unavailable dependency coverage refuses fragment generation, and a mismatch in either identity makes an existing fragment stale. The complete captured closure's primary_input must equal artifact; producer and consumer validate that relationship against the captured closure. V1 deliberately binds every dependency in the complete modeled closure, including dependencies such as textures that may not affect contacts. This can refuse generation for an unavailable unrelated dependency, but avoids a second format-specific relevance policy.

Collection-owned clips use the #409 logical identity plus its source, take-index, and exact take-name witness. Standalone documents use an exact embedded clip/take name scoped by both input identities; ambiguous or duplicate names are refused. No animation-array index, filename, or engine asset handle is an identity.

Collection-manifest V1 rejects duplicate logical clip ids while parsing as a collection control error, before collection generate-contact-fragment can select a clip. A valid collection take-index addresses the raw source take row; the producer resolves that row's complete normalized-index witness before sampling its internal document clip.

Points and windows use normalized clip time [0, 1], with the measured positive duration recorded for validation. Events have stable opaque ids, engine-neutral roles and phases, and deterministic ordering. V1's closed role vocabulary is left_foot, right_foot, left_hand, right_hand, left_toe, right_toe, left_knee, right_knee, left_elbow, right_elbow, root, prop, and body; its phases are begin, end, and marker. Trim, slice, and time-warp operations must transform the fragment with the same operation or return structured per-event outcomes/refusal. Events outside the retained interval are never silently clamped, dropped, or retained.

Confidence, when present, is finite and lies in [0, 1]. Core fields are closed. Extensions use strict envelopes with exactly schema, schema_version, and payload, where the extension's versioned schema owns the payload object; an unsupported but well-formed extension may be preserved as opaque data. Any transformer must understand and apply every extension's operation contract or refuse the whole operation with unsupported_extension; it may not copy opaque extension-owned times or event references unchanged.

The strict V1 reader caps a contact-fragment source at 8,388,608 bytes and 32 JSON container levels, with at most 4,096 events and 256 extensions. Authored strings are at most 4,096 UTF-8 bytes and identifiers at most 255 bytes; each extension payload is at most 262,144 canonical bytes and 16 levels deep. A complete fragment is at most 8,388,608 canonical bytes. A transform-result source and complete canonical result are each at most 16,777,216 bytes, with at most 4,096 control points and 4,096 event outcomes; its inline fragment obeys the fragment limits. Depth counts every object/array on the root-to-value path, including the root envelope as depth 1. A payload object also starts at depth 1 for its separate 16-level limit. Each exact maximum is accepted; N+1 is rejected during bounded decoding before the excess value is retained or an unbounded canonical buffer is allocated; canonical-byte limits use a bounded JCS sink. JSON Schema maxLength counts Unicode code points, while this reader's text and identifier limits count UTF-8 bytes, so a non-ASCII value may satisfy the schema and still be correctly refused by the reader. The reader accepts decoded IEEE-754 numbers only within the safe magnitude [-9007199254740991, 9007199254740991]; this includes identity byte counts and opaque extension payload numbers. Extension payloads are stored from their bounded canonical JCS bytes, so canonical serialization followed by strict reread preserves the validated fragment value. An explicitly empty extensions array is refused so omitted and present data do not canonicalize to the same value.

A minimal collection-scoped envelope is:

{
  "schema": "urn:animsmith:schema:contact-fragment:1",
  "schema_version": 1,
  "producer": {"tool": "animsmith", "version": "0.6.0"},
  "artifact": {"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "bytes": 123456},
  "dependency_closure_identity": {"sha256": "1111111111111111111111111111111111111111111111111111111111111111", "bytes": 456},
  "clip": {"scope": "collection", "logical_id": "com.example.pack/locomotion/walk-forward-in-place", "source": "walk-forward", "take_index": 0, "take_name": "Take 001"},
  "duration_s": 1.2,
  "events": [{"event_id": "left-foot/0", "role": "left_foot", "phase": "marker", "time": 0.23, "confidence": 0.92}],
  "extensions": [{"schema": "urn:example:contact-quality:1", "schema_version": 1, "payload": {"quality": "high"}}]
}

Seconds and frame values, when shown, are derived display values rather than identity or comparison coordinates. Canonical bytes use the complete RFC 8785 JSON Canonicalization Scheme (JCS), including its object-key, string, and number rules; every extension payload must also be JCS-canonicalizable. Before JCS serialization, events use the exact mixed-event sort tuple (start, kind_rank, end_key, role, phase, event_id): points have kind rank 0 with start = time and a null end sentinel that sorts before every numeric window end; windows use their declared start, have kind rank 1, and use their numeric end. This keeps point/window order stable when starts coincide. Tuple strings, including opaque event ids, compare by unsigned UTF-16 code units exactly like RFC 8785 property names, without Unicode normalization.

Trim, slice, resample, and time-warp use the separate urn:animsmith:schema:contact-transform-result:1 result. It binds input and, on success, output primary, dependency-closure, and canonical-fragment identities. Its strict top-level fields are schema, schema_version, operation, input, outcome, and event_outcomes, with output only on success and refusal { code, message } only on refusal. operation is a strict tagged object: trim/slice use interval { start, end }, resample uses mapping = "identity", and time_warp uses required finite positive output_duration_s plus ordered control_points with input_time/output_time from (0,0) to (1,1). Between adjacent knots (x0, y0) and (x1, y1), it maps t by the exact piecewise-linear formula y0 + ((t - x0) / (x1 - x0)) * (y1 - y0); exact knots map exactly, and both window endpoints use the same rule. A known V1 tag with an invalid numeric domain or ordering remains representable for an invalid_mapping refusal and uses an empty pre-inventory event_outcomes list. An unknown kind, version, field, mapping token, missing field, or malformed field type is a strict request/reader error and produces no V1 result or event outcomes. input has exactly {artifact:{sha256,bytes},dependency_closure_identity:{sha256,bytes},fragment:{sha256,bytes}} and refers to a separately supplied input fragment. Successful output has exactly {artifact:{sha256,bytes},dependency_closure_identity:{sha256,bytes},fragment:{sha256,bytes},contact_fragment}; all three identities must match the inline complete contact-fragment:1 and its two input bindings. The output closure identity is freshly captured rather than copied, and its closure primary_input must equal output artifact. For trim/slice [a,b], a point is outside exactly when t < a || t > b; endpoints are included. A window is outside exactly when end < a || start > b, contained exactly when a <= start && end <= b, and otherwise boundary-crossing. A crossing window receives refused with code partial_window and refuses the whole operation. Known-operation mapping failures, binding mismatches, unsupported extensions, or partial windows produce a typed refused result with no output field. After binding and identity validation, event_outcomes has exactly one {event_id, outcome} object per input event in canonical input order. It adds value only for transformed exact point/window values and code only for refused events; pre-inventory binding, identity, mapping-validation, or extension-support refusal uses an empty list. Global success requires all events to be transformed or outside and requires output; global refusal requires top-level refusal and omits output. The inline output duration is input_duration_s * (b - a) for trim/slice, the input duration for resample, and the required output_duration_s for time_warp; the inline fragment and operation must agree exactly. A rounded trim/slice duration that is not finite and positive refuses before event inventory with invalid_value and an empty event_outcomes list. All time/duration inputs and results are finite IEEE 754 binary64. The normative sequence is dx = rn(x1 - x0), alpha = rn(rn(t - x0) / dx), dy = rn(y1 - y0), and mapped = rn(y0 + rn(alpha * dy)); an exact knot bypasses interpolation. Trim/slice uses span = rn(b - a), mapped = rn(rn(t - a) / span), and output_duration_s = rn(input_duration_s * span). Here rn is IEEE 754 binary64 round-to-nearest, ties-to-even, with no fused or extended-precision intermediate, so independent producers feed the same numeric results to JCS. Refusal codes are partial_window, invalid_mapping, invalid_binding, invalid_value, and unsupported_extension. Malformed fragments/results and duplicate, missing, or unknown event-outcome identities are strict reader errors, not refusal results.

animsmith-core implements this mapping and strict result reader. The reader requires the separately supplied input fragment plus an external transform context containing the current input/output artifacts, their complete captured closures, the expected producer, and any handler-produced extension outputs. It validates each closure against its artifact and independently rederives the operation, event outcomes, and successful inline fragment. Opaque extensions are never copied merely because a caller lists their schema/version: an exact handler-produced output is required at every input extension position. Its published JSON Schema is contact-transform-result-v1.schema.json. Asset time mutation and generation-directory publication are separate collection-producer responsibilities.

The success shape is an illustrative frozen 0.5.0 transform-contract snapshot:

{
  "schema": "urn:animsmith:schema:contact-transform-result:1",
  "schema_version": 1,
  "operation": {"kind": "trim", "version": 1, "interval": {"start": 0.1, "end": 0.9}},
  "input": {"artifact": {"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "bytes": 123456}, "dependency_closure_identity": {"sha256": "1111111111111111111111111111111111111111111111111111111111111111", "bytes": 456}, "fragment": {"sha256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789", "bytes": 789}},
  "outcome": "transformed",
  "event_outcomes": [
    {"event_id": "left-foot/0", "outcome": "transformed", "value": {"time": 0.1625}},
    {"event_id": "right-foot/0", "outcome": "transformed", "value": {"window": {"start": 0.7625, "end": 0.8625}}}
  ],
  "output": {
    "artifact": {"sha256": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210", "bytes": 123456},
    "dependency_closure_identity": {"sha256": "2222222222222222222222222222222222222222222222222222222222222222", "bytes": 654},
    "fragment": {"sha256": "a1d63b5e10381d2aa635cfd74218a4e5d42f3d61c1451765e25d47a23e02d633", "bytes": 729},
    "contact_fragment": {
      "schema": "urn:animsmith:schema:contact-fragment:1",
      "schema_version": 1,
      "producer": {"tool": "animsmith", "version": "0.5.0"},
      "artifact": {"sha256": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210", "bytes": 123456},
      "dependency_closure_identity": {"sha256": "2222222222222222222222222222222222222222222222222222222222222222", "bytes": 654},
      "clip": {"scope": "collection", "logical_id": "com.example.pack/locomotion/walk-forward-in-place", "source": "walk-forward", "take_index": 0, "take_name": "Take 001"},
      "duration_s": 0.96,
      "events": [
        {"event_id": "left-foot/0", "role": "left_foot", "phase": "marker", "time": 0.1625, "confidence": 0.92},
        {"event_id": "right-foot/0", "role": "right_foot", "phase": "begin", "window": {"start": 0.7625, "end": 0.8625}}
      ]
    }
  }
}

The delivered contact-fragment producer samples strict stance-support contacts and writes its own canonical fragment sidecar. Before constructing its metric grid, the producer requires finite positive timing and checked frames * bones pose cells plus frames * tracks sampling work, each at or below the inclusive one-million V1 CLI-producer ceiling. A refusal preserves the destination. These resource bounds are not engine or artistic evidence. The producer does not transform contacts, validate foot placement, map engine-native event types, merge into a host's final sidecar, or establish runtime behavior, gameplay meaning, or engine correctness.

Transition families (#148)

The transition-family V1 identity is urn:animsmith:schema:transition-family:1. A declaration has a stable family id, an explicit ordered member list, a boundary selection (entry, exit, or both), and closed typed tolerances with explicit units and basis.

The document-local transition_families tables are admitted by AnimSmith's strict config loader, which retains the exact whole-config input identity with the normalized declaration. animsmith evaluate-transition-poses INPUT --format json evaluates one document against that authority. The separate collection envelope is evaluated by animsmith collection evaluate-transition-poses COLLECTION.toml --families TRANSITION_FAMILIES.toml --format json: it first binds one exact manifest identity and verifies every logical/source/take witness, then reloads only the source keys selected by the declared members. A stale manifest or member witness is control (exit 2, no result); unavailable member input makes its whole family incomplete rather than comparing a survivor subset.

The format-neutral core provides the strict V1 skeleton-basis identity and immutable transition-pose evaluation result contract at urn:animsmith:schema:transition-pose-evaluation:1. The document and manifest-bound collection adapters publish the JSON-only commands above. The schema is checked in as transition-pose-evaluation-v1.schema.json. That docs schema is canonical; the core crate ships an exact checked snapshot so packaged integration tests retain the same contract without a repository path dependency. Its subject_input field binds the exact raw subject selected by the declaration scope: the document evaluator supplies document bytes and the collection evaluator supplies manifest bytes without forking the V1 result wire. The document evaluator accepts the loader's same-load DependencyClosureV1, derives subject_input only from its primary_input, and retains the complete subject_dependency_closure_identity both at the subject and as each member's source_dependency_closure_identity. A configured family cannot be complete unless closure coverage is complete and that identity is present; otherwise it is incomplete/not_evaluated with dependency_closure_incomplete. Empty document declarations still produce no_configured_families without requiring a closure because no source data is evaluated.

For collection scope, subject_input is the manifest identity and no manifest dependency closure is invented. Each available member instead binds its own raw source_input and complete source_dependency_closure_identity. A source that could not be opened may retain a null source_input; an incomplete member closure leaves its closure identity absent, makes the whole family dependency_closure_incomplete, and does not erase closure identities retained for other available members. This closure binding covers external glTF buffers that can change sampled animation while the primary JSON identity stays equal.

Document-local family ids are one lowercase-ASCII token, 1–255 bytes, starting with [a-z0-9] and continuing with [a-z0-9._-]. The table key itself is the id, with no duplicate family_id field; quote the key whenever punctuation or a dot is present (the canonical spelling quotes it always), such as [transition_families."walk_to_run"] or [transition_families."combat.entry.v1"]. Collection family ids retain Appendix F's slash-qualified logical-id grammar and collection-id prefix.

The declaration distinguishes two ownership scopes:

• document families are placed in the existing animsmith.toml under [transition_families."<family_id>"] and resolve exact embedded clip/take identities. The reusable config carries no artifact digest; the document evaluator binds the primary document InputIdentity and complete dependency-closure identity in its output.
• collection families use a separate declaration envelope, not the collection-manifest V1 itself. The envelope binds the exact manifest InputIdentity {sha256, bytes}, then resolves declared logical clip ids plus their source, take-index, and take-name witnesses.

Members cannot cross scopes, point to paths or animation-array indices, or be silently removed when missing or ambiguous. stale_digest is collection-only: it means the declaration's manifest InputIdentity no longer matches. A source digest pin in that manifest is enforced by manifest resolution; a mismatch makes the member unavailable rather than creating a second identity in this declaration. Reusable document-local config has no stale-digest state at parse time; the document evaluator binds the exact primary document InputIdentity plus its complete dependency-closure identity and reports source/take resolution in its output. The existing [clips], [gait_groups], and [sync_groups] sections remain document-local and are not replaced by a second collection authority. Both placements share the transition-family:1 family-record semantics; only ownership and placement differ. Family declarations are canonicalized by stable family id while preserving member order.

Both placements cap the exact declaration and normalized envelope at 8,388,608 source or canonical bytes and 16 container levels. They permit at most 4,096 families, 4,096 members per family, and 16,384 members in aggregate. Authored strings are at most 4,096 UTF-8 bytes, with the 255-byte identifier limits applied more strictly. Depth counts each table/array or JSON object/array on the root-to-value path, including the root as depth 1. Each exact maximum is accepted; N+1 is rejected during bounded decoding before retention or unbounded canonical allocation; canonical-byte limits use a bounded JCS sink.

A collection-scoped declaration uses the following typed TOML-like shape; each logical id is accompanied by the #409 source/take witness and must agree with the manifest:

schema = "urn:animsmith:schema:transition-family:1"
schema_version = 1
scope = "collection"
collection_id = "com.example.pack"
manifest_input_identity = { sha256 = "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789", bytes = 9876 }

[[families]]
family_id = "com.example.pack/transitions/walk-to-run"
boundary = "both"

[families.basis]
translation = "skeleton-local-metres"
rotation = "skeleton-local-degrees"
time = "normalized-clip"

[families.tolerances]
translation_m = 0.05
rotation_deg = 5.0
time_normalized = 0.02

[[families.members]]
logical_id = "com.example.pack/locomotion/walk-forward-in-place"
source = "walk-forward"
take_index = 0
take_name = "Take 001"

[[families.members]]
logical_id = "com.example.pack/locomotion/run-forward-in-place"
source = "run-forward"
take_index = 0
take_name = "Take 001"

The document-local placement uses the existing config basis and the same family-record semantics:

[transition_families."walk_to_run"]
schema = "urn:animsmith:schema:transition-family:1"
schema_version = 1
scope = "document"
boundary = "entry"

[transition_families."walk_to_run".basis]
translation = "skeleton-local-metres"
rotation = "skeleton-local-degrees"
time = "normalized-clip"

[transition_families."walk_to_run".tolerances]
translation_m = 0.05
rotation_deg = 5.0
time_normalized = 0.02

[[transition_families."walk_to_run".members]]
take_index = 0
take_name = "Walk"

[[transition_families."walk_to_run".members]]
take_index = 1
take_name = "Run"

The collection envelope's manifest digest/bytes binding makes a manifest edit or reorder stale even when collection and logical ids are unchanged. No runtime check or transition graph is implied by either placement.

Both placements normalize to the exact closed JSON envelopes shown in DESIGN.md §F.11: one collection form retaining collection_id and manifest_input_identity, and one document form in which each quoted table key becomes family_id. Families sort by id, member order is retained, and RFC 8785 JCS produces the normalized declaration identity. V1 evidence separately binds the exact declaration source, normalized declaration, and evaluated document or manifest identities.

AnimSmith 0.6.0 ships both the document and manifest-bound collection transition-pose commands from #153. They emit the V1 result but do not infer graph edges, add gameplay metadata, or generate engine state-machine or blend-tree data. Those runtime and gameplay consumers remain follow-up work, including #164.

The complete normative contract, including ownership, strict resolution, and canonical serialization rules, is in DESIGN.md §F.10 and §F.11.

Reference

• Configuration reference — Complete animsmith.toml tables, keys, defaults, precedence, validation, globs, rig profiles, and engine settings.
• Built-in check reference — Look up every registered built-in check: current IDs, default findings, prerequisites, config keys, gap semantics, and remediation boundaries.
• CLI reference — Look up a command, flag, or exit code.
• Machine-readable output — Parse versioned --format json reports, glTF animation-addressability inventories, engine import advice, and producer evidence in a pipeline, validated by the JSON Schema under schemas/.

animsmith.toml configuration reference

animsmith.toml is an optional, strict project contract. Document-local commands (lint, measure, inspect, report, transform, fix, generate, and evaluate-transition-poses) use --config FILE, or auto-load ./animsmith.toml; no file means built-in defaults. Collection commands have their own control-file rules (see cli.md). Unknown tables and keys are errors. The parser validates finite numeric domains; embedded callers should also call Config::validate.

This page is the user-facing authority for what every key means. For who owns each surface and where its value comes from, start from declaring the contract. Exact Rust types are in the animsmith-core::config API. The check rationale and coverage vocabulary are in game-ready-clips.md.

Precedence and the run model

CLI --select, --allow, and --deny-warnings apply after the file is read; CLI selection and failure policy therefore override file run policy. severity controls content findings, not coverage gaps or required engine prediction-unavailable facets. off disables an applicable check only where that check permits it; note, warn (or warning), and error enable an opt-in check. --allow ID hides matching content findings from the CLI gate; it never repairs input or suppresses required prediction work.

Clip selectors are resolved field-by-field. Every matching clips glob is overlaid in lexicographic key order; a literal clip-name entry is applied last. Thus an exact key wins over every glob, and a later lexicographically greater glob wins only for fields it declares. * matches any sequence (including an empty sequence); there is no ? or character-class syntax. Empty or missing selector lists declare no policy. Group member names are exact (not globs).

Top-level tables

Rig selection

Checks and severity

Every check accepts severity = "off", "note", "warn"/"warning", or "error". Omitted severity uses the check's implementation-defined default: all built-ins are enabled by default except opt-in constant-nonunit-scale. time-complement is enabled by default, but is NotApplicable until a sync group declares a time_complement policy; an explicit non-off severity enables the opt-in scale check. The runner still records unselected, disabled, and not-applicable checks. See game-ready-clips.md.

Settings not consumed by a particular check are harmless in that check's table, but a misspelled field is rejected by deny_unknown_fields.

Clip expectations

Runtime nodes and globs

runtime_nodes.selectors is an ordered string array. Each item is an exact source-node name or a * glob and must resolve to exactly one named node for rest-world-scale; no match and multiple matches are typed coverage gaps. Duplicate spellings are de-duplicated at first occurrence. Selectors do not cross node and bone namespaces, and do not infer a node from a rig role.

Gait and same-time groups

Engine profiles (CLI)

The four selection keys have no implicit default: engine.profile, engine.profile_revision, engine.engine_version, and engine.importer. Either omit [engine] or specify all four. Exact supported tuples and setting defaults are owned by the versioned animsmith-engine profiles. The profile is evidence about importer behavior, not a claim that an engine loaded or played the asset.

engine.settings accepts profile-defined keys; unknown keys or values are rejected when the selected profile resolves. Common revision-1 settings are engine.settings.convert_units (bool), engine.settings.bake_axis_conversion (bool), and engine.settings.root_motion_source (string path), plus per-clip clips.<selector>.engine_settings.root_rotation, clips.<selector>.engine_settings.root_position_y, and clips.<selector>.engine_settings.root_position_xz (bake or extract). Revision-2 profiles may define engine.settings.animation_type (generic|humanoid|legacy), engine.settings.avatar_setup (create_from_this_model|copy_from_other_avatar), engine.settings.import_animation (bool), engine.settings.root_motion_source (string), engine.settings.root_rotation, engine.settings.root_position_y, engine.settings.root_position_xz (bake|extract), engine.settings.rotate_scene_entity (bool), engine.settings.rotate_meshes (bool), engine.settings.load_meshes (empty|nonempty), engine.settings.extension_handler_environment (bare_empty|bevy_pbr_stock_0_19), engine.settings.bevy_animation_feature (bool), engine.settings.load_animations (bool), engine.settings.animation_fps (positive integer), engine.settings.animation_trimming (bool), and engine.settings.sample_rate (default_30, source_determined, or custom_hz(N)). Per-clip revision-2 root policies use the same clips.<selector>.engine_settings.root_rotation, clips.<selector>.engine_settings.root_position_y, and clips.<selector>.engine_settings.root_position_xz paths. A setting is either explicit or the profile's verified default; no generic default is invented.

Transition families

Document-local families are strict tables, not core Config fields:

[transition_families."walk_to_run"]
schema = "urn:animsmith:schema:transition-family:1"
schema_version = 1
scope = "document"
boundary = "both"                 # entry | exit | both
[transition_families."walk_to_run".basis]
translation = "skeleton-local-metres"
rotation = "skeleton-local-degrees"
time = "normalized-clip"
[transition_families."walk_to_run".tolerances]
translation_m = 0.05
rotation_deg = 5.0
time_normalized = 0.05
[[transition_families."walk_to_run".members]]
take_index = 0
take_name = "walk"

The complete bounded grammar and allowed values are documented in collection-contracts.md. It is read before generic config decoding, so malformed declarations report a transition-family control error and never become ordinary check findings.

Minimal and advanced configurations

The smallest semantic contract is one loop declaration:

[clips.walk]
loop = true

For a project contract, start with examples/character.animsmith.toml. It demonstrates rig roles, runtime-node globs, independent movement ownership, glob/exact cap precedence, severity, gait rings, and same-time groups. The Mixamo tutorial and examples/mixamo.animsmith.toml show the profile with an in-place XZ declaration. Bevy examples are bevy.animsmith.toml, bevy-v2.animsmith.toml, and bevy-v3.animsmith.toml. CI parse-tests these examples and this page's key inventory; update that test when adding configuration authority.

Common mistakes and errors

• unknown field or unknown variant: spelling/casing is not supported.
• must be a finite non-negative number: a cap, tolerance, or amplitude is negative, NaN, or infinite. Positive-only values have the corresponding positive error.
• cannot declare both ...: choose one runtime selector spelling and one horizontal movement-owner spelling per entry.
• bad config ...: parser, validation, profile, and transition-family errors include the selected path and exit 2; no asset is linted. A coverage gap during a valid run is evidence of a missing prerequisite, not a parse error.

When changing a contract, run with --format json and retain the config path and tool version with the output. A clean result is evidence for that file and declaration set, not certification of retargeting, engine runtime behavior, or artistic quality.

Built-in check reference

This is the customer-facing reference for every registered built-in check in AnimSmith's current catalog. It complements the concise README check catalog, what game-ready means, and the exact Rust API on docs.rs.

Use this page when you need the current built-in ID, default findings, declarations or prerequisites, config keys and units, skip or coverage-gap semantics, and the practical boundary between built-in tooling, runtime policy, and DCC-side correction.

off in the inventory below means the check is registered but opt-in by default. Once selected, every built-in check can still be made inactive with [checks.<id>] severity = "off", and any selected opt-in check becomes active only after an explicit note, warn, or error severity.

Inventory

Mechanical checks

nan

• Default findings: error.
• Measurement and finding: flags any non-finite key time or keyed value. A finding means interpolation and pose evaluation are no longer trustworthy.
• Prerequisites and applicability: none. This is generic file-ready coverage.
• Config, defaults, and units: [checks.nan] severity only.
• Inactive, not-applicable, and coverage gaps: never reports not_applicable or a typed coverage gap once selected.
• Remediation and boundary: there is no safe built-in repair because the source float is undefined. Re-export or correct the source in the DCC/export step.
• Runtime and references: one poisoned float can explode, freeze, or otherwise corrupt the pose in-engine. See The pose flickers, spins, or explodes and API: Nan.

time-monotonic

• Default findings: error for negative or non-increasing key times, note for a first key that starts materially after zero.
• Measurement and finding: checks that key times start at or near zero and move strictly forward. A finding means the runtime may clamp-hold or sample incorrectly the track.
• Prerequisites and applicability: none. This is generic file-ready coverage.
• Config, defaults, and units: [checks.time-monotonic] severity only.
• Inactive, not-applicable, and coverage gaps: never not_applicable and no typed gaps once selected.
• Remediation and boundary: fix the export or source timing in the DCC. Use transform --slice only for an intentional clip trim, not to salvage invalid key ordering.
• Runtime and references: late starts can hold an unauthored pose; bad ordering is a hard data defect. See The pose flickers, spins, or explodes and API: TimeMonotonic.

quat-norm

• Default findings: error.
• Measurement and finding: reports the worst rotation key whose quaternion norm deviates materially from 1.0.
• Prerequisites and applicability: none. This is generic file-ready coverage.
• Config, defaults, and units: [checks.quat-norm] severity only.
• Inactive, not-applicable, and coverage gaps: never not_applicable and no typed gaps once selected.
• Remediation and boundary: animsmith fix can renormalize finite, non-zero quaternions losslessly. If the source exporter keeps reintroducing the issue, correct that upstream.
• Runtime and references: non-unit rotations skew interpolation, skinning, and blends. See The pose flickers, spins, or explodes, CLI repairs, and API: QuatNorm.

quat-flip

• Default findings: warning.
• Measurement and finding: counts adjacent rotation keys on opposite hemispheres. A finding means neighborhood-uncorrected slerp can take the long path.
• Prerequisites and applicability: none. This is generic file-ready coverage.
• Config, defaults, and units: [checks.quat-flip] severity only.
• Inactive, not-applicable, and coverage gaps: never not_applicable and no typed gaps once selected.
• Remediation and boundary: animsmith fix can flip equivalent quaternion signs into a hemisphere-consistent track. Re-export if the source keeps emitting unstable signs.
• Runtime and references: the visible symptom is a sudden long-way spin between keys. See The pose flickers, spins, or explodes, CLI repairs, and API: QuatFlip.

duration-sanity

• Default findings: error for invalid or missed declared duration pins and degenerate clip lengths, warning for trackless clips or mismatched channel end times.
• Measurement and finding: checks clip duration, optional declared duration_s, and spread between multi-key channel end times.
• Prerequisites and applicability: none. Declared duration pins refine a check that is otherwise generic.
• Config, defaults, and units: [checks.duration-sanity] severity; optional clips.<name>.duration_s.value and clips.<name>.duration_s.tolerance, both in seconds.
• Inactive, not-applicable, and coverage gaps: never not_applicable and no typed gaps once selected.
• Remediation and boundary: correct the authored range or export in the DCC. transform --slice and transform --hold-extend are explicit editing tools when the clip is intentionally being reshaped, not automatic correctness repairs.
• Runtime and references: bad duration contracts freeze shorter channels or desync gameplay timing. See The clip is the wrong length or freezes at the end and API: DurationSanity.

scale-keys

• Default findings: warning.
• Measurement and finding: reports temporally varying scale tracks.
• Prerequisites and applicability: none. This is generic file-ready coverage.
• Config, defaults, and units: [checks.scale-keys] severity only.
• Inactive, not-applicable, and coverage gaps: never not_applicable and no typed gaps once selected.
• Remediation and boundary: remove accidental animated scale in the DCC or export settings. Treat retained scale animation as an intentional authored choice that downstream runtime and retargeter owners must explicitly accept.
• Runtime and references: many rigs and retargeters mishandle animated scale. See The file is bloated, or the retargeter chokes and API: ScaleKeys.

non-uniform-scale

• Default findings: warning.
• Measurement and finding: reports scale tracks whose evaluated axis lengths are materially unequal.
• Prerequisites and applicability: none. This is generic file-ready coverage.
• Config, defaults, and units: [checks.non-uniform-scale] severity only.
• Inactive, not-applicable, and coverage gaps: never not_applicable and no typed gaps once selected.
• Remediation and boundary: normalize the authored transform in the DCC or export path unless your runtime and retargeter contract explicitly accepts the non-uniform scale.
• Runtime and references: non-uniform scale is a common retargeting and rig failure source. See The file is bloated, or the retargeter chokes and API: NonUniformScale.

constant-nonunit-scale

• Default findings: off by default; once enabled, findings are note.
• Measurement and finding: reports scale channels that stay constant but not at unit scale, including single-key pins.
• Prerequisites and applicability: none. This is a policy signal, not a mandatory file-ready failure.
• Config, defaults, and units: [checks.constant-nonunit-scale] severity only.
• Inactive, not-applicable, and coverage gaps: inactive until an explicit severity enables it; never reports typed gaps once active.
• Remediation and boundary: clean up the authored scale in the DCC if your runtime policy expects unit scale. Keep it enabled only when your team wants to surface that policy in lint results.
• Runtime and references: constant non-unit scale can still affect import, attachment, and retargeting expectations. See The file is bloated, or the retargeter chokes and API: ConstantNonunitScale.

constant-track

• Default findings: note.
• Measurement and finding: reports multi-key translation, rotation, or scale tracks that never materially move.
• Prerequisites and applicability: none. This is generic file-ready coverage.
• Config, defaults, and units: [checks.constant-track] severity only.
• Inactive, not-applicable, and coverage gaps: never not_applicable and no typed gaps once selected.
• Remediation and boundary: transform --prune-constant-tracks can remove the subset AnimSmith can prove redundant. Use DCC cleanup when the track carries authoring intent, unsupported curves, or broader rig cleanup.
• Runtime and references: constant multi-key tracks are usually export bloat, but removing them still needs contract review for transition and required motion evidence. See The file is bloated, or the retargeter chokes, Editing a clip, and API: ConstantTrack.

Contract-aware checks

required-bones

• Default findings: error.
• Measurement and finding: checks that every distinct name in rig.required_bones exists exactly once in the skeleton.
• Prerequisites and applicability: active only when rig.required_bones is non-empty. A usable skeleton is required.
• Config, defaults, and units: [checks.required-bones] severity and rig.required_bones.
• Inactive, not-applicable, and coverage gaps: not_applicable with no declared required bones; reports a skeleton_unavailable coverage gap when the file has no usable skeleton.
• Remediation and boundary: fix the exported skeleton, naming, or rig mapping in the DCC/export pipeline. This is not a clip-level animation repair.
• Runtime and references: missing sockets, IK targets, or mask bones break downstream binding even if no clip animates them. See A limb is T-posed, or a bone never moves and API: RequiredBones.

rest-world-scale

• Default findings: warning.
• Measurement and finding: checks the effective rest-world linear transform of explicitly selected source nodes against a uniform scale policy.
• Prerequisites and applicability: active only when runtime_nodes.selectors or the legacy checks.rest-world-scale.node_selectors alias declares at least one selector. Source-node transform evidence must exist, and each selector must resolve exactly once.
• Config, defaults, and units: [checks.rest-world-scale] severity, expected_uniform_scale default 1.0, and uniform_scale_tolerance default 0.0001; selectors live in runtime_nodes.selectors, with the legacy alias accepted only when the shared field is absent.
• Inactive, not-applicable, and coverage gaps: not_applicable without selectors; gaps report no-match, ambiguous selector resolution, or unavailable source-node transform evidence.
• Remediation and boundary: if the source is uniformly wrong, decide between scale whole-document, scale rest-bind, or DCC/export correction based on the actual scale problem. This check reports source-node evidence; it does not infer which rewrite you intend.
• Runtime and references: wrong rest-world scale breaks sockets, attachments, gameplay references, and engine-side assumptions even when animation keys are otherwise valid. See Scaling glTF safely, glTF and generic runtime guide, and API: RestWorldScale.

missing-bones

• Default findings: error.
• Measurement and finding: checks that each declared animates_bones member exists and carries at least one keyed track in the clip.
• Prerequisites and applicability: active only on clips that declare animates_bones.
• Config, defaults, and units: [checks.missing-bones] severity and clips.<name>.animates_bones.
• Inactive, not-applicable, and coverage gaps: not_applicable on clips without animates_bones; no typed coverage gaps once the declaration exists.
• Remediation and boundary: restore the missing keyed channel or correct the source clip and rig in the DCC/export path.
• Runtime and references: declared motion that never reaches the file reads as a static or wrong-rig limb at runtime. See A limb is T-posed, or a bone never moves and API: MissingBones.

frozen-bone

• Default findings: error.
• Measurement and finding: checks whether each declared animated bone rotates beyond the configured floor across the clip.
• Prerequisites and applicability: active only on clips that declare animates_bones. The bone must exist and carry at least one keyed track.
• Config, defaults, and units: [checks.frozen-bone] severity, min_rotation_deg default 1.0 degrees, and clips.<name>.animates_bones.
• Inactive, not-applicable, and coverage gaps: not_applicable on clips without animates_bones; no typed gaps once the declaration exists. Missing bones themselves belong to missing-bones.
• Remediation and boundary: correct the source clip, wrong slice, or masked-out track in the DCC/export pipeline.
• Runtime and references: the visible symptom is a limb that stays pinned, T-posed, or otherwise fails to animate even though the clip says it should. See A limb is T-posed, or a bone never moves and API: FrozenBone.

duplicate-loop-endpoint

• Default findings: warning.
• Measurement and finding: checks for the strict authored-key case where a declared loop repeats its first pose at the final endpoint and that closing key can be removed mechanically.
• Prerequisites and applicability: active only on clips declared loop = true, and only when authored endpoint analysis is available.
• Config, defaults, and units: [checks.duplicate-loop-endpoint] severity and clips.<name>.loop.
• Inactive, not-applicable, and coverage gaps: not_applicable when no clip declares a loop. Reports a measurement-unavailable gap when authored endpoint analysis cannot classify the clip.
• Remediation and boundary: transform --drop-duplicate-loop-endpoint can trim the mechanically removable endpoint subset. Non-classified loop endpoint modes still need authored review or a different transform.
• Runtime and references: redundant inclusive endpoints are a common DCC export artifact and can affect downstream loop handling. See The loop pops, Editing a clip, and API: DuplicateLoopEndpoint.

loop-closure

• Default findings: error.
• Measurement and finding: checks the largest per-bone model-space position and rotation delta between the final and first loop sample.
• Prerequisites and applicability: active only on clips declared loop = true and only when loop-continuity samples exist.
• Config, defaults, and units: [checks.loop-closure] severity, max_position_delta_m default 0.01 metres, max_rotation_delta_deg default 1.0 degrees, plus per-clip overrides clips.<name>.max_loop_position_delta_m and clips.<name>.max_loop_rotation_delta_deg.
• Inactive, not-applicable, and coverage gaps: not_applicable when no clip declares a loop. Reports measurement-unavailable gaps when the sampled loop-continuity evidence is missing or unusable for one or more bones.
• Remediation and boundary: re-author, reslice, or re-export the loop in the DCC. This is a diagnosis, not an automatic loop repair.
• Runtime and references: a failed closure produces an obvious pose jump at the wrap. See The loop pops and API: LoopClosure.

loop-seam

• Default findings: error.
• Measurement and finding: checks the feet-relative-to-hips wrap discontinuity, normalized by seam-adjacent in-clip step length.
• Prerequisites and applicability: active only on clips declared loop = true and only when hips plus at least one foot role resolve and a usable stride step can be sampled.
• Config, defaults, and units: [checks.loop-seam] severity, max_ratio default 1.5, and min_stride_step_m defaulting to the built-in minimum stride floor used by the metrics.
• Inactive, not-applicable, and coverage gaps: not_applicable when no clip declares a loop. Gaps report unresolved gait roles, clips too short to sample a cycle, unavailable foot-cycle metrics, or no usable stride step.
• Remediation and boundary: fix the loop cut or cycle in the DCC. AnimSmith intentionally reports the seam evidence rather than inventing a repair.
• Runtime and references: the symptom is a once-per-cycle pop even when the raw file is format-valid. See The loop pops and API: LoopSeam.

loop-seam-vel

• Default findings: error.
• Measurement and finding: checks the largest per-bone model-space linear velocity change between the incoming and outgoing loop seam.
• Prerequisites and applicability: active only on clips declared loop = true and only when loop-continuity samples exist.
• Config, defaults, and units: [checks.loop-seam-vel] severity, max_velocity_delta_mps default 0.1 metres per second, plus the per-clip override clips.<name>.max_loop_velocity_delta_mps.
• Inactive, not-applicable, and coverage gaps: not_applicable when no clip declares a loop. Reports measurement-unavailable gaps when loop-continuity samples are missing or unusable.
• Remediation and boundary: correct the authored wrap or the export timing in the DCC; there is no built-in automatic velocity repair.
• Runtime and references: this is the once-per-cycle hitch where the clip hits the right pose but changes speed abruptly at the seam. See The loop pops and API: LoopSeamVelocity.

loop-seam-rot

• Default findings: error.
• Measurement and finding: checks the largest per-bone model-space angular velocity change between the incoming and outgoing loop seam.
• Prerequisites and applicability: active only on clips declared loop = true and only when loop-continuity samples exist.
• Config, defaults, and units: [checks.loop-seam-rot] severity, max_angular_velocity_delta_degps default 5.0 degrees per second, plus the per-clip override clips.<name>.max_loop_angular_velocity_delta_degps.
• Inactive, not-applicable, and coverage gaps: not_applicable when no clip declares a loop. Reports measurement-unavailable gaps when loop-continuity samples are missing or unusable.
• Remediation and boundary: correct the authored wrap or export timing in the DCC; there is no built-in automatic angular-velocity repair.
• Runtime and references: this is the rotational version of a loop hitch or pulse at the seam. See The loop pops and API: LoopSeamRotation.

root-motion-speed

• Default findings: error.
• Measurement and finding: compares measured horizontal root travel against a declared speed_mps pin for clips whose XZ owner is not gameplay.
• Prerequisites and applicability: active only when a clip declares speed_mps and does not declare gameplay-owned XZ travel. Root or hips role resolution and measurable root travel are required.
• Config, defaults, and units: [checks.root-motion-speed] severity, clips.<name>.speed_mps.value, clips.<name>.speed_mps.tolerance, and the XZ owner via clips.<name>.movement_owner_xz or the compatibility alias clips.<name>.in_place.
• Inactive, not-applicable, and coverage gaps: not_applicable with no relevant speed pin. Gaps report unresolved root or hips roles or unavailable measured root-motion speed.
• Remediation and boundary: fix the clip's actual travel or the declared speed contract in the DCC/export path or config. This is not a runtime retiming suggestion from AnimSmith.
• Runtime and references: stale speed pins make motion-scaled playback slide or moonwalk. See The character glides or runs in place and API: RootMotionSpeed.

gait-group

• Default findings: error.
• Measurement and finding: compares measured gait phases across each declared blend-ring group and reports spread beyond the configured cap.
• Prerequisites and applicability: active only when gait_groups is non-empty. Hips and foot roles must resolve, and at least two members need measurable gait evidence above the configured amplitude floor.
• Config, defaults, and units: [checks.gait-group] severity, plus gait_groups.<name>.clips, gait_groups.<name>.max_gait_phase_spread in cycle fraction, and gait_groups.<name>.min_lr_amplitude_m in metres.
• Inactive, not-applicable, and coverage gaps: not_applicable with no gait groups. Gaps report unresolved gait roles, missing members, too few measurable members, or members excluded because phase evidence is unavailable or below the amplitude floor.
• Remediation and boundary: correct clip timing, loop structure, or selection in the DCC and review the declared group. AnimSmith does not reorder or retime the group automatically.
• Runtime and references: phase drift between directional blends shows up as sliding or popping feet when clips crossfade. See Directional blend members travel at different speeds and API: GaitGroup.

sync-group

• Default findings: error.
• Measurement and finding: compares declared same-time group members for duration, frame count, frame grid, and loop endpoint mode compatibility.
• Prerequisites and applicability: active only when sync_groups is non-empty, and each group needs at least two present members before full comparison is possible.
• Config, defaults, and units: [checks.sync-group] severity, plus sync_groups.<name>.clips, sync_groups.<name>.max_duration_delta_s in seconds, sync_groups.<name>.max_frame_count_delta in frames, and sync_groups.<name>.max_fps_delta in frames per second.
• Inactive, not-applicable, and coverage gaps: not_applicable with no sync groups. Gaps report missing members, too few present or measurable members, unavailable durations, unusable frame-grid evidence, or unavailable loop endpoint evidence.
• Remediation and boundary: realign or rebuild the compared clips and the group declaration in the DCC/export pipeline. This check reports compatibility; it does not choose a runtime retiming strategy.
• Runtime and references: mismatched same-time clips blend or switch at different semantic moments. See Feet skate when clips blend and API: SyncGroupCheck.

time-complement

• Default findings: warning.
• Measurement and finding: compares each declared same-time pair's gait-phase similarity against the similarity after reflecting one member's normalized cycle time.
• Prerequisites and applicability: active only when a sync group enables time_complement. Hips and foot roles must resolve, and at least two members need measurable gait phase above the configured amplitude floor.
• Config, defaults, and units: [checks.time-complement] severity, plus sync_groups.<name>.time_complement.min_reflected_time_advantage in [0, 1] and sync_groups.<name>.time_complement.min_lr_amplitude_m in metres. The check also uses sync_groups.<name>.clips.
• Inactive, not-applicable, and coverage gaps: not_applicable with no enabled time-complement policy. Gaps report missing members, unresolved gait roles, unavailable phase evidence, or too few measurable members.
• Remediation and boundary: treat this as a sync-diagnostic for authoring or runtime review, not as proof that time reflection is the right runtime fix.
• Runtime and references: a warning means same-time pairing may be working against the measured gait evidence. See Feet skate when clips blend and API: TimeComplement.

in-place

• Default findings: error.
• Measurement and finding: compares the declared horizontal movement owner to measured horizontal root travel.
• Prerequisites and applicability: active only when a clip declares movement_owner_xz or its compatibility alias in_place. Root or hips role resolution and measurable root travel are required.
• Config, defaults, and units: [checks.in-place] severity, clips.<name>.movement_owner_xz, or the compatibility alias clips.<name>.in_place.
• Inactive, not-applicable, and coverage gaps: not_applicable when no clip declares horizontal movement ownership. Gaps report unresolved root or hips roles or unavailable measured root speed.
• Remediation and boundary: fix the clip or the declared ownership in the DCC, export path, or contract config. This is an intent mismatch, not a built-in transform target.
• Runtime and references: a mismatch becomes visible gliding or running in place. See The character glides or runs in place and API: InPlace.

fps

• Default findings: warning.
• Measurement and finding: checks that a declared clip duration spans a whole number of frames and that keyed times stay on the declared frame grid.
• Prerequisites and applicability: active only on clips that declare fps.
• Config, defaults, and units: [checks.fps] severity and clips.<name>.fps in frames per second.
• Inactive, not-applicable, and coverage gaps: not_applicable on clips without fps. Reports an invalid_declared_fps coverage gap when the declared frame rate is non-finite or non-positive.
• Remediation and boundary: correct the authored frame rate or retiming in the DCC/export path. transform --slice is appropriate for an intentional frame-aligned cut, not for arbitrary resampling drift.
• Runtime and references: off-grid keys and fractional frame counts are common importer pain points. See The clip is the wrong length or freezes at the end and API: Fps.

bind-pose

• Default findings: warning.
• Measurement and finding: checks the mean first-frame rotation deviation from rest across bones with usable rotation tracks.
• Prerequisites and applicability: active whenever the file has clips. A clip needs at least three usable first-frame rotation tracks before the check can evaluate it.
• Config, defaults, and units: [checks.bind-pose] severity and max_mean_rest_delta_deg default 45 degrees.
• Inactive, not-applicable, and coverage gaps: not_applicable only when the document has no clips. Reports insufficient_rotation_evidence when a clip lacks enough usable first-frame rotation tracks.
• Remediation and boundary: correct the seed rig, export skeleton, or clip source in the DCC/export path. This is not a rest-bind scale rewrite.
• Runtime and references: a mismatched bind often presents as the wrong base pose or wrong-skeleton clip. See Files disagree about skeleton or clip identity and API: BindPose.

foot-slide

• Default findings: warning.
• Measurement and finding: checks whether each stance foot moves consistently with the declared speed_mps and the clip's measured horizontal root speed.
• Prerequisites and applicability: active only on clips that declare speed_mps. Root or hips roles must resolve, the clip must be long enough to sample stance, and a foot or toe role must resolve for each judged side.
• Config, defaults, and units: [checks.foot-slide] severity, contact_height_m default 0.03 metres, max_slide_mps default 0.3 metres per second. The clip-level speed_mps declaration is the prerequisite, not a foot-slide check setting.
• Inactive, not-applicable, and coverage gaps: not_applicable with no speed pin. Gaps report unresolved root or hips roles, clips too short to sample stance, unavailable root-motion speed, or unresolved foot or toe roles.
• Remediation and boundary: fix foot plants, root travel, or the declared speed pin in the DCC/export path and then review the runtime blend setup. This heuristic check intentionally does not auto-rewrite contact or infer movement ownership.
• Runtime and references: failed stance motion shows up as skating or slipping feet in motion or blends. See Feet slide within one clip and API: FootSlide.

animsmith CLI

animsmith is designed for artist inner loops, CI gates, and pipeline automation. It reads glTF/GLB everywhere; the released default build also reads FBX through the fbx feature. The CLI is tested on Linux, macOS, and Windows.

Install

Install the released CLI by downloading the archive for your platform from GitHub Releases:

Each archive has a matching .sha256 checksum file.

You can also install from crates.io with Cargo:

cargo install animsmith

From a source checkout, prefix commands with cargo run -p animsmith --.

Help

Every command has generated help:

animsmith --help
animsmith lint --help
animsmith fix --help
animsmith generate addressability --help
animsmith generate contact-fragment --help

There are no man pages yet, so --help is the canonical installed CLI reference. The help output reflects compile-time features: a --no-default-features binary omits feature-gated commands such as report, convert, and assemble.

animsmith --version states that same compile-time surface in one line:

animsmith <version> (<git describe of the source>) [features: fbx, report]

The parenthesized part appears only for a binary built from a checkout whose commit is not exactly the release tag. [features: ...] names the Cargo features that were compiled in, alphabetically, and reads [features: none] for a --no-default-features build: fbx means the binary reads FBX input, report means it can render HTML reports. The line is a label the build stamps on itself, so treat it as identification rather than as proof — run the command you depend on when a build's capabilities have to be established.

Commands

animsmith inspect <file>
animsmith measure <file...> [--format text|json]
animsmith lint <file...> [--format text|json|markdown] [--select id[,id]] [--allow id[,id]] [--deny-warnings]
animsmith evaluate-transition-poses <input.glb|input.gltf|input.fbx> [--config animsmith.toml] --format json
animsmith collection lint <collection.toml> [--format json]
animsmith collection dashboard --collection <collection-output.json> -o <dashboard.html> --authority <dashboard.json> [--evaluation <transition-pose-evaluation.json>] [--asset-report <logical-id>=<relative-report.html>]
animsmith collection generate-contact-fragment <manifest.toml> --clip <logical-id> -o <out.json> [--format text|json]
animsmith collection evaluate-directional-speed --policy <policy.toml> --evidence <collection-output.json> [--format json]
animsmith collection evaluate-transition-poses <collection.toml> --families <transition-families.toml> --format json
animsmith report <file> -o <report.html> [--clip name] [--evidence-only]
animsmith report <before> -o <comparison.html> --compare-after <after> --before-clip <before-name> --after-clip <after-name> [--evidence-only]
animsmith transform <file> -o <out.glb> [--clip name] [--slice START:END] [--hold-extend SECONDS] [--gait-anchor] [--drop-duplicate-loop-endpoint] [--prune-constant-tracks] [--fps N]
animsmith fix <file> (-o <out.glb>|--in-place|--dry-run) [--repair id[,id]]
animsmith convert <in.fbx|in.glb|in.gltf> -o <out.glb|out.gltf> [--material-texture-recipe recipe.toml] [--animation-only|--bake-static-mesh-transforms] [--format text|json]
animsmith assemble <recipe.toml> -o <out.glb> --evidence <out.json> [--format text|json]
animsmith scale whole-document <in.glb|in.gltf> -o <out.glb|out.gltf> --factor N --evidence <out.json> [--format text|json]
animsmith scale rest-bind <in.glb|in.gltf> -o <out.glb|out.gltf> --source-skin-index N --source-root-node-index N --expected-factor N --evidence <out.json> [--format text|json]
animsmith generate addressability <in.glb|in.gltf> [--format json|text|markdown]
animsmith generate contact-fragment <in.glb|in.gltf|in.fbx> --clip <take-name> -o <out.json> [--format text|json]
animsmith diff <before> <after> [--format text|json]
animsmith skeleton compare <source.glb|source.gltf|source.fbx> <target.glb|target.gltf|target.fbx> --correspondence <skeleton-correspondence.toml> [--format text|json]

inspect is the human-readable discovery view for exact asset-authored names. It inventories clips, bones, materials, and mesh-instance nodes, including each instance's mesh, skin status, and primitive/material context. Use those names when authoring assemble or material texture recipes.

Structural skeleton comparison

skeleton compare establishes only declared structural compatibility evidence for one source asset and one immutable target asset. It does not retarget, rewrite rest or bind data, infer aliases, generate an engine avatar, or prove runtime deformation, masking, contact, gameplay, or artistic acceptance.

The correspondence control is strict and identity-pinned. Generate its two input identities from the exact source and target bytes you intend to compare; a changed asset is a stale control input and exits 2 without a result. The selector declares the complete finite node-name set on each side; it does not infer a subtree from root_name. The named root must be included, every name must resolve exactly once in its input, and only these explicitly selected nodes contribute rows. This prevents meshes, props, cameras, and other scene attachments from silently becoming skeleton evidence. Parent comparison walks through unselected intermediate nodes to the nearest selected ancestor, so it describes this declared projection rather than the complete raw hierarchy. All tolerances are mandatory and have no defaults:

schema = "urn:animsmith:skeleton-correspondence:1"
schema_version = 1

[source]
input = { sha256 = "<64 lowercase hex characters>", bytes = 12345 }
selector = { root_name = "Hips", node_names = ["Hips", "Spine", "Head"] }

[target]
input = { sha256 = "<64 lowercase hex characters>", bytes = 23456 }
selector = { root_name = "Hips", node_names = ["Hips", "Spine", "Head"] }

[correspondence]
mode = "exact_name"

[tolerances]
translation_m = 0.001
rotation_deg = 0.1
scale_delta = 0.001
normalized_bone_length_ratio_delta = 0.01

For a deliberate rename, replace the correspondence table with a finite, one-to-one explicit map. Every map key and value must already be in the respective declared selector; the map is authority, not a suggestion:

[correspondence]
mode = "explicit"
map = { Hips = "Root", Spine = "Spine_01" }

The versioned urn:animsmith:schema:skeleton-compatibility:1 JSON result binds both primary inputs, complete dependency closures when they are available, the correspondence bytes, normalized basis, selectors, matching mode, and tolerances. It reports matched, missing, extra, and parent-mismatch rows; local and rest-world transform deltas; and child bone-length ratios where both corresponding parent/child rest-world positions are available. compatible means all required topology/rest facts were available and within the declared tolerances. incompatible names a complete mismatch. partial and not_evaluated record unavailable evidence and exit 1. Skin membership, inverse-bind evidence, and deformation-model evidence are separate facets; they never become an opaque score or turn this structural result into a deformation claim.

report --compare-after writes one offline synchronized before/after diagnostic. Both input files and both clip names are explicit; it refuses duplicate or incompatible named skeletons, missing/ambiguous clips, unavailable metric grids, identical or incomplete rooted dependency closures, and report work beyond its fixed bounds. Authored duplicate take names remain ambiguous even when a loader gives normalized clips distinct display suffixes. Each panel shows both its primary input and complete closure identity, and includes only selected-clip or whole-input gaps and predictions. The output cannot alias either primary input, a rooted sidecar, or the selected config; refusal preserves any existing output. The two panels synchronize by normalized sampled-frame phase and display both source times — that display mapping is not an authored time warp. Findings, coverage gaps, prediction provenance, and identities remain separate per side. Selecting a finding scrubs the linked time and highlights its uniquely mapped bone. One toggle beside the shared phase draws the two judged poses in a single pane instead of two — the before skeleton solid, the after one dashed over it, at the same two selected frames and through the same shared camera — and the two-pane layout stays the default. The overlay stands down while a loop-seam context is selected, because that context is one side's own two endpoint frames rather than one shared phase. The report is evidence for troubleshooting, not an artistic, gameplay, engine, or retargeting acceptance verdict.

--evidence-only omits the sampled pose grid from either report form and sets "evidence_only": true in the embedded data. The grid is the motion — every bone's model-space position on every judged frame — so a full report of a licensed clip carries that clip. Both forms keep their findings, coverage gaps and engine predictions; the comparison also keeps both sides' input identities, and the single-clip report its profile and source path (when the document has one). Both show a notice where each pose view would be and disable playback; the comparison also disables its pose overlay, which draws the same grid. So the document can be attached to an issue, published, or sent to a vendor where the source asset itself may not go (see the licensed-asset policy). Nothing else about the run changes: the same checks evaluate the same frames.

What is left to look at differs by form, because only one of them draws its charts on the Rust side. The single-clip report keeps its charts, and they retain exactly the root's X/Z path, the two foot-height series relative to the hips plus their difference, the last on its own right-hand axis, and — for each declared gait group with a member in the file — one left-minus-right foot-height series per member with its measured stride anchor. Nothing in any of them is per bone.

--clip NAME and the gait-group figure meet deliberately. The clip filter scopes the document to one clip: its pose grid, its findings and its own two charts. A gait group is a contract between clips, so the figure for a group that clip belongs to keeps drawing and naming every declared member — a group compared against one of its own members is not a comparison. Groups the selected clip does not belong to are not drawn at all. What that publishes beyond the selected clip is one left-minus-right foot-height series and one measured anchor per member, which is the single-series metric evidence the licensed-asset policy allows; the pose grid of a clip the filter excluded is never embedded. Every comparison panel is a viewer drawing made from the pose grid — both role-trajectory panels, both gait panels, and the shared root chart — so an evidence-only comparison replaces all of them with the same notice. Everything else the full comparison embeds stays: findings, coverage gaps, prediction provenance, identities, clip metadata, and the contexts each side was judged in. Rendering those panels on the Rust side is tracked as follow-up work and would restore them.

Both report forms follow the reader's prefers-color-scheme and read a URL fragment of &-separated key=value options, so one generated file can be deep-linked or embedded without regenerating it. Both honour theme=light and theme=dark, which pin the palette; embed=1, whose rules hide the running title and the interaction hint and nothing else, so the document fits an <iframe> with its findings, charts, and evidence disclosures in place; and frame=N, which scrubs to a judged frame. clip=NAME, with=NAME, and finding=INDEX are single-clip options — they land where clicking that clip, that pairing, or that finding lands, on the same selected row, frame, chart playhead, and 3D view — while the comparison addresses a finding through the #finding-<side>-<anchor> link its own panels carry, because its clip correspondence is declared by the two inputs rather than chosen in the viewer.

with=NAME names a second clip of the same document to play beside the selected one, which the viewer's with control also chooses. The two poses occupy the two halves of the one canvas, drawn through a single camera fitted to both clips' bounds so they share a scale, and coloured by the report's left/right tokens; a key below the canvas names each half in the colour that half is drawn in, and both clips' charts are shown.

The transport drives the selected clip, and each half is shown at the frame nearest the transport's normalized phase in its own grid, with both source times labelled. That one frame is also where that clip's chart playhead and root-path dot sit, so a chart never reports a frame other than the one its pose is drawn at. This source-phase mapping selects samples the checks already judged; it does not retime or resample authored clip time. An empty value, a missing or ambiguous name, and the selected clip's own name clear the pair. An evidence-only report has no sampled positions or local transforms to draw, so the omission notice replaces playback and the pairing selects charts only.

With two clips selected, enable illustrative blend to add a third pane. The weight slider runs from the primary clip at 0 to the paired clip at 1, starting at 0.5. The pane blends their sampled local transforms and runs forward kinematics; it does not interpolate model-space joint positions. It is labelled engine-agnostic illustrative blend, not Bevy, Unity, Unreal or Godot runtime evidence. Both source frames/times and the weight remain visible. The phase still chooses the nearest frame independently in each grid, so unequal durations are paired by phase rather than source seconds.

All panes share the source-based camera and existing orbit/zoom controls. Interior rotations can extend beyond the initial source bounds; zoom out if needed. Oversized added local data or malformed local samples show a blending omission reason without removing source findings or playback. The HTML blend contract defines the math, limits and motion-data boundary.

A key that is absent leaves that state as it is, so following one of those anchors inside an embedded, theme-pinned report does not un-pin it. A key that is present is applied as far as the document allows: a syntactically valid frame beyond the clip is clamped to its last frame, and a clip the document does not contain selects the first one, because a reader who asks for a position wants the nearest one the report can show. A value the parser cannot read at all restores that state's default instead — an unparsable frame restores frame 0, an unparsable clip the first clip, and a finding index the document cannot address clears the selection. Unknown keys and malformed pairs are ignored, no option changes the findings, coverage, or charts the document carries, and no viewer writes the fragment back.

The checked-in synthetic comparison walkthrough demonstrates seam endpoints, sampled stance and foot trajectories, shared-scale root paths, and visually unchanged structural-track remediation. Its generated GLBs are byte-checked against the repository-owned fixture builder in CI.

--config animsmith.toml is global for document-local commands. Without it, the CLI auto-loads ./animsmith.toml when present and otherwise uses built-in defaults. Collection commands deliberately reject the global spelling. collection lint uses each source config declared in the collection manifest, or exact built-in defaults when none is declared; it never discovers an ambient ./animsmith.toml. collection evaluate-directional-speed has no config or output-path option: its policy and evidence inputs fully declare its boundary.

collection dashboard is an offline current-state view, not a second collection ledger. It accepts only the strict current collection-output V11 contract, writes a self-contained HTML file and the separately versioned urn:animsmith:schema:collection-dashboard:1 authority that binds the exact input bytes, and never reloads source assets. Its optional transition-pose evaluation must bind the same manifest bytes. --asset-report names an exact logical clip and a safe relative HTML reference; the dashboard links it but never embeds source assets or samples. Its role filter means already-recorded resolved skeletal roles, not inferred gameplay or clip semantics. Filtering only hides rows locally: it cannot turn partial, unavailable, excluded, or incomplete evidence into a complete collection. The separate declared-source inventory remains visible even for sources with zero logical clips and retains observed identity plus availability, loader, and dependency-closure states. Every observed physical take remains source-owned and records its source take index/name, normalized index/name state, evidence, and outcome even when no logical clip declares it. Global finding/gap/prediction totals derive from those physical rows plus unscoped source findings and unscoped source-level required_prediction_unavailable facets; logical rows are navigation projections and are not counted a second time. Source/document findings without an exact clip match remain explicit unscoped source findings and still contribute to the unfiltered finding total; they are never guessed onto a clip row. Subjectless required-unavailable prediction facets likewise remain explicit source-level dashboard evidence with their recorded reasons; the dashboard does not invent a take or logical clip witness for them. When one source contains the same normalized name at multiple physical indices, name-addressed nested evidence has no unique witness. The dashboard retains each finding once as unscoped source evidence and marks the affected physical rows duplicate_normalized_clip_name; it does not copy findings, gaps, or predictions onto either take or logical row. Optional transition members carry a logical clip only when their source-input identity plus take index/name uniquely match one dashboard declaration. Strict readback rederives that relationship and rejects missing, forged, or ambiguous logical resolution. Every logical row whose availability is established must also reconcile its source, source-take index/name, evidence, coverage, and outcome with exactly one source-owned established physical row. Runtime-set gaps and lifecycle are also rederived from member availability: each non-established member requires one member_unavailable gap in member order, and complete is valid only when that derived gap list is empty. Strict readback rejects contradictions.

evaluate-transition-poses is a JSON-only, single-result transition-family contract, not a lint/check stream. It evaluates exact named/indexed takes in the input against document-local [transition_families."<id>"] declarations and never changes the input. When no config file is selected or found, its declaration authority is the exact zero-byte TOML input; this is deliberately the same authority as an explicitly empty config file. An absent or empty transition-family table emits no_configured_families and exits 0. With families, all complete passes exit 0; findings or any incomplete family emit the immutable result and exit 1. Invalid config/declaration, input loading, or output errors emit no result and exit 2. Collection transition-family reload/evaluation is a separate command boundary.

transform --gait-anchor is an explicit declaration that each selected clip is an in-place cyclic gait. Before rewriting, it samples the configured Root role (or Hips fallback) and refuses the whole command if trajectory evidence is missing/non-finite, horizontal accumulation exceeds 1 cm, or yaw accumulation exceeds 1°. Every nonconstant channel the operation would rotate must contain exactly one key at each --fps whole-frame sample over the clip duration, at the exact representable f32 key / fps time and period endpoint. Sparse, differently framed, duplicate-time, or off-grid trajectory evidence refuses, as do duplicate (bone, property) channels (including constant channels), so the phase shift remains a bijective authored-value permutation. Verification samples the exact admitted f32 key times, and mutation permutes output values by integer key index rather than resampling. Constant channels are exempt and cannot influence the declared period or shift. Before sampling, the command validates the complete skeleton, resolved metric roles, track targets/cardinalities, and finite evidence. Both declared-frame and maximum-authored-key work must independently fit these inclusive 1,000,000-sample bounds: declared frames × skeleton bones, declared frames × tracks, and maximum authored keys × skeleton bones. The translation and yaw caps apply directly; no interior step is an allowance. Yaw uses f64 first/final headings plus counted full-turn crossings. At sample zero it selects the local +Z, +Y, or +X axis with the greatest finite horizontal projection, in that tie order, and keeps that axis for the complete proof. A different source-axis convention is therefore accepted without per-sample axis switching; if the selected axis later has no horizontal projection, the command refuses. This avoids error growth with the admitted segment count. Four f32 successors at each inclusive cap cover only authored endpoint translation/quaternion quantization; other checks are unchanged. A refusal names the clip and selected bone, does not publish or replace the requested output, and emits no earlier per-clip success lines: standalone transform stdout is buffered until all selected clips and the artifact write succeed. Keep authored root motion unchanged, apply a runtime phase offset, or use separately designed trajectory-preserving tooling. The option does not convert root motion to in-place motion.

scale is the atomic linear-scale producer. It has two distinct subcommands because the two operations rewrite different domains and a factor alone does not identify which one was meant: whole-document converts every represented length by a declared factor (physical size changes; use it only when the source was authored in a different linear unit), and rest-bind removes one compensating inherited scale from the skinned hierarchy anchored at a declared source skin and source root node, preserving world joint translations and orientations, sampled trajectories, and skinned vertex positions while removing the composed scale. The scale workflow owns the operation-choice, glTF raw rewrite or narrow FBX staging, proof, publication, and support-boundary walkthrough; this page remains the installed command/flag/exit reference.

Every numeric and source-identity argument is required. Nothing is inferred from mesh bounds, character height, joint lengths, inverse-bind magnitude, filename, or asset category; there is no implicit first skin or root, no animsmith.toml key, no plan file, no in-place mode, and no per-run tolerance flag — the tolerance policy is fixed and its identity is recorded in the evidence. Input, output, and evidence paths must all be distinct. glTF/GLB keeps its input container; the narrow FBX rest-bind path emits a new .glb.

Accepted inputs are self-contained glTF/GLB for both operations, plus a complete-inventory .fbx for narrow rest-bind when the default FBX feature is enabled. See the scale workflow for the complete support boundary and rewrite/reload/proof sequence, and the output reference for typed refusal records and deterministic publication details.

scale splits its two failure codes by what the failure is a property of, not by how far the run got. A refusal that is a property of the input asset publishes nothing, leaves any prior pair byte-identical, and exits 1 — with the typed reason as prose on stderr under --format text and as the same evidence record with outcome: "rejected" on stdout under --format json. That includes bytes that do not parse as the glTF/GLB the extension declares, and a document whose size puts the sampled proof over the policy's work budget. A failure that is a property of the invocation or of the operator's filesystem exits 2 with prose on stderr: a declared factor that is not finite and positive, an input that cannot be opened, a wrong extension, a container the extension disagrees with, two arguments naming one file, or a missing output directory.

The three paths must name three different files, and each is compared by the file it actually reaches: the input is resolved through a symbolic link, because reading follows one, while a destination is not, because publishing renames over a link rather than through it. Passing a symlinked input alongside a destination naming its target is refused before anything is written. A symlinked input that aliases neither destination is accepted.

transform --drop-duplicate-loop-endpoint is the narrow mechanical transform for an inclusive DCC cycle export that copied frame 0 to the final frame. It accepts only a strict authored-key candidate: all channels must have one common finite, strictly increasing timeline; valid key cardinality; matching first and last values (vector components within 1e-5, sign-invariant quaternion angle within 1e-4 radians); and actual interior motion. It atomically removes the same complete terminal key count from every channel (including each cubic-spline key triplet), leaves retained data unchanged, and re-pins duration to the last retained key. Other clips are not generalized, retimed, or repaired by this flag. The resulting open-cycle representation no longer satisfies inclusive loop-closure, which expects a repeated final sample; the complete endpoint-mode classifier remains #22.

transform --prune-constant-tracks is an opt-in companion to the default constant-track note. It removes only multi-key translation, rotation, and scale tracks whose evaluated keyed values are constant: vector components may vary by at most 1e-4, and rotations by at most 1e-3 radians under sign-invariant quaternion comparison. Single-key pins, malformed/non-finite data, and cubic-spline tangents that create motion above tolerance are not candidates and remain unchanged. For each candidate, the transform either removes it or prints a refusal reason: removing it would change sampled local TRS or model-space position/rotation, it is the clip's last remaining track, sampling is unsafe, or it targets a bone named by that clip's effective animates_bones expectation. The latter preserves the evidence needed for missing-bones and frozen-bone; [rig] required_bones does not protect tracks because it is a skeleton-presence contract.

Pruning runs after any selected slice, hold extension, duplicate-endpoint removal, and gait anchoring, so the final clip is what is judged. Text output lists every removed or retained candidate with its original track index, bone, property, interpolation, key count, and (for retained tracks) reason; no machine-readable output schema changes. It does not reduce changing keys, rewrite DCC curves, remove custom curves AnimSmith does not model, decide whether a non-rest constant pin is artistically intentional, or repair cubic tangents.

Exit Codes

The code reports what the run did, never how well it could report it. This holds for parser-rendered help/version, text, Markdown, and every --format json path (measure, lint, evaluate-transition-poses, collection evaluate-transition-poses, collection lint, collection evaluate-directional-speed, diff, convert, assemble, scale, generate addressability). If stdout cannot accept the result — a closed pipe or full filesystem — the checked write never panics, a best-effort checked diagnostic goes to stderr, and the stdout-bearing path's already-established code stands except for evaluate-transition-poses or collection evaluate-transition-poses. These immutable results have no sidecar or previously established outcome: a failed stdout write is an operator error, produces no usable result, and exits 2. Thus lint … --format text | head still exits 1 for findings it found, inspect … | head still exits 0 for an inspection it completed, and scale still exits 1 for a refusal or 0 for a published pair. Stderr may itself be closed; losing both streams is still not a panic. Raising the stdout failure instead would report an operator error for work that was actually done and make exit semantics depend on presentation format. JSON serialization failure remains exit 2 because the CLI could not form a truthful record; delivery failure after rendering is only reporting for the ordinary streams. Other operator errors occur before stdout reporting, remain stderr-only, and retain exit 2.

For artifact producers, classification is by typed provenance, never by diagnostic wording. The JSON refusal identity is urn:animsmith:schema:producer-refusal:1:

A refusal is established before publication. It leaves any prior assembly artifact/evidence pair and any prior convert artifact byte-identical; the foot-cycle producer never replaces a generation. Convert still writes its successful single artifact directly, so this is not a rollback promise for an operator I/O failure during that write. Commands that render several related pieces attempt one checked stream when a single delivery boundary is promised. In particular, all selected fix repair reports and all parts of one conversion summary produce at most one stdout-failure diagnostic. Help and version delivery uses clap's own fallible styled writer, so forced ANSI color remains intact while a closed destination still follows this rule. Only stdout is affected; nothing about artifact publication changes.

A role-dependent check with missing prerequisites reports a typed coverage gap and does not fail the run — exit 0 means no failing findings among the checks that evaluated, not that every declared check evaluated; see reading a lint run for the full outcome vocabulary. A required-unavailable engine prediction is distinct: it exits 1 and cannot be suppressed by severity or --allow.

Use lint --deny-warnings when CI should fail on warnings as well as errors. fix --dry-run is the repair check mode: it exits 1 when the file has repairable defects and 0 otherwise, so CI can gate on "this asset needs fixing" without writing anything. The exit code reflects repairs fix would actually perform: tracks it cannot patch (data-URI buffers, cubic quat-norm tracks, quantized rotations) are printed as skipped[...] but do not fail the check — gate on lint (the quat-norm or quat-flip checks) when detection alone should fail CI.

Unsupported glTF Encodings

AnimSmith reads a narrower slice of glTF than the specification permits. A mesh accessor it cannot decode exactly as declared is refused with exit 2 rather than read as something else, so a run never reports numbers derived from bytes it misread.

Integer TEXCOORD_0 and WEIGHTS_0 accessors are accepted only when they declare "normalized": true, as glTF requires. The upstream reader rescales UNSIGNED_BYTE and UNSIGNED_SHORT values even when that flag is missing; AnimSmith refuses the unflagged accessor before decoding so measure cannot present an unauthorized rescaling as authored data. Normalized integer and FLOAT forms retain their decoded values. Re-export the malformed attribute with the flag, or as FLOAT; the refusal identifies its mesh, primitive, semantic, and accessor.

The common case is KHR_mesh_quantization: gltfpack and similar mesh optimizers store POSITION and NORMAL as BYTE/SHORT instead of FLOAT, and AnimSmith has no decoder for those. Which message you get depends on how the file declares the extension:

$ animsmith lint quantized.glb
animsmith: glTF parse error: invalid glTF: extensionsRequired[0] = "KHR_mesh_quantization": Unsupported extension;

$ animsmith lint quantized-declared-used-only.glb
animsmith: mesh 0 primitive 0 POSITION: accessor 0 is VEC3 of SHORT, but the loader reads VEC3 of FLOAT

Re-export without quantization — gltfpack -noq, or turn off the quantization option in whichever exporter produced the file — and the same asset loads. AnimSmith measures rigs and animation, so the unquantized source is the right input for it; keep the quantized build for shipping.

Two other shapes are refused with the same mesh N primitive M message: an accessor typed for a different element than the slot that references it (a VEC3 TEXCOORD_0), and one whose buffer layout the reader cannot walk (a byteStride shorter than its own element, a sparse block of count 0, or a dense/sparse byte extent beyond its declared buffer view or the external, data-URI, or GLB bytes that actually resolved). Short extents are refused rather than silently loaded as empty positions or indices, so a clean measurement never substitutes absent geometry for unreadable authored values. Those are invalid glTF rather than an unsupported feature, and the fix belongs at the source. The Khronos glTF-Validator names the same accessor — ACCESSOR_SMALL_BYTESTRIDE for the stride, and the schema's minimum: 1 on sparse.count for the sparse block — so run it on the file to see the defect in its own vocabulary. AnimSmith still has to check these itself, because the gltf crate it parses with does not: that crate's JSON validation bounds byteStride to 4..=252 without ever relating it to the accessor's element, so an unwalkable layout passes parsing and reaches the reader.

The same layout defect on an animation sampler is refused too, naming the clip and channel instead of a mesh:

$ animsmith lint poisoned-track.gltf
animsmith: clip 'walk' node 3 sampler input: accessor 0 reads its elements from buffer view 0, whose byteOffset 18446744073709551615 plus byteLength 12 is a byte extent that overflows

Sampler element encodings are checked independently before the selected reader is constructed. Inputs must be SCALAR of FLOAT; translation and scale outputs must be VEC3 of FLOAT; rotation outputs must be VEC4 and may use any of glTF's five decodable quaternion component types (BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT, or FLOAT); morph-weight output uses those same five component types as SCALAR. A mismatched type or component type is an operator error rather than a panic or a size-coincident reinterpretation:

$ animsmith lint mistyped-track.gltf
animsmith: animation 0 sampler 0 input for node 0 translation: accessor 0 is VEC3 of FLOAT, but the loader reads SCALAR of FLOAT

Feature Flags

The default binary enables fbx and report.

cargo install animsmith
cargo install animsmith --no-default-features

The no-default-features build has no C toolchain dependency and keeps the glTF-only workflow: inspect, measure, lint, transform, fix, scale, collection transform-foot-cycle, and diff. scale and the collection foot-cycle command are the minimal build's evidence-emitting producers. The HTML report command is controlled by the report feature. convert accepts FBX or glTF input (a glTF input is re-emitted, carrying its geometry) but is compiled only with the fbx feature. assemble is gated by the same feature because its maintained boundary accepts FBX sources as well as glTF.

The exact foot-cycle producer form is:

animsmith collection transform-foot-cycle COLLECTION.toml \
  --parameterization FOOT-CYCLE.toml --format json

--format json is required and JSON is the only format. There is no --output or --output-dir: the strict parameterization document is the sole destination authority. The destination must not exist. Success publishes one complete generation with exactly three files per declared member plus aggregate-evidence.json, then writes the exact aggregate file bytes to stdout. Valid asset/capability/refinement/proof refusal exits 1 with one producer-refusal:1 JSON record. Malformed or stale controls, unsafe paths, I/O, serialization, and publication races exit 2 with empty stdout. Full-scene conversion carries factor-only materials plus linked or embedded PNG/JPEG base-color, normal, metallic-roughness, and occlusion textures. Normal textures retain their glTF scale; FBX normal maps use glTF's default scale because ordinary FBX materials do not expose the same scalar. See the static asset workflow guide for why the normal slot matters, common bad handoffs, and the engine-side checks that conversion cannot perform.

--material-texture-recipe <PATH> applies explicit BaseColor, normal, metallic-roughness, and occlusion image mappings during conversion. It conflicts with --animation-only, which removes materials, and is compatible with --bake-static-mesh-transforms and either --format value. Without a recipe, ordinary linked and embedded textures keep their existing conversion path. See material texture recipes for the recipe contract, deterministic processing policy, and path rules.

assemble reads a versioned multi-source character recipe, uses one input as the authoritative skinned base, and exact-name remaps selected takes from other FBX or glTF inputs. It writes a GLB and assembly-evidence JSON as a rollback-safe publication pair. The command owns generic asset transforms; source extraction, project policy, and publication remain consumer concerns. The current recipe/evidence pair is v7. Recipe v7 may include an optional [rest_bind_scale] block whose exact root_node_name and expected factor are both required. The base must resolve that name to exactly one source node and exactly one non-empty source skin whose every joint is that node or its descendant. Every distinct FBX clip input uses an animation-only projection. A glTF/GLB clip retains its existing successful full rest/bind or meshless track-only path; role-specific admission additionally selects the track-only path when only unused geometry, deformation, material, or bind obligations would fail. Framing, dependency, raw-coverage, named-skeleton, and animation accessor/layout obligations remain strict. The compatibility domain contains the selected base skin joints, the root, their named ancestry, and each actual track target with its ancestry. Unreferenced base-only geometry or attachment descendants are not required in the clip. Boundary whitespace is invalid rather than trimmed. The block accepts glTF/GLB plus the narrow normalized/baked FBX subset admitted by the existing rest-bind capability boundary. That boundary may admit user-defined FBX properties and bounded external texture/video declarations after same-load evidence proves they are not scale-bearing. It also admits exactly ufbx's marker, LOD-group, stereo-camera, camera-switcher, and display-layer typed lists because they cannot supply hierarchy transforms, skin binds, tracks, or geometry to the normalized rest/bind bridge. Display layers contribute only node membership and editor visibility/freeze/color state. The boundary admits shader/binding-table metadata on the same basis. BindPose rows are admitted only when they cover every joint of each skin they touch and are finite, unambiguous, and reconcile with the converted cluster bind or node rest-world matrices already consumed by the bridge; no Pose remains required. Those rows remain counted in the raw aggregate; every other unmodeled typed list stays fail-closed, with exact nonzero kind counts in the refusal. The boundary still may admit enumerated scale-invariant conversion fidelity—omitted authored vertex/face/edge metadata, influence projection with complete effective coverage, triangulation, and exact-bit welding—while retaining the public inventory evidence. It refuses incomplete resource or construct coverage, extensions, and every unsupported transform, geometry, bind, or animation fact. A refusal names the exact failed fact or counter. An artifact or evidence destination that names one of the safe source-relative dependency keys retained by the same-load closure is an operator error even when capture was unavailable or refused; symlink-mediated dependency keys stop before publication rather than resolving through the link, and resource-budget truncation stops rather than trusting an unchecked tail. Publication never replaces a source sidecar. The command validates the base plus every clip's versioned skeleton basis before remapping any keys. V7 retains v6's composition with canonicalize_skin, ground_and_center, and remove_nodes: it applies those normalized assembly transforms to both the staged source and the rebased clip reference, then performs one final raw staged-GLB rewrite and proof. Recipe v4 retains its released refusal for that combination. Set prune_constant_tracks = true to remove only tracks proven constant after all other transforms, including track completion. Because this is all-property pruning, it can remove completion-generated (bone, property) coverage whose completed value is constant. Effective output clip animates_bones exact names are retained, while required_bones is never used as the carve-out. Evidence records every removed track and is empty when pruning is disabled or removes nothing. Leave pruning disabled where consumers need dense transition coverage and do not explicitly reset omitted properties; property-scoped selection is tracked in #401. Root-level remove_nodes exact-names base nodes and removes their descendant closure after animation transforms; any surviving track, skinned mesh-instance, or skin reference refuses the operation. With FBX rest_bind_scale, an unskinned mesh instance attached inside that declared closure is excluded from the private scale stage and removed with the node. It still blocks the scale plan when the node is not declared for removal. For every track-only clip input, v7 applies the accepted base plan's named animation-target factors (including cubic translation tangents) through the animation-only projection without inventing a bind rewrite. The named root and selected base skin-joint basis must still match, as must every actual track target and the named ancestry connecting those nodes. Unreferenced base-only geometry descendants do not participate in that clip proof. The projection never applies to the base; every base and full rest/bind path retains the strict raw capability contract. It performs no material, texture, or mesh garbage collection. Recipe/evidence v1 through v6 remain immutable historical contracts; v3 rejects rest_bind_scale as unknown. The recipe identity is urn:animsmith:schema:character-assembly-recipe:7; see character-assembly-recipe-v7.schema.json.

Static mesh transform bake

convert --bake-static-mesh-transforms is an explicit, opt-in conversion operation for a static mesh whose normalized placement must live directly in mesh-local geometry. It accumulates each accepted mesh node's rest transform through its hierarchy into positions, transforms normals with the inverse-transpose and normalizes them, and writes the result beneath a canonical identity root. Indices, UVs, model-supported material assignments, and embedded base-color, normal, metallic-roughness, and occlusion textures are retained. The default conversion is unchanged; --bake-static-mesh-transforms conflicts with --animation-only.

The operation fails with exit code 2 rather than guessing when the input has any animation track, a skin signal, a mesh definition with no unambiguous single instance (including shared definitions), malformed or non-finite scene data, a singular or near-singular transform, or a reflection. Skin baking, animated-node baking, and reflection handling are outside this operation's contract. Same-platform runs over the same input and options produce a byte-identical artifact. The static asset workflow guide shows the before/after model, when baking is appropriate, and why this is not a general scene flattener.

Repairs

Every repair is safe, lossless, and idempotent — that is the bar for adding one. Repairs have stable ids so scripts can pin exact behavior:

By default fix runs every repair. --repair id[,id] pins an exact list (animsmith fix --help names the valid ids). fix writes only when you explicitly choose a destination; --dry-run reports and sets the exit code without writing:

animsmith fix clip.glb --dry-run
animsmith fix clip.glb -o fixed.glb
animsmith fix clip.glb --in-place
animsmith fix clip.glb --repair quat-norm,quat-flip -o fixed.glb

Engine profiles and importer settings

An optional [engine] section selects one exact, versioned importer contract. There is no generic, automatic, nearest-version, or fallback profile. The released profile tuples are:

The accepted-source column is AnimSmith's bounded profile boundary, not a claim that the named engine supports no other source formats. An absent [engine] keeps the existing engine-neutral behavior.

Unity Generic revision 2 exposes the current closed setting vocabulary. Every applicable setting is required because the cited Unity 6000.3 documentation does not establish a default that AnimSmith can safely materialize:

[engine]
profile = "unity-generic"
profile_revision = 2
engine_version = "6000.3"
importer = "fbx-model-importer"

[engine.settings]
animation_type = "generic"
avatar_setup = "create_from_this_model"
import_animation = true
root_motion_source = "Reference/Root"

[clips."locomotion_*".engine_settings]
root_rotation = "extract"
root_position_y = "bake"
root_position_xz = "extract"

[clips.idle.engine_settings]
root_rotation = "bake"
root_position_y = "bake"
root_position_xz = "bake"

root_motion_source is an exact document-scoped source-transform path for Unity Generic revision 2. It is not applicable to Unity Humanoid. The three bake | extract choices are clip-scoped and resolve with the normal field-by-field rule: matching globs in lexical order, then an exact clip name last. Every real Generic clip must resolve all three choices. The frozen revision-2 document controls are animation_type = "generic", avatar_setup = "create_from_this_model", and import_animation = true. convert_units and bake_axis_conversion belong to the preserved revision-1 advice vocabulary, not this root-motion profile. Unreal, Godot and Bevy revision 1 expose no V1 settings, so supplying any setting is an error. Bevy revision 2 is the exact profile used by engine-unit-scale. It requires the load-time extension-handler environment and animation-feature state; other loader settings have version-pinned defaults that may be overridden explicitly:

[engine]
profile = "bevy"
profile_revision = 2
engine_version = "0.19.0"
importer = "gltf-asset-loader"

[engine.settings]
extension_handler_environment = "bare_empty" # or "bevy_pbr_stock_0_19"
bevy_animation_feature = true
rotate_scene_entity = false
rotate_meshes = false
load_meshes = "nonempty" # or "empty"
load_animations = true

The two handler values are closed, version-pinned environments: an empty registry, or exactly Bevy 0.19's stock PBR handler. Project/user extension handlers are outside the profile. The revision-2 settings are document-scoped; clip engine_settings are rejected.

The current revision 3 keeps the revision-2 tuple and settings and adds only the engine-track-support animation/channel gate. That check consumes bevy_animation_feature and load_animations; both retain whether their values were explicit or defaulted. The compiled feature gate has precedence: if it is disabled, the prediction is a dropped negative outcome regardless of the load_animations value. This revision uses load_animations to model the stock loader's animation path, not extensions, other animation constructs, or successful runtime survival.

The rule binds a bounded same-load raw animation inventory and independent per-animation channel coverage. A complete empty inventory is not applicable. Partial or unavailable source inventory emits exactly one subjectless, unsuppressible required_prediction_unavailable inventory facet and no retained-prefix predictions. A complete inventory may emit one negative facet per affected animation or channel row when a gate drops it. If complete source evidence demands more than the shared facet budget, the allocator-authorized prefix remains available and one canonical facet_budget_exceeded summary records the omitted suffix; this does not relabel the source inventory as partial. When both gates allow loading, the required result is instead a stable required_prediction_unavailable runtime-survival state. Dropped rows are not content findings and cannot be suppressed with --allow; any required unavailable facet still exits 1.

Revision 3's historical artifacts use output-v16 and V5 prediction provenance/readback. Revision-2/V4 and output-v15 readers and historical examples remain preserved. Unity Generic root-motion uses the separate V6 provenance and current output-v19 contract; output-v9 and every later historical reader remain immutable and readable.

All statically knowable tuple, setting, value, scope, and applicability errors are reported before input I/O. Accepted input format and required per-clip materialization are checked after loading. Profile selection never changes measure values. Current output-v19 records resolved profile provenance on lint files.

The first production rule is engine-addressability for the exact Bevy revision 1 / 0.19.0 / gltf-asset-loader tuple. With complete glTF/GLB source animation inventory, it emits one available facet whose subject is the exact Bevy display label Animation{i} for each source animation index i:

animsmith --config examples/bevy.animsmith.toml lint \
  --select engine-addressability examples/assets/walk.glb

Named, unnamed, and duplicate-named animations all use their distinct source indices; names do not become typed labels. Partial or unavailable source clip coverage emits one blocking animation_asset_label_inventory facet rather than predictions for the retained prefix. The rule predicts only the canonical GltfAssetLabel::Animation(i) selector spelling. It does not prove Bevy ran, that animation loading was enabled, that the runtime asset exists, or that its targets and graph wiring are usable. The selector can change when source animation order changes.

Current lint uses prediction provenance v3 with bounded 4,096/N+1 settings coverage. A 4,097th clip is retained as typed partial-settings overflow evidence, never as a complete prefix.

For the exact Unity Generic revision-2 tuple, engine-root-motion uses V6 provenance. It evaluates each explicitly declared movement_owner_xz, movement_owner_y, and movement_owner_yaw against the corresponding clip root_position_xz, root_position_y, and root_rotation setting. bake produces baked_into_pose, extract produces stored_as_root_motion; matching project/importer ownership is compatible, and a mismatch is an ordinary error finding with a scoped prediction facet. No numeric travel threshold is used: measured translation/yaw availability is required, while the measured magnitude is only evidence.

The path must match the explicitly resolved Root role in the raw FBX transform inventory. Hips is never a fallback for this engine rule. A missing or ambiguous path, Root mismatch, incomplete/unavailable raw inventory, incomplete intent/settings, duplicate clip name, or unavailable axis measurement emits required_prediction_unavailable; this is not a content finding, cannot be suppressed with --allow, and makes lint exit 1. Complete all-available work is complete, mixed work is partial, and all-unavailable work is not_evaluated. Raw path matching is case-sensitive and byte-exact; the only separator is unescaped /, with nonempty segments, no ./.., backslashes, controls, or Unicode format characters, and limits of 1,024 bytes per segment, 4,096 bytes per path, and 256 segments. The same-byte raw FBX projection retains source identities and parent chains, excludes the implicit root and generated helpers from matching, and reports NoMatch only under complete coverage. AnimSmith does not execute Unity, perform imported-asset readback or runtime playback, or certify engine behavior. The checked-in and CI fixtures for this slice are self-authored synthetic FBX only.

For the exact Unreal revision 1 / 5.8 / fbx-importer tuple, lint also runs engine-clip-boundary. The FBX adapter's same-load exact timing evidence is checked only for an absolute animation-stack end coordinate on its exact frame lattice. Missing or incomplete evidence is a required-unavailable facet; the command does not infer import ranges or other Unreal settings.

generate addressability emits the immutable V1 animation-only contract by default and whenever no exact Bevy revision-3 profile is selected. It emits canonical JSON by default:

animsmith generate addressability examples/assets/walk.glb \
  > walk.addressability.json

The neutral inventory retains source-order animation and channel indices, optional non-unique source names, channel targets and accessor indices, the primary-file identity, and the full dependency closure. Its identity covers only those neutral fields. Without an engine profile, or with a supported profile other than the historical exact Bevy revision-1 tuple above, the root bevy field is null. With that historical profile, it embeds same-load prediction provenance and the unchanged engine-addressability evaluation:

animsmith --config examples/bevy.animsmith.toml generate addressability \
  examples/assets/walk.glb --format markdown

Names remain metadata and never replace source indices. Partial or unavailable animation coverage stays visible in the neutral inventory. When the exact Bevy adapter is active, the existing required-unavailable facet makes the command exit 1; without that adapter the same neutral evidence exits 0. Non-glTF input, malformed or unknown profile selections, and an actual 4,097-clip input are operator errors (exit 2). Text and Markdown are escaped presentation views of the same validated value and add no conclusions to the JSON contract. This V1 does not inventory scenes, default scenes, skins, target paths or UUIDs, Bevy named-map winners, or extension support, and it does not certify a runtime load. Consumers using the strict staged reader must also keep each report at or below 256 MiB; the reader enforces this byte cap before UTF-8 or JSON decoding.

The richer exact-Bevy path emits the separate V2 contract urn:animsmith:schema:gltf-addressability:2, documented by gltf-addressability-v2.schema.json. It is selected only with the exact Bevy revision-3 profile/settings and keeps the V1 command contract and readers immutable. The same one engine-addressability evaluation is reused; rich rows do not introduce a second check lifecycle. Required-unavailable rich facets retain exit 1, complete or neutral output exits 0, and malformed tuple/config/input errors exit 2.

V2's raw inventory independently covers scenes, nodes, skins, node-to-skin attachments, and scene-root path candidates. It retains source indices, names, parents/children, ordered roots/joints, explicit skin.skeleton, and exact same-load primary/dependency-closure identity. Complete empty coverage proves absence; partial prefixes and unavailable domains do not. The explicit skin.skeleton member is source evidence only: Bevy ignores it and V2 makes no inferred-root claim. Scene-instantiated SkinnedMesh attachment is outside this static projection.

The pinned Bevy authority is tag v0.19.0, commit c6f634ca9f406d68ba5109d921247b654cb42c10, bevy_gltf 0.19.0 with locked gltf 1.4.1, plus commit-pinned label, loader, node-path, AnimationTargetId, feature, and root Cargo.lock sources. The isolated readback probe's committed lock is the graph authority: every Bevy 0.19 release crate in that lock is 0.19.0, and the probe rejects internal Bevy patch drift; independently-versioned helpers retain their own versions. Scene{i} exists for each declared scene; Gltf.default_scene routes only to an existing scene handle, with no DefaultScene label and no fabricated Scene0. Bevy eagerly creates Skin{i}/InverseBindMatrices for every source skin, including unreferenced skins, using identity fallback when inverse-bind data is absent. Skin{i} is created when any source node references it during the all-source-node pass; source skin indices, never collected-vector position, are identity.

Named scene/animation/skin maps are separate from typed labels and use source-order last-write-wins (skin winners follow lazily created skins in first-reference order). Target rows are per unique source animation target node and retain contributing animation/channel identities. Paths use authored names or GltfNode{source_index}, exclude the scene world-root name, and publish a path/UUID only when hierarchy, reachability, closure, feature settings, and collision evidence are complete. Missing bevy_animation, disabled load_animations, unreachable or multiply reachable targets, duplicate paths, UUID collisions, missing pointer width, and incomplete evidence are typed required-unavailable states. Target UUID reproduction requires explicitly declared 32- or 64-bit pointer width because Bevy hashes segment lengths using the target pointer width's little-endian encoding; host width is never inferred.

Each new rich V2 projection domain is bounded at 4,096 rows, with aggregate projection structural references at 65,536 and dynamic projection text at 1 MiB. The sealed embedded V1 animation inventory and CheckEvaluation scopes retain their own bounds. Names/path segments are capped at 1,024 UTF-8 bytes, paths at 4,096 bytes and 256 segments, and staged reports at 256 MiB. The explicit target_coverage projection reports target_domain_truncated at its row ceiling and is also required-unavailable whenever raw or animation/channel target-domain evidence is incomplete; other new-projection budget exhaustion reports projection_bounds_exceeded. No retained prefix is treated as collision-free. Strict readback rejects N+1 collections and contradictory states. A bounded second parse of already captured primary bytes is allowed within the same loader invocation; reopening the input or dependencies is not. V2 is prediction evidence only and does not claim runtime load success, target survival, scene spawning, graph wiring, or playback.

When the one shared check would exceed core's per-file facet budget, its rich prediction is compacted to one subjectless engine-addressability:facet-budget scope with facet_budget_exceeded. This preserves the existing one-lifecycle contract and does not turn omitted facets into positive evidence.

generate contact-fragment publishes canonical contact-fragment:1 bytes to --output. It selects one exact unique clip, samples the existing longest-authored-channel metric grid, and records only finite bilateral model-space stance support. Each retained two-or-more-sample run emits one normalized support window and one earliest-minimum marker. The source primary identity and complete dependency closure are bound into the fragment; an incomplete role, grid, closure, or other prerequisite is a typed exit-1 refusal and leaves any existing output unchanged. --format json writes the same canonical bytes to stdout; text is a presentation summary. The collection form selects one exact manifest logical id and reloads its declared source/config rather than consuming collection-output evidence. Neither form infers physical contact, footsteps, gameplay, IK, or engine behavior.

An output-v19 measure report deliberately has no engine provenance or loader-owned source format. diff also ignores the provenance on lint reports. When its operands are JSON reports, diff validates the complete version-matched records and compares their decoded version-matched measurements (historical v15/v16 or current v18); a selected engine profile does not change that report meaning. When its operands are source assets, the profile is still resolved against each loader-owned source format before measurement.

Runtime-facing attachment/socket/IK nodes have one shared engine-neutral policy:

[runtime_nodes]
selectors = ["weapon_socket", "ik_*_target"]

[checks.rest-world-scale]
expected_uniform_scale = 1.0
uniform_scale_tolerance = 0.0001

The older [checks.rest-world-scale].node_selectors field remains a compatibility alias. Declaring both spellings is a configuration error. An absent selector field or explicit empty list means no runtime-node policy.

Machine Output

measure, lint, collection lint, collection evaluate-directional-speed, diff, generate addressability, and generate import-advice support --format json. The native JSON contract is the source of truth and is versioned with schema_version. See output.md and the current urn:animsmith:schema:output:19. Output-v17 remains available as historical output-v17.schema.json with immutable identity urn:animsmith:schema:output:17. Output-v16 remains available as historical output-v16.schema.json with immutable identity urn:animsmith:schema:output:16. Nested measurement evidence has its own urn:animsmith:schema:measurements:18 measurements-v18.schema.json contract. urn:animsmith:schema:measurements:15, urn:animsmith:schema:output:9, urn:animsmith:schema:output:11, urn:animsmith:schema:output:12, urn:animsmith:schema:output:13, urn:animsmith:schema:output:14, and urn:animsmith:schema:output:15 remain historical immutable contracts alongside output-v16. diff retains strict version-matched readers for output-v11/v12 with measurements-v15 and output-v13 through output-v17 with measurements-v16; the latter retains identity urn:animsmith:schema:measurements:16; output-v9 and its measurements-v9 pairing remain immutable historical contracts. Output-v10 and earlier reports require regeneration from the original asset.

collection lint COLLECTION.toml --format json emits the separate current urn:animsmith:schema:collection-output:11 contract. Historical urn:animsmith:schema:collection-output:9, urn:animsmith:schema:collection-output:8, urn:animsmith:schema:collection-output:7, urn:animsmith:schema:collection-output:6, urn:animsmith:schema:collection-output:5, and urn:animsmith:schema:collection-output:4 remain immutable; the manifest directory is the control root; safe missing/unreadable sources, rejected readable bytes, digest/take mismatches, and incomplete runtime-set members remain typed rows and exit 1 while later safe sources continue. Invalid manifests, unsafe or nonregular paths, and missing/malformed selected configs exit 2 without an envelope. Source, clip, and set rows are canonical; member order remains the manifest order. Each source separately retains its primary input identity and a complete, partial, or unavailable dependency-closure state. Only a complete closure identity can establish that source, one of its clips, or a runtime-set member; partial/unavailable reasons remain typed and make the result incomplete with exit 1. Each established clip binds an exact source take index/name to a normalized clip index and carries duplicate-safe indexed measurements. The nested whole-document lint envelope uses current output v19 and measurements v18; output v18 and measurements v17 remain a matched historical reader pair with immutable identities urn:animsmith:schema:output:18 and urn:animsmith:schema:measurements:17. The preceding collection envelope is also retained as urn:animsmith:schema:collection-output:10. The strict reader preserves version binding for collection-output-v9 with output-v17, collection-output-v8 with output-v16, collection-output-v7 with output-v15, collection-output-v6 with output-v14 and collection-output-v5 with output-v13; older historical contracts remain immutable and are not retargeted. Regenerate current collection evidence before passing it to collection evaluators. Runtime sets keep decision: not_evaluated; they make no blend, controller, engine, artistic, or gameplay claim. Every declared member carries raw root_travel: its existing duration_s, root-trajectory translation availability, signed horizontal X/Z displacement, sampled horizontal travel, and speed availability/value. Binding-unavailable rows remain explicit with unavailable root-travel facts. evidence.root_travel reports the count of fully measured declared members and a complete/incomplete lifecycle; it never reduces the declared set to measurable rows. Gait-group member rows additionally carry raw gait-phase availability, and only a fully established, phase-measured set emits evidence.gait_phase.phase_spread with basis max_circular_deviation_from_mean; this preserves existing gait lint threshold semantics. See collection-output-v7.schema.json.

collection evaluate-directional-speed --policy POLICY.toml --evidence COLLECTION-OUTPUT.json --format json strictly reads a bounded collection-directional-speed-policy:1 declaration and a bounded collection-output V7, historical V6, or historical V5 document, then writes the separate immutable urn:animsmith:schema:collection-directional-speed-evaluation:1 result. The result binds the exact raw TOML and JSON byte identities and preserves every declared member in manifest order. Invalid, stale, wrong-kind, unreadable, malformed, or over-budget inputs exit 2 with no stdout. Incomplete root travel, zero endpoint displacement, zero ratio reference, numeric-range outcomes, and declared-policy findings write the result and exit 1; only a complete passing policy exits 0. It has no text/Markdown presentation, --output, subset, or inference mode. See collection-directional-speed-evaluation-v1.schema.json.

generate addressability has a separate immutable contract, urn:animsmith:schema:gltf-animation-addressability:1; see output.md and gltf-animation-addressability-v1.schema.json. The richer exact-Bevy path additionally has immutable contract urn:animsmith:schema:gltf-addressability:2; see gltf-addressability-v2.schema.json. Neither is output-v11 or a diff measurement operand.

generate contact-fragment is also outside output-v11: it writes the strict urn:animsmith:schema:contact-fragment:1 sidecar. Its exit-1 JSON refusal uses producer-refusal:1; exit 2 is reserved for CLI, config, path, or publication control failures.

generate import-advice requires an exact [engine] selection and all required settings, then binds that resolved profile to one input and the same-load raw facts, dependency closure, explicit clip intent, and normalized measurements:

animsmith --config unity.animsmith.toml generate import-advice export.fbx
animsmith --config unity.animsmith.toml generate import-advice export.fbx \
  --format markdown

The default JSON is the separate immutable contract urn:animsmith:schema:engine-import-advice:1; see output.md and engine-import-advice-v1.schema.json. The strict reader caps the serialized document at 256 MiB before decoding. Unity 6000.3 Generic/Humanoid projects only the resolved importer settings modeled by profile revision 1. Unreal 5.8 and Godot 4.7 revision 1 return a typed profile_settings_unmodeled refusal (exit 1). Available advice exits 0; config, unsupported-profile/input-format, I/O, and serialization errors exit 2. The command never invents authored frame numbers, sampling rates, unit conversion, or root-motion behavior. Text and Markdown are presentation-only views of the same validated value.

The exact revision-2 tuples are also supported by this command. Godot uses godot / 2 / 4.7 / resource-importer-scene with glTF JSON or GLB and projects only animation/fps (1..120, profile default 30) and animation/trimming (profile default false). Unreal uses unreal / 2 / 5.8 / fbx-importer with FBX and requires an explicit sample_rate = "default_30", "source_determined", or "custom_hz(n)" for 1..48,000 Hz. The V2 JSON identity is urn:animsmith:schema:engine-import-advice:2; its basis is bound to the document-scope import-setting projection and its optional projection is typed. An available document carries the projection; a refused document carries a typed reason and no projection. The schema is engine-import-advice-v2.schema.json. Neither state means the engine imported or played the asset: frame ranges, units, skeleton/retargeting, compression, root motion, runtime behavior, and project-file writes remain outside this output.

Measurements v16 retains the v15 clip evidence and adds source-order primitive geometry plus bounded leading-magic evidence for unsupported nonempty images. Measurements v15 added canonical per-bone local TRS channel coverage and sampled Root/Hips trajectory evidence. Root is preferred whenever that role resolves; Hips is only a typed fallback when Root is unresolved. The trajectory groups signed endpoint displacement, sampled horizontal travel and vertical extrema, plus net/unwrapped/travel yaw with independent translation and yaw availability. These are engine-neutral normalized-model-space regression facts from the shared uniform metric grid, not continuous-curve or engine root-motion extraction proof; see output.md for the full coordinate, sampling, and availability contract.

rest-world-scale is quiet until its config resolves a nonempty shared or legacy runtime-node selector policy. Each exact name or * glob must resolve to one source node; findings include the stable source-node path and ancestry so attachment/import policies can be traced back to the source projection. For glTF that projection is authored node state; for FBX it is ufbx-normalized metre/Y-up, adjusted/inheritance- compensated state rather than the raw FBX transform stack. See the selected-node scale workflow.

convert --format json emits conversion evidence v2, with immutable identity urn:animsmith:schema:conversion-evidence:2; see output.md and conversion-evidence-v2.schema.json. It records the requested options, counts from the written artifact, exact static-mesh transforms when requested, and recipe provenance when a material texture recipe is used. text is the default human-readable write summary. An asset refusal under --format json uses the independent immutable producer-refusal-v1.schema.json identity instead; conversion evidence v2 remains success-only and unchanged.

assemble writes evidence v7 to its required --evidence path, with immutable identity urn:animsmith:schema:character-assembly-evidence:7; see character-assembly-evidence-v7.schema.json. assemble --format json prints the same record to stdout — the identical bytes the evidence file receives, serialized once — in place of the default text publication summary. An asset refusal publishes neither member and exits 1; JSON emits producer-refusal:1 on stdout, while text emits its stable kind on stderr. Operator errors remain exit 2, stderr-only. A failed stdout delivery does not change an already-established success or refusal code.

scale writes scale evidence v4 for glTF/GLB to its required --evidence path, with immutable identity urn:animsmith:schema:scale-evidence:4; see output.md and scale-evidence-v4.schema.json. The same record is what scale --format json prints to stdout, for a refusal as well as for a published pair. For an artifact-proof-failed refusal from the exact-preservation walk, rejection.artifact_proof_differences names up to 16 raw JSON locations the walk found different; omitted counts locations beyond that fixed cap, and the full count is items.length + omitted. The field is null for other artifact-proof claims and for capability refusals, whose violations array retains its existing meaning.

With the default FBX feature, scale rest-bind INPUT.fbx -o OUTPUT.glb is a separate narrow producer contract. It accepts only the complete normalized ufbx inventory, emits the immutable urn:animsmith:schema:scale-evidence:5 record described by scale-evidence-v5.schema.json, and proves the exact re-encoded GLB after reload. It never writes FBX and makes no raw-FBX preservation claim. scale whole-document remains glTF/GLB-only.

Machine-readable lint rejects --allow so it cannot erase evidence. The flag remains a presentation and exit-policy convenience for text and Markdown.

Native JSON is deliberately shaped so serializers can be added later without redesigning the checks: SARIF for code scanning, GitLab Code Quality/CodeClimate for MR widgets, JUnit XML for CI dashboards, and CSV for ad-hoc analysis.

Each JSON measure and lint file row records an input SHA-256 and byte count for the exact primary file bytes parsed. Keep that row with retained review, promotion, or publication evidence; multi-file runs calculate one identity per argument in order. For .gltf, the identity deliberately does not cover external buffer or image files. Profiled lint embeds the bounded same-load dependency closure in prediction_provenance; other workflows must retain dependency provenance separately when that scope matters.

Human-readable command output keeps asset-derived names, messages, and paths on visibly ordered lines: terminal controls, Unicode line separators, and bidirectional formatting characters are rendered as visible escapes. Markdown also flattens line separators and neutralizes table/code-span delimiters before the text is pasted into a trusted review comment. JSON retains the original strings as machine data.

measure --format json also inventories glTF/GLB material definitions, texture-to-image links, and image metadata. Its exact core source-slot domain is base_color, normal, metallic_roughness, occlusion, then emissive. This lets a pipeline distinguish an emissive-only material from an untextured one and identify shared source resources without parsing the asset again. The nested contract reports material_resource_coverage: "complete" when that documented five-slot glTF/GLB domain was inspected and "unavailable" when a loader has no equivalent source-resource view. Complete does not cover extension-defined texture slots or promise writer/conversion preservation. This is descriptive evidence only: it does not accept, repair, resize, transcode, or otherwise fix an image. See machine-readable output for the full boundary.

CI Comments (lint --format markdown)

lint --format markdown renders findings as GitHub/GitLab-flavored Markdown for pasting into a CI comment or asset-review thread. It mirrors the text output's information — severity, check id, location, measured and expected values, per-clip grouping, and typed coverage gaps — as tables inside a per-file collapsible section, with a clean summary for a passing asset:

animsmith lint clip.glb --format markdown >> "$GITHUB_STEP_SUMMARY"

A file with findings is rendered as a <details> section (expanded for short lists, collapsed once a file carries more than ten findings so one noisy asset does not bury the rest of the comment). A file with neither findings nor gaps collapses to a one-line ✅ Clean summary. A footer tallies errors, warnings, notes, and gaps across every input. The exit code is unchanged from text and JSON — see Exit Codes. Repeated gaps with the same check id and code share one presentation row with a count and bounded subject list; JSON retains every original scope.

Markdown is presentation-only and carries no stability guarantees — gate automation on --format json (see output.md), and treat the Markdown as display text that may be re-laid-out between releases.

Machine-Readable Output

animsmith's native JSON is the stable source of truth for pipeline adapters. Text and Markdown lint output are presentation views over the same evaluation results. The HTML report renders the same typed findings, coverage gaps, and prediction facets beside its sampled-motion view.

HTML report: source poses and illustrative blending

The single-document report keeps source playback separate from its optional illustrative blend. Source panes draw the exact Rust model-space pose-grid positions judged by checks. The illustrative blend control appears only after the selected pair passes admission, and adds a third pane computed from the embedded sampled-local-trs-blend-v1 presentation authority. It produces no finding, metric, animation export or engine-runtime conformance claim. The separate before/after comparison report keeps its existing source-pose and overlay behavior.

A finding whose clip name is missing or ambiguous shows a refusal notice and leaves the source selection and frame unchanged. A uniquely named finding still selects its source clip and judged time.

Samples and blend math

Each included, admitted clip carries a dense local-transform stream alongside its source positions: frame-major, then bone-major, ten little-endian f32 components per record in tx, ty, tz, qx, qy, qz, qw, sx, sy, sz order. Existing parent indices identify roots or earlier bones. Rust sampling has already filled absent channels from the rest transform; malformed channel storage is not treated as an absent channel. No rest-pose copy or authored animation tracks are added to the report.

At shared normalized phase u, each clip selects its own nearest frame, round(u * (frames - 1)), clamped to its grid. The primary clip drives playback; both actual source times are labelled. This selects sampled frames and does not resample or time-warp authored clips. Pairing is available across admitted clips of the document and does not require gait-group membership. Name-based links resolve only unique names; an invalid or self-pair clears pairing.

At an interior weight w, translation and scale use componentwise (1-w)*a + w*b. Rotations use shortest-hemisphere normalized linear interpolation (nlerp): normalize both quaternions, negate the second only when their dot product is negative, retain its sign at an exact zero-dot tie, then normalize the weighted sum. These calculations use binary64 arithmetic. Full column-vector affine matrices compose T * R * S, with each root's own transform and world[parent] * local[child]; this retains shear from rotated nonuniform-scale ancestors. Finite zero and negative scales are allowed.

Weights 0 and 1 instead draw the corresponding source positions exactly. This explicit endpoint branch guarantees agreement with the source panes; it does not promise a universal continuity or imperceptibility bound for arbitrary scaled chains. Interior results must remain finite and representable as f32 before GPU upload; unavailable results clear the prior blend instead of displaying stale geometry. The binary64 Rust reference uses the same embedded f32 samples as the browser. Its synthetic-fixture conformance tolerance is 1e-5 + 1e-5 * abs(reference) metres per position component, not an engine acceptance threshold or a proof for arbitrary skeletons.

Added-data limits and omissions

The new local-authority path admits at most 1,024 bones, 4,096 included clips, 65,536 aggregate track-metadata records and 32 MiB of added raw local data (40 bytes per bone/frame, at most 838,860 complete records). Checked aggregate counts and byte arithmetic precede local-value inspection and stream allocation. The aggregate base64 allocation is also checked. Budget excess or arithmetic overflow omits all local streams, rather than keeping whichever clips fit first. Source playback, findings and report success remain intact.

After aggregate admission, malformed track targets, properties, storage, cardinalities or duplicate channels omit that clip's complete local stream. Non-finite sampled components or quaternion length outside 1 +/- 1e-4 do the same. Invalid shared parent topology makes all blends unavailable. Each refusal shows a reason; source findings remain available. The browser validates and decodes only the selected pair when selection changes, before showing blend controls, and retains at most two local streams. Weight, phase and repaint do not decode streams or scan the clip array. Reusable storage supports one O(bones) blend/FK pass per repaint, with no all-pairs table or blended trail.

This cap bounds added local data and its processing, not existing source pose allocation, sampling, checks, loader/caller data, full JSON or full HTML memory. render(inputs) -> String keeps its existing public API. The comparison's separate 32 MiB pose budget remains per side and is unchanged.

All three panes use the same fixed source-based camera. Interior blended rotations can extend outside those bounds; use the existing orbit/zoom controls. There is no guarantee every interior pose fits the initial view and no weight-dependent automatic refit.

The persistent caption reads:

Engine-agnostic illustrative blend of sampled local transforms (nlerp rotations). Normalized phase, not a time warp. Not Bevy, Unity, Unreal or Godot runtime evidence.

--evidence-only omits both source positions and local transforms and skips local-authority work. Both are motion-bearing data; neither belongs in a shared report when the source-motion license forbids it. The notice reads:

Pose playback and illustrative blending are omitted in this evidence-only report. No sampled positions or local transforms are embedded.

Skeleton compatibility

animsmith skeleton compare emits one immutable skeleton-compatibility-v1.schema.json (urn:animsmith:schema:skeleton-compatibility:1) result. Its control plane is the exact raw correspondence TOML bytes, recorded as correspondence.input. That TOML pins the exact source and target primary identities, their explicit selected node-name sets (including each selected root), the declared matching mode, the resolved explicit mapping (empty for exact-name mode), and every tolerance. It does not infer skeleton membership from scene graph reachability. Invalid or stale control input, unreadable input, or an input beyond the 64 MiB primary-source bound is an operator error (exit 2) and emits no result.

Each subject records selected_skeleton_identity: the exact identity of a canonical, name-ordered projection of the selected source-node measurements and selector. This is provenance derived from the loaded asset, not another authored rest-pose profile.

The result keeps structural topology/rest evidence separate from optional source skin-membership, inverse-bind, and deformation-model facets. A result is compatible only when every required topology/rest row was available and within its declared tolerances. Complete mismatches are incompatible; mixed available/unavailable required topology/rest evidence is partial even when another retained field also mismatches; and no evaluable correspondence is not_evaluated. The last three exit 1. Neither the outcome nor any optional facet establishes retargeting, runtime deformation, masking, contact, gameplay, or artistic acceptance.

rows are deterministic: correspondence-covered source rows are emitted in source-name order, followed by unmapped source names and then unmapped target names in their respective name orders. A matched row contains separate local and rest-world translation, rotation, and scale deltas; the world rotation value exists only where the existing source measurement proves a right-handed unit-orthonormal rest-world linear transform. A child-bone ratio value exists only when both corresponding parent/child world positions permit an independent nonzero length comparison. Parent correspondence and child length use the nearest selected ancestor, walking across unselected intermediate nodes; they compare the declared selector projection rather than claiming that the complete raw hierarchies are identical. missing_source, missing_target, and parent_mismatch rows are explicit rather than folded into a score.

Non-pass rows identify a deterministic owner_surface and remedy_class. These route work to the correspondence, selected skeleton authority, selected skin/bind evidence, or a documented measurement boundary; they do not infer project, artist, or vendor blame from structure alone. Unavailable source and target evidence sides carry the same routing fields. The text view renders the exact source, target, selected-skeleton, and correspondence identities; matching mode and explicit pairs; tolerances; every retained row delta; facet details; and remediation routing. JSON remains the stable adapter contract.

Transition-pose evaluation

animsmith evaluate-transition-poses INPUT --format json emits exactly one immutable urn:animsmith:schema:transition-pose-evaluation:1 result described by transition-pose-evaluation-v1.schema.json. It is neither an output-v11 measure/lint envelope nor a check stream. The result binds the exact input document bytes as subject_input, the complete exact config source as declaration_input, and the declaration's independent normalized identity as declaration_normalized. For configured document families it also binds the complete same-load dependency-closure identity at the subject and each member, so a changed external glTF animation buffer cannot be masked by unchanged primary JSON bytes. With no selected or ambient config, the exact declaration source is the defined zero-byte TOML sequence; an explicitly empty config is intentionally identical.

An absent or empty [transition_families] table is a complete passing result with reason: "no_configured_families". Complete configured passes exit 0; findings and every retained incomplete family exit 1 with this same result. If same-load dependency-closure capture is incomplete, configured families are retained as incomplete/not_evaluated with dependency_closure_incomplete; an empty declaration remains the complete no_configured_families pass because it evaluates no source data. Invalid config/declaration, contradictory witnesses, input/load failures, and serialization failures emit no result and exit 2. Because this result has no sidecar or previously published artifact, failed stdout delivery is also an operator error (exit 2), rather than a successful result with a best-effort diagnostic. V1 evaluates one loaded document and does not imply collection source reload, graph generation, engine runtime behavior, or input mutation.

animsmith collection evaluate-transition-poses COLLECTION.toml --families TRANSITION_FAMILIES.toml --format json uses the same immutable result schema, with subject_input bound to the exact collection manifest bytes. It verifies the envelope's manifest identity and every logical/source/take witness before source work. Missing, unreadable, oversized, digest-mismatched, malformed, or otherwise unusable source input makes its whole family incomplete/not_evaluated with member_unavailable; it never compares a surviving subset. A readable raw source retains its exact source_input even when unusable; only a source for which no complete bytes were available uses source_input: null, and only in a member_unavailable family. Per-family members may span documents but must have one exact normalized skeleton basis.

Collection lint

animsmith collection lint COLLECTION.toml --format json emits the separate current urn:animsmith:schema:collection-output:11 envelope. Historical urn:animsmith:schema:collection-output:9, urn:animsmith:schema:collection-output:8 (see collection-output-v8.schema.json), urn:animsmith:schema:collection-output:7, urn:animsmith:schema:collection-output:6, urn:animsmith:schema:collection-output:5, and urn:animsmith:schema:collection-output:4 envelopes remain immutable. It binds the exact manifest bytes to canonically ordered source, logical clip, and runtime-set records while preserving each set's declared member order. Every available source embeds its ordinary one-file output-v19 lint result; each established logical clip separately carries the existing ClipMeasurements value selected by raw source take index and exact authored take name, then mapped through the loader's observed normalized clip index. This duplicate-safe indexed projection does not revise the historical, immutable measurements-v15 name-keyed wire contract; collection-output-v11 embeds measurements-v18 in its nested output-v19 documents. The strict reader also preserves collection-output-v10 (urn:animsmith:schema:collection-output:10) with its exact nested output-v18 (urn:animsmith:schema:output:18) and measurements-v17 (urn:animsmith:schema:measurements:17) pair. The strict reader continues to bind historical collection-output-v9 only to output-v17 with measurements-v16, historical collection-output-v8 only to output-v16, historical collection-output-v7 only to output-v15, historical collection-output-v6 only to output-v14, and historical collection-output-v5 only to output-v13.

Source input, digest pin, config, loader, take inventory, and document-result states stay orthogonal. A readable digest mismatch can therefore retain its observed identity, loader result, and take drift without authorizing the clip binding. Missing/unreadable sources, rejected readable bytes, digest/take mismatches, and unestablished members produce a complete typed envelope and exit 1; manifest, rooted-path, selected-config, serialization, and tool errors exit 2 with no envelope. The frontend preflights the complete control plane before source execution and reads sources sequentially.

Collection dashboard

animsmith collection dashboard --collection COLLECTION-OUTPUT.json -o DASHBOARD.html --authority DASHBOARD.json consumes only a strict current collection-output V11 document. It writes a self-contained offline HTML presentation and the separate urn:animsmith:schema:collection-dashboard:1 machine authority. That authority records the exact raw collection-output identity, bounded source/take/logical-clip and ordered runtime-set projection, and optional compatible transition-pose evaluation input/result. The optional result must be transition-pose-evaluation V1 bound to the same manifest input; other evaluation contracts remain separate rather than being guessed into a per-member dashboard projection.

Every declared source has its own inventory row even when no logical clip binds to it. The row retains its safe locator, optional observed input identity, availability, loader state, dependency-closure state, and bounded observed-take inventory. Each physical take preserves its exact source-owned take index/name, normalized index/name state, evidence, and outcome without inventing a logical ID. Summary evidence totals count physical rows plus unscoped source findings and unscoped source-level required_prediction_unavailable facets; the logical-clip outcome partition remains a separate declared-row view. Valid nested findings that have no matching clip are retained as source-level unscoped findings and included in the dashboard finding total; the projection never assigns them to an arbitrary clip. Required-unavailable prediction facets without one exact physical witness are likewise retained once at source scope with their reason set rather than being guessed onto a take or logical row.

Nested check evidence is normalized-name addressed. If one source has that same normalized name at multiple physical indices, neither index is a unique witness: the physical rows carry duplicate_normalized_clip_name, name-addressed findings are counted once at source scope, and no findings, gaps, or predictions are guessed onto either physical or logical row. An established logical row must instead identify exactly one source-owned established physical row by source, source-take index, and take name, and its evidence/coverage/outcome must match that row during strict readback.

When transition evidence is present, a member's optional logical_clip is required exactly when its source_input, take_index, and take_name resolve uniquely through the dashboard source identities and logical declarations. Strict authority readback rederives the match rather than trusting the stored logical ID; absent, mismatched, and ambiguous witnesses remain unresolved. Runtime-set gaps and lifecycle are also rederived during strict readback from the declared member rows: each non-established member contributes one member_unavailable gap in member order, and the set is complete only when that derived gap list is empty.

The dashboard is inventory and evidence navigation only. It has no quality score and does not establish engine loading/playback, retargeting, contacts, visual or artistic quality, or gameplay acceptance. Caller-supplied per-asset report links must be exact logical-id keyed safe relative paths; source paths, licensed assets, and motion samples are never embedded.

Collection directional-speed evaluation

animsmith collection evaluate-directional-speed --policy POLICY.toml --evidence COLLECTION-OUTPUT.json --format json consumes only strict bounded collection-directional-speed-policy:1 TOML and collection-output V7, historical V6, or historical V5 JSON. It emits the JSON-only immutable urn:animsmith:schema:collection-directional-speed-evaluation:1 result described by collection-directional-speed-evaluation-v1.schema.json. The result identifies the raw policy and evidence bytes, retains all declared members in manifest order, and records incomplete/not-evaluated outcomes or declared-policy findings without evaluating a subset. Control-plane failures write no result and exit 2; result-bearing incomplete, not-evaluable, and finding outcomes exit 1; a complete passing policy exits 0.

Runtime-set evidence concludes only whether every declared membership and required indexed measurement was established. Its decision is always not_evaluated; it does not infer blending, synchronization, retargeting, controller policy, engine behavior, or artistic/gameplay readiness. A gait-group additionally projects each member's raw gait_phase availability (and phase when measured) onto that existing manifest-ordered member row. Its set-level evidence.gait_phase records lifecycle and members_measured; only a complete group (every declared member established and phase-measured) carries phase_spread and the explicit basis max_circular_deviation_from_mean. The scalar is the existing circular_phase_spread value, not a smallest covering arc, and is calculated from logical-ID-sorted phases even though member rows retain manifest order. Incomplete groups keep every member visible and omit both scalar fields; non-gait sets omit gait-phase evidence. Every declared member also carries raw root_travel: duration, translation availability, signed horizontal X/Z displacement, sampled horizontal travel, and speed availability/value. Set-level evidence.root_travel counts only members with every required raw fact and is complete only when all declared members are fully measured; it never reduces the set or adds direction, ratios, thresholds, or policy. The strict reader applies a 256 MiB N+1 cap before JSON decoding, validates current nested output-v19 plus historical collection-output-v9/output-v17, collection-output-v8/output-v16, collection-output-v7/output-v15, collection-output-v6/output-v14, and historical collection-output-v5/output-v13 through their existing reader, recomputes all summaries/work/set lifecycles, and rejects unknown fields or contradictory identities and states. Producer and reader also freeze 1 GiB per primary source, 16 GiB aggregate primary reads, and the collection-manifest V1 row/member/work limits. Derived normalized clip names allow at most 4,101 bytes: the 4,096-byte authored-name bound plus # and the largest duplicate ordinal permitted by the 4,096-clip manifest bound. Available nested measurement keys retain output-v19's 4,096-byte bound. If such a derived name cannot fit the immutable 4,096-byte text bound of the nested output-v19 contract, indexed clip measurements and physical binding are retained, but the nested document and its name-addressed check reference are nested_output_unavailable; the collection exits 1 instead of publishing schema-invalid nested JSON. After the aggregate N+1 witness is retained, later declared sources remain in the envelope as aggregate_exhausted with zero inspected bytes; they are not opened and cannot increase the terminal counter beyond N+1.

glTF animation addressability

animsmith generate addressability INPUT emits a separate, one-file V1 contract with immutable identity urn:animsmith:schema:gltf-animation-addressability:1. Its retrievable schema is gltf-animation-addressability-v1.schema.json. It is not an output-v11 measure/lint/diff envelope, and the two roots reject one another on readback. The staged reader accepts at most 256 MiB and applies that byte cap before UTF-8 or JSON decoding.

The root contains the normal bounded tool identity, the exact primary input identity, an engine-neutral inventory, and a nullable bevy adapter. The inventory retains the complete existing dependency-closure record plus raw source-order animation and channel observations. Source names are optional, non-unique metadata; source indices remain the identity authority. The inventory's canonical identity excludes tool metadata and the optional adapter, so selecting a profile does not change neutral evidence.

With no engine profile or another supported non-Bevy profile, bevy is null. For the exact Bevy revision 1 / 0.19.0 / gltf-asset-loader profile, it embeds the same-load prediction-provenance V1 record and the unchanged engine-addressability check evaluation. The evaluation's available facet subjects are the authoritative Animation{source_clip_index} display selectors. A required-unavailable facet remains blocking and makes the command exit 1. Incomplete dependency closure is retained honestly but does not, by itself, become a claim about runtime load success.

The contract is animation-only. It makes no scene, default-scene, skin, target-path or UUID, Bevy named-map-winner, extension-support, successful-load, target-survival, or animation-graph claim. JSON is canonical; --format text and --format markdown escape and render the same typed value without adding conclusions.

Rich glTF addressability v2

The richer producer is a separate immutable contract, urn:animsmith:schema:gltf-addressability:2; its schema is gltf-addressability-v2.schema.json. It preserves the V1 animation inventory and adds bounded same-load scene, node, skin, attachment, scene-path, default-scene, named-map, and animation- target evidence. V1 readers and the V1 Bevy revision-1 profile remain unchanged; selecting the richer exact Bevy path selects V2 rather than widening the historical root.

The raw inventory has independent coverage for scenes, nodes, skins, attachments, and path candidates. Complete empty domains prove absence; partial prefixes and unavailable domains never prove absence. Rows retain source-array indices, authored names, parents and child order, ordered scene roots, ordered skin joints, node-to-skin attachments, and all-scene root-to-node path candidates. An authored skin.skeleton is retained as an explicit source observation. Bevy 0.19 ignores that member, so V2 does not replace it with an inferred Bevy root. The report does not claim scene instantiation or SkinnedMesh attachment.

The exact Bevy adapter is paired with the existing one engine-addressability evaluation and reuses the V1 Animation{i} selector primitive. It is pinned to profile revision 3, Bevy v0.19.0, commit c6f634ca9f406d68ba5109d921247b654cb42c10, bevy_gltf 0.19.0, locked gltf 1.4.1, and commit-pinned label, loader, path, animation-target, feature, and root Cargo.lock sources. Scene{i} is emitted for each declared source scene; Gltf.default_scene is only a route to an existing Scene{i}. There is no DefaultScene label and no fabricated Scene0.

Bevy creates Skin{i}/InverseBindMatrices eagerly for every declared source skin, including unreferenced skins; an absent inverse-bind accessor uses the identity fallback. Skin{i} is materialized when any source node references the skin during Bevy's all-source-node construction pass. Source skin indices, not the order of Bevy's collected skin values, are identity. Named scene, animation, and skin maps are separate from typed labels and use source-order last-write-wins semantics (the skin map follows lazily created skins in first- reference order).

Target projections are per unique source animation target node and retain contributing animation/channel identities. Paths use authored node names, including an authored empty string exactly, or GltfNode{source_index} fallbacks, exclude the scene world-root name, and are projected only when reachability, hierarchy, dependency closure, feature settings, and collision checks are complete. A duplicate full path, multiple scene candidates, target-ID collision, unreachable target, missing bevy_animation, disabled load_animations, missing pointer width, or incomplete evidence is typed required_unavailable; no guessed path or UUID is published. Bevy's target-ID reproduction requires an explicit 32- or 64-bit pointer width because its segment lengths use target-width little-endian encoding; the host width is never inferred.

The projection also carries target_coverage, independently of the retained target rows. A target domain is complete, including when empty, only when the raw node/scene/path and animation/channel inventories are exhaustive. Partial or unavailable evidence makes coverage required_unavailable; a domain beyond the 4,096 row limit additionally reports target_domain_truncated, and an aggregate rich-projection limit uses projection_bounds_exceeded. This keeps positive-prefix target rows from being mistaken for proof of complete, collision-free coverage.

Each new rich projection domain is capped at 4,096 rows. Its aggregate structural references are capped at 65,536 and its dynamic projection text at 1 MiB; the sealed embedded V1 animation inventory and CheckEvaluation scopes retain their own bounds. Names and path segments are capped at 1,024 UTF-8 bytes, paths at 4,096 bytes and 256 segments, and the staged report reader at 256 MiB. Target coverage is an explicit projection: a retained canonical prefix is target_domain_truncated, while any new rich projection bound overflow is projection_bounds_exceeded; no retained target is treated as collision-free after truncation. Strict readback rejects N+1 collections and contradictory identities or states. A second bounded parse of already captured primary bytes is allowed within the same loader invocation, but no primary/dependency reopen is allowed. V2 remains prediction evidence only: it does not certify runtime loading, target survival, graph wiring, scene spawning, or playback. Required-unavailable prediction retains the existing exit-1 convention; malformed tuple, configuration, or input errors remain exit 2.

If the resulting single-check prediction would exceed core's per-file facet budget, the adapter compacts its unavailable facets to one subjectless engine-addressability:facet-budget scope with facet_budget_exceeded. This is a user-visible compaction marker, not a new check or a claim that omitted facets were available.

Engine import advice

animsmith generate import-advice INPUT emits a separate one-file V1 contract with immutable identity urn:animsmith:schema:engine-import-advice:1. Its retrievable schema is engine-import-advice-v1.schema.json. It is neither output-v11 nor the glTF addressability root; strict readers reject the other shapes. The staged reader applies a 256 MiB byte cap before UTF-8 or JSON decoding.

Every record embeds exact PredictionProvenanceV1: the frozen engine-profile fact bundle, fully materialized settings, authoritative source format, raw source facts, primary identity, and dependency closure from the same load. Each available clip row binds its source-order clip index to one normalized document index and carries the original source-name observation separately from the normalized name. It also retains explicit project loop/movement intent plus duration, speed, loop-endpoint, and declared-frame-grid measurement/status pairs. Advice identity is a domain-separated canonical digest of provenance identity, lifecycle, clip rows, and importer payload; tool build metadata is excluded.

For Unity 6000.3 Generic and Humanoid, the payload projects only settings already materialized by the frozen profile: Model Importer Convert Units, Bake Axis Conversion, Generic Root Motion Source, and each clip's lockRootRotation, lockRootHeightY, and lockRootPositionXZ. bake maps to true; extract maps to false. Unreal 5.8 and Godot 4.7 revision 1 have no modeled setting vocabulary, so they emit state: refused with profile_settings_unmodeled and exit 1 rather than guessing. Incomplete raw clip inventory, missing source-to-normalized linkage, or mismatched measurement/settings evidence likewise refuses without exposing a prefix.

V1 does not emit frame-number ranges, sample rates, unit conversions, root-motion predictions, or project-file mutations. Source seconds multiplied by a floating-point FPS are not authoritative authored frame coordinates. Available advice exits 0, typed refusal exits 1, and configuration, profile, format, input, or serialization errors exit 2. Text and Markdown are escaped presentation views; JSON remains the contract.

Revision-2 import-setting advice

The same command also emits the immutable V2 contract urn:animsmith:schema:engine-import-advice:2, described by engine-import-advice-v2.schema.json. It keeps the output-v15 tool, V4 prediction-provenance, and V4 prediction-basis types by reference, while adding only the V2 basis and optional native projection fields. The lifecycle is closed against the same-load dependency closure: complete closure requires available, the exact projection, and no refusal_reason; partial or unavailable closure requires refused, dependency_closure_incomplete, and no projection. Unknown tuples, missing settings, and unsupported formats are configuration errors rather than advice documents, so they cannot be recast as a guessed projection.

Only these exact profile/input tuples can produce an available V2 projection:

The projection is bounded to those documented keys and retains each value's explicit_config or profile_default origin. For Unreal, default_30 maps to bUseDefaultSampleRate=true; source_determined maps to false with CustomSampleRate=0; a custom rate maps to false with its explicit hertz. This is a deterministic same-load parameter projection only. It does not execute an engine importer, read back an imported asset, infer frame ranges, units, skeleton/retargeting, compression, root motion, runtime behavior, or write project files. The historical V1 contract and its refusal semantics remain immutable.

Contract identities

Validation and comparison JSON commands emit output contract v19 with the current protocol identity urn:animsmith:schema:output:19. Output-v17 retains identity urn:animsmith:schema:output:17 and remains retrievable historical schema evidence at output-v17.schema.json, paired with urn:animsmith:schema:measurements:16. Output-v16 remains retrievable historical schema evidence at output-v16.schema.json; its repository URL is a retrieval location, not the protocol identity urn:animsmith:schema:output:16. Output-v11 remains immutable historical schema evidence, and the measurement reader retains its validation paths for existing reports while CLI producers emit output-v19. urn:animsmith:schema:output:15, urn:animsmith:schema:output:14, urn:animsmith:schema:output:13, urn:animsmith:schema:output:12, and urn:animsmith:schema:output:11 remain immutable historical contracts and are never retargeted.

The current CLI emits output-v19. The Bevy revision-3 track-support slice continues to use V5 prediction provenance/readback with the bounded raw animation/channel inventory and gate outcomes described below. Unity Generic root-motion uses V6 prediction provenance. This does not retarget or invalidate output-v16, output-v15, or output-v9; all historical readers remain readable and their behavior remains preserved.

Those immutable prediction contracts consume measurements-v16. In output-v19, their basis values are validated against a deterministic measurements-v18-to-v16 evidence view: fully measured loop-continuity rows omit the V17-only per-bone status, while any unavailable bone projects to the historical unavailable outer fact; every V18-only rotation_xyzw fact is removed from skeleton and skin linear measurements. The output-v19 report still retains the complete measurements-v18 rows. This projection cannot turn unavailable evidence into measured evidence, and a projection or basis mismatch is rejected rather than weakening the prediction.

Output-v15 retains the V3 provenance/prediction path for revision-1 profiles and adds prediction-provenance:4, engine-profile-facts:2, resolved-engine-settings:3, raw scene/attachment inventory V1, machine results V1, and engine-prediction:4 for revision-2 profiles. One file cannot mix the two revisions. Settings retain at most 4,096 canonical clip rows. A 4,097th clip records partial coverage and bounded work; the identity commits to that state, and lint emits required-unavailable evidence (resolved_settings_overflow) instead of treating the retained prefix as a complete V1 inventory.

Measurement evidence is nested and independently versioned as urn:animsmith:schema:measurements:18. Its retrievable schema is measurements-v18.schema.json. Version 18 adds rotation_xyzw to every LinearTransformMeasurements surface exactly when its classification is unit_orthonormal. It is the canonical XYZW quaternion for the linear matrix's proper-orthogonal polar factor (the nearest proper rotation): the classifier deliberately admits small scale and shear residuals, which a quaternion does not encode. Exact rotations therefore recompose directly; tolerance-admitted residuals retain their matrix evidence alongside this orientation fact. Extraction uses all matrix branches near half turns, and the largest absolute component (XYZW tie order) is always non-negative, so equivalent q and -q rotations compare identically. The field is absent for uniform-scaled, non-uniform, sheared, reflected, singular, and non-finite transforms. Version 17 adds explicit availability to every per-bone loop-continuity row. Version 16 (urn:animsmith:schema:measurements:16), preserved at measurements-v16.schema.json, added per-primitive measurements in source primitive order. Each primitive records its nullable source material index, total decoded POSITION row count, and finite row count. Indexed primitives count each stored position once, not once per index reference. Primitive AABBs and centroids are finite-only and omitted when the finite count is zero. Version 16 also records leading_magic_hex only for unsupported, nonempty image payloads: at most the first 16 bytes as lowercase hex. It is bounded evidence, not a guessed format classification. urn:animsmith:schema:measurements:15 remains immutable historical evidence and has no primitive measurements or leading magic field. Version 15 added canonical per-bone TRS channel coverage and root-trajectory evidence. Version 14 introduced a sibling _availability status (measured, not_applicable, or unavailable) alongside its optional value field, so a consumer can distinguish "this clip has no subject for the fact" from "the fact applies, but derivation failed" — a distinction a bare optional value cannot express. Version 13 retains each per-joint source-declaration inverse-bind matrix beside the observations derived from it, refuses non-affine sources, and publishes a scale-free reciprocal infinity-norm condition number before trusting an inversion. Measurements v14 and earlier, and output v10 and earlier, remain immutable historical contracts. The historical output-v10 identity is urn:animsmith:schema:output:10. Output v9 first paired measurements-v15. Output v10 retained it and added the prediction-provenance substrate described below. Output v11 retains those contracts and adds role-resolution provenance: each delivered resolved bone name remains in rig.resolved_roles, while the matching policy appears in the parallel rig.resolved_role_policies map. Its rig.resolution_outcome is one of resolved, coverage, ambiguous_exact_match, ambiguous_folded_match, role_collision, or ambiguous_profile. Built-in profile fallback is only unique ASCII case-insensitive matching; explicit [rig.roles] entries remain exact and use explicit. Any future nested measurement revision will likewise require a new outer identity.

convert --format json is deliberately a separate conversion-evidence contract, not another command in the output-v11 envelope. Its immutable identity is urn:animsmith:schema:conversion-evidence:2; its retrievable schema is conversion-evidence-v2.schema.json. This lets producers pin conversion provenance independently of measurement and lint evidence.

An asset-property refusal from convert, assemble, generate contact-fragment, or collection transform-foot-cycle is not success evidence. Under --format json it uses the separate immutable urn:animsmith:schema:producer-refusal:1 contract, whose retrievable schema is producer-refusal-v1.schema.json.

This keeps conversion evidence v1/v2, assembly evidence v1-v7, output v1-v9, and scale evidence v1-v5 immutable. The record has outcome: "rejected", a null result, the command, and a typed {stage, kind, detail} rejection.

assemble writes a separate character-assembly-evidence v7 document to its required --evidence path, and prints the same record to stdout under --format json. Its immutable identity is urn:animsmith:schema:character-assembly-evidence:7; its retrievable schema is character-assembly-evidence-v7.schema.json. The paired GLB and evidence are prepared before publication, so an operator failure emits neither new destination and restores any prior pair.

scale writes scale-evidence v4 for glTF/GLB and the separate v5 FBX rest/bind record for the narrow FBX path to its required --evidence path, and prints the same record to stdout under --format json. Their immutable identities are urn:animsmith:schema:scale-evidence:4 and urn:animsmith:schema:scale-evidence:5; their retrievable schemas are scale-evidence-v4.schema.json and scale-evidence-v5.schema.json. The artifact and its evidence are prepared as temporaries and published as one pair, so a refusal or an operator failure emits neither destination and restores any prior pair.

Publication promotes the two temporaries with two renames, which are individually atomic but not atomic together. Only the artifact destination is moved aside first, so a process killed between the renames leaves the new artifact beside the previous evidence — a complete pair whose members disagree, which the evidence's own record of the artifact digest makes detectable. Backing the evidence up as well would turn that same window into a new artifact with no evidence at all. Both members are promoted from temporary files and therefore land with mode 0600 rather than the 0644 a plain create under the process umask would produce; this is shared by every producer that publishes a pair.

The --format json copy on stdout is a view of the pair, never a member of it. Both producers serialize their record exactly once and hand those same bytes to the evidence temporary and to stdout, so the file and the stream are identical by construction rather than by two serializers agreeing. Because the stream is not a destination, a stdout that cannot take it — a closed pipe, a full filesystem — changes nothing about publication and does not change the exit code: the failure is diagnosed on stderr and the outcome stands. Read the --evidence file, not stdout, when the record must be durable.

Conversion evidence v1 remains a historical immutable contract at urn:animsmith:schema:conversion-evidence:1. The current CLI emits v2 exclusively; regenerate v1 evidence when a v2 consumer is required.

Output-v2, output-v3, output-v4, output-v5, output-v6, output-v7, output-v8, output-v9, and output-v10 remain historical immutable contracts, as do output-v11 through output-v16. The current CLI emits output-v17; diff also retains strict version-matched historical readers, including output-v9. Regenerate an output-v14 report with a historical producer when a historical v14 artifact is required. Regenerate a current output-v19 report from the original asset with animsmith measure --format json when a current artifact is required.

Contact fragments

contact-fragment-v1.schema.json (urn:animsmith:schema:contact-fragment:1) is the strict, portable envelope for one selected clip's normalized contact facts. Its reader and RFC 8785 canonical serializer live in animsmith-core. animsmith generate contact-fragment is the strict V1 producer: it publishes a source-bound sidecar only after finite bilateral stance-support preflight and a complete dependency closure; typed refusals publish nothing. It reports sampled support, not physical contact or gameplay meaning.

The format-neutral core also implements the separately versioned contact-transform-result-v1.schema.json (urn:animsmith:schema:contact-transform-result:1) reader, canonical serializer, and exact trim/slice/resample/time-warp contact mapping. A result reader is given the separately supplied input fragment and an external context containing the current input/output artifacts, their complete captured closures, the expected producer, and any handler-produced extension outputs. It validates the closure-to-artifact bindings and independently rederives every event outcome and successful inline fragment instead of trusting copied result rows. Extension transformation requires exact schema/version-preserving output from an operation-specific handler; opaque payloads are never automatically copied, and unsupported extensions refuse the whole operation. This library contract does not mutate an animation asset or publish a collection generation directory.

Foot-cycle generation evidence

collection transform-foot-cycle publishes two strict success-evidence contracts outside the ordinary output envelope:

• each members/NNNNNN/evidence.json is urn:animsmith:schema:foot-cycle-member-evidence:1;
• aggregate-evidence.json is urn:animsmith:schema:foot-cycle-aggregate-evidence:1.

The aggregate is serialized once, staged as the generation member, and those same exact bytes are written to stdout after the no-replace directory publish. Its resource record includes itself: bounded serialization iterates the byte count to a stable exact value before publication, then verifies that the four component totals equal total_bytes and do not exceed 256 MiB. Member evidence binds the exact source/output/closure/contact identities and independent proof facts; the aggregate binds every deterministic relative path and member evidence identity in declared order. The retrievable schemas are foot-cycle-member-evidence-v1.schema.json and foot-cycle-aggregate-evidence-v1.schema.json.

A valid asset or capability refusal uses producer-refusal-v1.schema.json with command collection-transform-foot-cycle and exits 1. An operator failure emits no JSON and exits 2. The transformed contact fragments themselves remain the existing canonical contact-fragment:1 contract; the contact transform result is proof input and is not an extra generation file.

Foot-cycle failure diagnostics

Foot-cycle planner diagnostics use foot-cycle source preparation failed (<rule>), optionally followed by for member <logical-id>. Asset refusals carry this text in rejection.detail; operator failures carry it on stderr. The rule identifies which planner check failed without exposing source paths or nested parser errors. Logical IDs are bounded, validated collection IDs such as com.example/walk, not source-file locators.

The planner adapter names every current core error:

This is the adapter inventory, not a promise that every error can occur after CLI admission. The bounded readers, declaration constructors, manifest-binding preflight, and evidence assembly reject or prevent some states before the planner runs. Their existing diagnostics, validation order, and exit routes remain in effect. For example, an invalid declaration still reports control; the tool does not postpone that validation to obtain a planner label.

Planner asset refusals retain stage analysis and kind asset-recipe-mismatch. The two operator errors in the table still emit no JSON. A future unrecognized variant from the non-exhaustive core error enum uses the closed compatibility label unknown-planner-rule and the same asset-refusal route; no current variant uses that fallback. The four member IDs above are retained from the core error, and no member is inferred for other rules. In particular, the topology and map errors currently carry no member.

Proof refusals retain stage proof, kind proof-failed, and the existing foot-cycle proof failed (<rule>) text. ArtifactPreflight, ClipMap, ContactBoundary, and LoopContinuity append for member <logical-id> for the prepared member being judged, including when several members select separate clips in one source. ArtifactPreflight covers both candidate document shape and writer preflight. Other proof diagnostics retain their existing text; collection-wide failures such as GaitSpread have no member attribution. A failure still prevents publication of the generation.

Common envelope

{
  "schema_version": 19,
  "schema": "urn:animsmith:schema:output:19",
  "tool": {
    "name": "animsmith",
    "version": "0.14.0",
    "source": {
      "revision": "0123456789abcdef0123456789abcdef01234567",
      "dirty": false
    }
  },
  "command": "measure",
  "summary": { "files": 1 },
  "files": []
}

tool.version is the package's plain semantic version. Source revision and dirty state are separate fields so automation never has to parse a decorated version string. Packaged source records its Cargo VCS revision and leaves dirty as null; builds without trustworthy VCS metadata may leave both fields null.

Every measure and lint file record also includes input, with the exact primary-file byte count and lowercase SHA-256 digest of the bytes parsed for that row. Retain this identity with the JSON evidence when a pipeline promotes or publishes an asset: it proves which primary payload the recorded result describes. For multi-file invocations, rows stay in argument order and each has its own independently calculated identity.

The input identity covers only the named primary input file. For profiled lint output, the sibling prediction provenance carries the bounded same-load dependency closure, including identities for captured external resources when coverage is complete. A primary-file digest alone remains insufficient closure evidence for text glTF or another source with external dependencies.

Operator failures do not emit a JSON envelope. They exit 2, write a diagnostic to stderr, and leave stdout empty. Content findings exit 1 at the configured threshold. Any required_prediction_unavailable facet also exits 1 and cannot be suppressed by severity or --allow; ordinary engine-neutral coverage gaps remain nonblocking.

convert and assemble asset refusals exit 1. JSON mode emits exactly one producer-refusal v1 document on stdout and leaves stderr empty; text mode leaves stdout empty and emits one escaped stderr line carrying the same stable kind. A consumer can therefore branch on exit plus stdout without parsing English. Failure to serialize a truthful refusal record is an operator error; failure to deliver already serialized bytes keeps exit 1 and is diagnosed best-effort on stderr.

convert

convert --format json emits one conversion-evidence v2 document. It records the input and output paths, the requested options, and counts derived from the written artifact. It is producer evidence: consumers should use the stable field names and schema identity rather than parsing the text write summary.

That contract is success-only. A rejected source instead emits the shared producer-refusal v1 record:

{
  "schema_version": 1,
  "schema": "urn:animsmith:schema:producer-refusal:1",
  "tool": {
    "name": "animsmith",
    "version": "0.14.0",
    "source": { "revision": null, "dirty": null }
  },
  "command": "convert",
  "outcome": "rejected",
  "result": null,
  "rejection": {
    "stage": "transform",
    "kind": "transform-refused",
    "detail": "cannot bake static transforms: document has no mesh instances"
  }
}

{
  "schema_version": 2,
  "schema": "urn:animsmith:schema:conversion-evidence:2",
  "tool": {
    "name": "animsmith",
    "version": "0.14.0",
    "source": { "revision": null, "dirty": null }
  },
  "command": "convert",
  "input": "prop.fbx",
  "output": "prop.glb",
  "options": {
    "animation_only": false,
    "bake_static_mesh_transforms": true,
    "material_texture_recipe": null
  },
  "artifact": {
    "nodes": 2,
    "animations": 0,
    "meshes": 1,
    "primitive_positions": 3,
    "materials": 1,
    "clips_without_writable_tracks": 0
  },
  "static_mesh_bake": {
    "entries": [
      {
        "source_node_index": 4,
        "source_node_name": "prop",
        "source_mesh_ordinal": 0,
        "source_mesh_index": 7,
        "source_mesh_name": "prop_mesh",
        "output_node_index": 1,
        "output_mesh_index": 0,
        "world_transform": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
        "linear_determinant": 1,
        "primitive_count": 1,
        "position_count": 3,
        "normal_count": 3
      }
    ]
  }
}

static_mesh_bake is absent unless --bake-static-mesh-transforms was requested. Its entries are in deterministic source-node order. source_node_index, source_mesh_ordinal, and source_mesh_index identify the source record; names are display data and need not be unique. world_transform is the 16-element column-major rest world matrix applied to the source positions. linear_determinant records the accepted transform's linear determinant. The output node and mesh indices are indices in the generated artifact.

The static bake is opt-in and conflicts with --animation-only. It only accepts unanimated, unskinned, singly-instanced static geometry with finite, non-reflecting, non-singular (including near-singular) transforms. It bakes positions and inverse-transpose normalized normals into a canonical identity-root output while retaining indices, UVs, model-supported material assignments, and embedded base-color and normal textures. Unsupported input is an operator error, not partial evidence. Repeated same-platform conversion with the same input and options emits a byte-identical artifact.

When options.material_texture_recipe is a path, the top-level material_texture_recipe object is required. When it is null, that object is prohibited. This separates ordinary linked or embedded texture conversion from recipe provenance. The object records the recipe identity, declared recipe path and optional root, dimension cap, locked processor policy, and deterministic consumed/emitted image records:

{
  "schema_version": 1,
  "schema": "urn:animsmith:schema:material-texture-recipe:1",
  "path": "recipes/materials.toml",
  "texture_root": "textures",
  "max_dimension": 1024,
  "processor": {
    "image_crate": "image@0.25.10",
    "png_crate": "png@0.18.1",
    "jpeg_crate": "zune-jpeg@0.5.15",
    "base_color_algorithm": "sRGB-to-linear premultiplied-alpha Lanczos3",
    "normal_algorithm": "tangent-vector Triangle renormalize +Z fallback",
    "data_algorithm": "linear-channel Triangle",
    "output_encoding": "PNG RGBA8 compression=Best filter=NoFilter"
  },
  "consumed_inputs": [
    { "material_index": 0, "material_name": "surface", "slot": "base_color", "declared_path": "surface-base.png", "mime": "image/png", "dimensions": [2048, 1024] }
  ],
  "emitted_textures": [
    { "material_index": 0, "material_name": "surface", "slot": "base_color", "declared_path": "surface-base.png", "mime": "image/png", "dimensions": [1024, 512], "resized": true, "emitted_bytes": 1234 }
  ]
}

Each array has the required BaseColor and normal pair plus any declared metallic-roughness and occlusion slots for every recipe material. Records are ordered by source-material index, then BaseColor, normal, metallic-roughness, and occlusion; recipe declaration order does not affect them. material_index is the source-material identity; material_name is display data. emitted_bytes is the encoded byte count. See material texture recipes for containment and image semantics.

assemble

assemble writes character-assembly evidence v7 beside its GLB. The evidence binds the effective recipe and its SHA-256, every base/clip/recipe/texture input and digest, selected source takes and windows, exact track-operation counts, removed named-bone translation deltas, mesh and skin canonicalization, tool identity, and the final artifact digest and counts. When prune_constant_tracks is enabled, each clip also records the exact removed tracks in pruned_constant_tracks, including each track's index in the completed, normalized output clip immediately before pruning (the pre-prune authored order). In assembly evidence v3 through v7, bone_index is the BoneId in the post-canonicalization/pre-node-removal skeleton; removed_nodes provides the stable compaction ledger needed to derive a surviving final index. The array is empty when pruning is disabled or no track is removed. transforms.removed_nodes records the final structural projection in original pre-removal node order, with each node's name, original index, nullable original parent index, and whether it was selected directly. It is empty when the recipe selects no nodes. Paths remain operator-declared; canonical host paths used for containment checks are not serialized.

Assembly evidence remains success-only. A valid recipe that does not fit the loaded assets exits 1 before publication and uses producer-refusal v1 in JSON mode; invalid recipe syntax/schema/values or an input/path/publication I/O failure remains exit 2 with empty stdout.

When the optional recipe-v7 rest_bind_scale operation is active, evidence also pins the declared root name, every input's resolved root name/source-node index and applicable source-skin index, the effective staged source selectors and factor, the exact digest and versioned basis fingerprint for the base and every clip input, each semantic compatibility result, its rest-bind or skinless-clip-tracks application, and the shared scale proof over the exact staged artifact bytes. Full rest/bind rows name urn:animsmith:character-assembly-scale-basis:1; animation-only clip projections name urn:animsmith:character-assembly-skinless-clip-scale-basis:1 and omit the inapplicable resolved skin index. A captured clip source may carry a skin or mesh; its source_projection record remains raw-source evidence while the track-only scale projection excludes geometry, deformation, materials, and bind state before rebasing. For glTF/GLB, role-specific preflight retains framing, dependency, raw-coverage, named-skeleton, and animation accessor/layout safety. The stable skinless-clip-tracks value names the projected operation domain, not the raw source contents. Base and full rest/bind rows remain strict. residual_comparison_counts uses the same twelve stable field names as proof.residuals, keeping every measured maximum paired with the count from the shared proof API without changing immutable scale-evidence v4. V7 retains v6's captured input container and either its raw glTF preservation boundary or its normalized/baked FBX capability inventory and private staged-GLB identity. For FBX, that private stage may exclude an unskinned mesh instance inside a declared remove_nodes closure while the input digest and capability inventory continue to describe the captured raw source. Omitting the block omits this operation evidence and retains ordinary assembly behavior under the v7 envelope.

The normative recipe and evidence contracts are character-assembly-recipe-v7.schema.json and character-assembly-evidence-v7.schema.json. The recipe identity is urn:animsmith:schema:character-assembly-recipe:7; v1 through v6 remain immutable historical contracts. See multi-source character assembly for operation and consumer-boundary semantics. Migrate from v6 by selecting recipe/evidence v7 and replacing its two source indices with root_node_name; an omitted rest_bind_scale block retains the existing behavior, while v3 continues to reject that block as unknown.

scale

The scale workflow explains when to choose each operation and how the rewrite/reload/proof/publication transaction produces this record. This section is the wire-format authority.

glTF/GLB scale writes scale evidence v4 beside its artifact. One record serves both outcomes, discriminated by outcome:

A refused run's record is printed by --format json and is never written to the --evidence path: publication is an artifact/evidence pair, and a refusal has no artifact. This follows lint --format json, which prints its machine-readable result to stdout and exits 1 when the asset has a problem. For example, a finite negative primary skin weight is rejected during planning with rejection.kind: "negative-skin-weight"; the record has result: null and neither destination is written. Shared structural refusals likewise keep their specific existing kinds (such as invalid-parent, invalid-track-shape, or invalid-mesh-instance) rather than collapsing into a generic document-shape kind.

The record binds the operation and its declared selectors, the operator's declared paths verbatim, the input digest and byte count, and the complete raw capability manifest of the source. capability is null only for a refusal raised before an inventory existed — bytes that never parsed. A published record always carries the manifest, because publication is reachable only through a preflight that built one. In v4 that manifest includes the sorted JSON-pointer inventory of every static mesh/node and animated morph-weight source accepted for preservation. Static JSON weights retain their numeric values, while animated weight accessor payloads remain byte-exact. A published run adds the fixed tolerance policy by identity and in full, both observed-factor witnesses with the divergence between them and the ceiling the design expects of it, the affected node and skin identities in the raw source index space the selectors use, the rewritten model domains, proof coverage and results, the artifact-level residuals, and the artifact's own digest, byte count, rewritten accessors and rewritten JSON pointers.

Residuals are never published flat. Each is { "evaluated": bool, "max": number|null }, with max null exactly when the plan's obligations and the source's own payloads gave that claim nothing to check. A residual reported as 0.0 for a claim nothing evaluated would be a false record rather than a missing one, which Appendix D §D.6 forbids.

Every number in the record is guarded for finiteness before serialization. serde_json renders NaN and both infinities as null, which in a residual field would read as a checked-but-unmeasurable claim; the producer fails instead, and publishes nothing.

proof.read_back_digest_matches records the producer's own third artifact check: the staged artifact was re-read from disk and its digest compared with the bytes that were proved. The two frontend proofs already reload the candidate, re-run the shared core proof, and re-run the whole rewrite to byte-compare for determinism; what they cannot see is the write path, which is what this closes.

Paths are recorded exactly as the operator wrote them. Canonical host paths are computed only for publication-safety comparisons among input, output, evidence, and retained external dependency keys. They are deliberately not serialized, so identical arguments produce byte-identical evidence. Nothing in the record carries a timestamp.

The normative glTF/GLB contract is scale-evidence-v4.schema.json. The CLI emits v4 for glTF/GLB; immutable scale-evidence-v1.schema.json, scale-evidence-v2.schema.json, and scale-evidence-v3.schema.json remain available for historical records.

The narrow FBX scale rest-bind path emits v5, scale-evidence-v5.schema.json, and always writes a new .glb artifact. Its capability is the complete ufbx normalized-domain inventory, not a raw FBX accessor manifest. result binds the private staged GLB identity and then nests the v4-shaped exact GLB rewrite, reload/proof, and read-back record for the published candidate. This is a re-encoding proof, not a claim that FBX bytes, object properties, or authored curve keys were preserved. Source-aware admission can therefore allow user-defined properties and bounded external texture/video declarations when same-load evidence proves they do not affect rest/bind state. The frozen v5 record retains the inventory counts; the same-load loader source separately retains raw facts and dependency-closure coverage/identities, but v5 does not serialize those sidecars. Supported linked texture bytes are captured before staging so the operation does not silently remove them, without claiming raw FBX material/texture-assignment preservation. The inventory projection is frozen with v5: a new FBX fact requires a new evidence identity rather than silently changing this wire record. Whole-document FBX scaling remains refused.

A whole-document factor of one has no raw write set. Its v4 result.artifact.rewritten_accessors, rewritten_json_pointers, and reencoded_buffers arrays are empty, and result.proof.artifact.rewritten_accessor_count is zero. This factor-one behavior is carried forward unchanged from v3.

For rest/bind, result.domain_rewrites.scale_animation is true: every stored scale VEC3 is rebased by its topology multiplier — 1 / s at the selected root, 1 at strict affected descendants and unaffected nodes — including both cubic-spline tangent elements. It is false for whole-document conversion, which preserves dimensionless scale channels. The raw preflight also refuses an animation channel targeting a node authored with matrix as animated_matrix_node; no artifact or evidence file is written for that refusal.

For an artifact-proof-failed refusal from the exact raw-JSON-preservation walk, v2 added rejection.artifact_proof_differences: the artifact proof's bounded, deterministically ordered raw-JSON difference sample. items has one to 16 entries, each with a JSON-pointer location and an artifact_added, artifact_removed, or value_changed kind. omitted counts entries outside the prefix, so the full difference count is items.length + omitted. The field is null when that exact-preservation walk did not supply locations for the refusal. It does not replace rejection.violations, which continues to describe unsupported source capabilities.

measure and lint

Both commands put evidence under files[].measurements:

{
  "schema_version": 18,
  "schema": "urn:animsmith:schema:measurements:18",
  "clips": {},
  "mesh_definitions": [],
  "node_instances": [],
  "scenes": [],
  "skeleton_source_coverage": "unavailable",
  "skeleton_nodes": [],
  "skins": [],
  "material_resource_coverage": "complete",
  "material_definitions": [],
  "textures": [],
  "images": []
}

clips maps clip names to duration, frame count, animated bones, exact local TRS channel coverage, rotation ranges, optional per-bone loop continuity, and optional role-dependent gait, foot-seam, root-trajectory, and speed metrics. bone_channels is the canonical set of non-empty local channels present in the measured document:

"bone_channels": [
  { "bone_index": 0, "bone_name": "hips",
    "properties": ["translation", "rotation"] },
  { "bone_index": 3, "bone_name": "weapon_socket",
    "properties": ["scale"] }
]

Rows use skeleton-index order; properties use translation, rotation, scale order. Bone index is identity and the name is display metadata, so duplicate bone names remain distinguishable. Duplicate tracks for one (bone, property) pair collapse to one presence fact. This describes surviving normalized TRS coverage in the artifact regardless of which transforms were requested; it is not pruning evidence, track multiplicity, morph-weight coverage, or a raw source-channel inventory. animated_bones remains the sorted unique name projection for compatibility. Empty or structurally malformed channels do not contribute to bone_channels, animated_bones, or bone_rotation_range_deg; every rotation-range key is therefore also present in animated_bones.

mesh_definitions[].primitives is a source-order array. Each row retains the nullable source material_index, counts decoded base POSITION rows in vertex_count, and counts finite rows separately in finite_vertex_count. primitive_index retains the original zero-based source slot, so gaps are valid when a loader omits unsupported source primitives; normalized documents without source identity use contiguous retained-order fallback values. Indexed primitives count each stored position once; index references are not expanded or counted repeatedly. Primitive geometry_aabb and geometry_centroid use finite positions only and are absent when there are no finite positions. Mesh-level totals use the same finite-only geometry domain. For unsupported nonempty images, leading_magic_hex records at most the first 16 payload bytes as lowercase hex. It is evidence of the unsupported bytes, not an inferred or guessed image format; it is absent for supported images and other unavailable cases.

Each optional clip fact — loop_continuity, loop_endpoint_mode, frame_grid, loop_seam_ratio, gait (and its own gait.phase), root_trajectory (with independent nested translation and yaw facts), and speed_mps — carries a required sibling <field>_availability status (gait.phase uses phase_availability, nested beside phase inside the gait object) with one of three values:

• measured: the fact was derived; the sibling value field is present.
• not_applicable: this clip has no subject for the fact (for example, no declared loop, no resolvable gait roles, or no root/hips travel quantity); the sibling value field is absent.
• unavailable: the fact applies to this clip, but it could not be derived (evidence was insufficient or a producer stopped emitting it); the sibling value field is absent.

The value field is present if and only if its status is measured; the schema rejects a measured status without a value and a not_applicable or unavailable status with one. This distinction matters because the two absences require opposite handling: legitimate non-applicability should remain acceptable, while an applicable-but-unavailable metric must not silently pass a consumer threshold that only checks for a present value.

Field-by-field applicability:

root_trajectory selects the resolved Root role whenever it exists. Hips is used only as source_role: "hips_fallback" when Root is unresolved; a bad or unmeasurable resolved Root never causes a silent Hips fallback. A valid selection keeps its bone_index, bone_name, and source role even when one or both nested metric domains are unavailable. Translation and yaw are derived independently, so bad positions do not erase usable yaw and bad rotations do not erase usable translation.

Collection lint projects the existing per-document duration_s, root trajectory translation availability and X/Z/travel values, plus speed_mps availability/value, into each declared runtime-set member's root_travel object. evidence.root_travel.members_measured counts only rows that have all of those raw facts, while its lifecycle is complete only when that count equals the declared member count. It retains manifest member order and does not infer a direction, reference member, ratio, threshold, finding, or controller policy.

The translation domain is normalized right-handed, +Y-up model space in metres: +X is right and -Z is forward. Signed X/Z and Y displacement compare the final sample to sample zero. horizontal_travel_m sums the XZ length of every sampled step, so horizontal out-and-back motion does not collapse to a zero fact. Vertical min/max are sampled signed displacements from sample zero, include the initial zero, and contain the endpoint displacement.

Yaw chooses at sample zero the positive local Z, Y, or X axis with the largest finite horizontal projection (ties prefer Z, then Y, then X), records that heading_axis, and holds the witness for the clip. net_yaw_deg is the endpoint-equivalent signed result in [-180, 180]; unwrapped_yaw_deg is the signed sum after shortest-step wrap handling; and yaw_travel_deg sums the absolute sampled steps so reversals do not cancel. An adjacent sampled step within 0.0001 degrees of exactly 180 degrees has no recoverable direction, so yaw is unavailable rather than guessed. Positive yaw increases atan2(x, z); for a +Z-aligned witness this rotates +Z toward +X, the positive right-handed direction about normalized +Y. A multi-step endpoint-equivalent result within the same 0.0001-degree tolerance of a half turn is canonicalized to signed +180 or -180 using the sign of the unwrapped result.