# mbt-3d

React components for 3D character viewing with animations and morph targets.

## Installation

```bash
pnpm add mbt-3d
```

## Agent Guidance

- `AGENTS.md` is the package entrypoint for coding agents.
- Canonical rules live in `.ai/agent-rules/`.
- Factual reference lives in `.ai/agent-reference/`.
- Package-safe examples live in `.ai/agent-examples/`.

### Peer Dependencies

```bash
pnpm add react react-dom three @react-three/fiber @react-three/drei
```

## Requirements

- React >= 18.0.0
- Three.js >= 0.150.0
- @react-three/fiber >= 8.0.0
- @react-three/drei >= 9.0.0

## Local Development

For local development and testing with another project:

**1. Link the library:**

```bash
# In mbt-3d directory
pnpm link --global

# Start watch mode for auto-rebuild on changes
pnpm build:lib:watch
```

**2. Use in your project:**

```bash
# In your project directory
pnpm link --global mbt-3d
```

**3. When done, unlink:**

```bash
# In your project directory
pnpm unlink --global mbt-3d

# In mbt-3d directory
pnpm unlink --global
```

**Alternative: Use file: protocol**

```json
{
  "dependencies": {
    "mbt-3d": "file:../path/to/mbt-3d"
  }
}
```

This repo standardizes on `pnpm` only.

## Lighting and HDRI

`Scene3D` supports mixed lighting:

- `lights` and `environment` (HDRI) can be used together.
- `environment.intensity` controls scene environment intensity.
- `environment.blur` controls HDRI background blur when HDRI background is enabled.
- `renderer` accepts multiple parameters at once (`physicallyCorrectLights`, `outputColorSpace`, `toneMapping`, `toneMappingExposure`).
- Shadow-casting lights use `shadowMapSize: 2048` by default (override per light if needed).

```tsx
<Scene3D
  lights={[
    { type: 'ambient', intensity: 0.4 },
    {
      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,
  }}
>
  {children}
</Scene3D>
```

### Demo workflow

In `TextureUploadDemo`, designers can configure model/textures + HDRI + dynamic lights + renderer settings, then use `Copy Scene Settings` to export JSON preset for integration into the main app scene props.

## License

MIT
