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.