Skip to main content

Basics

Essential concepts and setup for Three.js development.

Installation​

# NPM
npm install three

# CDN
<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r158/three.min.js"></script>

Core Components​

Scene​

Container for all 3D objects, lights, and cameras.

const scene = new THREE.Scene();
scene.background = new THREE.Color(0x404040);
scene.fog = new THREE.Fog(0x404040, 1, 100);

Camera​

Defines the viewpoint and projection type.

// Perspective Camera (most common)
const camera = new THREE.PerspectiveCamera(
  75, // Field of view
  window.innerWidth / window.innerHeight, // Aspect ratio
  0.1, // Near clipping plane
  1000 // Far clipping plane
);

// Orthographic Camera
const camera = new THREE.OrthographicCamera(
  -10,
  10, // Left, right
  10,
  -10, // Top, bottom
  0.1,
  100 // Near, far
);

// Position camera
camera.position.set(0, 5, 10);
camera.lookAt(0, 0, 0);

Renderer​

Renders the scene to the screen.

const renderer = new THREE.WebGLRenderer({
  antialias: true,
  alpha: true,
});
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(window.devicePixelRatio);
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;

document.body.appendChild(renderer.domElement);

Basic Scene Setup​

// Create scene, camera, renderer
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(
  75,
  window.innerWidth / window.innerHeight,
  0.1,
  1000
);
const renderer = new THREE.WebGLRenderer();

renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// Add objects to scene
const geometry = new THREE.BoxGeometry();
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

// Position camera
camera.position.z = 5;

// Render
renderer.render(scene, camera);

Animation Loop​

function animate() {
  requestAnimationFrame(animate);

  // Update objects
  cube.rotation.x += 0.01;
  cube.rotation.y += 0.01;

  // Render scene
  renderer.render(scene, camera);
}
animate();

Responsive Design​

function onWindowResize() {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
}

window.addEventListener('resize', onWindowResize);

Object Management​

// Add objects
scene.add(mesh);

// Remove objects
scene.remove(mesh);

// Find objects
const object = scene.getObjectByName('myObject');
const objects = scene.getObjectsByProperty('type', 'Mesh');

// Traverse scene
scene.traverse(child => {
  if (child.isMesh) {
    console.log(child.name);
  }
});

Coordinate System​

  • Right-handed coordinate system
  • X-axis: Right (positive) / Left (negative)
  • Y-axis: Up (positive) / Down (negative)
  • Z-axis: Forward (positive) / Backward (negative)

Common Patterns​

Simple Scene Template​

class BasicScene {
  constructor() {
    this.scene = new THREE.Scene();
    this.camera = new THREE.PerspectiveCamera(
      75,
      window.innerWidth / window.innerHeight,
      0.1,
      1000
    );
    this.renderer = new THREE.WebGLRenderer();

    this.init();
    this.animate();
  }

  init() {
    this.renderer.setSize(window.innerWidth, window.innerHeight);
    document.body.appendChild(this.renderer.domElement);

    // Add your objects here
    this.createObjects();

    // Setup event listeners
    window.addEventListener('resize', () => this.onWindowResize());
  }

  createObjects() {
    // Override in subclasses
  }

  animate() {
    requestAnimationFrame(() => this.animate());
    this.update();
    this.render();
  }

  update() {
    // Update objects here
  }

  render() {
    this.renderer.render(this.scene, this.camera);
  }

  onWindowResize() {
    this.camera.aspect = window.innerWidth / window.innerHeight;
    this.camera.updateProjectionMatrix();
    this.renderer.setSize(window.innerWidth, window.innerHeight);
  }
}

Debugging​

// Stats.js for performance monitoring
const stats = new Stats();
document.body.appendChild(stats.dom);

function animate() {
  stats.begin();

  // Your animation code

  stats.end();
  requestAnimationFrame(animate);
}

// dat.GUI for controls
const gui = new dat.GUI();
gui.add(cube.rotation, 'x', 0, Math.PI * 2);
gui.add(cube.rotation, 'y', 0, Math.PI * 2);