@directivegames/genesys.js 3.1.24

package/docs/guides/18-lightmapping-system.md

@@ -0,0 +1,984 @@
+# Lightmapping System
+
+The Genesys.js lightmapping system provides powerful tools for pre-baking lighting into textures, enabling high-quality lighting with optimal runtime performance. This system is designed for authoring-time use, where users explicitly specify file paths for saving and loading lightmaps.
+
+## Overview
+
+Lightmapping works by:
+1. **Identifying static meshes** based on physics motion type
+2. **Baking lighting calculations** into texture atlases during development
+3. **Applying baked textures** to meshes at runtime for zero-cost lighting
+4. **Managing static vs dynamic lights** to balance quality and performance
+5. **Exporting/importing lightmap data** for persistence across sessions
+
+## Mesh Inclusion and Static vs Dynamic Classification
+
+The lightmapping system automatically determines which meshes to include based on their physics configuration:
+
+### Static Mesh Classification
+- **Included in lightmapping**: Meshes with `PhysicsMotionType.Static` (default for most mesh components)
+- **Excluded from lightmapping**: Meshes with `PhysicsMotionType.Dynamic`, `PhysicsMotionType.KinematicVelocityBased`, or `PhysicsMotionType.KinematicPositionBased`
+
+### Controlling Mesh Inclusion
+
+```typescript
+import * as ENGINE from 'genesys.js';
+
+// Static mesh - will be included in lightmapping
+const staticWall = new ENGINE.MeshComponent({
+  geometry: new THREE.BoxGeometry(10, 5, 1),
+  material: new THREE.MeshStandardMaterial(),
+  physicsOptions: {
+    enabled: true,
+    motionType: ENGINE.PhysicsMotionType.Static // Default - included in lightmaps
+  }
+});
+
+// Dynamic mesh - will be excluded from lightmapping
+const movingPlatform = new ENGINE.MeshComponent({
+  geometry: new THREE.BoxGeometry(4, 0.5, 4),
+  material: new THREE.MeshStandardMaterial(),
+  physicsOptions: {
+    enabled: true,
+    motionType: ENGINE.PhysicsMotionType.Dynamic // Excluded from lightmaps
+  }
+});
+
+// For GLTFMeshActors, the physics options are set on the root component
+const staticProp = new ENGINE.GLTFMeshActor({
+  modelUrl: '@engine/assets/models/statue.glb',
+  physicsOptions: {
+    enabled: true,
+    motionType: ENGINE.PhysicsMotionType.Static // Included in lightmaps
+  }
+});
+
+const movingVehicle = new ENGINE.GLTFMeshActor({
+  modelUrl: '@engine/assets/models/car.glb',
+  physicsOptions: {
+    enabled: true,
+    motionType: ENGINE.PhysicsMotionType.Dynamic // Excluded from lightmaps
+  }
+});
+```
+
+### Best Practices for Mesh Classification
+
+**Use Static (lightmapped) for:**
+- Architecture (walls, floors, ceilings)
+- Environmental props (rocks, trees, decorations)
+- Performance-critical scenarios where lighting doesn't change
+- Large-scale scenes with many static elements
+
+**Use Dynamic (excluded) for:**
+- Moving objects (vehicles, elevators, doors)
+- Player-controlled objects
+- Anything that changes position during gameplay
+- Objects that need real-time lighting responses
+
+## Core Components
+
+### LightmapManager
+The main interface for lightmap operations. The lightmap manager is now a core engine system that's automatically created and initialized alongside physics and navigation:
+
+```typescript
+import * as ENGINE from 'genesys.js';
+
+export class MyGameLoop extends ENGINE.BaseGameLoop {
+  private lightmapManager!: ENGINE.LightmapManager;
+
+  protected override async postStart(): Promise<void> {
+    // Get the lightmap manager from the world (automatically created by the engine)
+    this.lightmapManager = this.world.getLightmapManager();
+    
+    // The manager is ready to use - no manual initialization required
+    if (this.lightmapManager) {
+      console.log('Lightmap manager is available');
+    }
+  }
+}
+```
+
+### LightmapBaker
+Handles the actual lightmap baking process with support for:
+- **Multi-light baking**: Efficient handling of multiple light sources
+- **Progressive sampling**: Improved quality through sample accumulation
+- **Atlas generation**: Automatic UV packing and texture creation
+- **Debug visualizations**: Position, normal, and UV coordinate textures
+
+### LightmapSerializer
+Pure data transformation system with no file operations:
+- **Data-only export**: Converts lightmap data to serializable format without file I/O
+- **High-precision binary textures**: Preserves lighting quality in binary format
+- **Mesh mapping tracking**: Maintains actor-to-UV relationships
+- **Import validation**: Schema validation and data integrity checks
+- **Platform agnostic**: Works in browser, Node.js, Electron, or any JavaScript environment
+
+## Clean Architecture
+
+The lightmapping system follows clean architecture principles with clear separation of concerns:
+
+### Core Layer (LightmapManager & LightmapSerializer)
+- **Pure business logic**: No file I/O or platform-specific operations
+- **Data transformation**: Converts lightmap data to/from serializable formats
+- **Platform agnostic**: Works in any JavaScript environment
+- **Testable**: Can be unit tested without DOM or file system dependencies
+
+### Application Layer (Your Code)
+- **File operations**: Decides how to handle exported lightmap data
+- **UI interactions**: Progress updates, user controls, error handling
+- **Platform-specific logic**: Browser downloads, Node.js file system, cloud storage
+- **Integration**: Connects core lightmap functionality with your application needs
+
+### Benefits
+- **Flexibility**: Use the same core system across web, desktop, and server environments
+- **Maintainability**: Clear boundaries between lightmap logic and file operations
+- **Testability**: Core lightmap features can be tested independently
+- **Reusability**: Different applications can handle file operations differently
+- **Extensibility**: Easy to add new export destinations (cloud storage, databases, etc.)
+
+## Basic Usage
+
+### 1. Accessing the Lightmap Manager
+
+```typescript
+import * as ENGINE from 'genesys.js';
+
+export class LightmappingDemo extends ENGINE.BaseGameLoop {
+  private lightmapManager!: ENGINE.LightmapManager;
+
+  protected override async postStart(): Promise<void> {
+    // Get the automatically created lightmap manager
+    this.lightmapManager = this.world.getLightmapManager();
+    
+    // The manager is pre-configured with sensible defaults and ready to use
+    if (this.lightmapManager) {
+      console.log('Lightmap manager is ready');
+      
+      // Optional: Check if lightmaps were automatically loaded
+      if (this.lightmapManager.hasLightmapData()) {
+        console.log('Lightmaps were automatically loaded with the scene');
+      }
+    }
+  }
+}
+```
+
+### 2. Baking Lightmaps
+
+```typescript
+// Bake lightmaps with current settings
+private async bakeLightmaps(): Promise<void> {
+  try {
+    // Optional: Override specific settings for this bake
+    await this.lightmapManager.bakeLightmaps({
+      resolution: 2048,           // Higher resolution for final bake
+      casts: 128,                 // More ray casts for quality
+      progressiveSamples: 256,    // More samples for better quality
+      directLightEnabled: true,
+      indirectLightEnabled: false,
+      ambientLightEnabled: true,
+      ambientDistance: 15.0
+    });
+
+    console.log('✓ Lightmaps baked successfully!');
+  } catch (error) {
+    console.error('Failed to bake lightmaps:', error);
+  }
+}
+```
+
+### 3. Exporting Lightmaps
+
+The lightmapping system uses a clean architecture where the `LightmapManager` provides pure data export functionality, and file operations are handled by the application layer.
+
+#### Core Export Method (Pure Data)
+
+The `LightmapManager` only provides data export - no file operations:
+
+```typescript
+// Get lightmap data for custom handling
+private async exportLightmapData(): Promise<void> {
+  try {
+    if (!this.lightmapManager.hasLightmapData()) {
+      console.log('No lightmap data to export. Bake lightmaps first.');
+      return;
+    }
+
+    // Get pure lightmap data from the manager
+    const result = await this.lightmapManager.exportLightmapData('my-scene', {
+      includeSceneHash: true
+    });
+
+    // The manager returns data that you can handle as needed:
+    // - result.metadataJson: JSON string with lightmap metadata
+    // - result.textureBlob: Binary texture data as Blob
+    // - result.metadataFileName: Suggested filename for metadata
+    // - result.textureFileName: Suggested filename for texture
+
+    // Now you choose how to handle the data...
+  } catch (error) {
+    console.error('Export failed:', error);
+  }
+}
+```
+
+#### Application-Level File Operations
+
+Your application decides how to handle the exported data:
+
+##### Option 1: Download Files to User's Computer
+
+```typescript
+// Download files directly to user's computer
+private downloadLightmapFiles(result: LightmapDataExportResult): void {
+  // Download texture file
+  this.downloadBlob(result.textureBlob, result.textureFileName);
+  
+  // Download metadata file
+  const metadataBlob = new Blob([result.metadataJson], { type: 'application/json' });
+  this.downloadBlob(metadataBlob, result.metadataFileName);
+}
+
+private downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.style.display = 'none';
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}
+```
+
+##### Option 2: Save to Browser Storage
+
+```typescript
+// Save to IndexedDB for offline use
+private async saveToIndexedDB(result: LightmapDataExportResult): Promise<void> {
+  const request = indexedDB.open('LightmapStorage', 1);
+  
+  request.onsuccess = () => {
+    const db = request.result;
+    const transaction = db.transaction(['lightmaps'], 'readwrite');
+    const store = transaction.objectStore('lightmaps');
+    
+    store.add({
+      id: Date.now(),
+      metadata: result.metadataJson,
+      texture: result.textureBlob,
+      timestamp: new Date().toISOString()
+    });
+  };
+}
+```
+
+##### Option 3: Send to Server
+
+```typescript
+// Upload to server
+private async uploadToServer(result: LightmapDataExportResult): Promise<void> {
+  const formData = new FormData();
+  formData.append('metadata', result.metadataJson);
+  formData.append('texture', result.textureBlob, result.textureFileName);
+  
+  await fetch('/api/lightmaps', { 
+    method: 'POST', 
+    body: formData 
+  });
+}
+```
+
+##### Option 4: Save to File System (Node.js/Electron)
+
+```typescript
+// Save to file system in Node.js or Electron
+private async saveToFileSystem(result: LightmapDataExportResult): Promise<void> {
+  const fs = await import('fs').promises;
+  
+  // Save metadata
+  await fs.writeFile(result.metadataFileName, result.metadataJson);
+  
+  // Save texture
+  const textureBuffer = await result.textureBlob.arrayBuffer();
+  await fs.writeFile(result.textureFileName, new Uint8Array(textureBuffer));
+}
+```
+
+### 4. Importing Lightmaps
+
+```typescript
+// Import lightmaps from files
+private async importLightmaps(metadataFile: File, textureFile: File): Promise<void> {
+  try {
+    // Read file data
+    const lightmapText = await metadataFile.text();
+    const lightmapData = JSON.parse(lightmapText);
+    const textureData = await textureFile.arrayBuffer();
+
+    // Import and apply lightmaps
+    const result = await this.lightmapManager.importLightmap(
+      lightmapData,
+      new Uint8Array(textureData)
+    );
+
+    console.log('✓ Lightmaps imported and applied!');
+    console.log(`Baking options:`, result.bakingOptions);
+    console.log(`Mesh mappings:`, result.meshMappings.size);
+  } catch (error) {
+    console.error('Import failed:', error);
+  }
+}
+```
+
+## Scene Resource Configuration
+
+For automatic lightmap loading, you can configure explicit file paths in your scene files using the `SceneResources` system:
+
+### Setting Up Scene Resources
+
+```typescript
+// Configure lightmap resources programmatically
+world.setLightmapResources(
+  '@project/assets/lighting/indoor-scene.lightmap.json',
+  '@project/assets/lighting/indoor-scene.lightmap.bin'
+);
+
+// Configure NavMesh resources as well
+world.setNavMeshResource('@project/assets/navigation/indoor-nav.navmesh');
+```
+
+### Scene File Format
+
+Scene files support a `resources` section for explicit asset references:
+
+```json
+{
+  "class": "ENGINE.World",
+  "actors": [...],
+  "resources": {
+    "lightmap": {
+      "metadataPath": "@project/assets/lighting/level1-baked.lightmap.json",
+      "texturePath": "@project/assets/lighting/level1-baked.lightmap.bin"
+    },
+    "navMesh": {
+      "path": "@project/assets/navigation/level1.navmesh"
+    }
+  }
+}
+```
+
+### Automatic Loading
+
+When scene resources are configured, the engine automatically loads lightmaps during scene loading:
+
+```typescript
+// When loading a scene with configured lightmap resources
+await this.loadWorldDataFromPath(scenePath);
+
+// Engine automatically:
+// 1. Loads the scene data and actors
+// 2. Checks for lightmap resources in scene metadata
+// 3. If found, loads and applies lightmaps automatically
+// 4. Falls back to dynamic lighting if resources not found
+```
+
+### Benefits of Scene Resources
+
+- **Flexible Organization**: Place lightmap files anywhere in your project structure
+- **Version Management**: Use descriptive names for different lightmap versions
+- **Quality Variations**: Configure different lightmap resolutions for different platforms
+- **Tool Integration**: External editors can easily configure lightmap file references
+
+## Static vs Dynamic Lights
+
+The lightmapping system distinguishes between lights that are baked into textures and those that remain active at runtime.
+
+### Light Configuration
+
+```typescript
+// Lightmap-baked light - baked into lightmaps, hidden at runtime
+const sunLight = new ENGINE.DirectionalLightComponent({
+  color: 0xffffff,
+  intensity: 1.5,
+  bakeLightmaps: true    // Default - baked into lightmaps
+});
+
+// Runtime light - excluded from baking, 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);      // Baked into lightmaps
+flashlight.setLightmapBaked(false);   // Runtime only
+
+// Check light type
+if (light.isLightmapBaked()) {
+  console.log('This light will be baked into lightmaps');
+}
+```
+
+### Automatic Light Management
+
+The system automatically manages lights during the lightmapping process:
+
+1. **During Baking**: Only `bakeLightmaps: true` lights contribute to lightmaps
+2. **After Baking**: Static lights are hidden (their contribution is in the texture)
+3. **Dynamic Lights**: Always remain visible for real-time effects
+4. **When Removing Lightmaps**: All lights are restored to visible state
+
+### Best Practices for Light Types
+
+**Use Static Lights (baked) for:**
+- Environmental lighting (sun, ambient, architectural lights)
+- Performance-critical scenarios (mobile, VR)
+- Large-scale lighting that affects the entire scene
+- Lighting that doesn't change during gameplay
+
+**Use Dynamic Lights (runtime) for:**
+- Player-controlled lights (flashlights, spells)
+- Moving objects (vehicle headlights, character effects)
+- Interactive elements that respond to gameplay
+- Temporary effects (explosions, power-ups)
+
+## Advanced Features
+
+### Progressive Baking with Progress Callbacks
+
+```typescript
+await this.lightmapManager.bakeLightmaps(
+  {
+    resolution: 1024,
+    casts: 64,
+    progressiveSamples: 256
+  },
+  // Progress callback
+  (stage: string, progress: number, message?: string) => {
+    console.log(`[${stage}] ${progress.toFixed(1)}% - ${message || ''}`);
+    // Update UI progress bar here
+  }
+);
+```
+
+### Mesh Mapping Information
+
+```typescript
+// After importing, examine which meshes use which UV regions
+const result = await this.lightmapManager.importLightmap(lightmapData, textureData);
+
+for (const [key, mapping] of result.meshMappings) {
+  console.log(`Mesh ${key}:`);
+  console.log(`  Actor UUID: ${mapping.actorUuid}`);
+  console.log(`  Mesh Index: ${mapping.meshIndex}`);
+  console.log(`  UV Bounds: [${mapping.uvBounds.min.x}, ${mapping.uvBounds.min.y}] to [${mapping.uvBounds.max.x}, ${mapping.uvBounds.max.y}]`);
+}
+```
+
+### Manual Light Management
+
+```typescript
+// Get light categorization
+const { staticLights, dynamicLights } = this.lightmapManager.getLightsByType();
+
+console.log(`Static lights: ${staticLights.length}`);
+console.log(`Dynamic lights: ${dynamicLights.length}`);
+
+// Manual control over runtime lighting (usually automatic)
+this.lightmapManager.manageRuntimeLighting(true);  // Hide static lights
+this.lightmapManager.manageRuntimeLighting(false); // Show all lights
+```
+
+### Removing Applied Lightmaps
+
+```typescript
+// Remove lightmaps and restore original lighting
+this.lightmapManager.removeLightmaps();
+console.log('Lightmaps removed, dynamic lighting restored');
+```
+
+## File Structure and Serialization
+
+The lightmapping system uses a two-file approach to store lightmap data with maximum quality and precision:
+
+```
+my-scene.lightmap      # JSON metadata with baking options and mesh mappings
+my-scene.lightmap.bin  # High-precision binary texture data (Float32Array)
+```
+
+### Serialization Process
+
+The serialization system is designed to preserve complete lightmap fidelity and enable exact reconstruction:
+
+#### 1. Texture Data Serialization
+
+The lightmap texture is stored as high-precision binary data to avoid quality loss from image compression:
+
+```typescript
+// During export, the system:
+// 1. Reads pixels directly from the WebGL render target as Float32Array
+const pixelBuffer = new Float32Array(width * height * 4); // RGBA channels
+renderer.readRenderTargetPixels(renderTarget, 0, 0, width, height, pixelBuffer);
+
+// 2. Creates a binary blob from the raw float data
+const textureBlob = new Blob([pixelBuffer.buffer], { type: 'application/octet-stream' });
+
+// 3. Downloads as .lightmap.bin file
+```
+
+This approach preserves:
+- **Full precision**: No compression artifacts or color space conversions
+- **HDR values**: Lighting values can exceed the 0-1 range for realistic lighting
+- **Exact reconstruction**: Imported textures are bit-for-bit identical to exported ones
+
+#### 2. Metadata Serialization
+
+The JSON metadata file contains all information needed to reconstruct the lightmap:
+
+```typescript
+interface SerializedLightmap {
+  version: string;                    // File format version
+  metadata: {
+    exportDate: string;              // ISO timestamp
+    sceneHash?: string;              // Optional scene validation hash
+    bakingOptions: {                 // Complete baking parameters
+      resolution: number;
+      casts: number;
+      progressiveSamples: number;
+      lightSize: number;
+      lightPosition: [number, number, number];
+      directLightEnabled: boolean;
+      indirectLightEnabled: boolean;
+      ambientLightEnabled: boolean;
+      ambientDistance: number;
+    };
+  };
+  lightmap: {
+    textureFile: string;             // Reference to .bin file
+    width: number;                   // Texture dimensions
+    height: number;
+    format: 'float32';               // Data type
+    filterMode: number;              // THREE.js filter mode enum
+  };
+  meshMappings: Record<string, MeshMapping>;  // Actor-to-UV mappings
+  uv2Data: Record<string, MeshUV2Data[]>;     // UV2 coordinates for exact alignment
+}
+```
+
+#### 3. Mesh Mapping Serialization
+
+Each mesh's relationship to the lightmap atlas is preserved:
+
+```typescript
+interface MeshMapping {
+  actorUuid: string;      // Unique actor identifier
+  meshIndex: number;      // Which mesh within the actor
+  uvBounds: {
+    min: [number, number];  // UV atlas region bounds
+    max: [number, number];
+  };
+}
+```
+
+This enables:
+- **Actor tracking**: Which objects use which parts of the lightmap
+- **Multi-mesh support**: Actors with multiple meshes are handled correctly
+- **Atlas reconstruction**: Exact UV regions for each mesh
+
+#### 4. UV2 Data Preservation
+
+For perfect lightmap alignment, UV2 coordinates are also stored:
+
+```typescript
+interface MeshUV2Data {
+  meshIndex: number;
+  vertexCount: number;
+  uv2Coordinates: number[];  // Flattened [u1, v1, u2, v2, ...] array
+  geometryAttributes?: {     // For validation
+    positionCount: number;
+    normalCount: number;
+    hasUv: boolean;
+  };
+}
+```
+
+### Deserialization Process
+
+During import, the system reconstructs the lightmap with full fidelity:
+
+#### 1. Texture Reconstruction
+
+```typescript
+// 1. Validate binary data size
+const expectedSize = width * height * 4; // RGBA Float32
+if (float32Array.length !== expectedSize) {
+  throw new Error('Binary texture size mismatch');
+}
+
+// 2. Create DataTexture with exact original data
+const dataTexture = new THREE.DataTexture(
+  float32Array,          // Original Float32Array data
+  width, height,         // Original dimensions
+  THREE.RGBAFormat,      // RGBA channels
+  THREE.FloatType        // High-precision floats
+);
+
+// 3. Restore filtering and settings
+dataTexture.magFilter = originalFilterMode;
+dataTexture.minFilter = originalFilterMode;
+dataTexture.generateMipmaps = shouldGenerateMipmaps;
+dataTexture.flipY = false; // Consistent orientation
+```
+
+#### 2. Validation and Error Handling
+
+The system includes comprehensive validation:
+
+```typescript
+// Schema validation using Zod
+const lightmapSchema = z.object({
+  version: z.string(),
+  metadata: z.object({ /* ... */ }),
+  lightmap: z.object({ /* ... */ }),
+  meshMappings: z.record(z.string(), /* ... */),
+  uv2Data: z.record(z.string(), /* ... */)
+}).strict();
+
+// Runtime validation
+export function validateLightmapData(data: any): SerializedLightmap {
+  const result = lightmapSchema.safeParse(data);
+  if (!result.success) {
+    throw new Error(`Invalid lightmap data: ${result.error.message}`);
+  }
+  return result.data;
+}
+```
+
+### File Format Advantages
+
+This serialization approach provides several benefits:
+
+**High Precision**: Binary Float32 storage preserves exact lighting calculations without compression artifacts.
+
+**Complete Reconstruction**: All necessary data is stored to perfectly recreate the lightmap state.
+
+**Validation**: Schema validation and size checks prevent corruption issues.
+
+**Version Management**: File format versioning enables future compatibility handling.
+
+**Performance**: Binary texture data loads efficiently and integrates directly with Three.js.
+
+**Debugging**: Human-readable JSON metadata aids in troubleshooting and analysis.
+
+### Metadata Format
+
+```json
+{
+  "version": "1.0.0",
+  "metadata": {
+    "exportDate": "2025-01-21T12:00:00.000Z",
+    "sceneHash": "a1b2c3d4",
+    "bakingOptions": {
+      "resolution": 1024,
+      "casts": 64,
+      "progressiveSamples": 128,
+      "directLightEnabled": true,
+      "indirectLightEnabled": false,
+      "ambientLightEnabled": true,
+      "ambientDistance": 10.0
+    }
+  },
+  "lightmap": {
+    "textureFile": "my-scene.lightmap.bin",
+    "width": 1024,
+    "height": 1024,
+    "format": "float32",
+    "filterMode": 1006
+  },
+  "meshMappings": {
+    "actor1_0": {
+      "actorUuid": "abc123",
+      "meshIndex": 0,
+      "uvBounds": {
+        "min": [0.0, 0.0],
+        "max": [0.5, 0.5]
+      }
+    }
+  }
+}
+```
+
+## Integration Patterns
+
+### Development Workflow
+
+```typescript
+export class MyGameLoop extends ENGINE.BaseGameLoop {
+  protected override async postStart(): Promise<void> {
+    // Get the automatic lightmap manager
+    const lightmapManager = this.world.getLightmapManager();
+    
+    // 1. Set up scene with mixed lighting
+    const ambientLight = new ENGINE.AmbientLightComponent({
+      bakeLightmaps: true  // Bake ambient lighting
+    });
+
+    const playerFlashlight = new ENGINE.SpotLightComponent({
+      bakeLightmaps: false // Keep dynamic for gameplay
+    });
+
+    // 2. Bake during development
+    await lightmapManager.bakeLightmaps({
+      resolution: 1024,
+      casts: 64,
+      directLightEnabled: true,
+      ambientLightEnabled: true
+    });
+
+    // 3. Export lightmap data (application handles file operations)
+    const lightmapData = await lightmapManager.exportLightmapData('level-1');
+    
+    // Your application decides how to handle the data:
+    if (isProductionBuild) {
+      await this.uploadToServer(lightmapData);
+    } else {
+      this.downloadLightmapFiles(lightmapData);
+    }
+
+    // 4. In production builds, lightmaps are loaded automatically when scenes are loaded
+    // No manual import required - just ensure lightmap files are available
+  }
+
+  private downloadLightmapFiles(data: LightmapDataExportResult): void {
+    // Download texture file
+    this.downloadBlob(data.textureBlob, data.textureFileName);
+    
+    // Download metadata file
+    const metadataBlob = new Blob([data.metadataJson], { type: 'application/json' });
+    this.downloadBlob(metadataBlob, data.metadataFileName);
+  }
+
+  private async uploadToServer(data: LightmapDataExportResult): Promise<void> {
+    const formData = new FormData();
+    formData.append('metadata', data.metadataJson);
+    formData.append('texture', data.textureBlob);
+    await fetch('/api/lightmaps', { method: 'POST', body: formData });
+  }
+}
+```
+
+### Platform-Specific Implementations
+
+#### Browser Environment
+```typescript
+// Download files to user's computer
+private downloadLightmapFiles(data: LightmapDataExportResult): void {
+  const url = URL.createObjectURL(data.textureBlob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = data.textureFileName;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+```
+
+#### Node.js/Electron Environment
+```typescript
+// Save to file system
+private async saveToFileSystem(data: LightmapDataExportResult): Promise<void> {
+  const fs = await import('fs').promises;
+  await fs.writeFile(data.metadataFileName, data.metadataJson);
+  
+  const buffer = await data.textureBlob.arrayBuffer();
+  await fs.writeFile(data.textureFileName, new Uint8Array(buffer));
+}
+```
+
+#### Cloud Storage Integration
+```typescript
+// Upload to cloud storage (AWS S3, Google Cloud, etc.)
+private async uploadToCloud(data: LightmapDataExportResult): Promise<void> {
+  const bucket = getCloudStorageBucket();
+  
+  await bucket.upload(data.metadataFileName, data.metadataJson);
+  await bucket.upload(data.textureFileName, data.textureBlob);
+}
+```
+
+### Error Handling
+
+```typescript
+try {
+  await this.lightmapManager.importLightmap(lightmapData, textureData);
+} catch (error) {
+  if (error.message.includes('Invalid lightmap data')) {
+    console.log('Lightmap file corrupted, using dynamic lighting');
+  } else if (error.message.includes('version mismatch')) {
+    console.log('Lightmap was created with different engine version');
+  } else {
+    console.error('Failed to load lightmaps:', error);
+  }
+  // Fallback to dynamic lighting
+}
+```
+
+### Performance Considerations
+
+- **Texture Resolution**: Higher resolution = better quality but larger files and longer bake times
+- **Ray Casts**: More casts = better shadow quality but slower baking
+- **Progressive Samples**: Higher values improve quality through noise reduction
+- **File Sizes**: Lightmaps are typically 1-10MB depending on resolution and scene complexity
+- **Runtime Performance**: Zero cost after application - lighting is "frozen" in textures
+
+## Debugging and Visualization
+
+### Render Modes for Development
+
+The lightmapping system supports multiple visualization modes for debugging:
+
+```typescript
+// During development, you can visualize intermediate textures
+enum RenderMode {
+  Standard = 'standard',    // Normal scene rendering
+  Positions = 'positions',  // World position atlas
+  Normals = 'normals',      // World normal atlas  
+  UV = 'uv',               // UV coordinate debug
+  Lightmap = 'lightmap',   // Lightmap only
+  Beauty = 'beauty'        // Lightmap + original textures
+}
+
+// Apply render mode to scene materials
+private applyRenderMode(mode: RenderMode): void {
+  // Implementation varies based on your debug needs
+  // See lightmapping-demo.ts for complete example
+}
+```
+
+### Common Issues and Solutions
+
+**Poor lightmap quality:**
+- Increase `resolution` (1024, 2048, or higher)
+- Increase `casts` for better shadow quality
+- Increase `progressiveSamples` to reduce noise
+- Ensure meshes have proper UV2 coordinates
+
+**Lightmaps not applying:**
+- Check that meshes have UV2 coordinates
+- Verify `autoApply: true` in manager options
+- Ensure lightmap data was successfully baked
+
+**Seams or artifacts:**
+- Increase `padding` in atlas options
+- Enable `dilate: true` to extend lightmap edges
+- Check UV unwrapping quality in your 3D modeling software
+
+**Files not exporting:**
+- Ensure you have baked lightmaps first (`hasLightmapData()`)
+- Check browser download permissions
+- Verify filename doesn't contain invalid characters
+
+## Automatic Level Loading Integration
+
+The lightmapping system is now a core engine system that automatically integrates with the level loading process. The lightmap manager is created automatically alongside other core systems like physics and navigation.
+
+### Automatic Lightmap Loading
+
+When a scene is loaded using `loadWorldDataFromPath()`, the engine automatically:
+1. Creates a lightmap manager as a core system (like physics)
+2. Loads the scene and waits for all models to be fully loaded
+3. Looks for corresponding lightmap files in the same directory as the scene
+4. Automatically loads and applies lightmaps to the fully loaded meshes
+
+```typescript
+export class MyGameLoop extends ENGINE.BaseGameLoop {
+  protected override async postStart(): Promise<void> {
+    // The lightmap manager is created automatically by the engine
+    // No manual initialization required!
+    
+    // Optional: Access the lightmap manager if needed
+    const lightmapManager = this.world.getLightmapManager();
+    if (lightmapManager) {
+      console.log('Lightmap manager is available');
+    }
+  }
+
+  // Optional: Check for lightmap status after loading scenes
+  private checkLightmapStatus(sceneName: string): void {
+    const lightmapManager = this.world.getLightmapManager();
+    if (lightmapManager && lightmapManager.hasLightmapData()) {
+      console.log(`✓ Lightmaps automatically loaded for: ${sceneName}`);
+    } else {
+      console.log(`Scene loaded without lightmaps: ${sceneName}`);
+    }
+  }
+}
+
+// That's it! Just load your scenes normally:
+await gameLoop.loadWorldDataFromPath(ENGINE.AssetPath.fromString('@engine/assets/scenes/level1.genesys-scene'));
+// Lightmaps are automatically detected and applied if present
+```
+
+### File Detection Logic
+
+The auto-loading system uses a simple naming convention:
+
+```
+/assets/scenes/level1.genesys-scene    # Scene file
+/assets/scenes/level1.lightmap         # Lightmap metadata
+/assets/scenes/level1.lightmap.bin     # Lightmap texture data
+```
+
+When `level1.genesys-scene` is loaded, the engine automatically:
+1. Looks for `level1.lightmap` and `level1.lightmap.bin` in the same directory
+2. Loads both files using the storage provider (if they exist)
+3. Applies the lightmap data to the scene automatically
+4. Manages static/dynamic lighting and material updates
+
+### Production Workflow
+
+This integration enables a seamless production workflow:
+
+**During Development:**
+1. Create and iterate on your scene
+2. Bake lightmaps using the lightmapping demo
+3. Export lightmaps to files alongside your scene
+4. Test the auto-loading by reloading the scene
+
+**In Production:**
+1. Distribute scene files with their corresponding lightmap files
+2. Scenes automatically load with optimized lighting
+3. No runtime lightmap baking required
+4. Consistent visual quality across all devices
+
+### Error Handling and Fallbacks
+
+The auto-loading system gracefully handles missing or corrupted lightmap files:
+
+```typescript
+// If lightmap files are missing or invalid:
+// - Scene loads normally with dynamic lighting
+// - Warning messages logged to console
+// - No errors or crashes occur
+// - Fallback to standard lighting behavior
+```
+
+## Demo
+
+See the demo file for a complete working example:
+
+**`games/lightmapping-demo.ts`** - The main lightmapping demo featuring:
+- Automatic lightmap manager integration with the engine
+- Scene file loading with automatic lightmap detection
+- Interactive parameter controls with Tweakpane
+- Real-time baking with progress reporting
+- Export/import workflow with file selection
+- Render mode switching for debugging
+- Error handling and status reporting
+- Mixed static/dynamic lighting setup
+- Both automatic (for file system scenes) and manual (for user uploads) lightmap loading
+
+This system provides professional-quality lightmapping capabilities while maintaining full control over the asset pipeline and seamless integration with the level loading process.