mbt-3d

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

Installation

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

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:

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

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

2. Use in your project:

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

3. When done, unlink:

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

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

Alternative: Use file: protocol

{
  "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).

<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