# ThreeJS SDK Implementation Guide ## Introduction Three.js is a powerful, open-source JavaScript library that simplifies the process of creating and displaying 3D graphics and animations on the web, leveraging WebGL for GPU-accelerated rendering. Keep the files in the src/app directory structure for Next.js compatibility. ## Critical Implementation Notes - **CRITICAL**: All ThreeJS code MUST be run on the client side using 'use client' directive in Next.js components - **CRITICAL**: You are to implement game logic in a separate directory from rendering code - **CRITICAL**: You are to use ES modules and proper class organization for all game components - **CRITICAL**: You are to implement proper cleanup in component unmounting to prevent memory leaks - **CRITICAL**: You are to create procedural geometry rather than loading external assets - **CRITICAL**: You are to implement responsive design practices for all game components - **CRITICAL**: You are to use proper TypeScript types throughout the implementation - **CRITICAL**: You are to implement adaptive mobile controls with fixed virtual joysticks and buttons that automatically activate on devices with screen width below 768px - **CRITICAL**: You are to include Stats.js for real-time performance monitoring (FPS, frame time, draw calls) in a subtle, unobtrusive corner display - **CRITICAL**: You are to provide a contextual control box displaying key bindings that is responsive to screen size, initially visible but elegantly fading after user familiarization - **CRITICAL**: You are to implement performance optimizations including object pooling, frustum culling, and texture atlases to maintain high FPS - **CRITICAL**: You are to use low-poly models and simplified textures with mipmapping to ensure cross-device compatibility - **CRITICAL**: You are to implement a third-person camera perspective with configurable follow distance and smoothing - **CRITICAL**: You are to render contextually appropriate sprites/models that match the requested game type (planes for flight sims, spaceships for space games, etc.) - **CRITICAL**: You are to create map boundaries with visual indicators to prevent players from leaving the playable area - **CRITICAL**: You are to implement a reset/restart button that returns the player to the starting position - **CRITICAL**: You are to include pause functionality with a simple UI overlay - **CRITICAL**: You are to provide save/load functionality where appropriate using localStorage - **CRITICAL**: You are to implement Level of Detail (LOD) or Tile-based generation for large maps - **CRITICAL**: You are to simplify physics and controls to prioritize fun over realism unless specifically requested ## Project Structure and Environment Examples The following sections show both the recommended project structure for ThreeJS games and example implementations for common environments. Choose the structure that best fits your needs: ### 1. Full Game Project Structure For complex games with multiple features, use this structure: ``` src/ app/ page.tsx # Entry point integrating the game layout.tsx # Root layout game/ # Game-specific components page.tsx # Game page components/ ui/ # UI Components (menus, HUD) threejs/ core/ # Core ThreeJS setup renderer.ts # WebGL renderer setup scene.ts # Scene management camera.ts # Camera management lights.ts # Lighting setup controls.ts # Camera/player controls objects/ # Game object classes geometry/ # Procedural geometry materials/ # Custom materials entities/ # Game entities physics/ # Physics implementations animations/ # Animation system effects/ # Post-processing effects utils/ # Helper functions hooks/ useThree.ts # ThreeJS integration hook useGameLoop.ts # Game loop management useControls.ts # Input handling game/ state.ts # Game state management logic.ts # Game logic levels.ts # Level definitions constants.ts # Game constants ``` ### 2. Simple Environment Examples For simpler scenes or prototypes, use these streamlined structures: #### A. Simple Voxel World (Minecraft-like) ``` src/app/ page.tsx # Main entry point voxel-world/ page.tsx # Voxel world scene components/ Voxel.tsx # Single voxel component Chunk.tsx # 16x16x16 voxel chunk WorldGenerator.tsx # Procedural world generation hooks/ useVoxelControls.ts # Player movement and block placement utils/ noise.ts # Perlin/simplex noise for terrain chunkUtils.ts # Chunk management helpers ``` > **⚠️ Voxel World Performance Warning**: > Voxel worlds are computationally intensive. Implement these optimizations: > - Use instanced meshes for voxel rendering (THREE.InstancedMesh) > - Implement chunk-based loading/unloading with a reasonable view distance > - Use object pooling for chunk meshes > - Implement frustum culling for chunks > - Use Level of Detail (LOD) for distant chunks > - Consider using a spatial data structure (octree) for efficient chunk management > - Monitor memory usage with Stats.js as chunk count can grow quickly > - Consider using Web Workers for chunk generation to prevent main thread blocking #### B. Space Environment ``` src/app/ page.tsx # Main entry point space-scene/ page.tsx # Space scene components/ Star.tsx # Star particle system Planet.tsx # Planet with atmosphere SpaceShip.tsx # Simple spaceship model hooks/ useSpaceControls.ts # Camera and movement controls utils/ orbitUtils.ts # Orbital calculations particleUtils.ts # Star field generation ``` #### C. Simple Driving Environment ``` src/app/ page.tsx # Main entry point driving-scene/ page.tsx # Driving scene components/ Road.tsx # Road with markings Terrain.tsx # Procedural terrain (grass, hills) Car.tsx # Simple car model hooks/ useDrivingControls.ts # Car and camera controls utils/ roadUtils.ts # Road generation terrainUtils.ts # Terrain generation ``` ### Basic Scene Setup All environments use this basic setup pattern: ```typescript // src/app/[environment]/page.tsx 'use client'; import { useRef, useEffect } from 'react'; import * as THREE from 'three'; import { useThree } from '@/hooks/useThree'; import { useGameLoop } from '@/hooks/useGameLoop'; export default function EnvironmentPage() { const containerRef = useRef(null); const { scene, camera, renderer } = useThree(containerRef); // Game loop for updates useGameLoop((delta) => { // Update environment state // Update physics // Update animations }); // Scene setup useEffect(() => { if (!scene.current) return; // Add environment objects // Setup lighting // Setup camera position return () => { // Cleanup }; }, [scene]); return (

); } ``` ## Game Architecture Pattern Implement a clean separation between rendering and game logic using this pattern: ```tsx // src/hooks/useThree.ts import { useEffect, useRef } from 'react'; import * as THREE from 'three'; export function useThree(containerRef) { const renderer = useRef(null); const scene = useRef(null); const camera = useRef(null); useEffect(() => { // Initialize Three.js if (!containerRef.current) return; const width = containerRef.current.clientWidth; const height = containerRef.current.clientHeight; // Create scene, camera, renderer scene.current = new THREE.Scene(); camera.current = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000); renderer.current = new THREE.WebGLRenderer({ antialias: true, alpha: true }); renderer.current.setSize(width, height); renderer.current.setPixelRatio(window.devicePixelRatio); containerRef.current.appendChild(renderer.current.domElement); // Handle resize const handleResize = () => { if (!containerRef.current || !renderer.current || !camera.current) return; const width = containerRef.current.clientWidth; const height = containerRef.current.clientHeight; camera.current.aspect = width / height; camera.current.updateProjectionMatrix(); renderer.current.setSize(width, height); }; window.addEventListener('resize', handleResize); // Animation loop const animate = () => { if (!renderer.current || !scene.current || !camera.current) return; requestAnimationFrame(animate); renderer.current.render(scene.current, camera.current); }; animate(); // Cleanup return () => { window.removeEventListener('resize', handleResize); if (containerRef.current && renderer.current) { containerRef.current.removeChild(renderer.current.domElement); } // Dispose resources scene.current?.traverse((object) => { if (object instanceof THREE.Mesh) { object.geometry.dispose(); if (object.material instanceof THREE.Material) { object.material.dispose(); } else if (Array.isArray(object.material)) { object.material.forEach(material => material.dispose()); } } }); renderer.current?.dispose(); }; }, [containerRef]); return { scene, camera, renderer }; } ``` ## Performance Best Practices 1. **Object Pooling**: Reuse objects instead of creating/destroying them 2. **Instanced Rendering**: Use `THREE.InstancedMesh` for repeated objects 3. **Level of Detail**: Implement LOD for complex scenes 4. **Object Culling**: Only render what's visible 5. **Texture Atlases**: Combine textures into atlases 6. **Defer Rendering**: Use requestAnimationFrame properly 7. **Batch Similar Materials**: Reduce draw calls ```typescript // Example of object pooling class ObjectPool { private pool: T[] = []; private createFn: () => T; private resetFn: (obj: T) => void; constructor(createFn: () => T, resetFn: (obj: T) => void, initialSize = 0) { this.createFn = createFn; this.resetFn = resetFn; // Pre-populate pool for (let i = 0; i < initialSize; i++) { this.pool.push(this.createFn()); } } get(): T { if (this.pool.length > 0) { return this.pool.pop()!; } return this.createFn(); } release(obj: T): void { this.resetFn(obj); this.pool.push(obj); } } ``` ## Procedural Geometry Generation Implement procedural geometry to avoid external assets: ```typescript // src/components/threejs/objects/geometry/terrain.ts import * as THREE from 'three'; export function createTerrainGeometry( width = 10, height = 10, segments = 128, heightScale = 1, noiseScale = 0.2, ): THREE.BufferGeometry { const geometry = new THREE.PlaneGeometry(width, height, segments, segments); const positions = geometry.attributes.position.array; for (let i = 0; i < positions.length; i += 3) { // Get x,z coordinates (y is up in Three.js) const x = positions[i]; const z = positions[i + 2]; // Generate height using simplex/perlin noise // Here using a simple sine wave as placeholder const y = Math.sin(x * noiseScale) * Math.cos(z * noiseScale) * heightScale; // Apply height positions[i + 1] = y; } // Recompute normals for proper lighting geometry.computeVertexNormals(); return geometry; } ``` ## Game Entities Implementation Pattern Structure game entities using this component-based pattern: ```typescript // src/components/threejs/objects/entities/entity.ts import * as THREE from 'three'; import { v4 as uuidv4 } from 'uuid'; export interface Component { update(delta: number): void; dispose(): void; } export class Entity { id: string; mesh: THREE.Object3D; components: Map; constructor(mesh: THREE.Object3D) { this.id = uuidv4(); this.mesh = mesh; this.components = new Map(); } addComponent(name: string, component: Component): void { this.components.set(name, component); } getComponent(name: string): Component | undefined { return this.components.get(name); } update(delta: number): void { this.components.forEach(component => { component.update(delta); }); } dispose(): void { this.components.forEach(component => { component.dispose(); }); if (this.mesh instanceof THREE.Mesh) { if (this.mesh.geometry) { this.mesh.geometry.dispose(); } if (this.mesh.material instanceof THREE.Material) { this.mesh.material.dispose(); } else if (Array.isArray(this.mesh.material)) { this.mesh.material.forEach(material => material.dispose()); } } } } ``` ## Physics Implementation For simple physics, implement a lightweight system: ```typescript // src/components/threejs/physics/simple-physics.ts import * as THREE from 'three'; import { Entity } from '../objects/entities/entity'; export interface PhysicsBody { velocity: THREE.Vector3; acceleration: THREE.Vector3; mass: number; useGravity: boolean; isKinematic: boolean; } export class PhysicsComponent implements Component { private entity: Entity; private body: PhysicsBody; constructor(entity: Entity, options: Partial = {}) { this.entity = entity; this.body = { velocity: new THREE.Vector3(), acceleration: new THREE.Vector3(), mass: 1, useGravity: true, isKinematic: false, ...options }; } update(delta: number): void { if (this.body.isKinematic) return; // Apply gravity if (this.body.useGravity) { this.body.acceleration.y -= 9.8; // Gravity } // Update velocity this.body.velocity.addScaledVector(this.body.acceleration, delta); // Apply velocity to position this.entity.mesh.position.addScaledVector(this.body.velocity, delta); // Reset acceleration this.body.acceleration.set(0, 0, 0); } applyForce(force: THREE.Vector3): void { // F = ma, so a = F/m const accelerationChange = force.divideScalar(this.body.mass); this.body.acceleration.add(accelerationChange); } dispose(): void { // Nothing to dispose } } ``` ## Animation System Implement animation patterns for smooth transitions: ```typescript // src/components/threejs/animations/tween.ts export class Tween { private startValue: number; private endValue: number; private duration: number; private elapsedTime: number = 0; private onUpdate: (value: number) => void; private easing: (t: number) => number; private isComplete: boolean = false; constructor( startValue: number, endValue: number, duration: number, onUpdate: (value: number) => void, easing: (t: number) => number = Tween.easeInOutQuad ) { this.startValue = startValue; this.endValue = endValue; this.duration = duration; this.onUpdate = onUpdate; this.easing = easing; } update(delta: number): boolean { if (this.isComplete) return true; this.elapsedTime += delta; if (this.elapsedTime >= this.duration) { this.onUpdate(this.endValue); this.isComplete = true; return true; } const t = this.easing(this.elapsedTime / this.duration); const currentValue = this.startValue + (this.endValue - this.startValue) * t; this.onUpdate(currentValue); return false; } // Easing functions static linear(t: number): number { return t; } static easeInOutQuad(t: number): number { return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2; } } ``` ## Shader Implementation Pattern For custom materials and effects: ```typescript // src/components/threejs/materials/custom-shader.ts import * as THREE from 'three'; export function createCustomShaderMaterial(): THREE.ShaderMaterial { return new THREE.ShaderMaterial({ uniforms: { time: { value: 0 }, resolution: { value: new THREE.Vector2() }, color: { value: new THREE.Color(0x00aaff) } }, vertexShader: ` varying vec2 vUv; void main() { vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); } `, fragmentShader: ` uniform float time; uniform vec2 resolution; uniform vec3 color; varying vec2 vUv; void main() { // Create a pulsating effect float pulse = (sin(time * 2.0) + 1.0) * 0.5; // Create a gradient based on UV coordinates vec3 gradientColor = mix(color, color * 0.5, vUv.y); // Apply pulse vec3 finalColor = mix(gradientColor * 0.5, gradientColor, pulse); gl_FragColor = vec4(finalColor, 1.0); } `, transparent: true }); } ``` ## Game State Management Implement clean state management: ```typescript // src/game/state.ts import { create } from 'zustand'; export interface GameState { score: number; health: number; level: number; isPaused: boolean; isGameOver: boolean; // Actions incrementScore: (amount: number) => void; decrementHealth: (amount: number) => void; setLevel: (level: number) => void; togglePause: () => void; resetGame: () => void; setGameOver: () => void; } export const useGameState = create((set) => ({ score: 0, health: 100, level: 1, isPaused: false, isGameOver: false, incrementScore: (amount) => set((state) => ({ score: state.score + amount })), decrementHealth: (amount) => set((state) => { const newHealth = Math.max(0, state.health - amount); return { health: newHealth, isGameOver: newHealth <= 0 }; }), setLevel: (level) => set({ level }), togglePause: () => set((state) => ({ isPaused: !state.isPaused })), resetGame: () => set({ score: 0, health: 100, level: 1, isPaused: false, isGameOver: false }), setGameOver: () => set({ isGameOver: true }) })); ``` ## Game Loop and FPS Management The game loop implementation includes both core functionality and FPS management. Here's the complete implementation: ```typescript // src/hooks/useGameLoop.ts import { useRef, useEffect } from 'react'; import { useGameState } from '@/game/state'; interface GameLoopConfig { targetFPS: number; // Target frames per second (e.g., 60) maxDeltaTime: number; // Maximum time step (e.g., 0.1) timeScale: number; // Global time scale (e.g., 1.0) enableFixedTimeStep: boolean; // Whether to use fixed time steps } const DEFAULT_CONFIG: GameLoopConfig = { targetFPS: 60, maxDeltaTime: 0.1, timeScale: 1.0, enableFixedTimeStep: true }; export function useGameLoop( updateFn: (delta: number) => void, config: Partial = {} ) { const frameId = useRef(null); const lastTime = useRef(0); const accumulator = useRef(0); const { isPaused, isGameOver } = useGameState(); const finalConfig = { ...DEFAULT_CONFIG, ...config }; const fixedTimeStep = 1 / finalConfig.targetFPS; useEffect(() => { const animate = (time: number) => { frameId.current = requestAnimationFrame(animate); if (isPaused || isGameOver) return; const realDelta = (time - lastTime.current) / 1000; lastTime.current = time; const delta = Math.min(realDelta, finalConfig.maxDeltaTime); if (finalConfig.enableFixedTimeStep) { accumulator.current += delta; while (accumulator.current >= fixedTimeStep) { const scaledDelta = fixedTimeStep * finalConfig.timeScale; updateFn(scaledDelta); accumulator.current -= fixedTimeStep; } const alpha = accumulator.current / fixedTimeStep; } else { const scaledDelta = delta * finalConfig.timeScale; updateFn(scaledDelta); } }; lastTime.current = performance.now(); accumulator.current = 0; frameId.current = requestAnimationFrame(animate); return () => { if (frameId.current) { cancelAnimationFrame(frameId.current); } }; }, [updateFn, isPaused, isGameOver, finalConfig]); return { setTimeScale: (scale: number) => { finalConfig.timeScale = scale; }, setTargetFPS: (fps: number) => { finalConfig.targetFPS = fps; }, toggleFixedTimeStep: () => { finalConfig.enableFixedTimeStep = !finalConfig.enableFixedTimeStep; } }; } // Example usage with FPS management: export function GameComponent() { const updateGame = (delta: number) => { // All time-dependent calculations should use delta player.position.x += player.velocity.x * delta; player.position.y += player.velocity.y * delta; // Physics updates updatePhysics(delta); // Animation updates updateAnimations(delta); }; const { setTimeScale, setTargetFPS } = useGameLoop(updateGame, { targetFPS: 60, maxDeltaTime: 0.1, timeScale: 1.0, enableFixedTimeStep: true }); // Example: Slow motion effect const handleSlowMotion = () => { setTimeScale(0.5); // Half speed }; // Example: Adjust for different monitor refresh rates useEffect(() => { const refreshRate = window.matchMedia('(min-resolution: 120dpi)').matches ? 120 : 60; setTargetFPS(refreshRate); }, []); return ( // ... component JSX ); } ### FPS Management Best Practices 1. **Fixed Time Step** - Use fixed time steps for physics and game logic - Accumulate time and update in fixed intervals - Interpolate between states for smooth rendering 2. **Time Scaling** - Implement global time scale for game speed control - Allow runtime adjustment for slow-motion/fast-forward - Apply time scale to all time-dependent calculations 3. **Performance Considerations** - Cap maximum delta time to prevent large jumps - Monitor frame times and adjust quality settings - Consider frame skipping for slow devices 4. **Implementation Guidelines** - Always multiply time-dependent calculations by delta time - Use fixed time step for physics and game logic - Separate rendering from game state updates - Implement interpolation for smooth visual updates ``` ## Performance Monitoring with Stats.js Implement performance monitoring using Stats.js: ```typescript // src/hooks/useStats.ts import { useEffect, useRef } from 'react'; import Stats from 'stats.js'; export function useStats() { const statsRef = useRef(null); useEffect(() => { // Initialize Stats.js const stats = new Stats(); stats.showPanel(0); // 0: fps, 1: ms, 2: mb, 3+: custom stats.dom.style.cssText = 'position:absolute;top:0;left:0;cursor:pointer;opacity:0.9;z-index:10000'; document.body.appendChild(stats.dom); statsRef.current = stats; // Start monitoring const animate = () => { if (statsRef.current) { statsRef.current.begin(); // Your render code here statsRef.current.end(); } requestAnimationFrame(animate); }; animate(); return () => { if (statsRef.current) { document.body.removeChild(statsRef.current.dom); statsRef.current = null; } }; }, []); return statsRef; } // Usage in your game component: export function GameComponent() { const stats = useStats(); // Your game code here return (

{/* Stats.js will be automatically injected into the DOM */}

{/* Your game content */}

); } ``` For custom stats panels, you can extend the basic implementation: ```typescript // src/hooks/useExtendedStats.ts import { useEffect, useRef } from 'react'; import Stats from 'stats.js'; export function useExtendedStats() { const statsRef = useRef(null); useEffect(() => { const stats = new Stats(); // Add custom panel for game-specific metrics stats.addPanel(new Stats.Panel('Game', '#ff8', '#221')); stats.showPanel(0); // Show FPS panel by default // Style the stats panel stats.dom.style.cssText = ` position: absolute; top: 0; left: 0; cursor: pointer; opacity: 0.9; z-index: 10000; transition: opacity 0.2s; `; // Add hover effect stats.dom.addEventListener('mouseenter', () => { stats.dom.style.opacity = '1'; }); stats.dom.addEventListener('mouseleave', () => { stats.dom.style.opacity = '0.9'; }); document.body.appendChild(stats.dom); statsRef.current = stats; const animate = () => { if (statsRef.current) { statsRef.current.begin(); // Update custom panel with game metrics if (statsRef.current.panels[3]) { statsRef.current.panels[3].update( performance.memory?.usedJSHeapSize / 1048576 || 0, // Memory usage in MB 100 // Max value ); } statsRef.current.end(); } requestAnimationFrame(animate); }; animate(); return () => { if (statsRef.current) { document.body.removeChild(statsRef.current.dom); statsRef.current = null; } }; }, []); return statsRef; } ``` ## Best Practices Summary 1. **Memory Management** - Always dispose of geometries, materials, textures, and renderers - Use object pooling for frequently created/destroyed objects - Implement proper cleanup in useEffect returns - Use Stats.js to monitor memory usage and performance 2. **Performance Optimization** - Use instanced meshes for repeated objects - Implement LOD (Level of Detail) for complex objects - Merge geometries when possible - Use texture atlases - Monitor performance with Stats.js panels