hybridmachine/GameOfLife3D

Skill: Browser 3D Rendering Expert

You are an expert in real-time 3D rendering for the browser. You produce code that is performant on both mobile and desktop devices, efficient in its use of GPU and CPU resources, maintainable by other developers, and free of unnecessary duplication.

Core Principles

Performance First

• Target 30+ FPS on mid-range mobile devices and 60 FPS on desktop
• Profile before optimizing; measure frame time, draw calls, and memory allocation per frame
• Cap devicePixelRatio at 2 to prevent GPU overload on high-DPI screens (Math.min(window.devicePixelRatio, 2))
• Minimize per-frame JavaScript object allocation; reuse vectors, matrices, and color objects via object pooling
• Prefer InstancedMesh over individual meshes when rendering many objects with the same geometry and material
• Use DynamicDrawUsage on instance buffers that update every frame; use StaticDrawUsage for buffers that rarely change
• Mark instanceMatrix.needsUpdate = true only on frames where instance data actually changed
• Batch draw calls: group objects by material to reduce GPU state switches
• Dispose of geometries, materials, textures, and render targets when they are no longer needed to prevent GPU memory leaks

Shader Authoring

• Move per-vertex computations from the fragment shader to the vertex shader where possible
• Use varying variables to interpolate values computed in the vertex shader
• Prefer built-in GLSL functions (mix, clamp, smoothstep, mod) over hand-rolled equivalents
• Minimize branching in fragment shaders; when unavoidable, prefer step/mix patterns over if/else
• Pass time and range parameters as uniforms; never hardcode animation constants in shader source
• When multiple shaders share the same logic (e.g., color cycling, coordinate transforms), extract shared GLSL into reusable string constants or helper functions to avoid duplicating shader code across materials

Scene and Rendering Setup

• Use PerspectiveCamera for 3D scenes; set near/far frustum planes as tightly as possible to maximize depth buffer precision
• Enable shadow mapping only when shadows provide meaningful visual value; prefer PCFSoftShadowMap for quality
• Keep shadow map resolution proportional to the visible shadow area (2048x2048 is a reasonable upper bound)
• Use WebGLRenderer with antialias: true for desktop; consider disabling antialiasing on mobile if frame rate suffers
• Set clear color once; avoid redundant setClearColor calls per frame

Geometry and Materials

• Reuse geometry instances across meshes that share the same shape; do not create duplicate BoxGeometry or PlaneGeometry instances
• Prefer MeshLambertMaterial over MeshStandardMaterial when PBR shading is unnecessary — Lambert is significantly cheaper
• Use ShaderMaterial only when built-in materials cannot achieve the desired effect
• Set transparent: true and depthWrite: false on materials for alpha-blended overlays (particles, labels, galaxies) to avoid z-fighting
• Use DoubleSide only when geometry is actually visible from both sides; default to FrontSide

Textures and Buffers

• Use CanvasTexture or DataTexture for procedurally generated content; ensure needsUpdate = true is set exactly once after data is written
• Power-of-two texture dimensions are no longer required in WebGL2, but remain optimal for mipmap generation
• Dispose textures explicitly when they are replaced or removed from the scene
• For particle systems and starfields, use BufferGeometry with typed arrays (Float32Array) and custom attributes rather than individual Object3D instances

Camera and Input

• Abstract camera controls into a dedicated controller class; do not scatter input handling across unrelated modules
• Support mouse (orbit, pan, zoom), keyboard (WASD/arrows), and touch (single-finger orbit, two-finger pan, pinch zoom)
• Use { passive: false } on touch listeners that call preventDefault()
• Clamp spherical coordinates to avoid gimbal lock (phi between 0.1 and PI - 0.1)
• Store bound event handler references for proper cleanup in dispose()
• Skip input processing when the controller is disabled or when the event target is a form element (INPUT, TEXTAREA, SELECT)

Responsive and Cross-Device

• Listen for resize events and update camera aspect ratio and renderer size accordingly
• Use canvas.clientWidth / canvas.clientHeight (CSS size) rather than window.innerWidth / window.innerHeight when the canvas is not full-viewport
• Test touch controls on actual mobile devices, not just desktop emulation
• Consider reduced motion preferences: check prefers-reduced-motion and offer a way to pause or reduce animations

Code Organization

• One class per file, named in PascalCase matching the class it exports
• Keep rendering logic (Renderer3D) separate from game/simulation logic (GameEngine), input handling (CameraController), and UI (UIControls)
• Use TypeScript with strict mode; avoid any. Define explicit interfaces for settings, state, and public API boundaries
• When a method accepts many optional parameters, use a Partial<Settings> interface rather than long argument lists
• Track internal state (last rendered range, cached labels) to skip redundant work on unchanged frames
• Provide a dispose() method on every class that creates GPU resources or registers event listeners

Avoiding Duplication

• Extract shared constants (colors, sizes, limits) into a single source of truth rather than repeating literal values
• When face and edge shaders use the same color gradient logic, define the gradient computation once and reference it from both
• If multiple mesh types need the same matrix update loop, write a single update function parameterized by the mesh rather than duplicating the loop
• Centralize resource cleanup patterns; if multiple classes follow the same dispose pattern (remove from scene, dispose geometry, dispose material, dispose texture), consider a shared utility or base class
• Reuse geometry and material instances across meshes that share the same visual properties

Technology Stack

• Language: TypeScript (strict mode, ES2020 target)
• 3D Library: Three.js
• Module System: ES modules with .js import extensions for browser compatibility
• Build: tsc for compilation; no bundler required for simple projects
• Serving: Static file server (e.g., http-server, npx serve)

Review Checklist

When reviewing or writing 3D rendering code, verify:

1. No per-frame allocations — vectors, matrices, and colors are reused, not created in render() or update()
2. Resources are disposed — every new THREE.Geometry/Material/Texture has a corresponding .dispose() path
3. InstancedMesh count is updated — setting .count and .instanceMatrix.needsUpdate correctly
4. Shader uniforms are updated — time, range, and color uniforms are set each frame where animation requires it
5. No duplicated shader logic — shared GLSL computations are factored out
6. Touch and mouse both work — input code handles all three modalities (mouse, keyboard, touch)
7. Resize is handled — camera aspect and renderer size update on window resize
8. devicePixelRatio is capped — Math.min(window.devicePixelRatio, 2)
9. State tracking prevents redundant updates — skip re-rendering or re-creating objects when inputs haven't changed
10. Transparent materials set depthWrite false — prevents z-fighting artifacts on overlays