@directivegames/genesys.js 3.1.24

package/docs/guides/15-navigation-and-pathfinding.md

@@ -0,0 +1,818 @@
+## Instruction
+Use this doc to understand how navigation and pathfinding work in Genesys.js. Learn how to implement NavMesh-based pathfinding for ground-based NPCs, configure navigation parameters, and optimize pathfinding performance.
+
+# Navigation and Pathfinding in Genesys.js
+
+Navigation and pathfinding are fundamental systems for creating believable AI characters that can move intelligently through your game world. Genesys.js provides a powerful navigation system built on the high-performance [recast-navigation](https://github.com/recast-navigation/recast-navigation) library.
+
+This guide covers **ground-based navigation** using Navigation Meshes (NavMesh). For AI behavior and decision-making systems, see the **[AI and Behavior Trees Guide](6-ai-and-behavior-trees.md)**.
+
+---
+
+## 1. The Navigation Mesh (NavMesh)
+
+Before ground-based NPCs can navigate the world, they need a map of all the walkable areas. This map is called a **Navigation Mesh** (or NavMesh). It's a simplified 3D mesh that represents the surfaces an AI character can travel on.
+
+The `NavigationServer` is the global system responsible for building and querying this NavMesh. The engine uses the high-performance [recast-navigation](https://github.com/recast-navigation/recast-navigation) library to generate it.
+
+**Note**: Aerial NPCs using `AerialMovementComponent` do not require NavMesh and can move freely in 3D space. See the [AI and Behavior Trees Guide](6-ai-and-behavior-trees.md) for aerial movement patterns.
+
+### Basic NavMesh Generation
+
+You typically generate the NavMesh from your existing level geometry. It's best to use a simplified version of your visual mesh for performance.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class MyGame extends ENGINE.BaseGameLoop {
+    // Override the world configuration to enable the navigation server.
+    public override getWorldConfiguration(): ENGINE.WorldOptions {
+        return {
+            ...super.getWorldConfiguration(),
+            navigationOptions: {
+                engine: ENGINE.NavigationEngine.RecastNavigation,
+                // Set debug to true to see the generated NavMesh.
+                debug: true, 
+                // These parameters control the NavMesh generation.
+                // They define the size and capabilities of your AI agent.
+                options: {
+                    ...ENGINE.RecastNavigationServer.DEFAULT_OPTIONS,
+                    cs: 0.2, // Cell size
+                    ch: 0.2, // Cell height
+                    walkableSlopeAngle: 35,
+                    walkableHeight: 2, // Agent height
+                    walkableClimb: 0.5, // How high can they step up
+                    walkableRadius: 0.5, // Agent radius
+                }
+            }
+        };
+    }
+
+    protected override async postStart(): Promise<void> {
+        // This method is called after the world and its systems are initialized.
+
+        // Create the level geometry.
+        const ground = ENGINE.GameBuilder.createDefaultGround(this.world);
+
+        const obstacle = this.world.addBox({
+            position: new THREE.Vector3(0, 1.25, -10),
+            width: 10,
+            height: 2.5,
+            depth: 10
+        });
+
+        // Generate the NavMesh from the ground's mesh.
+        // It's crucial to do this AFTER all static level geometry has been added.
+        const navigationServer = this.world.getNavigationServer();
+        if (navigationServer) {
+            console.log("Generating Navigation Mesh...");
+            // We use the ground's mesh, but in a real game you might combine
+            // all static meshes into one for navmesh generation.
+            const groundMesh = ground.getComponent(ENGINE.MeshComponent)!.getMesh();
+            await navigationServer.createNavigationMesh(groundMesh);
+            console.log("Navigation Mesh generated successfully.");
+        }
+    }
+}
+```
+
+With `debug: true`, the engine will render the bright green NavMesh, allowing you to see exactly where your ground-based NPCs can walk.
+
+---
+
+## 2. Advanced NavMesh Generation
+
+The NavMesh generation system in Genesys.js provides extensive configuration options and multiple generation methods to suit different project needs. Understanding these options is crucial for creating optimal pathfinding in your game.
+
+### NavMesh Generation Methods
+
+Genesys.js offers several ways to generate navigation meshes:
+
+#### 1. Automatic Generation on Startup
+Set `generateOnStartUp: true` in your world configuration to automatically generate NavMesh from scene geometry:
+
+```typescript
+public override getWorldConfiguration(): ENGINE.WorldOptions {
+    return {
+        ...super.getWorldConfiguration(),
+        navigationOptions: {
+            engine: ENGINE.NavigationEngine.RecastNavigation,
+            debug: true,
+            generateOnStartUp: true, // Auto-generate NavMesh
+            options: ENGINE.RecastNavigationServer.DEFAULT_OPTIONS
+        }
+    };
+}
+```
+
+#### 2. Manual Generation from Single Mesh
+Generate NavMesh from a single mesh (typically a simplified ground mesh):
+
+```typescript
+const navigationServer = this.world.getNavigationServer();
+if (navigationServer) {
+    const groundMesh = ground.getComponent(ENGINE.MeshComponent)!.getMesh();
+    await navigationServer.createNavigationMesh(groundMesh);
+}
+```
+
+#### 3. Generation from Multiple Meshes
+Combine multiple meshes into a single NavMesh for complex scenes:
+
+```typescript
+const navigationServer = this.world.getNavigationServer();
+if (navigationServer) {
+    const meshes: THREE.Mesh[] = [
+        ground.getComponent(ENGINE.MeshComponent)!.getMesh(),
+        platform1.getComponent(ENGINE.MeshComponent)!.getMesh(),
+        platform2.getComponent(ENGINE.MeshComponent)!.getMesh()
+    ];
+    
+    await navigationServer.createNavigationMeshFromMeshes(meshes);
+}
+```
+
+#### 4. Automatic Scene-Based Generation
+Generate NavMesh from all GLTF actors with static physics motion type:
+
+```typescript
+// Create GLTF actors with static physics for your level geometry
+const levelGeometry = new ENGINE.GLTFMeshActor({
+    modelUrl: '@engine/assets/models/level.glb',
+    physicsOptions: {
+        enabled: true,
+        motionType: ENGINE.PhysicsMotionType.Static
+    }
+});
+
+// Generate NavMesh from all GLTF actors with Static motion type
+await this.world.createNavigationMeshFromScene();
+```
+
+### NavMesh Configuration Parameters
+
+The Recast Navigation system provides extensive configuration options. Here's a comprehensive breakdown:
+
+#### Core Parameters
+
+```typescript
+const navigationOptions = {
+    engine: ENGINE.NavigationEngine.RecastNavigation,
+    debug: true,
+    generateOnStartUp: true,
+    options: {
+        // Cell dimensions - smaller values = higher precision but slower generation
+        cs: 0.2,              // Cell size (XZ plane resolution)
+        ch: 0.2,              // Cell height (Y axis resolution)
+        
+        // Agent capabilities - define what your NPCs can do
+        walkableSlopeAngle: 35,    // Maximum slope angle in degrees
+        walkableHeight: 2.0,       // Minimum ceiling height for agent
+        walkableClimb: 0.5,        // Maximum step height agent can climb
+        walkableRadius: 0.5,       // Agent radius (affects corridor width)
+        
+        // Mesh generation quality
+        maxEdgeLen: 12,            // Maximum edge length in world units
+        maxSimplificationError: 1.3, // Edge simplification tolerance
+        
+        // Region processing
+        minRegionArea: 8,          // Minimum area for isolated regions
+        mergeRegionArea: 20,       // Merge regions smaller than this
+        
+        // Polygon generation
+        maxVertsPerPoly: 6,        // Maximum vertices per polygon
+        
+        // Detail mesh (for height sampling)
+        detailSampleDist: 6,       // Detail mesh sample distance
+        detailSampleMaxError: 1,   // Maximum detail mesh error
+        
+        // Border handling
+        borderSize: 0              // Border size around the mesh
+    }
+};
+```
+
+#### Parameter Guidelines by Scene Type
+
+**Small Indoor Scenes:**
+```typescript
+options: {
+    cs: 0.1,                    // High precision for tight spaces
+    ch: 0.1,
+    walkableRadius: 0.3,        // Smaller agent for doorways
+    walkableHeight: 2.0,
+    walkableClimb: 0.2,         // Low steps only
+    walkableSlopeAngle: 25,     // Gentle slopes only
+    maxEdgeLen: 6,              // Shorter edges for detail
+    minRegionArea: 4
+}
+```
+
+**Large Outdoor Scenes:**
+```typescript
+options: {
+    cs: 0.5,                    // Lower precision for performance
+    ch: 0.3,
+    walkableRadius: 1.0,        // Larger agent radius
+    walkableHeight: 2.5,
+    walkableClimb: 1.0,         // Can climb rocks/terrain
+    walkableSlopeAngle: 45,     // Steeper slopes allowed
+    maxEdgeLen: 20,             // Longer edges for efficiency
+    minRegionArea: 20
+}
+```
+
+**Multi-Level Structures:**
+```typescript
+options: {
+    cs: 0.2,
+    ch: 0.15,                   // Smaller height cells for precision
+    walkableHeight: 2.2,        // Account for floor thickness
+    walkableClimb: 0.3,         // Prevent stair climbing
+    walkableSlopeAngle: 15,     // Only ramps, not stairs
+    maxEdgeLen: 10,
+    minRegionArea: 10
+}
+```
+
+### Advanced Generation Techniques
+
+#### Using Manifold for Complex Geometry
+For scenes with complex boolean operations, use Manifold integration:
+
+```typescript
+public override getWorldConfiguration(): ENGINE.WorldOptions {
+    return {
+        ...super.getWorldConfiguration(),
+        useManifold: true, // Enable Manifold for CSG operations
+        navigationOptions: {
+            engine: ENGINE.NavigationEngine.RecastNavigation,
+            debug: true,
+            generateOnStartUp: true,
+            options: {
+                ...ENGINE.RecastNavigationServer.DEFAULT_OPTIONS,
+                // Adjust for post-CSG geometry
+                cs: 0.15,
+                ch: 0.15,
+                maxSimplificationError: 0.8 // Lower error for complex shapes
+            }
+        }
+    };
+}
+```
+
+#### Selective Mesh Inclusion
+Control which meshes contribute to NavMesh generation:
+
+```typescript
+// Method 1: Using physics motion type on GLTF actors
+const walkableSurface = new ENGINE.GLTFMeshActor({
+    modelUrl: '@engine/assets/models/ground.glb',
+    physicsOptions: {
+        enabled: true,
+        motionType: ENGINE.PhysicsMotionType.Static // Include in NavMesh generation
+    }
+});
+
+const decorativeObject = new ENGINE.GLTFMeshActor({
+    modelUrl: '@engine/assets/models/decoration.glb',
+    physicsOptions: {
+        enabled: true,
+        motionType: ENGINE.PhysicsMotionType.Dynamic // Exclude from NavMesh
+    }
+});
+
+// Method 2: Manual mesh collection
+const collectNavigationMeshes = (): THREE.Mesh[] => {
+    const meshes: THREE.Mesh[] = [];
+    
+    // Include only specific actors
+    const walkableActors = this.world.getActorsByPredicate(actor => 
+        actor.name.includes('walkable') || actor.name.includes('ground')
+    );
+    
+    walkableActors.forEach(actor => {
+        const meshComponent = actor.getComponent(ENGINE.MeshComponent);
+        if (meshComponent) {
+            meshes.push(meshComponent.getMesh());
+        }
+    });
+    
+    return meshes;
+};
+
+// Generate from collected meshes
+const navigationServer = this.world.getNavigationServer();
+if (navigationServer) {
+    const meshes = collectNavigationMeshes();
+    await navigationServer.createNavigationMeshFromMeshes(meshes);
+}
+```
+
+---
+
+## 3. NPC Movement Components
+
+Genesys.js provides movement components specifically designed for AI-controlled characters that integrate seamlessly with the navigation system.
+
+### Ground-Based Movement: NpcMovementComponent
+
+The `NpcMovementComponent` is the foundation for ground-based NPC movement. It extends `CharacterMovementComponent`, providing physics-based character movement with NavMesh pathfinding.
+
+```typescript
+const npc = new ENGINE.ThirdPersonCharacterPawn({
+    movementComponent: new ENGINE.NpcMovementComponent({
+        movementSpeed: 3, // How fast the NPC moves
+        turnSpeed: 5,     // How fast it turns
+        useNavigationServer: true, // Use NavMesh pathfinding
+        actorFollowingDistance: 2.0, // Stop distance when following
+        pathFollowingAccuracy: 3.0, // How close to get to waypoints
+        stopDistance: 1.0 // Distance to stop from targets
+    }),
+    camera: null // NPCs don't need cameras
+});
+```
+
+The `NpcMovementComponent` provides methods for:
+- **setPath()**: Set a path of waypoints for the NPC to follow
+- **setTargetPosition()**: Set a target position and automatically calculate the path using navigation server
+- **setTargetActor()**: Set a target actor to follow and automatically handle pathfinding
+- **followActor()**: Follow another actor at a specified distance
+- **stop()**: Stop all movement
+- **hasReachedCurrentTarget()**: Check if the NPC has reached its target
+- **getCurrentTarget()**: Get the current movement target
+
+### Debug Visualization
+
+Enable path visualization to debug NPC movement:
+
+```typescript
+const npc = new ENGINE.ThirdPersonCharacterPawn({
+    movementComponent: new ENGINE.NpcMovementComponent({
+        movementSpeed: 5,
+        useNavigationServer: true,
+        debugVisualization: {
+            enabled: true,
+            pathColor: 0x00ff00, // Green path lines
+            targetColor: 0xff0000, // Red target markers
+            lineWidth: 8,
+            showWaypoints: true,
+            waypointSize: 0.7
+        }
+    })
+});
+```
+
+---
+
+## 4. NavMesh Validation and Debugging
+
+### Debug Visualization
+Enable comprehensive debug visualization to understand your NavMesh:
+
+```typescript
+// Enable debug rendering
+navigationOptions: {
+    debug: true, // Shows NavMesh as green overlay
+    // ... other options
+}
+
+// Create additional debug visualization
+const debugVisualization = this.world.getNavigationServer()?.createDebugVisualization();
+if (debugVisualization) {
+    // Disable raycasting for debug mesh to prevent interference
+    debugVisualization.traverse((child) => {
+        child.raycast = () => {};
+    });
+    this.world.scene.add(debugVisualization);
+}
+```
+
+### NavMesh Validation Methods
+Validate your NavMesh programmatically:
+
+```typescript
+const navigationServer = this.world.getNavigationServer();
+if (navigationServer) {
+    // Check if a point is on the NavMesh
+    const testPoint = new THREE.Vector3(10, 0, 5);
+    const isOnNavMesh = navigationServer.isPointOnNavigationMesh(testPoint);
+    console.log(`Point ${testPoint} is on NavMesh: ${isOnNavMesh}`);
+    
+    // Get closest point on NavMesh
+    const closestPoint = navigationServer.getClosestPointOnNavigationMesh(testPoint);
+    console.log(`Closest NavMesh point: ${closestPoint}`);
+    
+    // Test pathfinding
+    const startPoint = new THREE.Vector3(0, 0, 0);
+    const endPoint = new THREE.Vector3(20, 0, 10);
+    const path = navigationServer.calculatePath(startPoint, endPoint);
+    console.log(`Path found with ${path.length} waypoints`);
+}
+```
+
+---
+
+## 5. Performance Optimization
+
+### Generation Performance
+- **Use appropriate cell sizes**: Smaller cells = higher quality but slower generation
+- **Limit mesh complexity**: Simplify source meshes before NavMesh generation
+- **Batch generation**: Generate NavMesh once after loading all static geometry
+- **Cache results**: Save generated NavMesh data for reuse
+
+### Runtime Performance
+- **Pathfinding frequency**: Limit path recalculation frequency in NPCs
+- **Path simplification**: Use appropriate `maxSimplificationError` values
+- **Region culling**: Use `minRegionArea` to eliminate tiny isolated areas
+
+---
+
+## 6. Common NavMesh Issues and Solutions
+
+### Issue: NPCs Getting Stuck
+**Symptoms**: NPCs stop moving or vibrate in place
+**Solutions**:
+```typescript
+// Increase agent radius to prevent tight squeezes
+walkableRadius: 1.0, // Instead of 0.5
+
+// Increase path following accuracy
+movementComponent: new ENGINE.NpcMovementComponent({
+    pathFollowingAccuracy: 3.0, // Larger tolerance
+    stopDistance: 1.5
+})
+```
+
+### Issue: NPCs Not Using Stairs/Ramps
+**Symptoms**: NPCs can't navigate vertical changes
+**Solutions**:
+```typescript
+// Adjust climb and slope parameters
+walkableClimb: 1.0,        // Allow higher steps
+walkableSlopeAngle: 45,    // Allow steeper slopes
+walkableHeight: 2.5        // Ensure enough clearance
+```
+
+### Issue: Disconnected NavMesh Regions
+**Symptoms**: NPCs can't reach certain areas
+**Solutions**:
+```typescript
+// Reduce minimum region area
+minRegionArea: 4,          // Allow smaller regions
+mergeRegionArea: 10,       // Merge nearby regions
+
+// Check for gaps in source geometry
+// Ensure all walkable surfaces are connected
+```
+
+### Issue: NavMesh Generation Fails
+**Symptoms**: No NavMesh appears, console errors
+**Solutions**:
+```typescript
+// Verify mesh has proper geometry
+const mesh = actor.getComponent(ENGINE.MeshComponent)?.getMesh();
+if (mesh) {
+    console.log('Positions:', mesh.geometry.attributes.position?.array);
+    console.log('Indices:', mesh.geometry.index?.array);
+}
+
+// Check for valid indices
+if (!mesh.geometry.index) {
+    mesh.geometry = mesh.geometry.toNonIndexed();
+}
+```
+
+---
+
+## 7. Integration with Game Loop
+
+The NavMesh generation integrates seamlessly with the game loop lifecycle:
+
+```typescript
+export class MyGame extends ENGINE.BaseGameLoop {
+    public override getWorldConfiguration(): ENGINE.WorldOptions {
+        return {
+            ...super.getWorldConfiguration(),
+            navigationOptions: {
+                engine: ENGINE.NavigationEngine.RecastNavigation,
+                debug: true,
+                generateOnStartUp: false, // Manual control
+                options: {
+                    ...ENGINE.RecastNavigationServer.DEFAULT_OPTIONS,
+                    cs: 0.2,
+                    ch: 0.2,
+                    walkableRadius: 0.8,
+                    walkableHeight: 2.0
+                }
+            }
+        };
+    }
+
+    protected override async postStart(): Promise<void> {
+        // Load scene first
+        await this.loadWorldDataFromPath(ENGINE.AssetPath.fromString('@engine/assets/scenes/level1.genesys-scene'));
+        
+        // Wait for all meshes to load
+        await this.world.waitForAllGLTFMeshesToLoad();
+        
+        // Generate NavMesh from scene
+        await this.world.createNavigationMeshFromScene();
+        
+        // Create NPCs after NavMesh is ready
+        await this.createNPCs();
+    }
+}
+```
+
+---
+
+## 8. Best Practices
+
+1. **Generate NavMesh after level geometry**: Always create your NavMesh after adding all static level geometry
+2. **Use appropriate parameters**: Choose NavMesh parameters based on your scene type and NPC requirements
+3. **Test incrementally**: Test NavMesh generation and pathfinding before adding complex AI behaviors
+4. **Debug visually**: Use NavMesh debug rendering to verify pathfinding coverage
+5. **Optimize for performance**: Balance NavMesh quality with generation and runtime performance
+6. **Validate programmatically**: Use validation methods to ensure NavMesh covers required areas
+7. **Handle edge cases**: Plan for disconnected regions and inaccessible areas
+8. **Monitor performance**: Track pathfinding performance and optimize slow queries
+
+---
+
+## 9. NavMesh Export and Import API
+
+Genesys.js provides a powerful export and import system for NavMesh data, enabling seamless integration with external editors and tools. This system uses the native binary serialization format from the `recast-navigation` library for maximum performance and data fidelity.
+
+### Automatic NavMesh Loading
+
+The engine automatically attempts to load NavMesh files when scenes are loaded:
+
+```typescript
+// When you load a scene like "level1.genesys-scene"
+await this.loadWorldDataFromPath(ENGINE.AssetPath.fromString('@engine/assets/scenes/level1.genesys-scene'));
+
+// The engine automatically looks for "level1.navmesh" in the same directory
+// If found, loads it directly; if not found, falls back to auto-generation (if enabled)
+```
+
+**Automatic Loading Behavior:**
+1. **Primary**: Attempts to load `scenename.navmesh` from the same directory
+2. **Fallback**: If file doesn't exist and `generateOnStartUp: true`, generates NavMesh from scene geometry
+3. **Console Feedback**: Provides clear logging for each step of the process
+
+## Scene Resource Configuration
+
+For precise control over NavMesh file locations, you can configure explicit paths in your scene files using the `SceneResources` system:
+
+### Setting Up Scene Resources
+
+```typescript
+// Configure NavMesh path programmatically
+world.setNavMeshResource('@project/assets/navigation/custom-nav.navmesh');
+
+// Configure multiple scene resources
+world.setLightmapResources(
+  '@project/assets/lighting/scene1.lightmap.json',
+  '@project/assets/lighting/scene1.lightmap.bin'
+);
+```
+
+### Scene File Format
+
+Scene files support a `resources` section for explicit asset references:
+
+```json
+{
+  "class": "ENGINE.World",
+  "actors": [...],
+  "resources": {
+    "navMesh": {
+      "path": "@project/assets/navigation/level1-indoor.navmesh"
+    },
+    "lightmap": {
+      "metadataPath": "@project/assets/lighting/level1.lightmap.json",
+      "texturePath": "@project/assets/lighting/level1.lightmap.bin"
+    }
+  }
+}
+```
+
+### Benefits of Scene Resources
+
+- **Flexible Organization**: Place NavMesh files anywhere in your project structure
+- **Descriptive Naming**: Use meaningful names that describe the NavMesh purpose
+- **Multi-Environment Support**: Different NavMesh configurations for various game modes
+- **Tool Integration**: External editors and build pipelines can easily configure resource paths
+
+### Loading Priority
+
+The engine follows this loading priority for NavMesh data:
+
+```typescript
+// When loading a scene
+await this.loadWorldDataFromPath(scenePath);
+
+// Engine loading priority:
+// 1. Scene resources configuration (highest priority)
+// 2. Convention-based file discovery
+// 3. Auto-generation from geometry (if enabled)
+```
+
+### Manual Export API
+
+Export NavMesh data to a binary `.navmesh` file:
+
+```typescript
+// World-level export (recommended)
+const result = await this.world.exportNavigationMesh(scenePath);
+if (result.success && result.data && result.filename) {
+    // Handle the exported ArrayBuffer data and filename as needed
+    console.log(`Exported ${result.filename}, size: ${result.data.byteLength} bytes`);
+}
+
+// Navigation server export (lower-level)
+const navigationServer = this.world.getNavigationServer();
+if (navigationServer && navigationServer.isReady()) {
+    const result = await navigationServer.exportNavigationMesh(scenePath);
+    // Handle result.data ArrayBuffer and result.filename
+}
+```
+
+### Manual Import API
+
+Import NavMesh data from a binary `.navmesh` file:
+
+```typescript
+// Import from file path (uses storage provider)
+const success = await this.world.importNavigationMesh(scenePath);
+if (success) {
+    console.log('NavMesh imported successfully');
+}
+
+// Import from binary data directly (recommended for user uploads)
+const fileData = await file.arrayBuffer(); // From File API
+const success = await this.world.importNavigationMeshFromData(fileData);
+if (success) {
+    console.log('NavMesh imported from binary data');
+    
+    // Update debug visualization if enabled
+    const navigationServer = this.world.getNavigationServer();
+    const debugVisualization = navigationServer?.createDebugVisualization();
+    if (debugVisualization) {
+        this.world.scene.add(debugVisualization);
+    }
+}
+```
+
+### File Format and Naming
+
+**File Extension**: `.navmesh`
+**Format**: Native binary format from `recast-navigation` library
+**Naming Convention**: `{scenename}.navmesh` (automatically derived from scene file name)
+
+```typescript
+// Scene: "/assets/scenes/level1.genesys-scene"
+// NavMesh: "/assets/scenes/level1.navmesh"
+
+// Scene: "demo.genesys-scene"  
+// NavMesh: "demo.navmesh"
+```
+
+### GameLoop Export/Import Methods
+
+The `BaseGameLoop` class provides convenient methods for NavMesh export/import:
+
+```typescript
+export class NavMeshEditorDemo extends ENGINE.BaseGameLoop {
+    private async exportCurrentNavMesh(): Promise<void> {
+        try {
+            // GameLoop export method - requires scene path for filename generation
+            const scenePath = ENGINE.AssetPath.fromString('@engine/assets/scenes/demo.genesys-scene');
+            const result = await this.exportNavigationMesh(scenePath);
+
+            if (result.success && result.data && result.filename) {
+                // Handle the exported data (result.data is ArrayBuffer, result.filename is string)
+                console.log(`NavMesh exported as ${result.filename}`);
+                // Download, save to file system, or upload to server
+                this.downloadFile(result.data, result.filename);
+            }
+        } catch (error) {
+            console.error('Export failed:', error);
+        }
+    }
+
+    private async importNavMeshFromFile(file: File): Promise<void> {
+        try {
+            // Read file as binary data
+            const fileData = await file.arrayBuffer();
+            
+            // GameLoop import method - accepts ArrayBuffer data directly
+            const success = await this.importNavigationMesh(fileData);
+            
+            if (success) {
+                console.log(`NavMesh imported from ${file.name}`);
+                
+                // Refresh debug visualization if needed
+                this.refreshDebugVisualization();
+            } else {
+                console.error('Import failed');
+            }
+        } catch (error) {
+            console.error('Import error:', error);
+        }
+    }
+
+    private async importFromSceneResources(): Promise<void> {
+        // Import from configured scene resources (no parameters needed)
+        const success = await this.importNavigationMesh();
+        
+        if (success) {
+            console.log('NavMesh imported from scene resources');
+        } else {
+            console.log('No NavMesh configured in scene resources');
+        }
+    }
+
+    // Handle the exported data as needed (save to file, send to server, etc.)
+
+    private refreshDebugVisualization(): void {
+        // Clear existing debug visualization
+        const existingDebug = this.world.scene.getObjectByName('NavmeshDebugVisualization');
+        if (existingDebug) {
+            this.world.scene.remove(existingDebug);
+        }
+
+        // Create new debug visualization
+        const navigationServer = this.world.getNavigationServer();
+        const debugVisualization = navigationServer?.createDebugVisualization();
+        if (debugVisualization) {
+            debugVisualization.name = 'NavmeshDebugVisualization';
+            debugVisualization.traverse((child) => {
+                child.raycast = () => {}; // Disable raycasting
+            });
+            this.world.scene.add(debugVisualization);
+        }
+    }
+}
+```
+
+
+
+### Best Practices for Export/Import
+
+1. **Export After Final Tuning**: Export NavMesh after you've finalized your navigation parameters
+2. **Version Control**: Include `.navmesh` files in version control alongside scene files
+3. **Automated Workflows**: Integrate export/import into your build pipeline for level updates
+4. **Testing**: Always test imported NavMesh files to ensure they work correctly
+5. **Backup Original**: Keep backups of generated NavMesh files before external modification
+6. **File Organization**: Store NavMesh files alongside their corresponding scene files
+
+### Error Handling
+
+The export/import system provides comprehensive error reporting:
+
+```typescript
+// Export error handling
+const result = await this.world.exportNavigationMesh(scenePath);
+if (!result.success) {
+    console.error('Export failed - check if NavMesh exists and is valid');
+}
+
+// Import error handling  
+try {
+    const success = await this.world.importNavigationMeshFromData(fileData);
+    if (!success) {
+        console.error('Import failed - file may be corrupted or incompatible');
+    }
+} catch (error) {
+    console.error('Import error:', error);
+    // Handle file read errors, format errors, etc.
+}
+```
+
+This export/import system enables powerful workflows with external tools while maintaining optimal performance through the native binary format.
+
+---
+
+## Next Steps
+
+Once you have navigation working, you can implement sophisticated AI behaviors using the behavior tree system. See the **[AI and Behavior Trees Guide](6-ai-and-behavior-trees.md)** to learn about:
+
+- Creating complex AI decision-making systems
+- Implementing behavior trees for NPCs
+- Aerial movement for flying enemies
+- Combat and interaction behaviors
+- Advanced AI debugging techniques
+
+This navigation system provides the foundation for sophisticated AI movement in your Genesys.js projects.
+
+---
+
+## 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/navigation/NavigationServer.ts}>
+<file path={src/navigation/RecastNavigationServer.ts}>
+<file path={src/components/movement/NpcMovementComponent.ts}>