# 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. ```plaintext THREEJS_VERSION = "0.175.0" ``` Keep the files in the src/app directory structure for Next.js compatibility. ## Critical Implementation Notes - **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 a real-time stats monitor showing FPS, mobile status, player position, and game score for all 3D games 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 Implement the following file structure for ThreeJS-based games: You must create these files since they do not exist yet: ``` 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 ``` ## 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 }) })); ``` ## Next.js Integration Example ```tsx // src/app/game/page.tsx 'use client'; import { useRef, useEffect } from 'react'; import { useGameState } from '@/game/state'; import { useThree } from '@/hooks/useThree'; import GameUI from '@/components/ui/GameUI'; import styles from './page.module.css'; export default function GamePage() { const containerRef = useRef(null); const { scene, camera } = useThree(containerRef); const { score, health, isPaused, isGameOver, togglePause, resetGame } = useGameState(); // Set up game useEffect(() => { if (!scene.current) return; // Add game objects to scene return () => { // Cleanup }; }, [scene]); return (

); } ``` ## Core Game Loop Implementation ```typescript // src/hooks/useGameLoop.ts import { useRef, useEffect } from 'react'; import { useGameState } from '@/game/state'; export function useGameLoop(updateFn: (delta: number) => void) { const frameId = useRef(null); const lastTime = useRef(0); const { isPaused, isGameOver } = useGameState(); useEffect(() => { const animate = (time: number) => { frameId.current = requestAnimationFrame(animate); if (isPaused || isGameOver) return; const delta = (time - lastTime.current) / 1000; // Convert to seconds lastTime.current = time; // Cap delta to avoid huge jumps const cappedDelta = Math.min(delta, 0.1); updateFn(cappedDelta); }; lastTime.current = performance.now(); frameId.current = requestAnimationFrame(animate); return () => { if (frameId.current) { cancelAnimationFrame(frameId.current); } }; }, [updateFn, isPaused, isGameOver]); } ``` ## Responsive Design Patterns ```typescript // src/hooks/useResponsiveThree.ts import { useEffect } from 'react'; import * as THREE from 'three'; export function useResponsiveThree( camera: React.MutableRefObject, renderer: React.MutableRefObject, containerRef: React.RefObject ) { useEffect(() => { const handleResize = () => { if (!containerRef.current || !camera.current || !renderer.current) return; const width = containerRef.current.clientWidth; const height = containerRef.current.clientHeight; const aspect = width / height; // Update camera camera.current.aspect = aspect; camera.current.updateProjectionMatrix(); // Adjust renderer renderer.current.setSize(width, height); renderer.current.setPixelRatio(Math.min(window.devicePixelRatio, 2)); // Cap pixel ratio for performance // Mobile-specific adjustments if (width < 768) { // Adjust camera for smaller screens camera.current.fov = 75; // Wider FOV on mobile camera.current.updateProjectionMatrix(); } else { camera.current.fov = 65; // Standard FOV on desktop camera.current.updateProjectionMatrix(); } }; window.addEventListener('resize', handleResize); handleResize(); // Call once initially return () => { window.removeEventListener('resize', handleResize); }; }, [camera, renderer, containerRef]); } ``` ## 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 2. **Performance Optimization** - Use instanced meshes for repeated objects - Implement LOD (Level of Detail) for complex objects - Merge geometries when possible - Use texture atlases 3. **Code Structure** - Separate rendering from game logic - Use component-based architecture for entities - Implement clean state management - Keep shader code modular and reusable 4. **Responsive Design** - Adjust camera parameters based on screen size - Scale complexity based on device capabilities - Implement touch controls for mobile 5. **Testing and Debug** - Use Stats.js for performance monitoring - Implement debug views for physics, collisions - Create visual helpers for development

Sound2Life