threejs-development

Three.js 3D Game Development Patterns

Project Structure

The Three.js game project uses Vite + TypeScript with this layout:

src/
  config.ts           - Game constants (VIEWPORT, CONTROLS, plus everything from GDD)
  main.ts             - DOM entry point, gets canvas element, calls startGame()
  scenes/
    BootScene.ts      - Creates WebGLRenderer, initializes MainScene, starts loop
    MainScene.ts      - Scene, Camera, Lights, animate loop, reset key - all gameplay here

Config-Driven Design

• All game constants (dimensions, speeds, colors, physics values) go in src/config.ts
• Scenes import from config - never hardcode values in scene files
• Colors are hex numbers (e.g. 0x4fc3f7) for Three.js materials

Scene Architecture

• MainScene is a class with a Three.js Scene, PerspectiveCamera, and WebGLRenderer
• The animate loop uses requestAnimationFrame with delta time
• Input is tracked via a keysPressed Set - use isKeyDown(code) to check
• Camera and lighting are pre-configured in the template - modify as needed

// Typical MainScene structure
class MainScene {
  scene: THREE.Scene;
  camera: THREE.PerspectiveCamera;
  renderer: THREE.WebGLRenderer;
  keysPressed: Set<string>;

  animate(time: number) {
    const delta = (time - this.lastTime) / 1000;
    this.lastTime = time;
    this.update(delta);
    this.renderer.render(this.scene, this.camera);
    requestAnimationFrame((t) => this.animate(t));
  }
}

Creating Game Objects (Geometric Primitives)

• Use THREE.BoxGeometry, THREE.SphereGeometry, THREE.CylinderGeometry for entities
• Wrap in THREE.Mesh with THREE.MeshStandardMaterial for lit appearance
• Add to scene: this.scene.add(mesh)

// Create a colored box
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshStandardMaterial({ color: 0x4fc3f7 });
const cube = new THREE.Mesh(geometry, material);
cube.position.set(0, 0.5, 0);
this.scene.add(cube);

// Create a sphere
const sphereGeo = new THREE.SphereGeometry(0.5, 16, 16);
const sphereMat = new THREE.MeshStandardMaterial({ color: 0xff5722 });
const sphere = new THREE.Mesh(sphereGeo, sphereMat);
this.scene.add(sphere);