3D Navigator Guide

Your agent for 3D development and rendering — covering 3D frameworks (Three.js, Babylon.js), WebGL, 3D model formats, scene composition, and optimization for web-based 3D experiences.

When to Use This Agent

Choose 3D Navigator Guide when:

• Building 3D web applications with Three.js, Babylon.js, or React Three Fiber
• Working with 3D model formats (glTF, GLTF, OBJ, FBX)
• Implementing 3D scene rendering, lighting, materials, and cameras
• Optimizing 3D performance for web browsers (LOD, instancing, culling)
• Building product configurators, virtual showrooms, or data visualizations in 3D

Consider alternatives when:

• You need game development (Unity, Unreal) — use a game engine agent
• You need CAD/engineering 3D — use a specialized CAD agent
• You need 2D web graphics — use a frontend developer agent

Quick Start

Copy
# .claude/agents/3d-navigator.yml
name: 3D Navigator Guide
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: 3D web development agent for Three.js, Babylon.js, WebGL, and interactive 3D experiences

Example invocation:

claude "Create a React Three Fiber scene with a 3D product viewer — load a GLTF model, add orbit controls, environment lighting, and a ground plane with shadows"

Core Concepts

Web 3D Stack

Layer	Technology	Purpose
Framework	Three.js, Babylon.js, A-Frame	3D scene management
React Integration	React Three Fiber, react-babylonjs	Declarative 3D in React
Physics	Cannon.js, Rapier, Ammo.js	Rigid body simulation
Post-Processing	EffectComposer, SSAO, Bloom	Visual effects
Loading	GLTFLoader, DRACOLoader	Model import and compression
Optimization	LOD, instancing, frustum culling	Performance

Three.js Scene Structure

Copy
// Basic Three.js scene
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, aspect, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true });

// Lighting
scene.add(new THREE.AmbientLight(0x404040, 0.5));
const dirLight = new THREE.DirectionalLight(0xffffff, 1);
dirLight.position.set(5, 10, 7.5);
dirLight.castShadow = true;
scene.add(dirLight);

// Load GLTF model
const loader = new THREE.GLTFLoader();
loader.load('model.glb', (gltf) => {
  scene.add(gltf.scene);
});

// Render loop
function animate() {
  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}
animate();

Configuration

Parameter	Description	Default
framework	3D framework (threejs, babylonjs, r3f)	r3f
model_format	3D model format (gltf, glb, obj, fbx)	glb
renderer	Rendering backend (webgl2, webgpu)	webgl2
shadows	Shadow quality (none, basic, soft)	soft
antialiasing	Antialiasing method (msaa, fxaa, smaa)	msaa

Best Practices

1. Use glTF/GLB as your primary 3D format. glTF is the "JPEG of 3D" — widely supported, efficient, and includes materials, animations, and textures in a single file. GLB is the binary version with smaller file sizes. Avoid OBJ and FBX for web delivery.

2. Implement progressive loading for large scenes. Load low-poly placeholder models first, then swap in high-detail versions asynchronously. Show loading progress to the user and ensure the scene is interactive before all assets finish loading.

3. Use instanced meshes for repeated geometry. Instead of creating 1,000 separate tree meshes, use InstancedMesh with per-instance transforms. This reduces draw calls from 1,000 to 1, dramatically improving frame rate.

4. Compress models with Draco or meshopt. Draco compression reduces GLTF file sizes by 80-90%. Use the DRACOLoader with Three.js to decompress at runtime. For animated models, meshopt provides better compression than Draco.

5. Optimize textures aggressively. Textures are typically the largest part of a 3D scene. Use power-of-two dimensions, compressed formats (KTX2 with basis universal), and appropriate resolution — a small background object doesn't need a 4K texture.

Common Issues

3D scene runs at low frame rate on mobile devices. Mobile GPUs are much weaker than desktop GPUs. Reduce polygon count, lower shadow resolution, decrease texture sizes, and reduce the number of lights. Target 30fps minimum on mid-range mobile devices.

GLTF model appears black or with wrong materials. Materials depend on proper lighting and environment maps. Add an environment map (scene.environment = hdrTexture) for PBR materials to reflect. Without it, metallic and glossy materials appear black.

Memory leaks cause the page to crash after navigating between 3D views. Three.js objects (geometries, materials, textures) must be manually disposed. Call .dispose() on all resources when removing objects from the scene. React Three Fiber handles this automatically when using JSX elements.