@directivegames/genesys.js 3.1.24

package/src/game/World.ts

@@ -0,0 +1,1430 @@
+/**
+ * World represents the entire runtime scene and all systems that operate within it.
+ *
+ * Detailed explanation:
+ * - Owns the Three.js scene graph, manages arrays of actors and coordinates their lifecycles.
+ * - Creates and controls global services including input, timers, physics, navigation and networking.
+ * - The tick method advances simulation, handles network replication and processes queued actor removals.
+ * - Supports serialization via WorldSerializer and produces debug nodes for editor tooling.
+ * - Manages camera references for rendering and exposes helpers to spawn basic shapes and geometry.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Instantiate a World in your game loop with physics and navigation options suited to the project.
+ * - Add or remove actors using the provided methods instead of manipulating the scene directly.
+ * - Query actors with getActors or getFirstActor when implementing gameplay logic.
+ * - Avoid spawning player controllers before beginPlay since they rely on world initialization.
+ */
+import * as THREE from 'three';
+
+import { Actor } from '../actors/Actor.js';
+import { GlobalParticleManager } from '../actors/GlobalParticleManager.js';
+import { PlayerController } from '../actors/PlayerController.js';
+import { GLTFMeshComponent, LightComponent } from '../components/index.js';
+import { MeshComponent } from '../components/visual/MeshComponent.js';
+import { ENABLE_LIGHTMAPS } from '../const.js';
+import { ManifoldWrapper } from '../csg/ManifoldWrapper.js';
+import { NetWorld } from '../multiplayer/index.js';
+import { createNavigationServer } from '../navigation/NavigationServer.js';
+import { createPhysicsEngine } from '../physics/PhysicsEngine.js';
+import { PhysicsMotionType } from '../physics/PhysicsTypes.js';
+import { LightmapManager } from '../render/lightmapping/LightmapManager.js';
+import { type PostProcessConfiguration, PostProcessManager } from '../render/PostProcessManager.js';
+import { PluginManager } from '../scripting/PluginManager.js';
+import { ClassRegistry, EngineClass } from '../systems/ClassRegistry.js';
+import { ConsoleCommand, ConsoleManager } from '../systems/ConsoleManager.js';
+import { ConsoleVariableHandler } from '../systems/ConsoleVariableHandler.js';
+import { InputManager } from '../systems/InputManager.js';
+import { ObjectNamingSystem } from '../systems/ObjectNamingSystem.js';
+import { StatsDisplay } from '../systems/Stats.js';
+import { TimerSystem } from '../systems/TimerSystem.js';
+import { TweenManager } from '../systems/TweenManager.js';
+import { WorldSerializer } from '../systems/WorldSerialization.js';
+import { UIManager } from '../ui/UIManager.js';
+import { GlobalAudioManager } from '../utils/GlobalAudioManager.js';
+import { resourceManager } from '../utils/ResourceManager.js';
+import { SceneGraphUtils } from '../utils/SceneGraphUtils.js';
+import { property } from '../utils/serialization/decorator.js';
+import { ISerializableObjectTag } from '../utils/serialization/serializable.js';
+import { isNode } from '../utils/Utils.js';
+import { ensure, shortUUID } from '../utils/Utils.js';
+
+import { GameMode } from './GameMode.js';
+import { Playable, PlayState } from './Playable.js';
+
+import type { BaseGameLoop } from './GameLoop.js';
+import type { Pawn } from '../actors/Pawn.js';
+import type { SkyboxComponent } from '../components/index.js';
+import type { SceneComponent } from '../components/SceneComponent.js';
+import type { INavigationServer, NavigationOptions } from '../navigation/NavigationServer.js';
+import type { IPhysicsEngine, PhysicsOptions } from '../physics/PhysicsEngine.js';
+import type { AssetPath } from '../storage/storageProvider.js';
+import type { ISerializable, SceneResources, SerializedWorld, WorldSerializationContext } from '../systems/WorldSerialization';
+import type { Delegate } from '../utils/Delegate.js';
+import type { ISceneGraphDebugNodeGenerator, SceneGraphDebugNode } from '../utils/SceneGraphUtils';
+import type { Dumper, Loader } from '../utils/serialization/serializer.js';
+
+export interface WorldOptions {
+  rendererDomElement: HTMLElement;
+  gameContainer: HTMLElement;
+  backgroundColor?: THREE.ColorRepresentation;
+  physicsOptions: PhysicsOptions
+  navigationOptions: NavigationOptions
+  useManifold?: boolean;
+  gameMode?: GameMode;
+  enableGamepad?: boolean;
+  gameId?: string;
+  gameLoop?: WeakRef<BaseGameLoop>;
+}
+
+export interface WorldDescriptionOptions {
+  // actor IDs, if specified, actors not in this list will be omitted and only contain basic uuid and name info
+  specifiedActors?: string[];
+
+  // whether to include the actor's components in the description
+  includeComponentsDetails?: boolean;
+}
+
+export interface RenderWindowSize {
+  width: number;
+  height: number;
+}
+
+export type GenericWorldDelegate = Delegate<[World], void>;
+
+@EngineClass('World')
+export class World extends Playable implements ISceneGraphDebugNodeGenerator, ISerializable {
+  readonly [ISerializableObjectTag] = true;
+
+  public readonly postProcessManager: PostProcessManager = new PostProcessManager();
+
+  public readonly uuid: string = shortUUID();
+  public readonly name: string;
+  public readonly scene: THREE.Scene;
+  public readonly inputManager: InputManager;
+  public readonly consoleManager: ConsoleManager;
+  public readonly timerSystem: TimerSystem;
+  public readonly tweenManager: TweenManager;
+  public readonly uiManager: UIManager;
+  public readonly gameMode: GameMode;
+  public readonly pluginManager: PluginManager;
+  private lastCameraWarningTime: number = 0;
+  public readonly netWorld: NetWorld;
+  public readonly audioListener: THREE.AudioListener | null;
+  public readonly globalAudioManager: GlobalAudioManager;
+  public readonly globalParticleManager: GlobalParticleManager;
+  public editorData: Record<string, any> = {};
+  public isEditorWorld: boolean = false;
+  public sceneResources: SceneResources | null = null;
+  public postProcessConfiguration: PostProcessConfiguration | null = null;
+
+  private actors: Actor[] = [];
+  private playerControllers: PlayerController[] = [];
+  private physicsEngine: IPhysicsEngine | null = null;
+  private navigationServer: INavigationServer | null = null;
+  private manifold: ManifoldWrapper | null = null;
+  private lightmapManager: LightmapManager | null = null;
+  private navigationMeshVisualization: THREE.Group | null = null;
+
+  // if valid for physics engine to be null if the user doesn't want it, so use a separate flag to track
+  private navigationServerCreated: boolean = false;
+  private physicsEngineCreated: boolean = false;
+  private manifoldCreated: boolean = false;
+  private lightmapManagerCreated: boolean = false;
+  private isTicking: boolean = false;
+  private actorsToRemove: Actor[] = [];
+  private hiddenInGameActors: Set<Actor> = new Set();
+  private hiddenInGameSceneComponents: Set<SceneComponent> = new Set();
+  private isPaused: boolean = false;
+  private slomo: number = 1;
+  private gameTime: number = 0;
+  private overrideCamera: THREE.Camera | null = null;
+  // the camera actor that is used for rendering the world
+  private skyboxComponent: SkyboxComponent | null = null;
+  private renderWindowSize: RenderWindowSize | null = null;
+  private nextTickFunctions: (() => void)[] = [];
+  private statsDisplay: StatsDisplay;
+
+  /**
+   * The camera used for rendering the world
+   */
+  public camera: THREE.Camera | null = null;
+
+  /**
+   * A fallback camera used when no active camera is available
+   */
+  private fallbackCamera: THREE.PerspectiveCamera;
+
+  /**
+     * Creates a new World instance
+     * @param options - Configuration options for the world including:
+     *                  - rendererDomElement: HTML element to attach the renderer to
+     *                  - backgroundColor: Optional background color for the scene
+     *                  - physicsOptions: Configuration for the physics engine
+     */
+  constructor(readonly options: WorldOptions) {
+    super();
+    this.netWorld = new NetWorld(this, options.gameId ?? 'default');
+    this.name = ObjectNamingSystem.generateName(this);
+    this.scene = new THREE.Scene();
+    this.scene.setWorld(this);
+    this.scene.background = new THREE.Color(options.backgroundColor);
+    this.actors = [];
+    this.inputManager = new InputManager({
+      rendererDomElement: options.rendererDomElement,
+      gameContainer: options.gameContainer,
+      world: new WeakRef(this),
+      enableGamepad: options.enableGamepad
+    });
+    this.timerSystem = new TimerSystem({
+      world: this
+    });
+    this.tweenManager = new TweenManager(this);
+    this.consoleManager = new ConsoleManager();
+    this.inputManager.addInputHandler(this.consoleManager);
+
+    // Register console variable handler for CVar system
+    this.consoleManager.addCommandHandler(new ConsoleVariableHandler());
+
+    // Register stats console handler
+    this.statsDisplay = new StatsDisplay(options.gameContainer);
+
+    this.uiManager = new UIManager({
+      container: options.gameContainer
+    });
+    this.inputManager.addInputHandler(this.uiManager);
+
+    this.gameMode = options.gameMode ?? new GameMode({});
+    this.gameMode.setWorld(this);
+
+    this.audioListener = !isNode() ? new THREE.AudioListener() : null;
+
+    this.globalAudioManager = GlobalAudioManager.getInstance();
+    this.globalAudioManager.setWorld(this);
+
+    // the global particle manager is never saved
+    this.globalParticleManager = new GlobalParticleManager();
+    this.globalParticleManager.setTransient(true);
+    this.addActors(this.globalParticleManager);
+
+    this.fallbackCamera = new THREE.PerspectiveCamera(75, 1, 0.1, 1000);
+    // Position the fallback camera at a reasonable default location
+    this.fallbackCamera.position.set(0, 5, 10);
+    this.fallbackCamera.lookAt(0, 0, 0);
+
+    this.pluginManager = new PluginManager(new WeakRef(this));
+  }
+
+  public export(context: WorldSerializationContext, includeDefaults: boolean): SerializedWorld {
+    return {
+      class: ClassRegistry.getClassNameChecked(this),
+      uuid: this.uuid,
+      ctor: context.exportObject(this.options, includeDefaults),
+      actors: this.actors.map(actor => context.exportObject(actor, includeDefaults)).filter(actor => !!actor),
+      resources: this.sceneResources ?? undefined,
+      properties: {
+        editorData: this.editorData,
+        postProcessConfiguration: this.postProcessConfiguration
+      }
+    };
+  }
+
+  public serialize(dumper: Dumper): void {
+    dumper.dumpValue('$uuid', this.uuid);
+    dumper.dumpValue('actors', this.actors.filter(actor => !!actor));
+    dumper.dumpValue('resources', this.sceneResources);
+    dumper.dumpValue('editorData', this.editorData);
+    dumper.dumpValue('postProcessConfiguration', this.postProcessConfiguration);
+
+    dumper.dumpProperties(this);
+  }
+
+  public deserialize(loader: Loader): void {
+    (this as any).uuid = loader.loadValue('$uuid') ?? this.uuid;
+
+    this.sceneResources = loader.loadValue('resources', this.sceneResources);
+    this.editorData = loader.loadValue('editorData', this.editorData);
+    this.postProcessConfiguration = loader.loadValue('postProcessConfiguration', this.postProcessConfiguration);
+
+    // I could do,
+    // ```
+    // const actors = [...this.actors];
+    // loader.loadValue('actors', actors);
+    // ```
+    // expecting the loader to populate into some existing actor, but let's assume that world is clean when loaded for now
+    const actors: Actor[] = loader.loadValue('actors');
+    const newlyLoadedActors = actors.filter(actor => actor && !this.actors.includes(actor));
+    this.addActors(...newlyLoadedActors);
+
+    loader.loadProperties(this);
+  }
+
+
+  /**
+   * The container element that holds the game UI and game content
+   */
+  public get gameContainer(): HTMLElement {
+    return this.options.gameContainer;
+  }
+
+  /**
+   * Gets the game loop
+   * @returns The game loop
+   */
+  public get gameLoop(): BaseGameLoop | null {
+    return this.options.gameLoop?.deref() ?? null;
+  }
+
+  /**
+   * Gets the render window size
+   * @returns The render window size
+   */
+  public getRenderWindowSize(): RenderWindowSize | null {
+    return this.renderWindowSize;
+  }
+
+  /**
+   * Sets the lightmap resource references for this scene.
+   * Used by external tools to configure lightmap file paths.
+   */
+  public setLightmapResources(metadataPath: string, texturePath: string): void {
+    this.sceneResources ??= {};
+    this.sceneResources.lightmap = {
+      metadataPath,
+      texturePath
+    };
+  }
+
+  /**
+   * Sets the NavMesh resource reference for this scene.
+   * Used by external tools to configure NavMesh file path.
+   */
+  public setNavMeshResource(path: string): void {
+    this.sceneResources ??= {};
+    this.sceneResources.navMesh = {
+      path
+    };
+  }
+
+  /**
+   * Clears lightmap resource references for this scene.
+   */
+  public clearLightmapResources(): void {
+    if (this.sceneResources) {
+      this.sceneResources.lightmap = undefined;
+    }
+  }
+
+  /**
+   * Clears NavMesh resource reference for this scene.
+   */
+  public clearNavMeshResource(): void {
+    if (this.sceneResources) {
+      this.sceneResources.navMesh = undefined;
+    }
+  }
+
+  /**
+   * Gets the current scene resource configuration.
+   */
+  public getSceneResources(): SceneResources | null {
+    return this.sceneResources;
+  }
+
+  /**
+   * Gets the current post-processing configuration.
+   */
+  public getPostProcessConfiguration(): PostProcessConfiguration | null {
+    return this.postProcessConfiguration;
+  }
+
+  /**
+   * Sets the post-processing configuration (merges with defaults).
+   * @param config - The post-processing configuration to set
+   */
+  public setPostProcessConfiguration(config: PostProcessConfiguration | null): void {
+    this.postProcessConfiguration = config;
+    if (config) {
+      this.postProcessManager.setConfiguration(config);
+    }
+  }
+
+  /**
+   * Updates the post-processing configuration (merges with current).
+   * @param config - The post-processing configuration to update
+   */
+  public updatePostProcessConfiguration(config: PostProcessConfiguration): void {
+    if (this.postProcessConfiguration) {
+      // Merge with existing configuration
+      const mergedEffects = [...this.postProcessConfiguration.effects];
+      for (const newEffect of config.effects) {
+        const existingIndex = mergedEffects.findIndex(e => e.type === newEffect.type);
+        if (existingIndex >= 0) {
+          mergedEffects[existingIndex] = { ...mergedEffects[existingIndex], ...newEffect };
+        } else {
+          mergedEffects.push(newEffect);
+        }
+      }
+      this.postProcessConfiguration = { effects: mergedEffects };
+    } else {
+      this.postProcessConfiguration = config;
+    }
+    this.postProcessManager.updateConfiguration(config);
+  }
+
+  /**
+   * Adds an actor to the world
+   * @param actor The actor to add
+   * @returns This world instance for method chaining
+   */
+  public addActor(actor: Actor): this {
+    return this.addActors(actor);
+  }
+
+  /**
+   * Adds one or more actors to the world
+   * @param actors The actors to add
+   * @returns This world instance for method chaining
+   */
+  public addActors(...actors: Actor[]): this {
+    if (!ensure(!this.isPlayEnded())) {
+      return this;
+    }
+
+    actors.forEach(actor => {
+      if (!ensure(!this.actors.includes(actor))) {
+        return;
+      }
+      this.actors.push(actor);
+      actor.setWorld(this);
+      this.scene.add(actor.rootComponent);
+      if (this.isPlaying()) {
+        actor.beginPlay();
+      }
+      if (actor instanceof PlayerController) {
+        if (this.playerControllers.length) {
+          throw new Error('Only one player controller is allowed in the world');
+        }
+        this.playerControllers.push(actor);
+      }
+      if (this.isEditorWorld) {
+        actor.onEditorAddToWorld();
+        this.onEditorActorAddToWorld?.(actor);
+      }
+    });
+
+    return this;
+  }
+
+  /**
+     * Gets the current physics engine instance
+     * @returns The physics engine instance if available, otherwise null
+     */
+  public getPhysicsEngine(): IPhysicsEngine | null {
+    return this.physicsEngine;
+  }
+
+  public getNavigationServer(): INavigationServer | null {
+    return this.navigationServer;
+  }
+
+  /**
+   * Creates a navigation mesh from the current scene.
+   * This method waits for both the scene to be fully loaded and all GLTF meshes to be loaded
+   * before generating the navigation mesh from actors with GLTFMeshComponents that are set to static motion type.
+   */
+  public async createNavigationMeshFromScene(): Promise<void> {
+    if (!this.navigationServerCreated) {
+      throw new Error('[Navigation Server] Navigation server not created');
+    }
+
+    const navigationServer = this.getNavigationServer();
+    if (!navigationServer) {
+      console.error('[Navigation Server] createNavigationMeshFromScene: Navigation server not available');
+      return;
+    }
+
+    const meshes: THREE.Mesh[] = [];
+
+    // gather all the relevant gltf mesh components
+    let gltfMeshComponents: GLTFMeshComponent[] = [];
+    for (const actor of this.actors) {
+      gltfMeshComponents.push(...actor.getComponents(GLTFMeshComponent));
+    }
+    gltfMeshComponents = gltfMeshComponents.filter(component => component.getPhysicsOptions()?.motionType === PhysicsMotionType.Static && !component.options.excludeFromNavigation);
+
+    if (gltfMeshComponents.length > 0) {
+      // wait for all the models to be loaded
+      await Promise.all(Object.values(resourceManager.getCachedModels()));
+      // Extract meshes from GLTFMeshComponents
+      for (const component of gltfMeshComponents) {
+        meshes.push(...component.getAllMeshes());
+      }
+    }
+
+    // gather all the relevant mesh components
+    let meshComponents: MeshComponent[] = [];
+    for (const actor of this.actors) {
+      meshComponents.push(...actor.getComponents(MeshComponent));
+    }
+    meshComponents = meshComponents.filter(component => component.getPhysicsOptions()?.motionType === PhysicsMotionType.Static && !component.options.excludeFromNavigation);
+    for (const component of meshComponents) {
+      meshes.push(component.getMesh());
+    }
+
+    if (meshes.length === 0) {
+      console.warn('[Navigation Server] No meshes found for navigation mesh generation');
+      return;
+    }
+
+    const success = await navigationServer.createNavigationMeshFromMeshes(meshes);
+    if (success) {
+      console.log('[Navigation Server] Navigation mesh created successfully');
+    }
+    else {
+      console.error('[Navigation Server] Failed to create navigation mesh');
+    }
+  }
+
+  /**
+   * Export the current navigation mesh to a binary file
+   * @param scenePath The path to the scene file (used to determine navmesh file path)
+   * @returns Promise resolving to export result with data and filename
+   */
+  public async exportNavigationMesh(scenePath: AssetPath): Promise<{ success: boolean; data?: ArrayBuffer; filename?: string }> {
+    const navigationServer = this.getNavigationServer();
+    if (!navigationServer) {
+      console.error('[World] exportNavigationMesh: Navigation server not available');
+      return { success: false };
+    }
+
+    return await navigationServer.exportNavigationMesh(scenePath);
+  }
+
+  /**
+   * Import a navigation mesh from a binary file
+   * @param scenePath The path to the scene file (used to determine navmesh file path)
+   * @returns Promise resolving to success/failure
+   */
+  public async importNavigationMesh(scenePath: AssetPath): Promise<boolean> {
+    const navigationServer = this.getNavigationServer();
+    if (!navigationServer) {
+      console.error('[World] importNavigationMesh: Navigation server not available');
+      return false;
+    }
+
+    return await navigationServer.importNavigationMesh(scenePath);
+  }
+
+  /**
+   * Import a navigation mesh from binary data directly
+   * @param navMeshData The NavMesh binary data as ArrayBuffer
+   * @returns Promise resolving to success/failure
+   */
+  public async importNavigationMeshFromData(navMeshData: ArrayBuffer): Promise<boolean> {
+    const navigationServer = this.getNavigationServer();
+    if (!navigationServer) {
+      console.error('[World] importNavigationMeshFromData: Navigation server not available');
+      return false;
+    }
+
+    return await navigationServer.importNavigationMeshFromData(navMeshData);
+  }
+
+  /**
+   * Clear the current navigation mesh
+   */
+  public clearNavigationMesh(): void {
+    const navigationServer = this.getNavigationServer();
+    if (!navigationServer) {
+      console.error('[World] clearNavigationMesh: Navigation server not available');
+      return;
+    }
+
+    navigationServer.clearNavigationMesh();
+  }
+
+  public getManifold(): ManifoldWrapper | null {
+    return this.manifold;
+  }
+
+  /**
+   * Removes an actor from the world
+   * @param actor The actor to remove
+   * @returns This world instance for method chaining
+   */
+  public removeActor(actor: Actor): this {
+    return this.removeActors(actor);
+  }
+
+  /**
+   * Removes one or more actors from the world
+   * @param actors - The actors to remove
+   * @returns This world instance for method chaining
+   */
+  public removeActors(...actors: Actor[]): this {
+    if (!ensure(!this.isPlayEnded())) {
+      return this;
+    }
+
+    if (this.isTicking) {
+      this.actorsToRemove.push(...actors);
+      return this;
+    }
+
+    actors.forEach(actor => {
+      const index = this.actors.indexOf(actor);
+      if (ensure(index !== -1, `${actor.getPathName()} not found in world`)) {
+        if (this.isPlaying()) {
+          actor.endPlay();
+        }
+        if (this.isEditorWorld) {
+          actor.onEditorRemoveFromWorld();
+          this.onEditorActorRemoveFromWorld?.(actor);
+        }
+        actor.setWorld(null);
+        this.actors.splice(index, 1);
+        this.scene.remove(actor.rootComponent);
+        if (actor instanceof PlayerController) {
+          const index = this.playerControllers.indexOf(actor);
+          if (index !== -1) {
+            this.playerControllers.splice(index, 1);
+          }
+        }
+      }
+    });
+
+    return this;
+  }
+
+  /**
+   * Schedules a function to be executed at the beginning of the next tick
+   * @param fn - The function to execute next tick
+   */
+  public runInNextTick(fn: () => void): void {
+    this.nextTickFunctions.push(fn);
+  }
+
+  /**
+     * Updates the world state for the current frame
+     * @param deltaTime - Time elapsed since last frame in seconds
+     */
+  public tick(deltaTime: number): void {
+    deltaTime *= this.slomo;
+    if (this.playState !== PlayState.Playing) {
+      return;
+    }
+
+    if (this.isPaused) {
+      return;
+    }
+
+    if (deltaTime <= 0) {
+      return;
+    }
+
+    this.gameTime += deltaTime;
+    this.isTicking = true;
+
+    // Execute functions scheduled for this tick
+    if (this.nextTickFunctions.length > 0) {
+      const functionsToExecute = [...this.nextTickFunctions];
+      this.nextTickFunctions = [];
+      for (const fn of functionsToExecute) {
+        try {
+          fn();
+        } catch (error) {
+          console.error('Error executing next tick function:', error);
+        }
+      }
+    }
+
+    // Process timer events before physics
+    this.timerSystem.tick(deltaTime);
+
+    // Update all managed tweens
+    this.tweenManager.update(deltaTime);
+
+    this.gameMode.tick(deltaTime);
+
+    for (const actor of this.actors) {
+      actor.tickPrePhysics(deltaTime);
+    }
+
+    if (this.physicsEngine) {
+      this.physicsEngine.tick(deltaTime);
+    }
+
+    for (const actor of this.actors) {
+      actor.tickPostPhysics(deltaTime);
+    }
+
+    this.netWorld.tick(deltaTime);
+
+    this.statsDisplay.tick();
+
+    // Ensure the audio listener is attached to the correct camera
+    const camera = this.getActiveCamera();
+    if (camera && this.audioListener && this.audioListener.parent != camera) {
+
+      camera.add(this.audioListener);
+      camera.getActor()?.onPreEndPlay.add((cameraActor) => {
+        this.audioListener?.removeFromParent();
+      });
+    }
+
+    this.isTicking = false;
+    this.removeActors(...this.actorsToRemove);
+    this.actorsToRemove = [];
+  }
+
+  /**
+   * Creates the physics engine
+   * @returns A promise that resolves when the physics engine is created
+   */
+  public async createPhysicsEngine(): Promise<void> {
+    if (this.physicsEngineCreated) {
+      throw new Error('Physics engine already created');
+    }
+
+    this.physicsEngine = await createPhysicsEngine(this.options.physicsOptions, this);
+    console.log('Physics engine created:', ClassRegistry.getClassOrConstructorName(this.physicsEngine));
+    this.physicsEngineCreated = true;
+  }
+
+  public async createManifold(): Promise<void> {
+    if (this.manifoldCreated) {
+      throw new Error('Manifold already created');
+    }
+
+    if (!this.options.useManifold) {
+      return;
+    }
+
+    this.manifold = new ManifoldWrapper();
+    await this.manifold?.initManifold();
+    this.manifoldCreated = true;
+  }
+
+  public async createNavigationServer(): Promise<void> {
+    if (this.navigationServerCreated) {
+      throw new Error('Navigation server already created');
+    }
+
+    this.navigationServer = await createNavigationServer(this.options.navigationOptions);
+    console.log('Navigation server created:', this.navigationServer);
+    this.navigationServerCreated = true;
+  }
+
+  /**
+   * Creates the lightmap manager
+   * @returns A promise that resolves when the lightmap manager is created
+   */
+  public async createLightmapManager(renderer?: any): Promise<void> {
+    if (this.lightmapManagerCreated || !ENABLE_LIGHTMAPS) {
+      return; // Already created, just return
+    }
+
+    try {
+      if (!renderer) {
+        console.warn('No renderer provided for lightmap manager creation');
+        return;
+      }
+
+      this.lightmapManager = new LightmapManager(this, renderer, {
+        autoApply: true,
+        progressiveBaking: true,
+      });
+
+      await this.lightmapManager.initialize();
+      console.log('Lightmap manager created and initialized');
+      this.lightmapManagerCreated = true;
+    } catch (error) {
+      console.warn('Failed to create lightmap manager:', error);
+      // Don't set lightmapManagerCreated to true if initialization failed
+      this.lightmapManager = null;
+    }
+  }
+
+  /**
+   * Gets the lightmap manager
+   * @returns The lightmap manager if created, otherwise null
+   */
+  public getLightmapManager(): LightmapManager | null {
+    return this.lightmapManager;
+  }
+
+  /**
+   * Generates a debug node for the world
+   * @returns A debug node for the world
+   */
+  public generateDebugNode(): SceneGraphDebugNode | null {
+    const children: (SceneGraphDebugNode | null)[] = [];
+    children.push(this.gameMode.generateDebugNode());
+    for (const actor of this.actors) {
+      children.push(actor.generateDebugNode());
+    }
+    return {
+      title: this.name,
+      children,
+      data: {
+        uuid: this.uuid,
+        ...this.options
+      }
+    };
+  }
+
+  /**
+   * Gets the first actor of a specified type
+   * @param type - The type of actor to search for
+   * @returns The first actor of the specified type or null if no such actor exists
+   */
+  public getFirstActor<T extends Actor>(type: new (...args: any[]) => T): T | null {
+    return this.actors.find(actor => actor instanceof type) as T | null;
+  }
+
+  /**
+   * Gets the first component of a specified type
+   * @param type - The type of component to search for
+   * @returns The first component of the specified type or null if no such component exists
+   */
+  public getComponent<T extends SceneComponent>(type: new (...args: any[]) => T): T | null {
+    for (const actor of this.actors) {
+      const component = actor.getComponent(type);
+      if (component) {
+        return component;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Gets all actors of a specified type
+   * @param type - The type of actor to search for
+   * @returns An array of all actors of the specified type
+   */
+  public getActors<T extends Actor>(type: abstract new (...args: any[]) => T = Actor as any): T[] {
+    return this.actors.filter(actor => actor instanceof type) as T[];
+  }
+
+  /**
+   * Gets an actor by its UUID
+   * @param uuid - The UUID of the actor to search for
+   * @returns The actor with the specified UUID or null if no such actor exists
+   */
+  public getActorByUuid<T extends Actor>(uuid: string): T | null {
+    return this.actors.find(actor => actor.uuid === uuid) as T | null;
+  }
+
+  /**
+   * Gets all actors that match a predicate
+   * @param predicate - The predicate to match
+   * @returns An array of all actors that match the predicate
+   */
+  public getActorsByPredicate(predicate: (actor: Actor) => boolean): Actor[] {
+    return this.actors.filter(predicate);
+  }
+
+  /**
+   * Gets the first actor with the specified tag
+   * @param tag - The tag to search for
+   * @returns The first actor with the specified tag or null if no such actor exists
+   */
+  public getFirstActorByTag(tag: string): Actor | null {
+    return this.actors.find(actor => actor.hasActorTag(tag)) ?? null;
+  }
+
+  /**
+   * Gets all actors with the specified tag
+   * @param tag - The tag to search for
+   * @returns An array of all actors with the specified tag
+   */
+  public getActorsByTag(tag: string): Actor[] {
+    return this.actors.filter(actor => actor.hasActorTag(tag));
+  }
+
+  /**
+   * Gets the first actor that has any of the specified tags
+   * @param tags - The tags to search for
+   * @returns The first actor with any of the specified tags or null if no such actor exists
+   */
+  public getFirstActorByAnyTag(tags: string[]): Actor | null {
+    return this.actors.find(actor => actor.hasAnyActorTag(tags)) ?? null;
+  }
+
+  /**
+   * Gets all actors that have any of the specified tags
+   * @param tags - The tags to search for
+   * @returns An array of all actors with any of the specified tags
+   */
+  public getActorsByAnyTag(tags: string[]): Actor[] {
+    return this.actors.filter(actor => actor.hasAnyActorTag(tags));
+  }
+
+  /**
+   * Gets the first actor that has all of the specified tags
+   * @param tags - The tags to search for
+   * @returns The first actor with all of the specified tags or null if no such actor exists
+   */
+  public getFirstActorByAllTags(tags: string[]): Actor | null {
+    return this.actors.find(actor => actor.hasAllActorTags(tags)) ?? null;
+  }
+
+  /**
+   * Gets all actors that have all of the specified tags
+   * @param tags - The tags to search for
+   * @returns An array of all actors with all of the specified tags
+   */
+  public getActorsByAllTags(tags: string[]): Actor[] {
+    return this.actors.filter(actor => actor.hasAllActorTags(tags));
+  }
+
+  /**
+   * Gets the first player pawn in the world
+   * @returns The first player pawn in the world or null if no player pawn exists
+   */
+  public getFirstPlayerPawn(): Pawn | null {
+    return this.getFirstActor(PlayerController)?.getPawn() ?? null;
+  }
+
+  /**
+   * Clears the world
+   */
+  public clearWorld(): void {
+    this.removeActors(...this.actors);
+    this.actors = [];
+    this.scene.remove(...this.scene.children);
+
+    if (this.isEditorWorld) {
+      this.onEditorActorAddToWorld = undefined;
+      this.onEditorActorRemoveFromWorld = undefined;
+    }
+  }
+
+  /**
+   * Gets the path name of the world
+   * @returns The path name of the world
+   */
+  public getPathName(): string {
+    return this.name;
+  }
+
+  /**
+   * Adds a box to the world
+   * @param options - The options for the box
+   * @returns The actor that was created
+   */
+  public addBox(options: {
+    position?: THREE.Vector3,
+    rotation?: THREE.Euler,
+    scale?: THREE.Vector3,
+    width?: number,
+    height?: number,
+    depth?: number,
+    color?: THREE.ColorRepresentation,
+    motionType?: PhysicsMotionType
+  }): Actor {
+    return this.addBasicGeometry({
+      ...options,
+      geometry: new THREE.BoxGeometry(options.width, options.height, options.depth),
+    });
+  }
+
+  /**
+   * Adds a sphere to the world
+   * @param options - The options for the sphere
+   * @returns The actor that was created
+   */
+  public addSphere(options: {
+    position?: THREE.Vector3,
+    rotation?: THREE.Euler,
+    scale?: THREE.Vector3,
+    radius?: number,
+    color?: THREE.ColorRepresentation,
+    motionType?: PhysicsMotionType
+  }): Actor {
+    return this.addBasicGeometry({
+      ...options,
+      geometry: new THREE.SphereGeometry(options.radius),
+    });
+  }
+
+  /**
+   * Adds a capsule to the world
+   * @param options - The options for the capsule
+   * @returns The actor that was created
+   */
+  public addCapsule(options: {
+    position?: THREE.Vector3,
+    rotation?: THREE.Euler,
+    scale?: THREE.Vector3,
+    radius?: number,
+    height?: number,
+    color?: THREE.ColorRepresentation,
+    motionType?: PhysicsMotionType
+  }): Actor {
+    return this.addBasicGeometry({
+      ...options,
+      geometry: new THREE.CapsuleGeometry(options.radius, options.height),
+    });
+  }
+
+  /**
+   * Adds a cylinder to the world
+   * @param options - The options for the cylinder
+   * @returns The actor that was created
+   */
+  public addCylinder(options: {
+    position?: THREE.Vector3,
+    rotation?: THREE.Euler,
+    scale?: THREE.Vector3,
+    radius?: number,
+    height?: number,
+    color?: THREE.ColorRepresentation,
+    motionType?: PhysicsMotionType
+  }): Actor {
+    return this.addBasicGeometry({
+      ...options,
+      geometry: new THREE.CylinderGeometry(options.radius, options.radius, options.height),
+    });
+  }
+
+  /**
+   * Adds a cone to the world
+   * @param options - The options for the cone
+   * @returns The actor that was created
+   */
+  public addCone(options: {
+    position?: THREE.Vector3,
+    rotation?: THREE.Euler,
+    scale?: THREE.Vector3,
+    radius?: number,
+    height?: number,
+    color?: THREE.ColorRepresentation,
+    motionType?: PhysicsMotionType
+  }): Actor {
+    return this.addBasicGeometry({
+      ...options,
+      geometry: new THREE.ConeGeometry(options.radius, options.height),
+    });
+  }
+
+  /**
+   * Adds a basic geometry to the world
+   * @param options - The options for the geometry
+   * @returns The actor that was created
+   */
+  public addBasicGeometry(options: {
+    position?: THREE.Vector3,
+    rotation?: THREE.Euler,
+    scale?: THREE.Vector3,
+    geometry: THREE.BufferGeometry,
+    color?: THREE.ColorRepresentation,
+    motionType?: PhysicsMotionType
+  }): Actor {
+    const actor = new Actor({
+      rootComponent: new MeshComponent({
+        position: options.position,
+        rotation: options.rotation,
+        scale: options.scale,
+        geometry: options.geometry,
+        material: new THREE.MeshStandardMaterial({ color: options.color }),
+        physicsOptions: {
+          enabled: !!options.motionType,
+          motionType: options.motionType
+        }
+      })
+    });
+    this.addActors(actor);
+    return actor;
+  }
+
+  /**
+   * Adds an axes helper to the world
+   * @param options - The options for the axes helper
+   * @returns The actor that was created
+   */
+  public addAxesHelper(options: {
+    position?: THREE.Vector3,
+    rotation?: THREE.Euler,
+    size?: number,
+  }): Actor {
+    const actor = new Actor({
+      position: options.position,
+      rotation: options.rotation,
+    });
+    actor.rootComponent.add(new THREE.AxesHelper(options.size));
+    this.addActors(actor);
+    return actor;
+  }
+
+  /**
+   * Returns an exported object representation of the world
+   * @param includeDefaults Whether to include default values
+   * @returns An exported object representation of the world
+   */
+  public asExportedObject(includeDefaults: boolean = false): any {
+    return WorldSerializer.exportObject(this, includeDefaults);
+  }
+
+  /**
+   * Gets the game time
+   * @returns The game time
+   */
+  public getGameTime(): number {
+    return this.gameTime;
+  }
+
+  /**
+   * Gets the active camera to render the scene
+   * @returns The active camera
+   */
+  public getActiveCamera(): THREE.Camera | null {
+    if (this.overrideCamera) {
+      return this.overrideCamera;
+    }
+
+    return this.playerControllers[0]?.getCamera() ?? null;
+  }
+
+  /**
+   * Renders the scene
+   * @param renderer - The renderer to use
+   */
+  public renderScene(renderer: THREE.WebGLRenderer, windowSize: RenderWindowSize) {
+    const camera = this.getActiveCamera();
+    if (!camera) {
+      this.logCameraWarning();
+    }
+
+    this.renderWindowSize = windowSize;
+    const cameraToUse = camera ?? this.fallbackCamera;
+
+    if (cameraToUse instanceof THREE.PerspectiveCamera) {
+      cameraToUse.aspect = windowSize.width / windowSize.height;
+      cameraToUse.updateProjectionMatrix();
+    }
+
+    this.postProcessManager.renderScene(renderer, this.scene, cameraToUse, windowSize);
+  }
+
+  /**
+   * Logs a warning when no camera is found, throttled to every 10 seconds
+   */
+  private logCameraWarning(): void {
+    const currentTime = Date.now();
+    // Only log warning every 10 seconds (10000ms)
+    if (currentTime - this.lastCameraWarningTime >= 10000) {
+      console.warn('No camera found. Please add a three.js camera to your pawn or set one using "world.setOverrideCamera(camera)".');
+      this.lastCameraWarningTime = currentTime;
+    }
+  }
+
+  /**
+   * Gets the override camera
+   * @returns The override camera
+   */
+  public getOverrideCamera(): THREE.Camera | null {
+    return this.overrideCamera;
+  }
+
+  /**
+   * Sets the override camera
+   * @param camera - The camera to set
+   */
+  public setOverrideCamera(camera: THREE.Camera | null): void {
+    this.overrideCamera = camera;
+  }
+
+  /**
+   * Gets the skybox component
+   * @returns The skybox component
+   */
+  public getSkyboxComponent(): SkyboxComponent | null {
+    return this.skyboxComponent;
+  }
+
+  /**
+   * Sets the skybox component
+   * @param component - The skybox component to set
+   */
+  public setSkyboxComponent(component: SkyboxComponent | null): void {
+    if (this.skyboxComponent && component && this.skyboxComponent !== component) {
+      ensure(false, 'Skybox component already set, cannot set another');
+      return;
+    }
+    this.skyboxComponent = component;
+  }
+
+  public destroy(): void {
+    if (this.isPlaying()) {
+      this.endPlay();
+    }
+
+    this.scene.setWorld(null);
+
+    // Reset camera warning timer
+    this.lastCameraWarningTime = 0;
+
+    // Clean up UI manager
+    this.uiManager.destroy();
+
+    // Clean up input manager
+    this.inputManager.destroy();
+
+    if (this.physicsEngine) {
+      this.physicsEngine.destroy();
+      this.physicsEngine = null;
+    }
+
+    this.consoleManager.removeCommandHandler(this);
+
+    this.consoleManager.destroy();
+
+    this.postProcessManager.destroy();
+
+    this.navigationServer?.destroy();
+
+    // Clean up navigation mesh visualization
+    if (this.navigationMeshVisualization) {
+      this.scene.remove(this.navigationMeshVisualization);
+      this.navigationMeshVisualization = null;
+    }
+
+    this.hiddenInGameActors.clear();
+    this.actors = [];
+  }
+
+  //====================================================================================================
+
+  protected override doBeginPlay(): void {
+    if (!this.physicsEngineCreated) {
+      throw new Error('Physics engine not created');
+    }
+
+    this.consoleManager.addCommandHandler(this);
+
+    // other actors can be spawned in the beginPlay call below and add themselves to this.actors
+    // so we must iterate over a copy
+    // and we're iterating on the actors before calling beginPlay on the subsystems below
+    // to avoid the issue where the subsystems can spawn actors which would get beginPlay called twice
+    for (const actor of [...this.actors]) {
+      actor.beginPlay();
+    }
+
+    this.inputManager.beginPlay();
+
+    // Begin play for the timer system
+    this.timerSystem.beginPlay();
+
+    this.gameMode.beginPlay();
+
+    this.netWorld.beginPlay();
+  }
+
+  protected override doEndPlay(): void {
+    for (const actor of this.actors) {
+      actor.endPlay();
+    }
+
+    this.netWorld.endPlay();
+
+    this.inputManager.endPlay();
+
+    this.gameMode.endPlay();
+
+    // End play for the timer system
+    this.timerSystem.endPlay();
+
+    // End play for the global audio manager
+    this.globalAudioManager.endPlay();
+  }
+
+  public describe(options?: WorldDescriptionOptions): Record<string, any> {
+    const description: Record<string, any> = {};
+    if (this.editorData && Object.keys(this.editorData).length > 0) {
+      description.info = this.editorData;
+    }
+
+    const specifiedActors = options?.specifiedActors;
+    return {
+      ...description,
+      actorsNumber: this.actors.length,
+      actors: this.actors.map(actor => actor.describe({
+        includeComponentsDetails: options?.includeComponentsDetails,
+        omitDescription: specifiedActors ? !specifiedActors.includes(actor.uuid) : false
+      })),
+    };
+  }
+
+  @ConsoleCommand('clearworld', 'Clear all actors from the world')
+  private clearWorldCommand(): string {
+    this.clearWorld();
+    return 'World cleared';
+  }
+
+  @ConsoleCommand('dumpsg', 'Dump scene graph to HTML file (usage: dumpsg [html])')
+  private dumpSG(format = 'html'): string {
+    format = format.toLowerCase();
+    if (format === 'html') {
+      const html = SceneGraphUtils.dumpHtml(this);
+      const blob = new Blob([html], { type: 'text/html' });
+      const url = URL.createObjectURL(blob);
+      window.open(url, '_blank');
+      return 'Scene graph dumped to html';
+    }
+    return 'Invalid format';
+  }
+
+  @ConsoleCommand('exportworld', 'Export world data to JSON file (usage: exportworld [includeDefaults])')
+  private exportWorld(includeDefaults?: string): boolean {
+    const worldData = WorldSerializer.exportObject(this, !!includeDefaults);
+    const worldDataString = JSON.stringify(worldData, null, 2);
+    const blob = new Blob([worldDataString], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    window.open(url, '_blank');
+    return true;
+  }
+
+  @ConsoleCommand('pause', 'Toggle world pause state')
+  private pause(): string {
+    this.isPaused = !this.isPaused;
+    return `World paused: ${this.isPaused}`;
+  }
+
+  @ConsoleCommand('slomo', 'Set world slow motion multiplier (usage: slomo <value>)')
+  private setSlomoCommand(value: string): string {
+    const num = parseFloat(value);
+    if (isNaN(num)) {
+      return 'Invalid number';
+    }
+    this.slomo = num;
+    return `World slomo set to: ${this.slomo}`;
+  }
+
+  @ConsoleCommand('clearcache', 'Clear all cached resources')
+  private clearCachedResources(): boolean {
+    resourceManager.clearCachedResources();
+    return true;
+  }
+
+  @ConsoleCommand('logcache', 'Log all cached resources to console')
+  private logCachedResources(): boolean {
+    resourceManager.logCachedResources();
+    return true;
+  }
+
+  @ConsoleCommand('show', 'Show/hide debug visualizations (usage: show <lighthelper | lightcamerahelper | navmesh | collision>)')
+  private show(helperType: string): string | boolean {
+    const type = helperType.toLowerCase();
+
+    if (type === 'stats') {
+      this.statsDisplay.toggle();
+      return 'Stats console toggled';
+    }
+
+    if (type === 'navmesh') {
+      const navigationServer = this.getNavigationServer();
+      if (!navigationServer) {
+        return 'Navigation server not available';
+      }
+
+      if (this.navigationMeshVisualization) {
+        // Remove existing visualization
+        this.scene.remove(this.navigationMeshVisualization);
+        this.navigationMeshVisualization = null;
+        return 'Navigation mesh visualization hidden';
+      } else {
+        // Create and add visualization
+        const visualization = navigationServer.createDebugVisualization();
+        if (!visualization) {
+          console.error('[Navigation Server] show navmesh: Failed to create debug visualization');
+          return 'Failed to create debug visualization';
+        }
+
+        // Disable raycasting for debug mesh to prevent interference with any gameplay
+        visualization.traverse((child) => {
+          child.raycast = () => { };
+        });
+
+        this.scene.add(visualization);
+        this.navigationMeshVisualization = visualization;
+        return 'Navigation mesh visualization shown';
+      }
+    }
+
+    if (type === 'collision') {
+      const physicsEngine = this.getPhysicsEngine();
+      if (!physicsEngine) {
+        return 'Physics engine not available';
+      }
+
+      physicsEngine.setDebugRendererEnabled(!physicsEngine.isDebugRendererEnabled());
+      return 'Collision debug visualization ' + (physicsEngine.isDebugRendererEnabled() ? 'enabled' : 'disabled');
+    }
+
+    const lightComponents: LightComponent<any, any>[] = [];
+
+    for (const actor of this.actors) {
+      lightComponents.push(...actor.getComponents(LightComponent));
+    }
+
+    if (type === 'lighthelper') {
+      for (const lightComponent of lightComponents) {
+        lightComponent.showHelper(!lightComponent.isHelperVisible());
+      }
+      return `Toggled light helpers for ${lightComponents.length} lights`;
+    } else if (type === 'lightcamerahelper') {
+      for (const lightComponent of lightComponents) {
+        lightComponent.showCameraHelper(!lightComponent.isCameraHelperVisible());
+      }
+      return `Toggled light camera helpers for ${lightComponents.length} lights`;
+    } else {
+      return 'Invalid helper type. Use: lighthelper, lightcamerahelper, navmesh, or collision';
+    }
+  }
+
+  public setActorHiddenInGame(actor: Actor, hidden: boolean): void {
+    if (!this.isEditorWorld) {
+      if (hidden) {
+        this.hiddenInGameActors.add(actor);
+        actor.rootComponent.traverse(obj => obj.layers.disableAll());
+        this.postProcessManager.hiddenObjects.add(actor.rootComponent);
+      } else {
+        this.postProcessManager.hiddenObjects.delete(actor.rootComponent);
+        actor.rootComponent.traverse(obj => obj.layers.enable(0));
+        this.hiddenInGameActors.delete(actor);
+      }
+    }
+  }
+
+  public setSceneComponentHiddenInGame(sceneComponent: SceneComponent, hidden: boolean): void {
+    if (!this.isEditorWorld) {
+      if (hidden) {
+        this.hiddenInGameSceneComponents.add(sceneComponent);
+        sceneComponent.traverse(obj => obj.layers.disableAll());
+        this.postProcessManager.hiddenObjects.add(sceneComponent);
+      } else {
+        this.postProcessManager.hiddenObjects.delete(sceneComponent);
+        sceneComponent.traverse(obj => obj.layers.enable(0));
+        this.hiddenInGameSceneComponents.delete(sceneComponent);
+      }
+    }
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  private onEditorActorAddToWorld?: (actor: Actor) => void;
+  private onEditorActorRemoveFromWorld?: (actor: Actor) => void;
+
+  public setIsEditorWorld(isEditorWorld: boolean, onActorAddToWorld?: (actor: Actor) => void, onActorRemoveFromWorld?: (actor: Actor) => void): void {
+    this.isEditorWorld = isEditorWorld;
+    if (onActorAddToWorld) {
+      this.onEditorActorAddToWorld = onActorAddToWorld;
+    }
+    if (onActorRemoveFromWorld) {
+      this.onEditorActorRemoveFromWorld = onActorRemoveFromWorld;
+    }
+  }
+}