# Integration Guide

MoonBVHKit is designed for asset-pipeline checks rather than GUI plug-ins.

## CI Asset Gate

Use the parser and validator to reject malformed BVH clips before they enter a game project.

```mbt
test "validate clip" {
  let report = @moonbvhkit.validate_bvh(@moonbvhkit.fixture_walk_bvh())
  assert_true(report.ok())
}
```

## Unity Workflow

`build_unity_clip_plan(document)` creates metadata that a Unity-side tool can consume:

- clip name
- frame rate
- duration
- root joint
- joint paths
- root-motion delta
- importer warnings

MoonBVHKit does not call Unity or require Unity to be installed. This keeps the package portable and easy to verify in MoonBit CI.

## Blender Workflow

`build_blender_import_plan(document)` describes how a BVH clip should be treated before import:

- armature name
- bone and leaf counts
- frame start and end
- FPS
- whether root motion should be preserved
- axis and conversion notes

MoonBVHKit does not ship a Python add-on. Editor-side integrations can read the JSON plan generated by this package.

## Exported Tables

`joint_table_csv(document)` can be used to inspect skeleton layout.

`channel_range_csv(document)` highlights animated and static channels.

`root_motion_csv(document)` produces per-frame root translation samples.

## Recommended Pipeline

1. Export ASCII BVH from capture or animation software.
2. Feed the BVH text into `parse_bvh`.
3. Run `validate_document`.
4. Inspect `analyze_bvh` and `channel_ranges`.
5. Compare `summarize_skeleton` or `compare_skeletons` against a reference rig.
6. Run `quality_report` and use `recommended_action` as the CI gate decision.
7. Generate a Unity or Blender plan.
8. Import into the target tool only after validation passes.

This gives MoonBit a real role in the pipeline without depending on native editor environments during package verification.

## Retarget Planning

`build_name_based_retarget_map(source, target)` can create a first-pass compatibility table for same-named bones. It is intentionally conservative: it reports channel compatibility and leaves actual retargeting to the downstream DCC or engine runtime.

`compare_skeletons(reference, candidate)` is better for CI gates because it highlights missing, extra, and mismatched paths.

## Motion Cleanup

`normalize_root_origin(document)` rewrites copied frame data so the first root position starts at zero.

`detect_root_teleports(document, threshold)` flags abrupt root translation jumps.

`slice_document(document, start_frame, end_frame)` produces a shorter clip while preserving the parsed skeleton.

`resample_document_nearest(document, target_frame_count)` changes sample density while preserving clip duration and endpoint frames.

`root_motion_bounds(document)` returns the minimum, maximum, and occupied size of root translation for framing, culling, and asset review.

## Quality Gate

`quality_report(document)` combines validation findings with motion-oriented heuristics such as very short clips, low frame rate, and large root-position jumps.

Use `quality_report_to_json(report)` when a CI job or editor-side bridge needs a machine-readable decision. Use `quality_action_for_bvh(input)` for the shortest parse-and-decide path.

Use `quality_report_to_junit_xml(report)` when CI should display BVH quality findings alongside normal test results.

## Import Profiles

Use `evaluate_import_profile(document, unity_import_profile())` or `evaluate_import_profile(document, blender_import_profile())` when a project wants editor-specific limits without binding to the editor.

Use `strict_ci_import_profile()` for repository gates where unknown channels, low quality scores, or overly large clips should block the asset before review.

`evaluate_default_import_profiles(document)` returns a compact matrix across Unity, Blender, strict CI, and preview presets. Export it with `import_decisions_to_csv(decisions)` for dashboards or build logs.

`evaluate_bvh_batch(assets, profile)` applies one profile to a named asset set and returns accepted/blocked totals plus every individual decision. JSON and CSV exporters make the result suitable for build artifacts.

The built-in CLI exposes the same gate:

```bash
moon run cmd/main -- --quality --json
moon run cmd/main -- --profile unity
moon run cmd/main -- --profiles --csv
moon run cmd/main -- --bounds --json
moon run cmd/main -- --resample 12
moon run cmd/main -- --batch --profile strict-ci --csv
moon run cmd/main -- --junit
```