@directivegames/genesys.js 3.1.24

package/src/actors/Actor.ts

@@ -0,0 +1,1183 @@
+/**
+ * Actor - base class for any object that can be placed in a Genesys world.
+ *
+ * Detailed explanation:
+ * - Wraps a root `SceneComponent` to anchor visuals, physics, and child components.
+ * - Interacts with the world lifecycle by dispatching begin/end play and tick events.
+ * - Supports serialization via `WorldSerializer` so instances can be saved as prefabs.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Extend this class to create new actor types with custom components.
+ * - Override `tickBeforePhysics` or `tickAfterPhysics` for per-frame behavior.
+ * - Register subclasses with `ClassRegistry` if you want them loadable from data.
+ * - Include serializable fields in `toJSON` when state should persist across sessions.
+ */
+
+import 'reflect-metadata';
+import * as THREE from 'three';
+
+import { PrimitiveComponent } from '../components/PrimitiveComponent.js';
+import { SceneComponent } from '../components/SceneComponent.js';
+import { Playable } from '../game/Playable.js';
+import { PlayState } from '../game/Playable.js';
+import { NetMovementPredictor } from '../multiplayer/MovementPrediction.js';
+import { type INetObject, NetWorld } from '../multiplayer/NetWorld.js';
+import { ClassRegistry, EngineClass } from '../systems/ClassRegistry.js';
+import { ObjectNamingSystem } from '../systems/ObjectNamingSystem.js';
+import { isLegacyData, WorldSerializer } from '../systems/WorldSerialization.js';
+import { Delegate } from '../utils/Delegate.js';
+import { DescriptionHelper } from '../utils/DescriptionHelpers.js';
+import { isAsyncLoadable } from '../utils/IAsyncLoadable.js';
+import { type ClassPropertyMetadata, getPropertyMetadata } from '../utils/serialization/decorator.js';
+import { property } from '../utils/serialization/decorator.js';
+import { instantiatePrefab } from '../utils/serialization/prefab.js';
+import { ISerializableObjectTag } from '../utils/serialization/serializable.js';
+import { ensure, shortUUID } from '../utils/Utils.js';
+
+import type { PlayerController } from './PlayerController.js';
+import type { DamageHitInfo } from '../components/CharacterStatsComponent.js';
+import type { World } from '../game/World.js';
+import type { CollisionEvent, IPhysicsEngine } from '../physics/PhysicsEngine.js';
+import type { ComponentPhysicsOptions } from '../physics/PhysicsTypes.js';
+import type { ISerializable, SerializedActor, WorldSerializationContext } from '../systems/WorldSerialization.js';
+import type { EditorClassMeta, EditorPropertyChangedResult, IEditorObject } from '../utils/EditorClassMeta.js';
+import type { IAsyncLoadable } from '../utils/IAsyncLoadable.js';
+import type { ISceneGraphDebugNodeGenerator, SceneGraphDebugNode } from '../utils/SceneGraphUtils.js';
+import type { Dumper, Loader, PrefabInfo } from '../utils/serialization/serializer.js';
+
+
+export type ActorTickDelegate = Delegate<[Actor, number], void>;
+export type ActorAddedToWorldDelegate = Delegate<[Actor, World], void>;
+export type GenericActorDelegate = Delegate<[Actor], void>;
+export type ActorClickDelegate = Delegate<[Actor, THREE.Intersection], void>;
+export type ActorCollisionDelegate = Delegate<[Actor, SceneComponent, Actor, SceneComponent, CollisionEvent], void>;
+
+/**
+ * Options for configuring an Actor instance
+ */
+export interface ActorOptions {
+  /** Initial position in world space */
+  position?: THREE.Vector3;
+  /** Initial rotation in world space */
+  rotation?: THREE.Euler;
+  /** Initial scale in world space */
+  scale?: THREE.Vector3;
+  /** Initial root component */
+  rootComponent?: SceneComponent;
+  /** Initial scene components added under the root component */
+  sceneComponents?: SceneComponent[];
+  /** Tags for identifying and grouping actors */
+  actorTags?: string[];
+  /**
+   * Internal flag to indicate if the actor is being deserialized
+   * @internal
+   */
+  __isDeserializing?: boolean;
+}
+
+export interface ActorNetState {
+  position: [number, number, number];
+  rotation: [number, number, number];
+  scale: [number, number, number];
+  timestamp: number;
+}
+
+/**
+ * Options for describing an actor in the scene
+ * Used to generate a description of the actor's properties
+ */
+export interface ActorDescriptionOptions {
+  // whether to include the actor's components in the description
+  includeComponentsDetails?: boolean;
+
+  // if true, will omit all description, and only include the name and uuid
+  omitDescription?: boolean;
+}
+
+/**
+ * Base class for all actors in the scene
+ * An actor is an object that can be placed in the world and has components attached to it
+ */
+@EngineClass('Actor')
+export class Actor<TOptions extends ActorOptions = ActorOptions> extends Playable implements
+  ISceneGraphDebugNodeGenerator,
+  ISerializable,
+  IEditorObject,
+  INetObject {
+
+  static readonly EDITOR_CLASS_META: EditorClassMeta = {
+    actorTags: {
+      isTagProperty: true,
+    }
+  } as const;
+
+  readonly [ISerializableObjectTag] = true;
+
+  @property({editorOnly: true, hidden: true})
+  public editorData: Record<string, any> = {};
+
+  @property({transientOnPrefab: true, readonly: true})
+  readonly uuid: string = shortUUID();
+
+  readonly name: string;
+  private _rootComponent: SceneComponent;
+  protected world: World | null = null;
+  protected lifeSpan: number = 0;
+  protected remoteNetClientId: string | null = null;
+  protected remoteNetDeviceId: string | null = null;
+  protected netRelevant: boolean = false;
+  protected movementPredictor: NetMovementPredictor | null = null;
+
+  // deprecate in favor of $$prefab
+  protected prefabName: string | null = null;
+  protected prefabData: SerializedActor | null = null;
+  protected prefabInheritanceChain: Record<string, SerializedActor> | null = null;
+
+  @property({ ctorArg: 'ctorArgOnly' })
+  private ctorArgOptions: TOptions;
+
+  // make it protected/private later
+  public $prefab: PrefabInfo | null = null;
+
+  private transient: boolean = false;
+  protected actorTags: string[] = [];
+
+  @property({default: false, category: 'Advanced'})
+  private hiddenInGame: boolean = false;
+  @property({default: false, category: 'Advanced'})
+  private editorOnly: boolean = false;
+
+  /** Invoked when this actor is added to a world */
+  public readonly onAddedToWorld: ActorAddedToWorldDelegate = new Delegate<[Actor, World], void>();
+  /** Invoked during tick before physics simulation */
+  public readonly onTickPrePhysics: ActorTickDelegate = new Delegate<[Actor, number], void>();
+  /** Invoked during tick after physics simulation */
+  public readonly onTickPostPhysics: ActorTickDelegate = new Delegate<[Actor, number], void>();
+  /** Invoked when this actor begins play */
+  public readonly onBeginPlay: GenericActorDelegate = new Delegate<[Actor], void>();
+  /** Invoked when this actor ends play */
+  public readonly onEndPlay: GenericActorDelegate = new Delegate<[Actor], void>();
+  /** Invoked right before this actor starts end play, so it's still in `playing` state */
+  public readonly onPreEndPlay: GenericActorDelegate = new Delegate<[Actor], void>();
+  /** Invoked when this actor is clicked */
+  public readonly onClicked: ActorClickDelegate = new Delegate<[Actor, THREE.Intersection], void>();
+
+  /**
+   * Invoked when this actor collides with another actor
+   * Parameters: [thisActor, thisActorComponent, otherActor, otherActorComponent, collisionEvent]
+   */
+  public readonly onCollideWith: ActorCollisionDelegate = new Delegate<[Actor, SceneComponent, Actor, SceneComponent, CollisionEvent], void>();
+  /**
+   * Invoked when this actor overlaps with another actor
+   * Parameters: [thisActor, thisActorComponent, otherActor, otherActorComponent, collisionEvent]
+   */
+  public readonly onOverlapWith: ActorCollisionDelegate = new Delegate<[Actor, SceneComponent, Actor, SceneComponent, CollisionEvent], void>();
+  /**
+   * Invoked when this actor stops colliding with another actor
+   * Parameters: [thisActor, thisActorComponent, otherActor, otherActorComponent, collisionEvent]
+   */
+  public readonly onStopCollidingWith: ActorCollisionDelegate = new Delegate<[Actor, SceneComponent, Actor, SceneComponent, CollisionEvent], void>();
+  /**
+   * Invoked when this actor stops overlapping with another actor
+   * Parameters: [thisActor, thisActorComponent, otherActor, otherActorComponent, collisionEvent]
+   */
+  public readonly onStopOverlappingWith: ActorCollisionDelegate = new Delegate<[Actor, SceneComponent, Actor, SceneComponent, CollisionEvent], void>();
+
+  static get DEFAULT_OPTIONS(): ActorOptions {
+    return {
+      actorTags: []
+    } as const;
+  }
+
+  /**
+     * Creates a new Actor instance
+     * @param options Configuration options for the actor
+     */
+  constructor(readonly options: TOptions = {} as TOptions) {
+    super();
+    this.ctorArgOptions = options;
+    options = { ...Actor.DEFAULT_OPTIONS, ...options, };
+    this.name = ObjectNamingSystem.generateName(this);
+    this.actorTags = options.actorTags ? [...options.actorTags] : [];
+    let rootComponent = options.rootComponent;
+    if (rootComponent && !ensure(rootComponent.getActor() === null)) {
+      rootComponent = undefined;
+    }
+    if (rootComponent) {
+      this._rootComponent = rootComponent;
+      if (options.position) {
+        this.rootComponent.position.copy(options.position);
+      }
+      if (options.rotation) {
+        this.rootComponent.rotation.copy(options.rotation);
+      }
+      if (options.scale) {
+        this.rootComponent.scale.copy(options.scale);
+      }
+    } else {
+      this._rootComponent = new SceneComponent({
+        position: options.position,
+        rotation: options.rotation,
+        scale: options.scale
+      });
+    }
+    this.rootComponent.setActor(this);
+    for (const component of options.sceneComponents ?? []) {
+      if (component instanceof SceneComponent) {
+        this.rootComponent.add(component);
+      } else {
+        console.trace(`${component} is not a SceneComponent`);
+      }
+    }
+
+    this.rootComponent.updateMatrixWorld(true);
+
+    const legacyPrefabName = (options as any).prefabName;
+    if (legacyPrefabName) {
+      this.prefabName = legacyPrefabName;
+    }
+  }
+
+  /**
+   * Gets the prefab name of this actor
+   * @returns The prefab name or null if not set
+   */
+  public getPrefabName(): string | null {
+    return this.prefabName ?? this.$prefab?.$path ?? null;
+  }
+
+  /**
+   * Gets the prefab data of this actor
+   * @returns The prefab data or null if not set
+   */
+  public getPrefabData(): SerializedActor | null {
+    return this.prefabData;
+  }
+
+  /**
+   * Gets the prefab inheritance chain of this actor
+   * @returns The prefab inheritance chain or null if not set
+   */
+  public getPrefabInheritanceChain(): Record<string, SerializedActor> | null {
+    return this.prefabInheritanceChain;
+  }
+
+  /**
+   * Sets the prefab name and data of this actor
+   * @param name The prefab name
+   * @param data The prefab data
+   * @param inheritanceChain The full prefab inheritance chain (optional)
+   * @returns This actor instance for method chaining
+   */
+  public setPrefab(name: string, data: SerializedActor, inheritanceChain?: Record<string, SerializedActor>): this {
+    this.prefabName = name;
+    this.prefabData = data;
+    this.prefabInheritanceChain = inheritanceChain ?? null;
+    return this;
+  }
+
+  /**
+   * Clears the prefab name and data of this actor
+   * @returns This actor instance for method chaining
+   */
+  public clearPrefab(): this {
+    this.prefabName = null;
+    this.prefabData = null;
+    this.prefabInheritanceChain = null;
+    return this;
+  }
+
+  /**
+   * Gets all tags of this actor
+   * @returns Array of tags (empty array if no tags)
+   */
+  public getActorTags(): string[] {
+    return [...this.actorTags]; // Return a copy to prevent external mutation
+  }
+
+  /**
+   * Sets the tags of this actor
+   * @param tags The tags to set
+   * @returns This actor instance for method chaining
+   */
+  public setActorTags(tags: string[]): this {
+    this.actorTags = [...tags]; // Store a copy to prevent external mutation
+    return this;
+  }
+
+  /**
+   * Adds a tag to this actor (if not already present)
+   * @param tag The tag to add
+   * @returns This actor instance for method chaining
+   */
+  public addActorTag(tag: string): this {
+    if (!this.actorTags.includes(tag)) {
+      this.actorTags.push(tag);
+    }
+    return this;
+  }
+
+  /**
+   * Removes a tag from this actor
+   * @param tag The tag to remove
+   * @returns This actor instance for method chaining
+   */
+  public removeActorTag(tag: string): this {
+    const index = this.actorTags.indexOf(tag);
+    if (index !== -1) {
+      this.actorTags.splice(index, 1);
+    }
+    return this;
+  }
+
+  /**
+   * Checks if this actor has the specified tag
+   * @param tag The tag to check for
+   * @returns True if the actor has the specified tag, false otherwise
+   */
+  public hasActorTag(tag: string): boolean {
+    return this.actorTags.includes(tag);
+  }
+
+  /**
+   * Checks if this actor has any of the specified tags
+   * @param tags The tags to check for
+   * @returns True if the actor has at least one of the specified tags, false otherwise
+   */
+  public hasAnyActorTag(tags: string[]): boolean {
+    return tags.some(tag => this.actorTags.includes(tag));
+  }
+
+  /**
+   * Checks if this actor has all of the specified tags
+   * @param tags The tags to check for
+   * @returns True if the actor has all of the specified tags, false otherwise
+   */
+  public hasAllActorTags(tags: string[]): boolean {
+    return tags.every(tag => this.actorTags.includes(tag));
+  }
+
+  /**
+   * Sets whether this actor is transient (excluded from serialization)
+   * @param transient Whether this actor is transient
+   */
+  public setTransient(transient: boolean): void {
+    this.transient = transient;
+  }
+
+  /**
+   * Gets whether this actor is transient
+   * @returns Whether this actor is transient
+   */
+  public isTransient(): boolean {
+    return this.transient;
+  }
+
+  /**
+   * Spawns a prefab actor
+   * @param prefabName The name of the prefab
+   * @param transform The transform of the actor
+   * @param prefabs The prefabs to use
+   * @returns The spawned actor
+   */
+  public static async spawnPrefabActor(
+    prefabName: string,
+    transform?: { position?: THREE.Vector3, rotation?: THREE.Euler, scale?: THREE.Vector3 },
+    prefabs: Record<string, any> = {},
+    isEditor?: boolean
+  ): Promise<Actor | null> {
+    const prefabData = prefabs[prefabName];
+    if (isLegacyData(prefabData)) {
+      return await WorldSerializer.loadActor({
+        ctor: {
+          position: transform?.position,
+          rotation: transform?.rotation,
+          scale: transform?.scale,
+        },
+        prefabName,
+      }, prefabs, isEditor);
+    }
+
+    return instantiatePrefab(prefabName, prefabs, {ctorArgsOverrides: {
+      position: transform?.position,
+      rotation: transform?.rotation,
+      scale: transform?.scale,
+    }});
+  }
+
+  public getDefaultOptions(): TOptions {
+    return (this.constructor as typeof Actor).DEFAULT_OPTIONS as TOptions;
+  }
+
+  /**
+   * Exports the actor to a serializable format
+   * @param context The serialization context
+   * @param includeDefaults Whether to include default values
+   * @returns The serialized data
+   */
+  public export(context: WorldSerializationContext, includeDefaults: boolean): SerializedActor {
+    const properties: Record<string, any> = {
+      editorData: this.editorData,
+      actorTags: this.actorTags?.length > 0 ? [...this.actorTags] : undefined,
+      hiddenInGame: this.hiddenInGame ? true : undefined,
+      editorOnly: this.editorOnly ? true : undefined,
+    };
+
+    // Include @property decorated properties
+    const metadata = getPropertyMetadata(this.constructor);
+    for (const propName of Object.keys(metadata)) {
+      if (propName in this) {
+        properties[propName] = (this as any)[propName];
+      }
+    }
+
+    const data: SerializedActor = {
+      uuid: this.uuid,
+      class: ClassRegistry.getClassNameChecked(this),
+      properties
+    };
+    data.ctor = context.exportObject({
+      ...this.getExportedConstructor(),
+      rootComponent: this.rootComponent,
+    }, includeDefaults);
+    data.prefabName = this.prefabName ?? undefined;
+
+    // Include parent prefab name if this is a prefab with inheritance
+    if (this.prefabData?.parentPrefabName) {
+      data.parentPrefabName = this.prefabData.parentPrefabName;
+    }
+
+    return data;
+  }
+
+  /**
+     * Triggers the click event on this actor
+     * @param intersection The intersection data from raycasting
+     */
+  public clicked(intersection: THREE.Intersection): void {
+    this.onClicked.invoke(this, intersection);
+  }
+
+  /**
+   * Readonly access to the root scene component of this actor
+   * @returns The root scene component
+   */
+  public get rootComponent(): SceneComponent {
+    return this._rootComponent;
+  }
+
+  /**
+     * Sets the root scene component of this actor
+     * @param newRootComponent The new root scene component
+     * @param copyTransform Whether to copy the transform from the existing root component
+     */
+  public setRootComponent(newRootComponent: SceneComponent, copyTransform: boolean): this {
+    if (!ensure(!this.isPlayEnded())) {
+      return this;
+    }
+
+    if (!ensure(newRootComponent.getActor() === null)) {
+      return this;
+    }
+
+    if (copyTransform) {
+      newRootComponent.position.copy(this.rootComponent.position);
+      newRootComponent.rotation.copy(this.rootComponent.rotation);
+      newRootComponent.scale.copy(this.rootComponent.scale);
+    }
+
+    const oldRootComponent = this.rootComponent;
+    oldRootComponent.removeFromParent();
+    oldRootComponent.setActor(null);
+    this._rootComponent = newRootComponent;
+    this.rootComponent.setActor(this);
+    this.rootComponent.updateMatrixWorld(true);
+    if (this.isPlaying()) {
+      this.rootComponent.beginPlay();
+    }
+    if (this.world) {
+      this.world.scene.add(newRootComponent);
+    }
+    return this;
+  }
+
+  /**
+   * If the root component is a scene component and it has a single child, replace the root component with the child
+   * @returns True if the root component was collapsed, false otherwise
+   */
+  public collapseRootComponent(): boolean {
+    if (ensure(this.getPlayState() === PlayState.NotStarted)) {
+      // don't use "instanceof SceneComponent" as we want pure equality check
+      if (ClassRegistry.getClassOrConstructorName(this.rootComponent) === 'SceneComponent' && this.rootComponent.children.length === 1) {
+        const child = this.rootComponent.children[0];
+        if (ensure(child instanceof SceneComponent)) {
+          child.removeFromParent();
+          this.setRootComponent(child as SceneComponent, true);
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  /**
+     * Sets the world this actor belongs to
+     * @param world The world to set, or null to remove from current world
+     */
+  public setWorld(world: World | null): void {
+    if (!ensure(!this.world || !world)) {
+      return;
+    }
+    this.world = world;
+    if (world) {
+      this.onAddedToWorld.invoke(this, world);
+    }
+  }
+
+  /**
+     * Gets the world this actor belongs to
+     * @returns The world or null if not in a world
+     */
+  public getWorld(): World | null {
+    return this.world;
+  }
+
+  /**
+     * Updates this actor before physics simulation
+     * @param deltaTime Time in seconds since the last tick
+     */
+  public tickPrePhysics(deltaTime: number): void {
+    if (this.lifeSpan > 0) {
+      this.lifeSpan -= deltaTime;
+      if (this.lifeSpan <= 0) {
+        this.destroy();
+        return;
+      }
+    }
+
+    if (this.movementPredictor) {
+      const predictedTransform = this.movementPredictor.predictCurrentTransform();
+      if (predictedTransform) {
+        const lerpedTransform = NetMovementPredictor.lerpTransform({
+          position: this.rootComponent.position,
+          rotation: this.rootComponent.quaternion,
+          scale: this.rootComponent.scale,
+        }, predictedTransform, NetMovementPredictor.LerpAlpha);
+        this.setWorldTransform({
+          position: lerpedTransform.position,
+          rotation: new THREE.Euler().setFromQuaternion(lerpedTransform.rotation),
+          scale: lerpedTransform.scale,
+        });
+      }
+    }
+
+    this.rootComponent.tickPrePhysics(deltaTime);
+    this.onTickPrePhysics.invoke(this, deltaTime);
+  }
+
+  /**
+     * Updates this actor after physics simulation
+     * @param deltaTime Time in seconds since the last tick
+     */
+  public tickPostPhysics(deltaTime: number): void {
+    this.rootComponent.tickPostPhysics(deltaTime);
+    this.onTickPostPhysics.invoke(this, deltaTime);
+    if (this.movementPredictor) {
+      this.movementPredictor.addLocalTransform({
+        timestamp: NetMovementPredictor.currentTime(),
+        position: this.rootComponent.position.clone(),
+        rotation: this.rootComponent.quaternion.clone(),
+        scale: this.rootComponent.scale.clone(),
+      });
+    }
+  }
+
+  /**
+     * Gets the forward direction vector of this actor
+     * @returns Normalized forward direction vector
+     */
+  public forwardDirection(): THREE.Vector3 {
+    return new THREE.Vector3(0, 0, -1).applyQuaternion(this.rootComponent.quaternion).normalize();
+  }
+
+  /**
+     * Gets the right direction vector of this actor
+     * @returns Normalized right direction vector
+     */
+  public rightDirection(): THREE.Vector3 {
+    return new THREE.Vector3(1, 0, 0).applyQuaternion(this.rootComponent.quaternion).normalize();
+  }
+
+  /**
+     * Gets the up direction vector of this actor
+     * @returns Normalized up direction vector
+     */
+  public upDirection(): THREE.Vector3 {
+    return new THREE.Vector3(0, 1, 0).applyQuaternion(this.rootComponent.quaternion).normalize();
+  }
+
+  /**
+     * Gets the physics engine from the world this actor belongs to
+     * @returns The physics engine or null if not in a world or world has no physics engine
+     */
+  public getPhysicsEngine(): IPhysicsEngine | null {
+    return this.world ? this.world.getPhysicsEngine() : null;
+  }
+
+  /**
+     * Sets whether this actor is hidden in the scene
+     * @param hidden True to hide the actor, false to show it
+     * @returns This actor instance for method chaining
+     */
+  public setHidden(hidden: boolean): this {
+    if (this.isHidden() !== hidden) {
+      this.rootComponent.setHidden(hidden, true);
+    }
+    return this;
+  }
+
+  /**
+     * Checks if this actor is currently hidden
+     * @returns True if the actor is hidden, false otherwise
+     */
+  public isHidden(): boolean {
+    return this.rootComponent.isHidden();
+  }
+
+  /**
+   * Replaces the physics options for this actor
+   * @param newOptions The new physics options
+   * @param propagateToChildren Whether to propagate the new options to child components
+   * @returns This actor instance for method chaining
+   */
+  public replacePhysicsOptions(newOptions: ComponentPhysicsOptions, propagateToChildren: boolean = false): this {
+    this.rootComponent.replacePhysicsOptions(newOptions, propagateToChildren);
+    return this;
+  }
+
+  /**
+   * Overrides the physics options for this actor
+   * @param newOptions The new physics options
+   * @param propagateToChildren Whether to propagate the new options to child components
+   * @returns This actor instance for method chaining
+   */
+  public overridePhysicsOptions(newOptions: ComponentPhysicsOptions, propagateToChildren: boolean = false): this {
+    this.rootComponent.overridePhysicsOptions(newOptions, propagateToChildren);
+    return this;
+  }
+
+  /**
+     * Sets whether physics simulation is enabled for this actor
+     * @param enable True to enable physics, false to disable
+     * @param propagateToChildren Whether to propagate the change to child components
+     * @returns This actor instance for method chaining
+     */
+  public setPhysicsEnabled(enable: boolean, propagateToChildren: boolean = false): this {
+    this.rootComponent.setPhysicsEnabled(enable, propagateToChildren);
+    return this;
+  }
+
+  /**
+     * Checks if physics simulation is enabled for this actor
+     * @returns True if physics is enabled, false otherwise
+     */
+  public isPhysicsEnabled(): boolean {
+    return (this.rootComponent instanceof PrimitiveComponent) && this.rootComponent.isPhysicsEnabled();
+  }
+
+  /**
+   * Generates a debug node for the actor
+   * @returns A debug node for the actor
+   */
+  public generateDebugNode(): SceneGraphDebugNode | null {
+    const children: (SceneGraphDebugNode | null)[] = [];
+    children.push(this.rootComponent.generateDebugNode());
+    return {
+      title: this.name,
+      children,
+      data: {
+        uuid: this.uuid,
+      }
+    };
+  }
+
+  /**
+   * Gets the life span of this actor
+   * @returns The life span in seconds
+   */
+  public getLifeSpan(): number {
+    return this.lifeSpan;
+  }
+
+  /**
+   * Sets the life span of this actor
+   * @param lifeSpan The life span in seconds
+   * @returns This actor instance for method chaining
+   */
+  public setLifeSpan(lifeSpan: number): this {
+    this.lifeSpan = lifeSpan;
+    return this;
+  }
+
+  /**
+   * Adds a component to the actor root component
+   * @param component The component to add
+   * @returns This actor instance for method chaining
+   */
+  public addComponent(component: SceneComponent): this {
+    return this.addComponents(component);
+  }
+
+  /**
+   * Adds multiple components to the actor root component
+   * @param components The components to add
+   * @returns This actor instance for method chaining
+   */
+  public addComponents(...components: SceneComponent[]): this {
+    components.forEach(component => {
+      this.rootComponent.add(component);
+    });
+    return this;
+  }
+
+  /**
+   * Gets the first component/child object of a specified type
+   * @param type - The type of component/child object to search for
+   * @returns The first component/child object of the specified type or null if no such component exists
+   */
+  public getComponent<T extends THREE.Object3D>(type: abstract new (...args: any[]) => T = SceneComponent as any): T | null {
+    return this.rootComponent.getComponent(type);
+  }
+
+
+  /**
+   * Gets all components/child objects of a specified type
+   * @param type - The type of component/child object to search for
+   * @returns An array of all components/child objects of the specified type
+   */
+  public getComponents<T extends THREE.Object3D>(type: abstract new (...args: any[]) => T = SceneComponent as any): T[] {
+    return this.rootComponent.getComponents(type);
+  }
+
+  /**
+   * Gets the path name of this actor
+   * @returns The path name of this actor
+   */
+  public getPathName(): string {
+    return this.world ? `${this.world.getPathName()}.${this.name}` : this.name;
+  }
+
+  /**
+   * Destroys this actor
+   */
+  public destroy(): void {
+    if (this.world) {
+      this.world.removeActors(this);
+    }
+  }
+
+  /**
+   * Handles the death of this actor
+   * @param hitInfo The hit information
+   */
+  public handleDeath(hitInfo?: DamageHitInfo): void {
+    this.destroy();
+  }
+
+  /**
+   * Returns an exported object representation of this actor
+   * @param includeDefaults Whether to include default values
+   * @returns An exported object representation of this actor
+   */
+  public asExportedObject(includeDefaults: boolean = false): any {
+    return WorldSerializer.exportObject(this, includeDefaults);
+  }
+
+  public asExportedPrefabData(): any {
+    return WorldSerializer.exportAsPrefab(this);
+  }
+
+  /**
+   * Sets the world transform of this actor
+   * @param transform The transform to set
+   */
+  public setWorldTransform(transform: { position?: THREE.Vector3, rotation?: THREE.Euler, scale?: THREE.Vector3 }): void {
+    this.rootComponent.setWorldTransform(transform);
+  }
+
+  /**
+   * Sets the world position of this actor
+   * @param position The position to set
+   */
+  public setWorldPosition(position: THREE.Vector3): void {
+    this.setWorldTransform({ position });
+  }
+
+  /**
+   * Sets the world rotation of this actor
+   * @param rotation The rotation to set
+   */
+  public setWorldRotation(rotation: THREE.Euler): void {
+    this.setWorldTransform({ rotation });
+  }
+
+  /**
+   * Sets the world scale of this actor
+   * @param scale The scale to set
+   */
+  public setWorldScale(scale: THREE.Vector3): void {
+    this.setWorldTransform({ scale });
+  }
+
+  /**
+   * Sets the world quaternion of this actor
+   * @param quat The quaternion to set
+   */
+  public setWorldQuaternion(quaternion: THREE.Quaternion): void {
+    this.setWorldTransform({ rotation: new THREE.Euler().setFromQuaternion(quaternion) });
+  }
+
+  /**
+   * Gets the world position of this actor
+   * @returns The world position of this actor
+   */
+  public getWorldPosition(): THREE.Vector3 {
+    return this.rootComponent.getWorldPosition();
+  }
+
+  /**
+   * Gets the world rotation of this actor
+   * @returns The world rotation of this actor
+   */
+  public getWorldRotation(): THREE.Euler {
+    return this.rootComponent.getWorldRotation();
+  }
+
+  /**
+   * Gets the world scale of this actor
+   * @returns The world scale of this actor
+   */
+  public getWorldScale(): THREE.Vector3 {
+    return this.rootComponent.getWorldScale();
+  }
+
+  /**
+   * Gets the world quaternion of this actor
+   * @returns The world quaternion of this actor
+   */
+  public getWorldQuaternion(): THREE.Quaternion {
+    return this.rootComponent.getWorldQuaternion();
+  }
+
+  /**
+   * Gets the world transform of this actor
+   * @returns The world transform of this actor
+   */
+  public getWorldTransform(): { position: THREE.Vector3, rotation: THREE.Euler, scale: THREE.Vector3 } {
+    return this.rootComponent.getWorldTransform();
+  }
+
+
+
+  public setNetRelevant(relevant: boolean): void {
+    this.netRelevant = relevant;
+  }
+
+  public isNetRelevant(): boolean {
+    return this.netRelevant;
+  }
+
+  public getNetObjectId(): string {
+    return `${ClassRegistry.getClassOrConstructorName(this)}'${this.uuid}'`;
+  }
+
+  public setRemoteNetClientId(clientId: string): void {
+    this.remoteNetClientId = clientId;
+  }
+
+  public setRemoteNetDeviceId(deviceId: string): void {
+    this.remoteNetDeviceId = deviceId;
+  }
+
+  public getNetDeviceId(): string {
+    return this.remoteNetDeviceId ?? NetWorld.getDeviceId();
+  }
+
+  public getNetClientId(): string {
+    if (this.remoteNetClientId) {
+      return this.remoteNetClientId;
+    }
+    const netWorld = this.getWorld()?.netWorld;
+    if (!netWorld) {
+      throw new Error('Failed to get net world when getting net client id');
+    }
+    return netWorld.clientId;
+  }
+
+  public consumeLocalDynamicState(): boolean {
+    return false;
+  }
+
+  public getNetConstructionData(): object | null {
+    return this.asExportedObject();
+  }
+
+  public getNetDynamicState(lastReplicatedState: object | null): object | null {
+    const lastState = lastReplicatedState ? (lastReplicatedState as ActorNetState) : null;
+    const lastPosition = lastState?.position;
+    const lastRotation = lastState?.rotation;
+    const lastScale = lastState?.scale;
+    const currentPosition = this.rootComponent.position.toArray();
+    const currentRotation = this.rootComponent.rotation.toArray();
+    const currentScale = this.rootComponent.scale.toArray();
+    if (lastState &&
+      NetWorld.isVectorNearlyEqual(lastPosition!, currentPosition) &&
+      NetWorld.isVectorNearlyEqual(lastRotation!, currentRotation as [number, number, number]) &&
+      NetWorld.isVectorNearlyEqual(lastScale!, currentScale)) {
+      return null;
+    }
+    return {
+      position: currentPosition,
+      rotation: currentRotation,
+      scale: currentScale,
+      timestamp: NetMovementPredictor.currentTime(),
+    } as ActorNetState;
+  }
+
+  public setNetDynamicState(dynamicState: object): void {
+    const { position, rotation, scale, timestamp } = dynamicState as ActorNetState;
+    this.movementPredictor ??= new NetMovementPredictor();
+    this.movementPredictor.addRemoteTransform({
+      timestamp,
+      position: new THREE.Vector3(position[0], position[1], position[2]),
+      rotation: new THREE.Quaternion().setFromEuler(new THREE.Euler(rotation[0], rotation[1], rotation[2])),
+      scale: new THREE.Vector3(scale[0], scale[1], scale[2]),
+    });
+  }
+
+  public setOverrideMaterial(material: THREE.Material | null): this {
+    this.rootComponent.setOverrideMaterial(material, true);
+    return this;
+  }
+
+  //====================================================================================================
+
+  /**
+   * Gets the constructor data for this actor
+   * @returns The constructor data for this actor
+   */
+  protected getExportedConstructor(): any {
+    const transientRoot = this.rootComponent.isTransient();
+    return {
+      ...this.options,
+      // if the root is transient then the actor transform needs to be saved in the ctor
+      position: transientRoot ? this.getWorldPosition() : undefined,
+      rotation: transientRoot ? this.getWorldRotation() : undefined,
+      scale: transientRoot ? this.getWorldScale() : undefined,
+      // scene components are serialized as part of the actor scene graph so no need to serialize them separately
+      sceneComponents: undefined,
+      __isDeserializing: undefined,
+      // this is merely used for clearing out the prefab name from the ctor for the legacy format
+      prefabName: undefined,
+    };
+  }
+
+  protected override doBeginPlay(): void {
+    this.rootComponent.beginPlay();
+    this.onBeginPlay.invoke(this);
+    this.getWorld()?.netWorld.addNetObject(this);
+    if (this.isHiddenInGame()) {
+      this.getWorld()?.setActorHiddenInGame(this, true);
+    }
+  }
+
+  protected override doPreEndPlay(): void {
+    this.onPreEndPlay.invoke(this);
+  }
+
+  protected override doEndPlay(): void {
+    if (this.isHiddenInGame()) {
+      this.getWorld()?.setActorHiddenInGame(this, false);
+    }
+    this.getWorld()?.netWorld.removeNetObject(this);
+    this.rootComponent.endPlay();
+    this.onEndPlay.invoke(this);
+    this.world = null;
+  }
+
+  // calc all scene components for bounding boxes first
+  public calcBoundingBox(): THREE.Box3 {
+    this.rootComponent.updateMatrixWorld(true);
+    const sceneComponents = this.getComponents(SceneComponent);
+    for (const component of sceneComponents) {
+      component.calcBoundingBox();
+    }
+
+    return this.getBoundingBox();
+  }
+
+  // simply use the cached bounding box of scene components
+  public getBoundingBox(): THREE.Box3 {
+    const box = new THREE.Box3();
+    const sceneComponents = this.getComponents(SceneComponent);
+    for (const component of sceneComponents) {
+      const componentBox = component.boundingBox;
+      if (componentBox) {
+        box.union(componentBox);
+      }
+    }
+    return box;
+  }
+
+  /**
+   * Returns a description of this actor for a summary of this actor. Useful for AI assistants.
+   * @returns An object describing the actor's properties
+   */
+  public describe(options?: ActorDescriptionOptions): any {
+    if (options?.omitDescription) {
+      const simpleDescription: any = {
+        name: this.name,
+        uuid: this.uuid
+      };
+
+      if (this.editorData?.displayName) {
+        simpleDescription.displayName = this.editorData.displayName;
+      }
+
+      return simpleDescription;
+    }
+
+    const description: any = {
+      name: this.name,
+      uuid: this.uuid,
+      className: ClassRegistry.getClassName(this) ?? this.constructor.name,
+      position: DescriptionHelper.dumpPosition(this.getWorldPosition()),
+      rotation: DescriptionHelper.dumpRotation(this.getWorldRotation()),
+      scale: DescriptionHelper.dumpScale(this.getWorldScale())
+    };
+
+    if (this.editorData?.displayName) {
+      description.displayName = this.editorData.displayName;
+    }
+
+    if (this.editorData?.description) {
+      description.description = this.editorData.description;
+    }
+
+    this.calcBoundingBox();
+    const boundingBox = this.getBoundingBox();
+    if (!boundingBox.isEmpty()) {
+      description.boundingBox = DescriptionHelper.dumpBoundingBox(this.getBoundingBox());
+    }
+
+    const describeSceneComponent = (component: THREE.Object3D) => {
+      const componentDescription = component.describe({ recalculateBounds: false, includeDetails: options?.includeComponentsDetails });
+      if (component.children && component.children.length > 0) {
+        const children = component.children.map(describeSceneComponent).filter(child => child && Object.keys(child).length > 0);
+        if (children.length > 0) {
+          componentDescription.children = children;
+        }
+      }
+      return componentDescription;
+    };
+    description.rootComponent = describeSceneComponent(this.rootComponent);
+
+    return description;
+  }
+
+  public isHiddenInGame(): boolean {
+    return this.hiddenInGame;
+  }
+  public setHiddenInGame(hidden: boolean) {
+    this.hiddenInGame = hidden;
+    if (this.world) {
+      this.world.setActorHiddenInGame(this, hidden);
+    }
+  }
+
+  public isEditorOnly(): boolean {
+    return this.editorOnly;
+  }
+
+  public setEditorOnly(editorOnly: boolean) {
+    this.editorOnly = editorOnly;
+  }
+
+  /**
+   * Gets the camera used for rendering when this actor is the view target
+   * @returns The camera found
+   */
+  public getCamera(): THREE.Camera | null {
+    return this.getComponent(THREE.Camera) ?? null;
+  }
+
+  /**
+   * Gets the player controller that controls this actor
+   * @returns The current player controller or null if none
+   */
+  public getPlayerController(): PlayerController | null {
+    return null;
+  }
+
+  /**
+   * Return if this actor is player controlled
+   */
+  public isPlayerControlled(): boolean {
+    return !!this.getPlayerController();
+  }
+
+  public async waitForComponentsToLoad(): Promise<void> {
+    const components = this.getComponents(SceneComponent);
+    const asyncLoadables = components.filter(c => isAsyncLoadable(c)) as IAsyncLoadable[];
+    const loadPromises = asyncLoadables.map(c => c.waitForLoad());
+    await Promise.all(loadPromises);
+  }
+
+  public serialize(dumper: Dumper): void {
+    dumper.dumpValue('rootComponent', this.rootComponent, '_rootComponent');
+    dumper.dumpProperties(this);
+    if (this.isEditorOnly()) {
+      dumper.markEditorOnly();
+    }
+  }
+
+  public deserialize(loader: Loader): void {
+    const rootComponent = loader.loadValue('rootComponent', this.rootComponent) as SceneComponent;
+    if (rootComponent && rootComponent !== this.rootComponent) {
+      this.setRootComponent(rootComponent, false);
+    }
+    loader.loadProperties(this);
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public onEditorPropertyChanged(path: string, value: any, result: EditorPropertyChangedResult): void {
+    if (path === 'actorTags') {
+      this.setActorTags(value as string[]);
+    }
+  }
+
+  public onEditorSelectedChanged(isSelected: boolean, selectedActors: Actor[]): void {
+    this.getComponents(SceneComponent).forEach(sceneComponent => sceneComponent.onEditorSelectedChanged(isSelected, selectedActors));
+  }
+
+  public onEditorAddToWorld(): void {
+    this.getComponents(SceneComponent).forEach(sceneComponent => sceneComponent.onEditorAddToWorld());
+  }
+
+  public onEditorRemoveFromWorld(): void {
+    this.getComponents(SceneComponent).forEach(sceneComponent => sceneComponent.onEditorRemoveFromWorld());
+  }
+
+  public getConfigurationWarnings(): string[] {
+    const warnings: string[] = [];
+    // Add any actor-specific warnings here
+    return warnings;
+  }
+
+  public getEditorClassIcon(): string | null {
+    return 'Icon_Actor';
+  }
+}