# Agent Reference

This folder holds factual package reference for `mbt-3d`.

## Public Components

- `Scene3D`
- `Model`
- `AnimatedModel`
- `MorphableModel`
- `BoneAttachment`

## Advanced Hooks

- `useClonedModel`
- `preloadModel`
- `useAnimationController`
- `useMorphTargets`
- `useMeshVisibility`
- `useMaterialColor`
- `useMaterialTexture`
- `preloadTextures`
- `useEyeAnimation`

## Exported Types

- `Scene3DProps`
- `RendererConfig`
- `ToneMappingMode`
- `ModelProps`
- `ModelInfo`
- `AnimatedModelProps`
- `AnimatedModelInfo`
- `AnimatedModelHandle`
- `AnimatedModelAnimationMask`
- `AnimatedModelAnimationLayer`
- `AnimatedModelAnimationLayerInput`
- `MorphableModelProps`
- `MorphableModelHandle`
- `BoneAttachmentProps`
- `MaterialTextures`

## Peer Dependencies

- `react`
- `react-dom`
- `three`
- `@react-three/fiber`
- `@react-three/drei`

## Important Public Patterns

- `Scene3D` supports `lights`, `environment`, and `renderer` together.
- `Scene3D` preserves camera state while the same scene stays mounted.
- `AnimatedModel` supports controlled animation, layered animation, morph targets, and `BoneAttachment` children.
- `AnimatedModel` auto-plays the first available animation when `defaultAnimation` is omitted.
- `AnimatedModelHandle.playAnimation()` uses matching logic that can resolve partial animation names.
- `MorphableModel` exposes morph target discovery and imperative morph updates through its handle.
- `BoneAttachment` expects a real bone name from the animated parent model.

## Model Requirements

- Source assets must be GLB or GLTF.
- Embedded animations must be present in the model file for `AnimatedModel` behavior.
- Morph targets must exist in the source asset for `MorphableModel` features.
- Bone names must exist in the model for `BoneAttachment` to work.

## Common Bone Name Families

- Blender Rigify: `DEF-handR`, `DEF-handL`, `DEF-spine`
- Mixamo: `RightHand`, `LeftHand`, `Spine`
- Custom rigs: `hand_r`, `hand_l`, `spine_upper`

Reference docs should stay factual. Policy and maintenance rules belong in `.ai/agent-rules/`.
