3d-scene-composition

name	3d-scene-composition
description	Guide for composing complex 3D scenes from reusable components in a React environment.

Skill: 3D Scene Composition

Category: Frontend Engineering Priority: High

---

Description

This skill enables agents to build complex, interactive 3D scenes by composing reusable components from react-three-drei, react-three-fiber, and other compatible libraries. It covers scene hierarchy, asset management, lighting, camera setup, interaction, and performance.

Purpose

To produce maintainable, performant, and visually coherent 3D scenes without rebuilding common primitives from scratch. This skill is the bridge between individual 3D components and a complete, interactive 3D application.

Trigger

Use this skill when:

• A user requests a 3D scene with multiple interacting objects.
• You need to combine 3D models, lighting, cameras, and controls into a unified React component.
• You are building a simulation, dashboard, or visualizer that requires 3D presentation.
• You need to make 3D objects interactive (clickable, hoverable, selectable).

Context

• Project uses React and @react-three/fiber.
• @react-three/drei is available for helpers and abstractions.
• 3D assets are available or can be procedurally generated.
• Target device performance and SSR constraints are known.
• The scene is part of a larger skill such as urban-grid-3d-sim.

Workflow

1. Define the scene purpose. Clarify what the scene must communicate and which interactions are required.
2. Set up the Canvas. Use <Canvas> from @react-three/fiber with an appropriate dpr and camera.
3. Configure lighting. Add ambient, directional, and point lights as needed. Use <Environment> from drei for realistic reflections when appropriate.
4. Choose a camera and controls. Use PerspectiveCamera or OrthographicCamera with OrbitControls or CameraControls from drei.
5. Build the scene graph. Compose meshes, groups, and helper components in a logical hierarchy.
6. Integrate assets. Load models, textures, and materials with useGLTF, useTexture, and useLoader.
7. Add interaction. Implement click, hover, and selection handlers using ThreeEvent handlers and raycasting.
8. Optimize performance. Use instancedMesh, cap pixel ratio, preload assets, and memoize expensive objects.
9. Implement cleanup. Dispose of geometries, materials, textures, and controls on unmount.
10. Verify. Run the verification checklist and update documentation.

Examples

Good: Composed scene with interactive elements

import { Canvas } from '@react-three/fiber'
import { OrbitControls, PerspectiveCamera, Grid, Box } from '@react-three/drei'

function Scene() {
  return (
    <Canvas>
      <PerspectiveCamera makeDefault position={[10, 10, 10]} />
      <OrbitControls />
      <ambientLight intensity={0.5} />
      <directionalLight position={[10, 10, 5]} />
      <Grid args={[50, 50]} />
      <Box position={[0, 0.5, 0]} onClick={(e) => console.log('clicked')}>
        <meshStandardMaterial color="orange" />
      </Box>
    </Canvas>
  )
}

Bad: Monolithic scene with no reusable parts

// Avoid dumping all objects in a single component without separation.
function BadScene() {
  return (
    <Canvas>
      { /* 50+ inline meshes, lights, and controls all together */ }
    </Canvas>
  )
}

Anti-patterns

• Creating a single monolithic component that owns everything.
• Loading the same asset multiple times instead of reusing or preloading it.
• Adding lights without considering performance or visual hierarchy.
• Ignoring SSR constraints by running 3D code on the server.
• Using inline Three.js object creation inside render loops.
• Neglecting cleanup for geometries, materials, and controls.

Verification

• The scene has a clear purpose and communicates it visually.
• Lighting, camera, and controls are appropriate for the scene.
• Components are reusable and logically grouped.
• Assets are preloaded or shared where possible.
• Interactions are implemented and tested.
• Performance is verified on target devices.
• SSR and client-only constraints are respected.
• Cleanup is implemented on unmount.
• Cross-skill references are used (React Three Fiber, React Three Drei, Performance).

Cross Skill References

• React Three Fiber: Core renderer and Canvas setup.
• React Three Drei: Ready-made helpers, controls, and abstractions.
• Performance Optimization: Profiling, draw calls, and instancing.
• Frontend Engineering: React patterns, component structure, and SSR.
• Urban Grid 3D Simulation: Advanced scene composition for urban infrastructure.

References

• React Three Fiber docs: https://docs.pmnd.rs/react-three-fiber/getting-started/introduction
• React Three Drei docs: https://github.com/pmndrs/drei
• Three.js docs: https://threejs.org/docs/