ThreeJS Game Development Guidelines

Project Architecture

Use modular architecture with clear separation of concerns
Implement core engine components:
- ```
Application
```
  - Main entry point and game loop
- ```
InputManager
```
  - Handle keyboard and mouse input
- ```
AssetManager
```
  - Load and manage 3D models, textures, audio
- ```
GameWorld
```
  - Manage scene, lighting, and physical world
- ```
UIManager
```
  - Handle UI interactions and HUD
- ```
Player
```
  - Player character controller and camera
- ```
EntityManager
```
  - Manage game entities (enemies, pickups)
- ```
PhysicsSystem
```
  - Handle collisions and physics

Input System

Keyboard Input

Track key states in real-time (not just events)
Use standardized key codes (KeyW, KeyA, KeyS, KeyD)
Handle both keydown and keyup events
Implement key mapping configuration
Example:

// Store key states in an object
this.keyState = {};

// Update key states on events
document.addEventListener('keydown', (e) => {
  this.keyState[e.code] = true;
});

document.addEventListener('keyup', (e) => {
  this.keyState[e.code] = false;
});

// Access key state in game loop
if (this.keyState['KeyW']) {
  // Move forward
}

Mouse Input for FPS Camera

Use Pointer Lock API for FPS mouse control
Track mouse movement deltas, not absolute position
Apply sensitivity scaling to mouse input
Reset mouse movement after applying to camera
Example:

// Request pointer lock on container click
container.addEventListener('click', () => {
  container.requestPointerLock();
});

// Track pointer lock state
document.addEventListener('pointerlockchange', () => {
  this.pointerLocked = document.pointerLockElement === container;
});

// Track mouse movement when pointer is locked
document.addEventListener('mousemove', (e) => {
  if (this.pointerLocked) {
    this.mouseMovement.x = e.movementX || 0;
    this.mouseMovement.y = e.movementY || 0;
  }
});

Camera Controls

Set proper camera rotation order for FPS controls:

camera.rotation.order = 'YXZ'; // Critical for FPS camera

Implement yaw (left/right) rotation around Y-axis
Implement pitch (up/down) rotation around X-axis
Clamp vertical rotation to prevent camera flipping
Example:

// Apply mouse movement to camera rotation
const sensitivity = 0.002;

// Horizontal rotation (yaw)
this.rotation.y -= mouseMovement.x * sensitivity;

// Vertical rotation (pitch) with clamping
this.rotation.x -= mouseMovement.y * sensitivity;
this.rotation.x = Math.max(-Math.PI/2 + 0.01, Math.min(Math.PI/2 - 0.01, this.rotation.x));

// Apply rotation to camera
camera.rotation.copy(this.rotation);

Character Movement

Calculate movement direction based on input
Normalize movement vector to prevent faster diagonal movement
Transform movement vector to camera orientation
Apply movement with time-based speed
Example:

// Get input direction
const moveX = (keyState['KeyD'] ? 1 : 0) - (keyState['KeyA'] ? 1 : 0);
const moveZ = (keyState['KeyS'] ? 1 : 0) - (keyState['KeyW'] ? 1 : 0);

// Create and normalize movement vector
const moveDir = new THREE.Vector3(moveX, 0, moveZ);
if (moveDir.length() > 1) moveDir.normalize();

// Get forward and right vectors from camera
const forward = new THREE.Vector3(0, 0, 1).applyEuler(new THREE.Euler(0, rotation.y, 0));
const right = new THREE.Vector3(1, 0, 0).applyEuler(new THREE.Euler(0, rotation.y, 0));

// Calculate world movement direction
const worldDir = new THREE.Vector3();
worldDir.addScaledVector(forward, -moveDir.z);
worldDir.addScaledVector(right, moveDir.x);
worldDir.normalize();

// Apply movement
position.addScaledVector(worldDir, moveSpeed * deltaTime);

Game Loop

Use requestAnimationFrame for the game loop
Calculate delta time between frames
Clamp delta time to prevent "time jumps"
Update all game systems with delta time
Example:

const now = performance.now();
const deltaTime = Math.min((now - lastTime) / 1000, 0.1); // Seconds, clamped to 100ms
lastTime = now;

// Update game systems
inputManager.update();
player.update(deltaTime);
enemyManager.update(deltaTime);
physics.update(deltaTime);
renderer.render(scene, camera);

Asset Management

Implement async loading with promises
Show loading progress to the user
Use a central registry for assets
Preload critical assets before game start
Example:

async loadAssets(onProgress) {
  const total = this.assetList.length;
  let loaded = 0;
  
  // Create load promises for all assets
  const promises = this.assetList.map(asset => {
    return this.loadAsset(asset).then(() => {
      loaded++;
      onProgress(loaded / total);
    });
  });
  
  // Wait for all assets to load
  await Promise.all(promises);
}

Performance Optimization

Use object pooling for frequently created/destroyed objects
Implement level of detail (LOD) for complex models
Use frustum culling for off-screen objects
Batch similar meshes where possible
Use instancing for repeated geometry
Optimize lighting with baked shadows
Minimize draw calls by combining materials
Use sprite sheets for particles and effects

Debugging Tools

Implement FPS counter and performance monitors
Add debug mode with visual helpers
Use THREE.js inspector in development
Implement console commands for testing
Add visual debugging for physics and collisions
Example:

// FPS counter
let frames = 0;
let lastFpsTime = 0;

function updateFps(now) {
  frames++;
  if (now >= lastFpsTime + 1000) {
    const fps = frames * 1000 / (now - lastFpsTime);
    debugText.textContent = `FPS: ${Math.round(fps)}`;
    frames = 0;
    lastFpsTime = now;
  }
}

Best Practices

Pre-compute and cache values where possible
Use Object3D hierarchy for logical grouping
Implement proper disposal of resources (geometries, materials, textures)
Use raycasting for interaction and collision detection
Separate game logic from rendering
Implement proper event handling with custom events
Use quaternions for smooth rotations
Avoid unnecessary matrix computations

Common Pitfalls to Avoid

Not normalizing movement vectors (causing faster diagonal movement)
Incorrect camera rotation order (use YXZ for FPS camera)
Not applying delta time to movement (causing inconsistent speeds)
Memory leaks from not disposing unused resources
Excessive draw calls from too many materials
Not handling window resize for responsive canvas
Missing pointer lock implementation for FPS controls

ThreeJS Game Development Guidelines

Project Architecture

Use modular architecture with clear separation of concerns
Implement core engine components:
- ```
Application
```
  - Main entry point and game loop
- ```
InputManager
```
  - Handle keyboard and mouse input
- ```
AssetManager
```
  - Load and manage 3D models, textures, audio
- ```
GameWorld
```
  - Manage scene, lighting, and physical world
- ```
UIManager
```
  - Handle UI interactions and HUD
- ```
Player
```
  - Player character controller and camera
- ```
EntityManager
```
  - Manage game entities (enemies, pickups)
- ```
PhysicsSystem
```
  - Handle collisions and physics

Input System

Keyboard Input

Track key states in real-time (not just events)
Use standardized key codes (KeyW, KeyA, KeyS, KeyD)
Handle both keydown and keyup events
Implement key mapping configuration
Example:

// Store key states in an object
this.keyState = {};

// Update key states on events
document.addEventListener('keydown', (e) => {
  this.keyState[e.code] = true;
});

document.addEventListener('keyup', (e) => {
  this.keyState[e.code] = false;
});

// Access key state in game loop
if (this.keyState['KeyW']) {
  // Move forward
}

Mouse Input for FPS Camera

Use Pointer Lock API for FPS mouse control
Track mouse movement deltas, not absolute position
Apply sensitivity scaling to mouse input
Reset mouse movement after applying to camera
Example:

// Request pointer lock on container click
container.addEventListener('click', () => {
  container.requestPointerLock();
});

// Track pointer lock state
document.addEventListener('pointerlockchange', () => {
  this.pointerLocked = document.pointerLockElement === container;
});

// Track mouse movement when pointer is locked
document.addEventListener('mousemove', (e) => {
  if (this.pointerLocked) {
    this.mouseMovement.x = e.movementX || 0;
    this.mouseMovement.y = e.movementY || 0;
  }
});

Camera Controls

Set proper camera rotation order for FPS controls:

camera.rotation.order = 'YXZ'; // Critical for FPS camera

Implement yaw (left/right) rotation around Y-axis
Implement pitch (up/down) rotation around X-axis
Clamp vertical rotation to prevent camera flipping
Example:

// Apply mouse movement to camera rotation
const sensitivity = 0.002;

// Horizontal rotation (yaw)
this.rotation.y -= mouseMovement.x * sensitivity;

// Vertical rotation (pitch) with clamping
this.rotation.x -= mouseMovement.y * sensitivity;
this.rotation.x = Math.max(-Math.PI/2 + 0.01, Math.min(Math.PI/2 - 0.01, this.rotation.x));

// Apply rotation to camera
camera.rotation.copy(this.rotation);

Character Movement

Calculate movement direction based on input
Normalize movement vector to prevent faster diagonal movement
Transform movement vector to camera orientation
Apply movement with time-based speed
Example:

// Get input direction
const moveX = (keyState['KeyD'] ? 1 : 0) - (keyState['KeyA'] ? 1 : 0);
const moveZ = (keyState['KeyS'] ? 1 : 0) - (keyState['KeyW'] ? 1 : 0);

// Create and normalize movement vector
const moveDir = new THREE.Vector3(moveX, 0, moveZ);
if (moveDir.length() > 1) moveDir.normalize();

// Get forward and right vectors from camera
const forward = new THREE.Vector3(0, 0, 1).applyEuler(new THREE.Euler(0, rotation.y, 0));
const right = new THREE.Vector3(1, 0, 0).applyEuler(new THREE.Euler(0, rotation.y, 0));

// Calculate world movement direction
const worldDir = new THREE.Vector3();
worldDir.addScaledVector(forward, -moveDir.z);
worldDir.addScaledVector(right, moveDir.x);
worldDir.normalize();

// Apply movement
position.addScaledVector(worldDir, moveSpeed * deltaTime);

Game Loop

Use requestAnimationFrame for the game loop
Calculate delta time between frames
Clamp delta time to prevent "time jumps"
Update all game systems with delta time
Example:

const now = performance.now();
const deltaTime = Math.min((now - lastTime) / 1000, 0.1); // Seconds, clamped to 100ms
lastTime = now;

// Update game systems
inputManager.update();
player.update(deltaTime);
enemyManager.update(deltaTime);
physics.update(deltaTime);
renderer.render(scene, camera);

Asset Management

Implement async loading with promises
Show loading progress to the user
Use a central registry for assets
Preload critical assets before game start
Example:

async loadAssets(onProgress) {
  const total = this.assetList.length;
  let loaded = 0;
  
  // Create load promises for all assets
  const promises = this.assetList.map(asset => {
    return this.loadAsset(asset).then(() => {
      loaded++;
      onProgress(loaded / total);
    });
  });
  
  // Wait for all assets to load
  await Promise.all(promises);
}

Performance Optimization

Use object pooling for frequently created/destroyed objects
Implement level of detail (LOD) for complex models
Use frustum culling for off-screen objects
Batch similar meshes where possible
Use instancing for repeated geometry
Optimize lighting with baked shadows
Minimize draw calls by combining materials
Use sprite sheets for particles and effects

Debugging Tools

Implement FPS counter and performance monitors
Add debug mode with visual helpers
Use THREE.js inspector in development
Implement console commands for testing
Add visual debugging for physics and collisions
Example:

// FPS counter
let frames = 0;
let lastFpsTime = 0;

function updateFps(now) {
  frames++;
  if (now >= lastFpsTime + 1000) {
    const fps = frames * 1000 / (now - lastFpsTime);
    debugText.textContent = `FPS: ${Math.round(fps)}`;
    frames = 0;
    lastFpsTime = now;
  }
}

Best Practices

Pre-compute and cache values where possible
Use Object3D hierarchy for logical grouping
Implement proper disposal of resources (geometries, materials, textures)
Use raycasting for interaction and collision detection
Separate game logic from rendering
Implement proper event handling with custom events
Use quaternions for smooth rotations
Avoid unnecessary matrix computations

Common Pitfalls to Avoid

Not normalizing movement vectors (causing faster diagonal movement)
Incorrect camera rotation order (use YXZ for FPS camera)
Not applying delta time to movement (causing inconsistent speeds)
Memory leaks from not disposing unused resources
Excessive draw calls from too many materials
Not handling window resize for responsive canvas
Missing pointer lock implementation for FPS controls

ThreeJS Game Development Guidelines

ThreeJS Game Development Guidelines

Project Architecture

Input System

Keyboard Input

Mouse Input for FPS Camera

Camera Controls

Character Movement

Game Loop

Asset Management

Performance Optimization

Debugging Tools

Best Practices

Common Pitfalls to Avoid

Related Skills

Markdown Converter

Nano Banana Pro

1password

ThreeJS Game Development Guidelines

Project Architecture

Input System

Keyboard Input

Mouse Input for FPS Camera

Camera Controls

Character Movement

Game Loop

Asset Management

Performance Optimization

Debugging Tools

Best Practices

Common Pitfalls to Avoid