@directivegames/genesys.js 3.1.24

package/games/navmesh-primitives-demo.ts

@@ -0,0 +1,1252 @@
+import * as ENGINE from 'genesys.js';
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import * as SkeletonUtils from 'three/examples/jsm/utils/SkeletonUtils.js';
+import { Pane } from 'tweakpane';
+
+/**
+ * Navmesh Primitives Demo
+ *
+ * This demo showcases automatic navmesh generation using the built-in scene analysis system,
+ * including the new export/import functionality for external editor workflows:
+ *
+ * Features Demonstrated:
+ * - Setting up scenes with primitive MeshComponents (boxes, spheres, cylinders)
+ * - Setting up scenes with GLTF models from the asset library
+ * - **Automatic scene analysis**: NavMesh generation finds all static geometry automatically
+ * - Respects `excludeFromNavigation` flags on mesh components
+ * - Only includes actors with `PhysicsMotionType.Static` motion type
+ * - Debug visualization of the generated navmesh
+ * - Interactive Tweakpane UI for real-time navmesh parameter adjustment
+ * - Real-time navmesh regeneration with updated parameters
+ * - **Export current navmesh to binary file for external editors**
+ * - **Import navmesh from binary file (direct application without regeneration)**
+ * - **NEW: Scene export with explicit resource metadata (no more currentScenePath!)**
+ * - **NEW: External tool APIs for setting resource references in scenes**
+ *
+ * The demo creates two environments side by side:
+ * LEFT SIDE (Primitives): Ground plane, primitive obstacles, platforms, maze walls
+ * RIGHT SIDE (GLTF): Floor tiles, modular walls, trees, rocks, vehicles, structures
+ * - **Automatic scene analysis**: No manual mesh collection required!
+ * - Green debug visualization overlay showing walkable areas across both scenes
+ * - Tweakpane controls for adjusting all Recast Navigation parameters
+ * - Export/Import buttons for navmesh workflow testing
+ *
+ * Export/Import Workflow:
+ * 1. Generate a navmesh using the "Regenerate Navmesh" button (automatic scene analysis)
+ * 2. Export it to binary file using "Export NavMesh" button
+ * 3. Optionally modify the navmesh in an external editor
+ * 4. Import the modified navmesh using "Import NavMesh" button
+ * 5. The imported navmesh is applied directly without regeneration
+ *
+ * NEW Resource Metadata Workflow:
+ * 1. Use "Set NavMesh Reference in Scene" to configure resource path
+ * 2. Use "Export Scene with NavMesh Reference" to save scene with metadata
+ * 3. External tools can edit scenes to set resource references
+ * 4. Engine automatically loads resources from scene metadata
+ */
+
+export class NavmeshPrimitivesDemo extends ENGINE.BaseGameLoop {
+
+  private pane!: Pane;
+
+  // Tweakpane controls and parameters - defined as static getter to be available during construction
+  private static get DEFAULT_NAVMESH_PARAMS(): {
+    cs: number;
+    ch: number;
+    walkableSlopeAngle: number;
+    walkableHeight: number;
+    walkableClimb: number;
+    walkableRadius: number;
+    maxEdgeLen: number;
+    maxSimplificationError: number;
+    minRegionArea: number;
+    mergeRegionArea: number;
+    maxVertsPerPoly: number;
+    detailSampleDist: number;
+    detailSampleMaxError: number;
+    borderSize: number;
+    debugEnabled: boolean;
+    sceneType: 'Primitives' | 'GLTF' | 'Both';
+    } {
+    return {
+      // Cell dimensions
+      cs: 0.2,              // Cell size (XZ plane resolution)
+      ch: 0.2,              // Cell height (Y axis resolution)
+
+      // Agent capabilities
+      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
+
+      // Debug visualization
+      debugEnabled: true,        // Show navmesh debug visualization
+
+      // Scene control
+      sceneType: 'Both' as 'Primitives' | 'GLTF' | 'Both'  // Which scene types to show
+    };
+  }
+
+  private navmeshParams = { ...NavmeshPrimitivesDemo.DEFAULT_NAVMESH_PARAMS };
+
+  constructor(container: HTMLElement, options?: ENGINE.BaseGameLoopOptions) {
+    super(container, options);
+    this.setupCamera(container);
+  }
+
+  /**
+   * Configure the world with navigation server enabled
+   */
+  public override getWorldConfiguration(): ENGINE.WorldOptions {
+    // Use static defaults during construction when instance fields aren't ready yet
+    const params = NavmeshPrimitivesDemo.DEFAULT_NAVMESH_PARAMS;
+
+    return {
+      ...super.getWorldConfiguration(),
+      navigationOptions: {
+        engine: ENGINE.NavigationEngine.RecastNavigation,
+        debug: params.debugEnabled,
+        generateOnStartUp: false, // Manual generation after adding meshes
+        options: {
+          ...ENGINE.RecastNavigationServer.DEFAULT_OPTIONS,
+          cs: params.cs,
+          ch: params.ch,
+          walkableSlopeAngle: params.walkableSlopeAngle,
+          walkableHeight: params.walkableHeight,
+          walkableClimb: params.walkableClimb,
+          walkableRadius: params.walkableRadius,
+          maxEdgeLen: params.maxEdgeLen,
+          maxSimplificationError: params.maxSimplificationError,
+          minRegionArea: params.minRegionArea,
+          mergeRegionArea: params.mergeRegionArea,
+          maxVertsPerPoly: params.maxVertsPerPoly,
+          detailSampleDist: params.detailSampleDist,
+          detailSampleMaxError: params.detailSampleMaxError,
+          borderSize: params.borderSize
+        }
+      }
+    };
+  }
+
+  protected override async preStart(): Promise<void> {
+    // Set up basic lighting
+    this.setupLighting();
+
+    // Create scenes based on current settings
+    this.createActiveScenes();
+  }
+
+  protected override postStart(): void {
+    // // Generate navmesh after all geometry is in place
+    // await this.generateNavmesh();
+
+    // Create Tweakpane UI controls
+    this.createTweakPane();
+
+    // Log information about the new export/import functionality
+    console.log('🚀 NavMesh Export/Import Demo Ready!');
+    console.log('📝 Use Export/Import controls to save/load navmesh as GLTF files');
+    console.log('🆕 NEW: Scene export with resource metadata system!');
+  }
+
+
+  /**
+   * Create all scenes and set initial visibility based on scene type setting
+   */
+  private createActiveScenes(): void {
+    // Always create both scenes so we can toggle between them
+    this.createScene();
+    this.createGLTFScene();
+
+    // Set initial visibility based on current scene type
+    this.updateSceneVisibility();
+
+    console.log(`Created all scenes, showing: ${this.navmeshParams.sceneType}`);
+  }
+
+  /**
+   * Update scene visibility based on current scene type setting
+   */
+  private updateSceneVisibility(): void {
+    const sceneType = this.navmeshParams.sceneType;
+
+    // Get all actors in the world
+    const allActors = this.world.getActorsByPredicate(() => true);
+
+    allActors.forEach(actor => {
+      // Determine if this is a primitive or GLTF actor based on components
+      const hasMeshComponent = actor.getComponent(ENGINE.MeshComponent) !== null;
+      const hasGLTFComponent = actor.getComponent(ENGINE.GLTFMeshComponent) !== null;
+
+      // Skip lighting actors
+      if (actor.name.includes('Light') || actor.name.includes('light')) {
+        return;
+      }
+
+      let shouldBeVisible = false;
+
+      if (hasMeshComponent && !hasGLTFComponent) {
+        // This is a primitive actor
+        shouldBeVisible = sceneType === 'Primitives' || sceneType === 'Both';
+      } else if (hasGLTFComponent) {
+        // This is a GLTF actor
+        shouldBeVisible = sceneType === 'GLTF' || sceneType === 'Both';
+      } else {
+        // Keep other actors visible (like lighting)
+        shouldBeVisible = true;
+      }
+
+      // Update visibility
+      actor.rootComponent.visible = shouldBeVisible;
+    });
+
+    console.log(`Updated scene visibility: ${sceneType}`);
+  }
+
+  /**
+   * Set up basic lighting for the scene
+   */
+  private setupLighting(): void {
+    console.log('Setting up lighting...');
+
+    // Ambient light for overall illumination
+    const ambientLight = new ENGINE.Actor({
+      name: 'AmbientLight',
+      sceneComponents: [
+        new ENGINE.AmbientLightComponent({
+          color: 0x404080,
+          intensity: 0.4
+        })
+      ]
+    });
+    this.world.addActors(ambientLight);
+
+    // Directional light as main light source with shadows
+    const directionalLight = new ENGINE.Actor({
+      name: 'DirectionalLight',
+      position: new THREE.Vector3(10, 20, 10),
+      sceneComponents: [
+        new ENGINE.DirectionalLightComponent({
+          color: 0xffffff,
+          intensity: 1.5,
+          castShadow: true
+        })
+      ]
+    });
+    this.world.addActors(directionalLight);
+  }
+
+  /**
+     * Create the scene with various primitive MeshComponents
+     */
+  private createScene(): void {
+    console.log('Creating scene with primitive meshes...');
+
+    // Create ground plane
+    this.createGroundPlane();
+
+    // Create various obstacles and platforms
+    this.createObstacles();
+
+    // Create platforms at different heights
+    this.createPlatforms();
+
+    // Create a maze-like structure
+    this.createMazeWalls();
+  }
+
+  /**
+     * Create the main ground plane
+     */
+  private createGroundPlane(): void {
+    const ground = new ENGINE.Actor({
+      name: 'Ground',
+      position: new THREE.Vector3(0, 0, 0),
+      rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.BoxGeometry(40, 0.2, 40),
+        material: new THREE.MeshStandardMaterial({
+          color: 0x8B7355, // Brown ground color
+          roughness: 0.8,
+          metalness: 0.1
+        })
+      })
+    });
+
+    // Enable shadows
+    const meshComponent = ground.rootComponent as ENGINE.MeshComponent;
+    meshComponent.receiveShadow = true;
+
+    this.world.addActors(ground);
+  }
+
+  /**
+     * Create various obstacles using different primitive shapes
+     */
+  private createObstacles(): void {
+    // Box obstacles
+    const boxObstacle1 = new ENGINE.Actor({
+      name: 'BoxObstacle1',
+      position: new THREE.Vector3(5, 1, 5),
+      rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.BoxGeometry(2, 2, 2),
+        material: new THREE.MeshStandardMaterial({
+          color: 0xFF6B6B, // Red
+          roughness: 0.7,
+          metalness: 0.2
+        })
+      })
+    });
+
+    const boxObstacle2 = new ENGINE.Actor({
+      name: 'BoxObstacle2',
+      position: new THREE.Vector3(-8, 1.5, -3),
+      rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.BoxGeometry(3, 3, 1.5),
+        material: new THREE.MeshStandardMaterial({
+          color: 0x4ECDC4, // Teal
+          roughness: 0.6,
+          metalness: 0.3
+        })
+      })
+    });
+
+    // Cylinder obstacles
+    const cylinderObstacle1 = new ENGINE.Actor({
+      name: 'CylinderObstacle1',
+      position: new THREE.Vector3(-5, 1, 8),
+      rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.CylinderGeometry(1.5, 1.5, 2, 8),
+        material: new THREE.MeshStandardMaterial({
+          color: 0x45B7D1, // Blue
+          roughness: 0.5,
+          metalness: 0.4
+        })
+      })
+    });
+
+    const cylinderObstacle2 = new ENGINE.Actor({
+      name: 'CylinderObstacle2',
+      position: new THREE.Vector3(10, 0.75, -8),
+      rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.CylinderGeometry(1, 1, 1.5, 6),
+        material: new THREE.MeshStandardMaterial({
+          color: 0x96CEB4, // Green
+          roughness: 0.8,
+          metalness: 0.1
+        })
+      })
+    });
+
+    // Sphere obstacles
+    const sphereObstacle = new ENGINE.Actor({
+      name: 'SphereObstacle',
+      position: new THREE.Vector3(0, 1.2, -12),
+      rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.SphereGeometry(1.2, 16, 12),
+        material: new THREE.MeshStandardMaterial({
+          color: 0xFECA57, // Yellow
+          roughness: 0.4,
+          metalness: 0.6
+        })
+      })
+    });
+
+    // Enable shadows for all obstacles
+    const obstacles = [boxObstacle1, boxObstacle2, cylinderObstacle1, cylinderObstacle2, sphereObstacle];
+    obstacles.forEach(obstacle => {
+      const meshComponent = obstacle.rootComponent as ENGINE.MeshComponent;
+      meshComponent.castShadow = true;
+      meshComponent.receiveShadow = true;
+    });
+
+    this.world.addActors(...obstacles);
+  }
+
+  /**
+     * Create elevated platforms using box geometry
+     */
+  private createPlatforms(): void {
+    // Platform 1 - Low platform
+    const platform1 = new ENGINE.Actor({
+      name: 'Platform1',
+      position: new THREE.Vector3(12, 1, 12),
+      rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.BoxGeometry(6, 2, 6),
+        material: new THREE.MeshStandardMaterial({
+          color: 0x686DE0, // Purple
+          roughness: 0.7,
+          metalness: 0.2
+        })
+      })
+    });
+
+    // Platform 2 - Medium platform
+    const platform2 = new ENGINE.Actor({
+      name: 'Platform2',
+      position: new THREE.Vector3(-12, 2, 12),
+      rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.BoxGeometry(5, 4, 5),
+        material: new THREE.MeshStandardMaterial({
+          color: 0xF8B500, // Orange
+          roughness: 0.6,
+          metalness: 0.3
+        })
+      })
+    });
+
+    // Platform 3 - High platform with ramp
+    const platform3 = new ENGINE.Actor({
+      name: 'Platform3',
+      position: new THREE.Vector3(-12, 3, -12),
+      rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.BoxGeometry(4, 6, 4),
+        material: new THREE.MeshStandardMaterial({
+          color: 0xE17055, // Dark orange
+          roughness: 0.8,
+          metalness: 0.1
+        })
+      })
+    });
+
+    // Ramp to platform 3
+    const ramp = new ENGINE.Actor({
+      name: 'Ramp',
+      position: new THREE.Vector3(-8, 1.5, -12),
+      rotation: new THREE.Euler(0, 0, Math.PI / 12), // Slight slope
+      rootComponent: new ENGINE.MeshComponent({
+        geometry: new THREE.BoxGeometry(4, 0.5, 4),
+        material: new THREE.MeshStandardMaterial({
+          color: 0xA29BFE, // Light purple
+          roughness: 0.7,
+          metalness: 0.2
+        })
+      })
+    });
+
+    // Enable shadows for platforms
+    const platforms = [platform1, platform2, platform3, ramp];
+    platforms.forEach(platform => {
+      const meshComponent = platform.rootComponent as ENGINE.MeshComponent;
+      meshComponent.castShadow = true;
+      meshComponent.receiveShadow = true;
+    });
+
+    this.world.addActors(...platforms);
+  }
+
+  /**
+   * Create a simple maze-like structure using box walls
+   */
+  private createMazeWalls(): void {
+    const walls: ENGINE.Actor[] = [];
+
+    // Create a series of wall segments to form a mini maze
+    const wallConfigs = [
+      { pos: [15, 1, 0], size: [1, 2, 8] },    // Vertical wall 1
+      { pos: [8, 1, -5], size: [6, 2, 1] },    // Horizontal wall 1
+      { pos: [2, 1, -8], size: [1, 2, 6] },    // Vertical wall 2
+      { pos: [-2, 1, -5], size: [4, 2, 1] },   // Horizontal wall 2
+      { pos: [-8, 1, 0], size: [1, 2, 6] },    // Vertical wall 3
+      { pos: [-12, 1, 3], size: [6, 2, 1] },   // Horizontal wall 3
+    ];
+
+    wallConfigs.forEach((config, index) => {
+      const wall = new ENGINE.Actor({
+        name: `MazeWall${index + 1}`,
+        position: new THREE.Vector3(config.pos[0], config.pos[1], config.pos[2]),
+        rootComponent: new ENGINE.MeshComponent({
+          geometry: new THREE.BoxGeometry(config.size[0], config.size[1], config.size[2]),
+          material: new THREE.MeshStandardMaterial({
+            color: 0x74B9FF, // Light blue
+            roughness: 0.8,
+            metalness: 0.2
+          })
+        })
+      });
+
+      const meshComponent = wall.rootComponent as ENGINE.MeshComponent;
+      meshComponent.castShadow = true;
+      meshComponent.receiveShadow = true;
+
+      walls.push(wall);
+    });
+
+    this.world.addActors(...walls);
+  }
+
+  /**
+   * Create a scene using GLTF models for navmesh testing
+   */
+  private createGLTFScene(): void {
+    console.log('Creating GLTF scene for navmesh testing...');
+
+    // Create a base ground using sandbox floor assets
+    this.createGLTFGround();
+
+    // Create walls and structures
+    this.createGLTFStructures();
+
+    // Add decorative elements and obstacles
+    this.createGLTFDecorations();
+
+    // Add some buildings/larger structures
+    this.createGLTFBuildings();
+  }
+
+  /**
+   * Create ground/floor using GLTF tiles
+   */
+  private createGLTFGround(): void {
+    // Create a grid of floor tiles
+    const floorSize = 4; // Assuming each floor tile is about 4x4 units
+    const gridSize = 6; // 6x6 grid of tiles
+    for (let x = 0; x < gridSize; x++) {
+      for (let z = 0; z < gridSize; z++) {
+        const floor = new ENGINE.Actor({
+          name: `GLTFFloor_${x}_${z}`,
+          position: new THREE.Vector3(
+            (x - gridSize/2) * floorSize + 30, // Offset to the right of primitive scene
+            0,
+            (z - gridSize/2) * floorSize
+          ),
+          rootComponent: new ENGINE.GLTFMeshComponent({
+            modelUrl: '@engine/assets/dev/models/SandboxAsset/Floors/SM_SB_Floor_01.glb',
+            physicsOptions: {
+              enabled: true,
+              motionType: ENGINE.PhysicsMotionType.Static
+            }
+          })
+        });
+
+        this.world.addActors(floor);
+      }
+    }
+  }
+
+  /**
+   * Create walls and structural elements
+   */
+  private createGLTFStructures(): void {
+    const structures = [
+      // Main walls creating rooms
+      {
+        name: 'WallNorth1',
+        position: new THREE.Vector3(25, 0, -10),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Walls/SM_SB_Wall_L_01_128x96.glb'
+      },
+      {
+        name: 'WallNorth2',
+        position: new THREE.Vector3(35, 0, -10),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Walls/SM_SB_Wall_L_02_128x96.glb'
+      },
+      {
+        name: 'WallEast1',
+        position: new THREE.Vector3(40, 0, -5),
+        rotation: new THREE.Euler(0, Math.PI/2, 0),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Walls/SM_SB_Wall_L_01B_128x96.glb'
+      },
+      {
+        name: 'WallEast2',
+        position: new THREE.Vector3(40, 0, 5),
+        rotation: new THREE.Euler(0, Math.PI/2, 0),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Walls/SM_SB_Wall_L_03_128x96.glb'
+      },
+      {
+        name: 'WallSouth1',
+        position: new THREE.Vector3(35, 0, 10),
+        rotation: new THREE.Euler(0, Math.PI, 0),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Walls/SM_SB_Aztec_Wall_01.glb'
+      },
+      {
+        name: 'WallSouth2',
+        position: new THREE.Vector3(25, 0, 10),
+        rotation: new THREE.Euler(0, Math.PI, 0),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Walls/SM_SB_Aztec_Wall_02.glb'
+      },
+      // Interior walls creating obstacles
+      {
+        name: 'InteriorWall1',
+        position: new THREE.Vector3(30, 0, 0),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Walls/SM_SB_BrickBlock01.glb'
+      },
+      {
+        name: 'InteriorWall2',
+        position: new THREE.Vector3(27, 0, -5),
+        rotation: new THREE.Euler(0, Math.PI/4, 0),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Walls/SM_SB_BrickBlock02.glb'
+      }
+    ];
+
+    structures.forEach(structure => {
+      const wall = new ENGINE.Actor({
+        name: structure.name,
+        position: structure.position,
+        rotation: structure.rotation ?? new THREE.Euler(0, 0, 0),
+        rootComponent: new ENGINE.GLTFMeshComponent({
+          modelUrl: structure.modelUrl,
+          physicsOptions: {
+            enabled: true,
+            motionType: ENGINE.PhysicsMotionType.Static
+          }
+        })
+      });
+
+      this.world.addActors(wall);
+    });
+  }
+
+  /**
+   * Add decorative elements and obstacles
+   */
+  private createGLTFDecorations(): void {
+    const decorations = [
+      // Trees for natural obstacles
+      {
+        name: 'Tree1',
+        position: new THREE.Vector3(32, 0, -7),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Trees/SM_SB_CaribbeanPine_01.glb'
+      },
+      {
+        name: 'Tree2',
+        position: new THREE.Vector3(38, 0, 3),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Trees/SM_SB_CoconutTree01.glb'
+      },
+      {
+        name: 'Tree3',
+        position: new THREE.Vector3(22, 0, 7),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Trees/SM_SB_QueenPalm_01.glb'
+      },
+      // Rocks as obstacles
+      {
+        name: 'Rock1',
+        position: new THREE.Vector3(28, 0, 2),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Rocks/SM_SB_Rock01.glb'
+      },
+      {
+        name: 'Rock2',
+        position: new THREE.Vector3(34, 0, -3),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Rocks/SM_SB_Rock02.glb'
+      },
+      // Foliage for detail
+      {
+        name: 'Plant1',
+        position: new THREE.Vector3(26, 0, -2),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Foliage/SM_SB_Plant01.glb'
+      },
+      {
+        name: 'Fern1',
+        position: new THREE.Vector3(37, 0, -1),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Foliage/SM_SB_Fern01.glb'
+      },
+      // Game items as interesting obstacles
+      {
+        name: 'MovingPlatform',
+        position: new THREE.Vector3(29, 0, 5),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Game Items/SM_SB_MovingPlatform_01.glb'
+      }
+    ];
+
+    decorations.forEach(decoration => {
+      const actor = new ENGINE.Actor({
+        name: decoration.name,
+        position: decoration.position,
+        rootComponent: new ENGINE.GLTFMeshComponent({
+          modelUrl: decoration.modelUrl,
+          physicsOptions: {
+            enabled: true,
+            motionType: ENGINE.PhysicsMotionType.Static
+          }
+        })
+      });
+
+      this.world.addActors(actor);
+    });
+  }
+
+  /**
+   * Add some larger structures and vehicles
+   */
+  private createGLTFBuildings(): void {
+    const structures = [
+      // Large floor pieces as elevated platforms
+      {
+        position: new THREE.Vector3(45, 2, -8),
+        modelUrl: '@engine/assets/dev/models/Architecture/SM_Floor_400x400.glb'
+      },
+      {
+        position: new THREE.Vector3(45, 1, 0),
+        modelUrl: '@engine/assets/dev/models/Architecture/SM_Floor_300x300.glb'
+      },
+      {
+        position: new THREE.Vector3(45, 1.5, 8),
+        modelUrl: '@engine/assets/dev/models/Architecture/SM_Floor_200x400.glb'
+      },
+      // Add a vehicle as an obstacle
+      {
+        name: 'Car1',
+        position: new THREE.Vector3(20, 0, 0),
+        rotation: new THREE.Euler(0, Math.PI/4, 0),
+        modelUrl: '@engine/assets/dev/models/Vehicles/SM_Car01.glb'
+      },
+      // Add some larger decorative items
+      {
+        name: 'Slide1',
+        position: new THREE.Vector3(24, 0, 4),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Slides/SM_SB_Slide_Module.glb'
+      },
+      {
+        name: 'Bridge1',
+        position: new THREE.Vector3(33, 1, -8),
+        modelUrl: '@engine/assets/dev/models/SandboxAsset/Game Items/SM_SB_HangingBridgeMiddle.glb'
+      }
+    ];
+
+    structures.forEach(structure => {
+      const actor = new ENGINE.Actor({
+        name: structure.name,
+        position: structure.position,
+        rotation: structure.rotation ?? new THREE.Euler(0, 0, 0),
+        rootComponent: new ENGINE.GLTFMeshComponent({
+          modelUrl: structure.modelUrl,
+          physicsOptions: {
+            enabled: true,
+            motionType: ENGINE.PhysicsMotionType.Static
+          }
+        })
+      });
+
+      this.world.addActors(actor);
+    });
+  }
+
+  /**
+   * Generate navmesh automatically from all static geometry in the scene
+   * Uses the built-in World.createNavigationMeshFromScene() method which automatically:
+   * - Finds all GLTFMeshComponents with Static motion type and !excludeFromNavigation
+   * - Finds all MeshComponents with Static motion type and !excludeFromNavigation
+   * - Waits for GLTF models to load before processing
+   */
+  private async generateNavmesh(): Promise<void> {
+    console.log('Generating navmesh using built-in scene analysis...');
+
+    const navigationServer = this.world.getNavigationServer();
+    if (!navigationServer) {
+      console.error('Navigation server not available');
+      return;
+    }
+
+    try {
+      // Update navigation server options with current parameters before generation
+      const navmeshOptions = {
+        cs: this.navmeshParams.cs,
+        ch: this.navmeshParams.ch,
+        walkableSlopeAngle: this.navmeshParams.walkableSlopeAngle,
+        walkableHeight: this.navmeshParams.walkableHeight,
+        walkableClimb: this.navmeshParams.walkableClimb,
+        walkableRadius: this.navmeshParams.walkableRadius,
+        maxEdgeLen: this.navmeshParams.maxEdgeLen,
+        maxSimplificationError: this.navmeshParams.maxSimplificationError,
+        minRegionArea: this.navmeshParams.minRegionArea,
+        mergeRegionArea: this.navmeshParams.mergeRegionArea,
+        maxVertsPerPoly: this.navmeshParams.maxVertsPerPoly,
+        detailSampleDist: this.navmeshParams.detailSampleDist,
+        detailSampleMaxError: this.navmeshParams.detailSampleMaxError,
+        borderSize: this.navmeshParams.borderSize
+      };
+
+      // Update the navigation server's options
+      (navigationServer as any).options = { ...(navigationServer as any).options, ...navmeshOptions };
+
+      // Use the built-in scene analysis method
+      // This automatically finds all static mesh components that should be included in navigation
+      await this.world.createNavigationMeshFromScene();
+
+      console.log('✅ NavMesh generated successfully using automatic scene analysis!');
+
+      // Create debug visualization if enabled
+      if (this.navmeshParams.debugEnabled) {
+        const debugVisualization = navigationServer.createDebugVisualization();
+        if (debugVisualization) {
+          // Disable raycasting for debug mesh to prevent interference
+          debugVisualization.traverse((child) => {
+            child.raycast = () => {};
+          });
+          debugVisualization.name = 'NavmeshDebugVisualization';
+          this.world.scene.add(debugVisualization);
+          console.log('Debug visualization added to scene');
+        }
+      }
+    } catch (error) {
+      console.error('❌ Error during navmesh generation:', error);
+    }
+  }
+
+  /**
+   * Set up camera for better viewing of both scenes
+   */
+  private setupCamera(container: HTMLElement): void {
+    // Create and set an override camera for better scene viewing
+    const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
+    const controls = new OrbitControls(camera, container);
+    controls.enableDamping = true;
+    controls.dampingFactor = 0.25;
+    controls.enableZoom = true;
+    controls.enablePan = true;
+    controls.enableRotate = true;
+    // controls.enableKeys = true;
+    // Position camera to see both primitive scene (left) and GLTF scene (right)
+    camera.position.set(15, 20, 35);
+    camera.lookAt(new THREE.Vector3(15, 0, 0)); // Look at center between both scenes
+    this.world.setOverrideCamera(camera);
+    console.log('Camera positioned for dual scene overview');
+  }
+
+  /**
+   * Create Tweakpane UI for navmesh controls
+   */
+  private createTweakPane(): void {
+    this.pane = new Pane({ title: 'Navmesh Generation Controls' });
+
+    // Actions folder - split into generation and export/import
+    const generationFolder = this.pane.addFolder({ title: 'NavMesh Generation', expanded: true });
+
+    const regenerateButton = generationFolder.addButton({ title: 'Regenerate Navmesh' });
+    regenerateButton.on('click', () => {
+      this.regenerateNavmesh();
+    });
+
+    // Export/Import folder for the new functionality
+    const exportImportFolder = this.pane.addFolder({ title: 'Export/Import', expanded: true });
+
+    const exportButton = exportImportFolder.addButton({ title: 'Export NavMesh' });
+    exportButton.on('click', () => {
+      this.exportNavmesh();
+    });
+
+    const importButton = exportImportFolder.addButton({ title: 'Import NavMesh' });
+    importButton.on('click', () => {
+      this.openImportDialog();
+    });
+
+    // Scene export functionality demonstrating the new metadata system
+    const sceneExportFolder = this.pane.addFolder({ title: 'Scene Export (New System)', expanded: true });
+
+    const exportSceneButton = sceneExportFolder.addButton({ title: 'Export Scene with NavMesh Reference' });
+    exportSceneButton.on('click', () => {
+      this.exportSceneWithNavMeshReference();
+    });
+
+    const setNavMeshReferenceButton = sceneExportFolder.addButton({ title: 'Set NavMesh Reference in Scene' });
+    setNavMeshReferenceButton.on('click', () => {
+      this.setNavMeshReferenceInScene();
+    });
+
+    // Status display following lightmapping demo pattern
+    this.pane.addBlade({ view: 'separator' });
+    const statusElement = document.createElement('div');
+    statusElement.style.padding = '8px';
+    statusElement.style.fontSize = '12px';
+    statusElement.style.color = '#888';
+    statusElement.style.backgroundColor = '#1a1a1a';
+    statusElement.style.borderRadius = '4px';
+    statusElement.innerHTML = 'Status: Ready<br/>🚀 NavMesh Export/Import Demo<br/>📝 1. Generate a navmesh<br/>📤 2. Export to .navmesh file<br/>📥 3. Import .navmesh file<br/>🔧 Files saved as scenename.navmesh<br/>🆕 NEW: Export scenes with resource metadata!';
+    sceneExportFolder.element.appendChild(statusElement);
+
+    // Store reference for updates
+    (this as any).statusElement = statusElement;
+
+    // Cell dimensions folder
+    const cellFolder = this.pane.addFolder({ title: 'Cell Dimensions', expanded: true });
+    cellFolder.addBinding(this.navmeshParams, 'cs', {
+      min: 0.05,
+      max: 1.0,
+      step: 0.05,
+      label: 'Cell Size (XZ)'
+    });
+    cellFolder.addBinding(this.navmeshParams, 'ch', {
+      min: 0.05,
+      max: 1.0,
+      step: 0.05,
+      label: 'Cell Height (Y)'
+    });
+
+    // Agent capabilities folder
+    const agentFolder = this.pane.addFolder({ title: 'Agent Capabilities', expanded: true });
+    agentFolder.addBinding(this.navmeshParams, 'walkableSlopeAngle', {
+      min: 0,
+      max: 90,
+      step: 1,
+      label: 'Max Slope (°)'
+    });
+    agentFolder.addBinding(this.navmeshParams, 'walkableHeight', {
+      min: 0.5,
+      max: 5.0,
+      step: 0.1,
+      label: 'Agent Height'
+    });
+    agentFolder.addBinding(this.navmeshParams, 'walkableClimb', {
+      min: 0.1,
+      max: 2.0,
+      step: 0.1,
+      label: 'Max Step Height'
+    });
+    agentFolder.addBinding(this.navmeshParams, 'walkableRadius', {
+      min: 0.1,
+      max: 2.0,
+      step: 0.1,
+      label: 'Agent Radius'
+    });
+
+    // Mesh quality folder
+    const qualityFolder = this.pane.addFolder({ title: 'Mesh Quality', expanded: false });
+    qualityFolder.addBinding(this.navmeshParams, 'maxEdgeLen', {
+      min: 1,
+      max: 50,
+      step: 1,
+      label: 'Max Edge Length'
+    });
+    qualityFolder.addBinding(this.navmeshParams, 'maxSimplificationError', {
+      min: 0.1,
+      max: 5.0,
+      step: 0.1,
+      label: 'Simplification Error'
+    });
+
+    // Region processing folder
+    const regionFolder = this.pane.addFolder({ title: 'Region Processing', expanded: false });
+    regionFolder.addBinding(this.navmeshParams, 'minRegionArea', {
+      min: 1,
+      max: 50,
+      step: 1,
+      label: 'Min Region Area'
+    });
+    regionFolder.addBinding(this.navmeshParams, 'mergeRegionArea', {
+      min: 1,
+      max: 100,
+      step: 1,
+      label: 'Merge Region Area'
+    });
+
+    // Advanced settings folder
+    const advancedFolder = this.pane.addFolder({ title: 'Advanced Settings', expanded: false });
+    advancedFolder.addBinding(this.navmeshParams, 'maxVertsPerPoly', {
+      min: 3,
+      max: 12,
+      step: 1,
+      label: 'Max Verts Per Poly'
+    });
+    advancedFolder.addBinding(this.navmeshParams, 'detailSampleDist', {
+      min: 1,
+      max: 20,
+      step: 1,
+      label: 'Detail Sample Dist'
+    });
+    advancedFolder.addBinding(this.navmeshParams, 'detailSampleMaxError', {
+      min: 0.1,
+      max: 5.0,
+      step: 0.1,
+      label: 'Detail Max Error'
+    });
+    advancedFolder.addBinding(this.navmeshParams, 'borderSize', {
+      min: 0,
+      max: 10,
+      step: 1,
+      label: 'Border Size'
+    });
+
+    // Scene control folder
+    const sceneFolder = this.pane.addFolder({ title: 'Scene Control', expanded: true });
+    const sceneTypeControl = sceneFolder.addBinding(this.navmeshParams, 'sceneType', {
+      options: {
+        'Primitives Only': 'Primitives',
+        'GLTF Only': 'GLTF',
+        'Both Scenes': 'Both'
+      },
+      label: 'Scene Type'
+    });
+    sceneTypeControl.on('change', () => {
+      this.updateSceneVisibility();
+      // Regenerate navmesh with the new scene configuration
+      this.regenerateNavmesh();
+    });
+
+    // Debug visualization folder
+    const debugFolder = this.pane.addFolder({ title: 'Debug Visualization', expanded: true });
+    const debugToggle = debugFolder.addBinding(this.navmeshParams, 'debugEnabled', {
+      label: 'Show Debug Mesh'
+    });
+    debugToggle.on('change', () => {
+      this.toggleDebugVisualization();
+    });
+
+    console.log('Tweakpane UI created successfully');
+  }
+
+  /**
+   * Regenerate navmesh with current parameters
+   */
+  private async regenerateNavmesh(): Promise<void> {
+    console.log('Regenerating navmesh with updated parameters...');
+
+    // Clear existing debug visualization
+    this.clearDebugVisualization();
+
+    // Generate new navmesh
+    await this.generateNavmesh();
+  }
+
+  /**
+   * Export the current navmesh to a binary file
+   */
+  private async exportNavmesh(): Promise<void> {
+    this.updateStatus('Exporting navmesh to binary file...');
+
+    const navigationServer = this.world.getNavigationServer();
+    if (!navigationServer) {
+      this.updateStatus('❌ Navigation server not available');
+      return;
+    }
+
+    if (!navigationServer.isReady()) {
+      this.updateStatus('❌ No navmesh to export - generate first');
+      return;
+    }
+
+    try {
+      // Create a dummy scene path for the demo (in a real game this would be the actual scene path)
+      const demoScenePath = ENGINE.AssetPath.fromString('@project/assets/scenes/navmesh-demo.genesys-scene');
+
+      const result = await this.exportNavigationMesh(demoScenePath);
+
+      if (result.success && result.data && result.filename) {
+        // Download the NavMesh file directly to user's computer
+        const blob = new Blob([result.data], { type: 'application/octet-stream' });
+        this.downloadBlob(blob, result.filename);
+
+        this.updateStatus(`✅ NavMesh exported as ${result.filename}`);
+        console.log(`✅ NavMesh exported successfully as ${result.filename}`);
+      } else {
+        this.updateStatus('❌ Export failed');
+        console.error('❌ Failed to export navmesh');
+      }
+    } catch (error) {
+      this.updateStatus(`❌ Export error: ${error}`);
+      console.error('❌ Error during NavMesh export:', error);
+    }
+  }
+
+  /**
+   * Helper method to download a blob as a file (following lightmapping demo pattern)
+   */
+  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);
+  }
+
+  /**
+   * Opens a file dialog to select a navmesh file to import
+   */
+  private openImportDialog(): void {
+    // Create file input element for navmesh files
+    const fileInput = document.createElement('input');
+    fileInput.type = 'file';
+    fileInput.accept = '.navmesh';
+    fileInput.multiple = false;
+    fileInput.style.display = 'none';
+
+    // Handle file selection
+    fileInput.addEventListener('change', (event) => {
+      const target = event.target as HTMLInputElement;
+      const file = target.files?.[0];
+
+      if (file) {
+        this.importNavmeshFromFile(file);
+      }
+
+      // Clean up
+      document.body.removeChild(fileInput);
+    });
+
+    // Add to DOM and trigger click
+    document.body.appendChild(fileInput);
+    fileInput.click();
+  }
+
+  /**
+   * Import a navmesh from a selected file
+   */
+  private async importNavmeshFromFile(file: File): Promise<void> {
+    try {
+      this.updateStatus('📂 Loading navmesh file...');
+
+      // Read the NavMesh binary file
+      const fileData = await file.arrayBuffer();
+
+      this.updateStatus('📥 Importing navmesh data...');
+
+      // Import using the new API - can import from data directly
+      const success = await this.importNavigationMesh(fileData);
+
+      if (success) {
+        this.updateStatus(`✅ NavMesh imported from ${file.name}`);
+        console.log(`✅ NavMesh imported successfully from ${file.name}`);
+
+        // Clear and recreate debug visualization if enabled
+        if (this.navmeshParams.debugEnabled) {
+          this.clearDebugVisualization();
+          this.toggleDebugVisualization();
+        }
+      } else {
+        this.updateStatus('❌ Import failed - check console for details');
+        console.error('❌ Failed to import NavMesh');
+      }
+    } catch (error) {
+      this.updateStatus(`❌ Import error: ${error}`);
+      console.error('❌ Import failed:', error);
+    }
+  }
+
+  /**
+   * Sets a NavMesh resource reference in the current scene using the new metadata system
+   */
+  private setNavMeshReferenceInScene(): void {
+    this.updateStatus('Setting NavMesh reference in scene metadata...');
+
+    // Set the NavMesh resource reference using the new API
+    const navMeshPath = '@engine/assets/dev/navmesh-demo.navmesh';
+    this.world.setNavMeshResource(navMeshPath);
+
+    this.updateStatus(`✅ NavMesh reference set: ${navMeshPath}`);
+    console.log(`✅ NavMesh resource reference set in scene: ${navMeshPath}`);
+    console.log('Scene resources:', this.world.getSceneResources());
+  }
+
+  /**
+   * Exports the current scene with NavMesh resource metadata
+   */
+  private exportSceneWithNavMeshReference(): void {
+    this.updateStatus('Exporting scene with NavMesh resource metadata...');
+
+    try {
+      // Ensure we have a NavMesh reference set
+      if (!this.world.getSceneResources()?.navMesh) {
+        this.setNavMeshReferenceInScene();
+      }
+
+      // Export the current world/scene
+      const context = new ENGINE.WorldSerializationContext();
+      const sceneData = this.world.export(context, false);
+
+      // Convert to JSON string with nice formatting
+      const sceneJson = JSON.stringify(sceneData, null, 2);
+
+      // Create and download the scene file
+      const blob = new Blob([sceneJson], { type: 'application/json' });
+      this.downloadBlob(blob, 'navmesh-demo-with-metadata.genesys-scene');
+
+      this.updateStatus('✅ Scene exported with NavMesh resource metadata');
+      console.log('✅ Scene exported with resource metadata:', sceneData.resources);
+
+      // Log what the new system does differently
+      console.log('🆕 NEW SYSTEM FEATURES:');
+      console.log('- Scene file explicitly references NavMesh file path');
+      console.log('- No more fragile path manipulation');
+      console.log('- External tools can set resource references');
+      console.log('- Engine loads resources from explicit paths');
+      console.log('Resource metadata in scene:', sceneData.resources);
+
+    } catch (error) {
+      this.updateStatus(`❌ Scene export error: ${error}`);
+      console.error('❌ Error during scene export:', error);
+    }
+  }
+
+  /**
+   * Updates the status display in the UI
+   */
+  private updateStatus(message: string): void {
+    const statusElement = (this as any).statusElement;
+    if (statusElement) {
+      statusElement.innerHTML = `Status: ${message}`;
+    }
+  }
+
+  /**
+   * Toggle debug visualization on/off
+   */
+  private toggleDebugVisualization(): void {
+    const navigationServer = this.world.getNavigationServer();
+    if (!navigationServer) return;
+
+    if (this.navmeshParams.debugEnabled) {
+      // Show debug visualization
+      const debugVisualization = navigationServer.createDebugVisualization();
+      if (debugVisualization) {
+        debugVisualization.traverse((child) => {
+          child.raycast = () => {};
+        });
+        debugVisualization.name = 'NavmeshDebugVisualization';
+        this.world.scene.add(debugVisualization);
+        console.log('Debug visualization enabled');
+      }
+    } else {
+      // Hide debug visualization
+      this.clearDebugVisualization();
+      console.log('Debug visualization disabled');
+    }
+  }
+
+  /**
+   * Clear existing debug visualization
+   */
+  private clearDebugVisualization(): void {
+    const existingDebug = this.world.scene.getObjectByName('NavmeshDebugVisualization');
+    if (existingDebug) {
+      this.world.scene.remove(existingDebug);
+    }
+  }
+
+  /**
+   * Clean up resources when demo is destroyed
+   */
+  public override destroy(): void {
+    // Clean up debug visualization
+    this.clearDebugVisualization();
+
+    // Clean up Tweakpane
+    if (this.pane) {
+      this.pane.dispose();
+    }
+
+    super.destroy();
+  }
+}
+
+// Export the demo for use
+export default NavmeshPrimitivesDemo;