# Agent Examples

Use these examples when a consumer app needs package-level usage patterns for `mbt-3d`.

## Basic Scene

```tsx
import { Model, Scene3D } from 'mbt-3d';

function WeaponPreview({ modelUrl }: { modelUrl: string }) {
  return (
    <Scene3D
      camera={{ position: [0, 1.5, 4], fov: 45 }}
      style={{ width: 420, height: 420 }}
    >
      <Model url={modelUrl} />
    </Scene3D>
  );
}
```

## Scene With HDRI And Custom Lights

```tsx
<Scene3D
  camera={{ position: [0, 2, 5], fov: 45 }}
  lights={[
    { type: 'ambient', intensity: 0.35 },
    {
      type: 'spot',
      position: [5, 8, 5],
      intensity: 120,
      castShadow: true,
      shadowMapSize: 2048,
    },
  ]}
  environment={{
    files: '/hdri/studio.hdr',
    intensity: 1.2,
    blur: 0.15,
    background: false,
  }}
  renderer={{
    physicallyCorrectLights: true,
    outputColorSpace: 'srgb',
    toneMapping: 'ACESFilmicToneMapping',
    toneMappingExposure: 1,
  }}
  style={{ width: 600, height: 800 }}
>
  {children}
</Scene3D>
```

## Animated Character

```tsx
import { AnimatedModel, Scene3D } from 'mbt-3d';

function CharacterPreview({ modelUrl }: { modelUrl: string }) {
  return (
    <Scene3D
      camera={{ position: [0, 1.5, 4], fov: 45 }}
      style={{ width: 500, height: 700 }}
    >
      <AnimatedModel
        url={modelUrl}
        defaultAnimation="Idle"
        position={[0, -1, 0]}
      />
    </Scene3D>
  );
}
```

## Bone Attachment

```tsx
import { AnimatedModel, BoneAttachment, Model } from 'mbt-3d';

<AnimatedModel url={characterUrl} defaultAnimation="Idle">
  <BoneAttachment bone="hand_r">
    <Model url={weaponUrl} scale={0.7} />
  </BoneAttachment>
</AnimatedModel>;
```

## Morph Targets

```tsx
import { MorphableModel } from 'mbt-3d';

<MorphableModel
  url={characterUrl}
  morphTargets={{
    muscular: 0.5,
    thin: 0.2,
  }}
/>;
```

## Imperative Animation Control

```tsx
import { AnimatedModel } from 'mbt-3d';
import { useRef } from 'react';
import type { AnimatedModelHandle } from 'mbt-3d';

const characterRef = useRef<AnimatedModelHandle>(null);

<AnimatedModel ref={characterRef} url={characterUrl} defaultAnimation="Idle" />;

characterRef.current?.playAnimation('Attack', { loop: false });
```

## Advanced Hook

```tsx
import { preloadModel } from 'mbt-3d';

void preloadModel(modelUrl);
```

## Texture Preload

```tsx
import { preloadTextures } from 'mbt-3d';

preloadTextures({
  Metal: {
    map: resolvedMetalMap,
    normalMap: resolvedMetalNormalMap,
  },
});
```

## Multiple Character Slots

```tsx
<Scene3D
  camera={{ position: [0, 2, 8] }}
  background="#1a1a2e"
  style={{ width: '100%', height: '100vh' }}
>
  <AnimatedModel
    url={heroAUrl}
    defaultAnimation="Idle"
    position={[-2, -1, 0]}
  />

  <AnimatedModel url={heroBUrl} defaultAnimation="Idle" position={[0, -1, 0]}>
    <BoneAttachment bone="hand_r">
      <Model url={swordUrl} />
    </BoneAttachment>
  </AnimatedModel>

  <AnimatedModel url={heroCUrl} defaultAnimation="Idle" position={[2, -1, 0]} />
</Scene3D>
```

## Important Notes

- These examples assume the consumer has already resolved or prepared the asset URL.
- Consumer-specific CDN resolution, local asset servers, and preload orchestration belong in the consumer app docs, not in `mbt-3d`.
- Prefer package-level examples here over demo-only repo paths like `/models/...` when writing guidance for consumers.
- Supported source assets are GLB/GLTF, with embedded animations or morph targets when the consumer needs those features.
