@directivegames/genesys.js 3.1.24

package/docs/guides/4-visuals-and-rendering.md

@@ -0,0 +1,946 @@
+## Instruction
+Use this doc to understand how visuals and rendering work in Genesys.js and learn how to display 3D models using MeshComponent and GLTFMeshComponent, apply materials and textures, and set up lighting to create visually appealing game scenes.
+
+# 4-visuals-and-rendering.md
+
+## Visuals and Rendering in Genesys.js
+
+The visual appearance of your game is crucial for creating an immersive experience. Genesys.js, built on top of Three.js, provides a powerful and flexible system for rendering 3D models, applying materials, and lighting your scenes. This guide covers the essential components and techniques for controlling the visuals of your game.
+
+---
+
+## 1. Displaying 3D Models
+
+The primary way to get a 3D object on screen is by using a component that manages a `THREE.Mesh`.
+
+### `MeshComponent` for Primitive Shapes
+
+For simple geometric shapes like cubes, spheres, or planes, the `ENGINE.MeshComponent` is the perfect tool. You provide it with a Three.js `BufferGeometry` and a `Material`.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// Create an actor to hold our mesh.
+const simpleActor = new ENGINE.Actor({
+    position: new THREE.Vector3(0, 1, 0),
+    rootComponent: new ENGINE.MeshComponent({
+        // Define the shape.
+        geometry: new THREE.SphereGeometry(0.5, 32, 16),
+        // Define the surface appearance.
+        material: new THREE.MeshStandardMaterial({
+            color: 'red',
+            roughness: 0.2,
+            metalness: 0.8
+        })
+    })
+});
+
+// Add it to the world to be rendered.
+// world.addActors(simpleActor);
+```
+
+### `GLTFMeshComponent` for Complex Models
+
+For complex models created in 3D modeling software like Blender, you'll typically use the glTF format (`.gltf` or `.glb`). The `ENGINE.GLTFMeshComponent` is designed to load and display these files.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// Create an actor to display a loaded model.
+const modelActor = new ENGINE.Actor({
+    position: new THREE.Vector3(0, 0, -5),
+    rootComponent: new ENGINE.GLTFMeshComponent({
+        // The path to your model file, relative to your project's asset root.
+        modelUrl: '@engine/assets/models/MySpaceship.glb',
+        // Optional: override all materials in the model with a single one.
+        // materialOverride: new THREE.MeshNormalMaterial() 
+    })
+});
+
+// world.addActors(modelActor);
+```
+
+Model loading is asynchronous. You can use the `onModelLoaded` callback to execute code once the model is ready. This is especially important for things like animation setup.
+
+```typescript
+const gltfComponent = modelActor.rootComponent as ENGINE.GLTFMeshComponent;
+
+gltfComponent.onModelLoaded(() => {
+    console.log("Spaceship model has finished loading!");
+    // Now it's safe to access the model's data, e.g., gltfComponent.gltf
+});
+```
+
+---
+
+## 2. Materials
+
+Materials define the surface properties of an object: its color, texture, shininess, and more. Genesys.js uses Three.js materials directly.
+
+The most common material for realistic rendering is `THREE.MeshStandardMaterial`, which works with a physically-based rendering (PBR) workflow.
+
+### Using Textures
+
+To apply a texture, you load it and assign it to a material's `map` property. The engine provides a custom `UrlTexture` class that integrates with the serialization system.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// Create a texture from a URL.
+const woodTexture = new ENGINE.UrlTexture({
+    url: '@engine/assets/textures/wood_albedo.png',
+    wrapS: THREE.RepeatWrapping,
+    wrapT: THREE.RepeatWrapping
+});
+
+// Create another texture for the normal map.
+const woodNormalMap = new ENGINE.UrlTexture({
+    url: '@engine/assets/textures/wood_normal.png',
+    wrapS: THREE.RepeatWrapping,
+    wrapT: THREE.RepeatWrapping
+});
+
+// Create the material.
+const woodMaterial = new THREE.MeshStandardMaterial({
+    map: woodTexture,          // Base color texture
+    normalMap: woodNormalMap,  // For surface detail
+    roughness: 0.8,
+    metalness: 0.1
+});
+
+// Create a cube with this material.
+const woodCube = new ENGINE.MeshComponent({
+    geometry: new THREE.BoxGeometry(2, 2, 2),
+    material: woodMaterial
+});
+```
+
+### `MaterialUtils`
+
+The engine provides a `MaterialUtils` class with some helpful presets:
+
+*   `MaterialUtils.DefaultMaterial`: A simple checkerboard material, great for placeholders.
+*   `MaterialUtils.MeshWorldSpaceNormalMaterial`: A debug material that visualizes the mesh's normals in world space.
+*   `MaterialUtils.scaleUVsBySize()`: A utility to automatically scale a texture's UVs based on the mesh size, preventing stretching. This is used by `GameBuilder.createDefaultGround()`.
+
+---
+
+## 3. Lighting
+
+A scene isn't complete without lighting. Genesys provides a component for each type of Three.js light, allowing you to easily add them to your scene as part of an actor.
+
+### Light Component Types
+
+*   **`AmbientLightComponent`**: Provides a constant, non-directional light to the entire scene. It's useful for setting a baseline brightness so shadows aren't completely black.
+*   **`DirectionalLightComponent`**: Simulates a distant light source like the sun, where all light rays are parallel. This is the primary light source for casting shadows in outdoor scenes.
+*   **`PointLightComponent`**: Emits light in all directions from a single point, like a light bulb.
+*   **`SpotLightComponent`**: Emits light in a cone shape, like a flashlight or stage light.
+*   **`HemisphereLightComponent`**: Simulates ambient light from the sky and ground with two different colors.
+
+### Adding Lights to the Scene
+
+You add lights by creating an `Actor` and attaching a light component to it. The position and rotation of the actor will determine the light's position and direction.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class MyGame extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // --- The Sun ---
+        // A directional light to simulate the sun.
+        const sunActor = new ENGINE.Actor({
+            // Position the light source high up and to the side.
+            position: new THREE.Vector3(50, 80, 30),
+            sceneComponents: [
+                new ENGINE.DirectionalLightComponent({
+                    color: 0xfffde8, // A warm, sunny color
+                    intensity: 1.5,
+                    // Enable shadow casting for this light.
+                    castShadow: true
+                })
+            ]
+        });
+        // The light will point from its position towards the world origin (0,0,0) by default.
+        this.world.addActors(sunActor);
+
+        // --- Ambient Light ---
+        // A soft ambient light to fill in the shadows.
+        const ambientActor = new ENGINE.Actor({
+            sceneComponents: [
+                new ENGINE.AmbientLightComponent({
+                    color: 0x404080, // A cool, bluish ambient color
+                    intensity: 0.3
+                })
+            ]
+        });
+        this.world.addActors(ambientActor);
+        
+        // --- A Point Light ---
+        // A flickering point light for a torch.
+        const torchActor = new ENGINE.Actor({
+            position: new THREE.Vector3(5, 1.5, -5),
+            sceneComponents: [
+                new ENGINE.PointLightComponent({
+                    color: 0xffa500, // Orange
+                    intensity: 2,
+                    distance: 10, // Light fades out over 10 units
+                    decay: 2
+                })
+            ]
+        });
+        this.world.addActors(torchActor);
+    }
+}
+```
+
+### Shadows
+
+For an object to cast or receive shadows, two things must be true:
+
+1.  A light source (like a `DirectionalLightComponent`) must have `castShadow: true`.
+2.  A `MeshComponent` must have `castShadow: true` (to cast a shadow) and/or `receiveShadow: true` (to have shadows cast upon it).
+
+The `GameBuilder`'s default ground and pawn are already configured to receive and cast shadows, respectively.
+
+```typescript
+// This cube will both cast a shadow and have shadows cast upon it.
+const shadowCube = new ENGINE.MeshComponent({
+    geometry: new THREE.BoxGeometry(1, 1, 1),
+    material: new THREE.MeshStandardMaterial({ color: 'white' })
+});
+
+shadowCube.castShadow = true;
+shadowCube.receiveShadow = true;
+```
+
+### Static vs Dynamic Lights (Lightmapping)
+
+When using the lightmapping system, lights can be configured as either static (baked into lightmaps) or dynamic (runtime only):
+
+```typescript
+// Static light - baked into lightmaps for optimal performance
+const sunLight = new ENGINE.DirectionalLightComponent({
+  color: 0xffffff,
+  intensity: 1.5,
+  bakeLightmaps: true    // Default - will be baked and hidden at runtime
+});
+
+// Dynamic light - excluded from lightmaps, stays active for real-time effects
+const flashlight = new ENGINE.SpotLightComponent({
+  color: 0xffffff,
+  intensity: 100,
+  bakeLightmaps: false   // Runtime-only lighting
+});
+
+// Set lightmap baking
+sunLight.setLightmapBaked(true);      // bakeLightmaps: true
+flashlight.setLightmapBaked(false);   // bakeLightmaps: false
+```
+
+**Use static lights for:** Environmental lighting, architectural lights, performance-critical scenarios
+**Use dynamic lights for:** Player-controlled lights, moving objects, interactive elements, temporary effects
+
+For detailed lightmapping workflows, see the [Lightmapping System guide](18-lightmapping-system.md).
+
+---
+
+## 4. Skyboxes
+
+A skybox creates the illusion of a distant environment surrounding your entire scene, providing both visual background and environmental lighting through reflections. Genesys.js provides the `ENGINE.SkyboxComponent` which supports two types of skyboxes: texture-based and procedural.
+
+### Creating a Skybox with `GameBuilder`
+
+The easiest way to add a skybox to your scene is using the `GameBuilder` helper:
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class MyGame extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Create a default skybox with HDR texture
+        const skyboxComponent = ENGINE.GameBuilder.createDefaultSkybox(this.world);
+        
+        // The skybox is now active and providing environmental lighting
+    }
+}
+```
+
+### Texture-Based Skyboxes
+
+Texture-based skyboxes use panoramic images to create realistic environments. The component supports both HDR formats (`.hdr`, `.exr`) for high dynamic range lighting and standard image formats (`.png`, `.jpg`).
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// Create an actor with a skybox component
+const skyboxActor = new ENGINE.Actor({
+    components: [
+        new ENGINE.SkyboxComponent({
+            // HDR texture for realistic lighting
+            url: '@engine/assets/textures/skybox/forest_environment.hdr'
+        })
+    ]
+});
+
+// Add to world
+// world.addActors(skyboxActor);
+
+// Or dynamically change the skybox texture
+const skyboxComponent = skyboxActor.getComponent(ENGINE.SkyboxComponent);
+skyboxComponent.createTextureSkybox('@engine/assets/textures/skybox/sunset_sky.hdr');
+```
+
+**Recommended HDR Sources:**
+- [Poly Haven](https://polyhaven.com/hdris) - Free HDR environments
+- HDR formats provide better lighting and reflections than standard images
+
+### Finding and Managing Skybox Components
+
+Once you've created a skybox, you can find and manage it from anywhere in your code using the world's component query methods:
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class MyGame extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Create initial skybox
+        ENGINE.GameBuilder.createDefaultSkybox(this.world);
+    }
+
+    // Method to change skybox based on game state
+    private updateEnvironment(timeOfDay: 'dawn' | 'day' | 'dusk' | 'night'): void {
+        // Find the existing skybox component in the world
+        const skyboxComponent = this.world.getComponent(ENGINE.SkyboxComponent);
+        
+        if (!skyboxComponent) {
+            console.warn('No skybox component found in world');
+            return;
+        }
+
+        // Update skybox based on time of day
+        switch (timeOfDay) {
+            case 'dawn':
+                skyboxComponent.createProceduralSkybox({
+                    width: 2048, height: 1024,
+                    bottomColor: '#ffb347', // Peach
+                    middleColor: '#ffa500', // Orange
+                    topColor: '#ff8c00'     // Dark orange
+                });
+                break;
+            case 'day':
+                skyboxComponent.createTextureSkybox('@engine/assets/textures/skybox/clear_day.hdr');
+                break;
+            case 'dusk':
+                skyboxComponent.createProceduralSkybox({
+                    width: 2048, height: 1024,
+                    bottomColor: '#ff4500', // Red-orange
+                    middleColor: '#ff6347', // Tomato
+                    topColor: '#ffd700'     // Gold
+                });
+                break;
+            case 'night':
+                skyboxComponent.createTextureSkybox('@engine/assets/textures/skybox/starry_night.hdr');
+                break;
+        }
+    }
+
+    // Check if a skybox exists
+    private hasSkybox(): boolean {
+        return this.world.getComponent(ENGINE.SkyboxComponent) !== null;
+    }
+
+    // Remove skybox entirely
+    private removeSkybox(): void {
+        const skyboxComponent = this.world.getComponent(ENGINE.SkyboxComponent);
+        if (skyboxComponent) {
+            const skyboxActor = skyboxComponent.getOwner();
+            if (skyboxActor) {
+                this.world.removeActors(skyboxActor);
+            }
+        }
+    }
+}
+```
+
+**Key Methods for Skybox Management:**
+
+- **`world.getComponent(ENGINE.SkyboxComponent)`**: Finds the first (and typically only) skybox component in the world
+- **`skyboxComponent.createTextureSkybox(url)`**: Switches to a texture-based skybox
+- **`skyboxComponent.createProceduralSkybox(options)`**: Switches to a procedural skybox
+- **`skyboxComponent.getOwner()`**: Gets the actor that owns the skybox component (useful for removal)
+
+This approach allows you to:
+- Change skyboxes dynamically based on game events
+- Implement time-of-day systems
+- Switch between different environment themes
+- Check if a skybox exists before modifying it
+- Remove skyboxes when needed
+
+### Procedural Skyboxes
+
+For stylized games or when you don't have HDR textures, procedural skyboxes generate gradient-based environments programmatically:
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+const proceduralSkybox = new ENGINE.SkyboxComponent();
+
+// Create a sunset gradient skybox
+proceduralSkybox.createProceduralSkybox({
+    width: 2048,        // Texture resolution width
+    height: 1024,       // Texture resolution height
+    bottomColor: '#ff4500',  // Orange bottom (horizon)
+    middleColor: '#ff6347',  // Red-orange middle
+    topColor: '#ffd700'      // Gold top (sky)
+});
+
+const skyboxActor = new ENGINE.Actor({
+    components: [proceduralSkybox]
+});
+
+// world.addActors(skyboxActor);
+```
+
+### Environment Mapping and Reflections
+
+Skyboxes automatically provide environment mapping for materials in your scene. This means reflective surfaces will show the skybox environment, creating realistic reflections:
+
+```typescript
+// Create a reflective sphere that will show the skybox
+const reflectiveSphere = new ENGINE.Actor({
+    position: new THREE.Vector3(0, 2, 0),
+    rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.SphereGeometry(1, 32, 16),
+        material: new THREE.MeshStandardMaterial({
+            color: 'white',
+            roughness: 0.1,    // Low roughness = more reflective
+            metalness: 0.9     // High metalness = mirror-like
+        })
+    })
+});
+
+// The sphere will automatically reflect the skybox environment
+// world.addActors(reflectiveSphere);
+```
+
+### Dynamic Skybox Switching
+
+You can change skyboxes during runtime to create time-of-day effects or different environments:
+
+```typescript
+class DynamicSkyboxGame extends ENGINE.BaseGameLoop {
+    private skyboxComponent: ENGINE.SkyboxComponent;
+    private timeOfDay = 0;
+
+    protected override preStart(): void {
+        this.skyboxComponent = ENGINE.GameBuilder.createDefaultSkybox(this.world);
+        
+        // Change skybox every 10 seconds
+        setInterval(() => {
+            this.updateTimeOfDay();
+        }, 10000);
+    }
+
+    private updateTimeOfDay(): void {
+        this.timeOfDay = (this.timeOfDay + 1) % 4;
+        
+        switch (this.timeOfDay) {
+            case 0: // Dawn
+                this.skyboxComponent.createProceduralSkybox({
+                    width: 2048, height: 1024,
+                    bottomColor: '#ffb347', middleColor: '#ffa500', topColor: '#ff8c00'
+                });
+                break;
+            case 1: // Day
+                this.skyboxComponent.createTextureSkybox('@engine/assets/textures/skybox/day_sky.hdr');
+                break;
+            case 2: // Sunset
+                this.skyboxComponent.createProceduralSkybox({
+                    width: 2048, height: 1024,
+                    bottomColor: '#ff4500', middleColor: '#ff6347', topColor: '#ffd700'
+                });
+                break;
+            case 3: // Night
+                this.skyboxComponent.createProceduralSkybox({
+                    width: 2048, height: 1024,
+                    bottomColor: '#191970', middleColor: '#483d8b', topColor: '#4b0082'
+                });
+                break;
+        }
+    }
+}
+```
+
+### Automatic Environment Mapping Integration
+
+Genesys.js extends Three.js's `MeshStandardMaterial` to automatically integrate with skybox components for seamless environment mapping. This system provides realistic reflections and environmental lighting without requiring manual material configuration.
+
+#### How It Works
+
+When you create a skybox using `SkyboxComponent`, it automatically becomes available as an environment map for all `MeshStandardMaterial` objects in your scene. The engine patches the material's `envMap` and `envMapIntensity` properties to dynamically reference the active skybox.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class AutoEnvironmentExample extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Create a skybox - this will automatically provide environment mapping
+        const skyboxComponent = ENGINE.GameBuilder.createDefaultSkybox(this.world);
+        
+        // Create a reflective sphere - no manual envMap setup needed!
+        const reflectiveSphere = new ENGINE.Actor({
+            position: new THREE.Vector3(0, 2, 0),
+            rootComponent: new ENGINE.MeshComponent({
+                geometry: new THREE.SphereGeometry(1, 32, 16),
+                material: new THREE.MeshStandardMaterial({
+                    color: 'white',
+                    roughness: 0.1,    // Low roughness = more reflective
+                    metalness: 0.9     // High metalness = mirror-like
+                    // No need to set envMap - it's automatic!
+                })
+            })
+        });
+        
+        this.world.addActors(reflectiveSphere);
+    }
+}
+```
+
+#### Manual Override Support
+
+You can still manually set `envMap` and `envMapIntensity` on materials when you need specific control:
+
+```typescript
+// Create a material with custom environment mapping
+const customMaterial = new THREE.MeshStandardMaterial({
+    color: 'gold',
+    roughness: 0.2,
+    metalness: 0.8,
+    // Manual override - this will take precedence over the skybox
+    envMap: myCustomEnvironmentTexture,
+    envMapIntensity: 1.5
+});
+
+// This material will use the custom envMap instead of the skybox
+const customReflectiveObject = new ENGINE.Actor({
+    rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.BoxGeometry(1, 1, 1),
+        material: customMaterial
+    })
+});
+```
+
+#### Dynamic Skybox Changes
+
+When you change skyboxes dynamically, all materials automatically update their environment mapping:
+
+```typescript
+class DynamicEnvironmentExample extends ENGINE.BaseGameLoop {
+    private skyboxComponent: ENGINE.SkyboxComponent;
+    
+    protected override preStart(): void {
+        // Create initial skybox
+        this.skyboxComponent = ENGINE.GameBuilder.createDefaultSkybox(this.world);
+        
+        // Create multiple reflective objects
+        for (let i = 0; i < 5; i++) {
+            const sphere = new ENGINE.Actor({
+                position: new THREE.Vector3(i * 3 - 6, 1, 0),
+                rootComponent: new ENGINE.MeshComponent({
+                    geometry: new THREE.SphereGeometry(0.8, 32, 16),
+                    material: new THREE.MeshStandardMaterial({
+                        color: new THREE.Color().setHSL(i * 0.2, 1, 0.5),
+                        roughness: i * 0.2,
+                        metalness: 0.9
+                    })
+                })
+            });
+            this.world.addActors(sphere);
+        }
+        
+        // Change environment every 5 seconds
+        setInterval(() => this.cycleEnvironment(), 5000);
+    }
+    
+    private cycleEnvironment(): void {
+        // All spheres will automatically reflect the new environment
+        this.skyboxComponent.createProceduralSkybox({
+            width: 2048, height: 1024,
+            bottomColor: `hsl(${Math.random() * 360}, 70%, 50%)`,
+            middleColor: `hsl(${Math.random() * 360}, 70%, 70%)`,
+            topColor: `hsl(${Math.random() * 360}, 70%, 90%)`,
+            envMapIntensity: 0.8
+        });
+    }
+}
+```
+
+#### Environment Map Intensity Control
+
+The skybox's `envMapIntensity` setting controls how strongly the environment affects material reflections:
+
+```typescript
+// Create skybox with specific intensity
+const skyboxComponent = new ENGINE.SkyboxComponent({
+    url: '@engine/assets/textures/skybox/studio_lighting.hdr',
+    envMapIntensity: 1.2  // Stronger environmental reflections
+});
+
+// All materials will automatically use this intensity unless overridden
+const material = new THREE.MeshStandardMaterial({
+    color: 'silver',
+    roughness: 0.1,
+    metalness: 1.0
+    // envMapIntensity will be 1.2 from the skybox
+});
+```
+
+#### Technical Implementation Details
+
+The automatic environment mapping works through these mechanisms:
+
+1. **World Registration**: When a `SkyboxComponent` begins play, it registers itself with the world using `world.setSkyboxComponent(this)`
+
+2. **Material Patching**: The engine patches `MeshStandardMaterial.prototype` to override the `envMap` and `envMapIntensity` getters
+
+3. **Dynamic Resolution**: When a material's `envMap` is accessed, it checks:
+   - First: Any manually set `envMap` value (takes precedence)
+   - Second: The active skybox component's texture via `world.getSkyboxComponent()?.getTexture()`
+
+4. **Automatic Updates**: Materials automatically detect environment changes and trigger shader recompilation when needed
+
+This system ensures that:
+- Materials automatically receive environmental lighting and reflections
+- Manual overrides always take precedence when needed
+- Dynamic skybox changes propagate to all materials seamlessly
+- No performance overhead when materials have manual environment maps
+
+### Performance Considerations
+
+- **HDR Textures**: Provide the best visual quality but are larger in file size
+- **Procedural Skyboxes**: Lightweight and customizable, perfect for stylized games
+- **Resolution**: Higher resolution procedural skyboxes (4096x2048) look better but use more memory
+- **Environment Mapping**: Automatically applied to all `MeshStandardMaterial` objects in the scene
+- **Shader Compilation**: Environment changes may trigger shader recompilation, so avoid frequent skybox switching in performance-critical scenarios
+
+---
+
+## 5. Tone Mapping
+
+Tone mapping is a crucial post-processing technique that converts high dynamic range (HDR) lighting values to the limited range that can be displayed on standard monitors. Genesys.js provides access to Three.js's tone mapping system through the renderer, allowing you to control how bright lights and HDR environments are displayed.
+
+### Understanding Tone Mapping
+
+When using HDR lighting (from skyboxes, bright lights, or emissive materials), the light values can exceed the 0-1 range that monitors can display. Tone mapping algorithms compress this wide range of values while preserving visual detail and contrast, similar to how your eye adapts to different lighting conditions.
+
+### Default Settings
+
+By default, Genesys.js uses Reinhard tone mapping with an exposure of 1.0:
+
+```typescript
+// This is automatically set in the Renderer constructor
+renderer.toneMapping = THREE.ReinhardToneMapping;
+renderer.toneMappingExposure = 1.0;
+```
+
+### Available Tone Mapping Algorithms
+
+Genesys.js supports all of Three.js's tone mapping algorithms, each with different visual characteristics:
+
+```typescript
+import * as THREE from 'three';
+import * as ENGINE from 'genesys.js';
+
+class ToneMappingDemo extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Access the renderer through the world
+        const renderer = this.world.getRenderer().renderer;
+        
+        // No tone mapping - raw HDR values (may appear very bright/washed out)
+        renderer.toneMapping = THREE.NoToneMapping;
+        
+        // Linear tone mapping - simple linear scaling
+        renderer.toneMapping = THREE.LinearToneMapping;
+        
+        // Reinhard tone mapping - smooth, natural-looking (default)
+        renderer.toneMapping = THREE.ReinhardToneMapping;
+        
+        // Cineon tone mapping - film-like, higher contrast
+        renderer.toneMapping = THREE.CineonToneMapping;
+        
+        // ACES Filmic tone mapping - industry standard, cinematic look
+        renderer.toneMapping = THREE.ACESFilmicToneMapping;
+        
+        // AgX tone mapping - modern, balanced approach
+        renderer.toneMapping = THREE.AgXToneMapping;
+        
+        // Neutral tone mapping - minimal color shift
+        renderer.toneMapping = THREE.NeutralToneMapping;
+    }
+}
+```
+
+### Tone Mapping Exposure
+
+The `toneMappingExposure` property acts like a camera's exposure setting, controlling the overall brightness of the scene:
+
+```typescript
+import * as ENGINE from 'genesys.js';
+
+class ExposureDemo extends ENGINE.BaseGameLoop {
+    private currentExposure = 1.0;
+    
+    protected override preStart(): void {
+        // Create a bright HDR environment
+        ENGINE.GameBuilder.createDefaultSkybox(this.world);
+        
+        // Add some bright lights
+        const brightLight = new ENGINE.Actor({
+            position: new THREE.Vector3(5, 10, 5),
+            sceneComponents: [
+                new ENGINE.PointLightComponent({
+                    color: 0xffffff,
+                    intensity: 100, // Very bright light
+                    distance: 20
+                })
+            ]
+        });
+        this.world.addActors(brightLight);
+        
+        // Set up exposure controls
+        this.setupExposureControls();
+    }
+    
+    private setupExposureControls(): void {
+        const renderer = this.world.getRenderer().renderer;
+        
+        // Keyboard controls for exposure
+        window.addEventListener('keydown', (event) => {
+            switch (event.key) {
+                case '1': // Dark exposure
+                    this.currentExposure = 0.5;
+                    break;
+                case '2': // Normal exposure
+                    this.currentExposure = 1.0;
+                    break;
+                case '3': // Bright exposure
+                    this.currentExposure = 2.0;
+                    break;
+                case '4': // Very bright exposure
+                    this.currentExposure = 4.0;
+                    break;
+                case 'ArrowUp': // Increase exposure
+                    this.currentExposure = Math.min(this.currentExposure * 1.1, 10);
+                    break;
+                case 'ArrowDown': // Decrease exposure
+                    this.currentExposure = Math.max(this.currentExposure * 0.9, 0.1);
+                    break;
+            }
+            
+            renderer.toneMappingExposure = this.currentExposure;
+            console.log(`Exposure: ${this.currentExposure.toFixed(2)}`);
+        });
+    }
+}
+```
+
+### Tone Mapping Algorithm Comparison
+
+Each tone mapping algorithm produces different visual results:
+
+```typescript
+import * as ENGINE from 'genesys.js';
+
+class ToneMappingComparison extends ENGINE.BaseGameLoop {
+    private toneMappingModes = [
+        { name: 'No Tone Mapping', value: THREE.NoToneMapping },
+        { name: 'Linear', value: THREE.LinearToneMapping },
+        { name: 'Reinhard', value: THREE.ReinhardToneMapping },
+        { name: 'Cineon', value: THREE.CineonToneMapping },
+        { name: 'ACES Filmic', value: THREE.ACESFilmicToneMapping },
+        { name: 'AgX', value: THREE.AgXToneMapping },
+        { name: 'Neutral', value: THREE.NeutralToneMapping }
+    ];
+    private currentModeIndex = 2; // Start with Reinhard (default)
+    
+    protected override preStart(): void {
+        // Create a scene with varied lighting conditions
+        this.setupTestScene();
+        this.setupToneMappingControls();
+    }
+    
+    private setupTestScene(): void {
+        // HDR skybox for environmental lighting
+        ENGINE.GameBuilder.createDefaultSkybox(this.world);
+        ENGINE.GameBuilder.createDefaultGround(this.world);
+        
+        // Create materials with different brightness levels
+        const materials = [
+            new THREE.MeshStandardMaterial({ color: 0x808080 }), // Mid-gray
+            new THREE.MeshStandardMaterial({ color: 0xffffff }), // White
+            new THREE.MeshStandardMaterial({ 
+                color: 0x000000, 
+                emissive: 0xff0000, 
+                emissiveIntensity: 2 
+            }), // Bright red emissive
+            new THREE.MeshStandardMaterial({ 
+                color: 0x000000, 
+                emissive: 0x00ff00, 
+                emissiveIntensity: 5 
+            }), // Very bright green emissive
+        ];
+        
+        // Create spheres with different materials
+        materials.forEach((material, index) => {
+            const sphere = new ENGINE.Actor({
+                position: new THREE.Vector3(index * 3 - 4.5, 2, 0),
+                rootComponent: new ENGINE.MeshComponent({
+                    geometry: new THREE.SphereGeometry(1, 32, 16),
+                    material: material
+                })
+            });
+            this.world.addActors(sphere);
+        });
+        
+        // Add a very bright directional light
+        const brightSun = new ENGINE.Actor({
+            position: new THREE.Vector3(10, 20, 10),
+            sceneComponents: [
+                new ENGINE.DirectionalLightComponent({
+                    color: 0xffffff,
+                    intensity: 3, // Bright sunlight
+                    castShadow: true
+                })
+            ]
+        });
+        this.world.addActors(brightSun);
+    }
+    
+    private setupToneMappingControls(): void {
+        const renderer = this.world.getRenderer().renderer;
+        
+        window.addEventListener('keydown', (event) => {
+            if (event.key === 'Tab') {
+                event.preventDefault();
+                
+                // Cycle through tone mapping modes
+                this.currentModeIndex = (this.currentModeIndex + 1) % this.toneMappingModes.length;
+                const currentMode = this.toneMappingModes[this.currentModeIndex];
+                
+                renderer.toneMapping = currentMode.value;
+                console.log(`Tone Mapping: ${currentMode.name}`);
+            }
+        });
+        
+        console.log('Press Tab to cycle through tone mapping modes');
+        console.log('Current mode:', this.toneMappingModes[this.currentModeIndex].name);
+    }
+}
+```
+
+### Accessing the Renderer
+
+To modify tone mapping settings in your game, you need to access the renderer through the world:
+
+```typescript
+import * as ENGINE from 'genesys.js';
+
+class MyGame extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Get the renderer from the world
+        const renderer = this.world.getRenderer().renderer;
+        
+        // Modify tone mapping settings
+        renderer.toneMapping = THREE.ACESFilmicToneMapping;
+        renderer.toneMappingExposure = 1.5;
+        
+        // Set up your scene...
+        ENGINE.GameBuilder.createDefaultSkybox(this.world);
+        ENGINE.GameBuilder.createDefaultLighting(this.world);
+    }
+}
+```
+
+### Best Practices
+
+**Choosing a Tone Mapping Algorithm:**
+- **ReinhardToneMapping** (default): Good general-purpose choice, natural-looking
+- **ACESFilmicToneMapping**: Industry standard for cinematic/realistic games
+- **AgXToneMapping**: Modern alternative with good color reproduction
+- **NeutralToneMapping**: Minimal color shifts, good for stylized games
+- **CineonToneMapping**: Higher contrast, film-like appearance
+- **LinearToneMapping**: Simple scaling, may wash out highlights
+- **NoToneMapping**: Only use with low dynamic range lighting
+
+**Setting Exposure:**
+- Start with `1.0` and adjust based on your scene's brightness
+- Lower values (0.5-0.8) for very bright scenes or sunny outdoor environments
+- Higher values (1.5-3.0) for darker scenes or indoor environments
+- Use exposure to balance HDR skyboxes with your scene lighting
+
+**Performance Considerations:**
+- Tone mapping has minimal performance impact
+- Changing tone mapping algorithms may trigger shader recompilation
+- Set tone mapping once during initialization rather than changing frequently
+
+### Dynamic Tone Mapping
+
+You can create adaptive exposure systems that respond to gameplay:
+
+```typescript
+import * as ENGINE from 'genesys.js';
+
+class AdaptiveExposureGame extends ENGINE.BaseGameLoop {
+    private targetExposure = 1.0;
+    private currentExposure = 1.0;
+    private exposureSpeed = 2.0; // Adaptation speed
+    
+    protected override preStart(): void {
+        ENGINE.GameBuilder.createDefaultSkybox(this.world);
+        this.setupAdaptiveExposure();
+    }
+    
+    protected override tick(deltaTime: number): void {
+        // Smoothly interpolate exposure towards target
+        const exposureDiff = this.targetExposure - this.currentExposure;
+        this.currentExposure += exposureDiff * this.exposureSpeed * deltaTime;
+        
+        const renderer = this.world.getRenderer().renderer;
+        renderer.toneMappingExposure = this.currentExposure;
+    }
+    
+    private setupAdaptiveExposure(): void {
+        // Simulate entering different lighting conditions
+        window.addEventListener('keydown', (event) => {
+            switch (event.key) {
+                case 'b': // Bright outdoor
+                    this.targetExposure = 0.6;
+                    break;
+                case 'n': // Normal indoor
+                    this.targetExposure = 1.0;
+                    break;
+                case 'd': // Dark cave
+                    this.targetExposure = 2.5;
+                    break;
+            }
+        });
+    }
+}
+```
+
+This tone mapping system allows you to fine-tune the visual appearance of your game, ensuring that HDR lighting and bright environments are displayed correctly while maintaining visual detail and artistic intent.
+
+## Source Code
+Below are relevant engine source code you MUST digest in order to get complete understanding of the topic. Read them carefully.
+
+```
+<file path={src/render/Renderer.ts}>
+<file path={src/actors/Actor.ts}>
+<file path={src/components/SceneComponent.ts}>
+<file path={src/components/visual/MeshComponent.ts}>
+<file path={src/components/visual/GLTFMeshComponent.ts}>
+<file path={src/components/visual/SkyboxComponent.ts}>
+<file path={src/components/visual/TerrainMeshComponent.ts}>
+<file path={src/render/Texture.ts}>
+<file path={src/game/GameBuilder.ts}>
+```