@directivegames/genesys.js 3.1.24

package/src/utils/ThreeJsExtensions.ts

@@ -0,0 +1,1200 @@
+/**
+ * ThreeJsExtensions augments THREE.Object3D with convenience methods tailored for Genesys.
+ *
+ * Detailed explanation:
+ * - Adds transform setters and getters that operate in both local and world space without manual matrix math.
+ * - Provides tree traversal helpers to fetch objects by type and generates debug data for SceneGraph utilities.
+ * - Marks objects as hidden or transient using userData flags so the engine can skip them when needed.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Import this file once near engine startup so the prototype methods are patched before any scenes are built.
+ * - Use `setWorldTransform` or `getWorldTransform` when synchronizing with physics or other global systems.
+ * - Avoid heavy per-frame allocations; reuse vectors or quaternions where possible when calling these methods.
+ */
+import * as THREE from 'three';
+
+import { SceneComponent } from '../components/SceneComponent.js';
+import { ClassRegistry } from '../systems/ClassRegistry.js';
+import { WorldSerializer } from '../systems/WorldSerialization.js';
+import { ensure } from '../utils/Utils.js';
+
+import type { SceneGraphDebugNode } from './SceneGraphUtils.js';
+import type { ComponentDescriptionOptions } from '../components/Component.js';
+import type { World } from '../game/World.js';
+import type { ComponentPhysicsOptions } from '../physics/PhysicsTypes.js';
+import type { Actor } from 'src/actors/Actor.js';
+
+const tempPosition = new THREE.Vector3();
+const tempRotation = new THREE.Euler();
+const tempScale = new THREE.Vector3();
+const tempQuaternion = new THREE.Quaternion();
+
+declare module 'three' {
+  interface Object3D {
+    /**
+     * When true, position is interpreted as world position rather than local.
+     * Useful for objects that need to maintain a fixed world position regardless of parent transforms.
+     */
+    useAbsolutePosition: boolean;
+
+    /**
+     * When true, rotation is interpreted as world rotation rather than local.
+     * Useful for objects that need to maintain a fixed world rotation regardless of parent transforms.
+     */
+    useAbsoluteRotation: boolean;
+
+    /**
+     * When true, scale is interpreted as world scale rather than local.
+     * Useful for objects that need to maintain a fixed world scale regardless of parent transforms.
+     */
+    useAbsoluteScale: boolean;
+
+    /**
+     * Gets the Actor that owns this object by traversing up the parent hierarchy.
+     * Returns null if this object is not part of an Actor's scene graph.
+     */
+    getActor(): Actor | null;
+
+    /**
+     * Gets the full hierarchical path name of this object (e.g., "Actor.RootComponent.Mesh").
+     * Uses the object's name property or falls back to its class name.
+     */
+    getPathName(): string;
+
+    /**
+     * Generates a debug node structure for visualization in scene graph debugging tools.
+     * Includes transform data, visibility, and recursively processes all children.
+     */
+    generateDebugNode(): SceneGraphDebugNode | null;
+
+    /**
+     * Finds the first object of the specified type in this object and its descendants.
+     * Uses depth-first search to traverse the scene graph.
+     * @param type The constructor/class to search for
+     * @returns The first matching object or null if not found
+     */
+    getComponent<T extends THREE.Object3D>(type: abstract new (...args: any[]) => T): T | null;
+
+    /**
+     * Finds all objects of the specified type in this object and its descendants.
+     * Recursively searches the entire subtree.
+     * @param type The constructor/class to search for
+     * @returns Array of all matching objects (may be empty)
+     */
+    getComponents<T extends THREE.Object3D>(type: abstract new (...args: any[]) => T): T[];
+
+    /**
+     * Checks if this object is hidden (not visible).
+     * @returns true if the object is hidden
+     */
+    isHidden(): boolean;
+
+    /**
+     * Sets the visibility state of this object.
+     * @param hidden Whether to hide (true) or show (false) the object
+     * @param propagateToChildren Whether to apply the visibility change to all children
+     */
+    setHidden(hidden: boolean, propagateToChildren: boolean): this;
+
+    /**
+     * Checks if this object is marked as transient (temporary/non-persistent).
+     * Transient objects are typically excluded from serialization.
+     * @returns true if the object is transient
+     */
+    isTransient(): boolean;
+
+    /**
+     * Marks this object as transient or persistent.
+     * Transient objects are excluded from world serialization.
+     * @param transient Whether the object should be transient
+     */
+    setTransient(transient: boolean): this;
+
+    /**
+     * Sets the local position relative to the parent.
+     * @param pos The new local position
+     */
+    setLocalPosition(pos: THREE.Vector3): this;
+
+    /**
+     * Sets the local rotation relative to the parent using Euler angles.
+     * @param rot The new local rotation
+     */
+    setLocalRotation(rot: THREE.Euler): this;
+
+    /**
+     * Sets the local rotation relative to the parent using a quaternion.
+     * @param quaternion The new local rotation quaternion
+     */
+    setLocalQuaternion(quaternion: THREE.Quaternion): this;
+
+    /**
+     * Sets the local scale relative to the parent.
+     * @param scale The new local scale
+     */
+    setLocalScale(scale: THREE.Vector3): this;
+
+    /**
+     * Sets multiple local transform properties at once.
+     * @param transform Object containing optional position, rotation, and/or scale
+     */
+    setLocalTransform(transform: { position?: THREE.Vector3, rotation?: THREE.Euler, scale?: THREE.Vector3 }): this;
+
+    /**
+     * Adds a delta to the current local position.
+     * @param delta The position offset to add
+     */
+    addLocalPosition(delta: THREE.Vector3): this;
+
+    /**
+     * Adds a delta rotation to the current local rotation.
+     * @param delta The rotation offset to add (in Euler angles)
+     */
+    addLocalRotation(delta: THREE.Euler): this;
+
+    /**
+     * Sets the world position, automatically converting to local space if parented.
+     * @param pos The new world position
+     */
+    setWorldPosition(pos: THREE.Vector3): this;
+
+    /**
+     * Sets the world rotation using Euler angles, automatically converting to local space if parented.
+     * @param rot The new world rotation
+     */
+    setWorldRotation(rot: THREE.Euler): this;
+
+    /**
+     * Sets the world rotation using a quaternion, automatically converting to local space if parented.
+     * @param quaternion The new world rotation quaternion
+     */
+    setWorldQuaternion(quaternion: THREE.Quaternion): this;
+
+    /**
+     * Sets the world scale, automatically converting to local space if parented.
+     * @param scale The new world scale
+     */
+    setWorldScale(scale: THREE.Vector3): this;
+
+    /**
+     * Sets multiple world transform properties at once.
+     * @param transform Object containing optional position, rotation, and/or scale in world space
+     */
+    setWorldTransform(transform: { position?: THREE.Vector3, rotation?: THREE.Euler, scale?: THREE.Vector3 }): this;
+
+    /**
+     * Adds a delta to the current world position.
+     * @param delta The world position offset to add
+     */
+    addWorldPosition(delta: THREE.Vector3): this;
+
+    /**
+     * Adds a delta rotation to the current world rotation.
+     * @param delta The world rotation offset to add (in Euler angles)
+     */
+    addWorldRotation(delta: THREE.Euler): this;
+
+    /**
+     * Gets the complete world transform as an object with position, rotation, and scale.
+     * @returns Object containing world position, rotation (Euler), and scale
+     */
+    getWorldTransform(): { position: THREE.Vector3, rotation: THREE.Euler, scale: THREE.Vector3 };
+
+    /**
+     * Gets the world position of this object.
+     * @param target Optional target vector to store the result (creates new if not provided)
+     * @returns The world position
+     */
+    getWorldPosition(target?: THREE.Vector3): THREE.Vector3;
+
+    /**
+     * Gets the world rotation as Euler angles.
+     * @param target Optional target Euler to store the result (creates new if not provided)
+     * @returns The world rotation
+     */
+    getWorldRotation(target?: THREE.Euler): THREE.Euler;
+
+    /**
+     * Gets the world scale of this object.
+     * @param target Optional target vector to store the result (creates new if not provided)
+     * @returns The world scale
+     */
+    getWorldScale(target?: THREE.Vector3): THREE.Vector3;
+
+    /**
+     * Gets the world rotation as a quaternion.
+     * @param target Optional target quaternion to store the result (creates new if not provided)
+     * @returns The world rotation quaternion
+     */
+    getWorldQuaternion(target?: THREE.Quaternion): THREE.Quaternion;
+
+    /**
+     * Generates a string representation of the object hierarchy for debugging.
+     * @param depth Starting indentation depth
+     * @param printTransform Whether to include transform data (position, rotation, scale)
+     * @returns Formatted string showing the hierarchy
+     */
+    printHierarchy(depth: number, printTransform: boolean): string;
+
+    /**
+     * Exports this object to a serializable format for saving/loading.
+     * @param includeDefaults Whether to include properties that match default values
+     * @returns Serialized object representation
+     */
+    asExportedObject(includeDefaults: boolean): any;
+
+    /**
+     * Generates a description of this object's properties for UI/debugging.
+     * @param options Options for controlling the description format
+     * @returns Object containing descriptive properties
+     */
+    describe(options?: ComponentDescriptionOptions): Record<string, any>;
+
+    /**
+     * Temporarily overrides the material on this object (useful for effects like highlighting).
+     * @param material The override material (null to restore original)
+     * @param recursive Whether to apply to all descendants
+     */
+    setOverrideMaterial(material: THREE.Material | null, recursive: boolean): this;
+
+    // Lifecycle methods that propagate through the scene graph
+    /**
+     * Called when this object enters play mode (added to an active world).
+     * Recursively calls beginPlay on all children.
+     */
+    beginPlay(): void;
+
+    /**
+     * Called when this object exits play mode (removed from world or world stops).
+     * Recursively calls endPlay on all children.
+     */
+    endPlay(): void;
+
+    /**
+     * Update tick called before physics simulation.
+     * Recursively calls tickPrePhysics on all children.
+     * @param deltaTime Time elapsed since last frame in seconds
+     */
+    tickPrePhysics(deltaTime: number): void;
+
+    /**
+     * Update tick called after physics simulation.
+     * Recursively calls tickPostPhysics on all children.
+     * @param deltaTime Time elapsed since last frame in seconds
+     */
+    tickPostPhysics(deltaTime: number): void;
+
+    /**
+     * Replaces physics options for this object and optionally its children.
+     * @param newOptions The new physics configuration
+     * @param propagateToChildren Whether to apply to all descendants
+     */
+    replacePhysicsOptions(newOptions: ComponentPhysicsOptions, propagateToChildren: boolean): this
+
+    /**
+     * Overrides the physics options for this object and optionally its children.
+     * @param newOptions The new physics configuration
+     * @param propagateToChildren Whether to apply to all descendants
+     */
+    overridePhysicsOptions(newOptions: ComponentPhysicsOptions, propagateToChildren: boolean): this
+  }
+
+  interface Scene {
+    /**
+     * Gets the World instance that owns this scene.
+     * @returns The owning World or null if not attached to a world
+     */
+    getWorld(): World | null;
+
+    /**
+     * Associates this scene with a World instance.
+     * @param world The World to associate with (or null to clear)
+     */
+    setWorld(world: World | null): this;
+  }
+
+  interface Material {
+    /**
+     * Exports this material to a serializable format.
+     * @param includeDefaults Whether to include properties that match default values
+     * @returns Serialized material representation
+     */
+    asExportedObject(includeDefaults: boolean): any;
+  }
+
+  interface Vector3 {
+    /**
+     * Checks if this vector is approximately equal to another within a tolerance.
+     * @param other The vector to compare against
+     * @param epsilon Maximum allowed difference per component (default: 0.00001)
+     * @returns true if vectors are approximately equal
+     */
+    almostEquals(other: THREE.Vector3Like, epsilon?: number): boolean;
+  }
+
+  interface Euler {
+    /**
+     * Checks if this Euler rotation is approximately equal to another within a tolerance.
+     * @param other The Euler to compare against
+     * @param epsilon Maximum allowed difference per component in radians (default: 0.00001)
+     * @returns true if rotations are approximately equal
+     */
+    almostEquals(other: THREE.Euler, epsilon?: number): boolean;
+  }
+}
+
+/**
+ * Gets the World instance associated with this scene.
+ * The World reference is stored in userData for easy access.
+ */
+THREE.Scene.prototype.getWorld = function (): World | null {
+  return this.userData.world as World | null;
+};
+
+/**
+ * Associates a World instance with this scene.
+ * Used by the engine to track which World owns each scene.
+ */
+THREE.Scene.prototype.setWorld = function (world: World | null): THREE.Scene {
+  this.userData.world = world;
+  return this;
+};
+
+// Define getter/setter properties for absolute transform flags
+Object.defineProperty(THREE.Object3D.prototype, 'useAbsolutePosition', {
+  get: function() {
+    return this.userData.useAbsolutePosition === true;
+  },
+  set: function(value: boolean) {
+    this.userData.useAbsolutePosition = value;
+  },
+  enumerable: true,
+  configurable: true
+});
+
+Object.defineProperty(THREE.Object3D.prototype, 'useAbsoluteRotation', {
+  get: function() {
+    return this.userData.useAbsoluteRotation === true;
+  },
+  set: function(value: boolean) {
+    this.userData.useAbsoluteRotation = value;
+  },
+  enumerable: true,
+  configurable: true
+});
+
+Object.defineProperty(THREE.Object3D.prototype, 'useAbsoluteScale', {
+  get: function() {
+    return this.userData.useAbsoluteScale === true;
+  },
+  set: function(value: boolean) {
+    this.userData.useAbsoluteScale = value;
+  },
+  enumerable: true,
+  configurable: true
+});
+
+function printMaterial(indent: string, material: THREE.Material): string {
+  let result = `${indent}- ${material.type}: '${material.name ?? 'unnamed'}'\n`;
+
+  for (const [key, value] of Object.entries(material)) {
+    if (value instanceof THREE.Texture) {
+      result += `${indent}  - ${key} (${ClassRegistry.getClassOrConstructorName(value)}): '${value.name ?? 'unnamed'}'\n`;
+      result += `${indent}    - Dimensions: ${value.width}x${value.height}x${value.depth}\n`;
+      // result += `${indent}    - Format: ${value.format}\n`;
+      // result += `${indent}    - Type: ${value.type}\n`;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Traverses up the parent hierarchy to find the Actor that owns this object.
+ * Components and other scene objects use this to access their owning Actor.
+ */
+THREE.Object3D.prototype.getActor = function (): Actor | null {
+  return this.parent?.getActor() ?? null;
+};
+
+/**
+ * Serializes this object using the WorldSerializer for saving/loading.
+ * Handles conversion to JSON-compatible format with proper class registration.
+ */
+THREE.Object3D.prototype.asExportedObject = function (includeDefaults: boolean): any {
+  return WorldSerializer.exportObject(this, includeDefaults);
+};
+
+/**
+ * Generates a human-readable string representation of the object hierarchy.
+ * Useful for debugging scene structure and understanding parent-child relationships.
+ * Includes geometry and material information for meshes.
+ */
+THREE.Object3D.prototype.printHierarchy = function (depth: number = 0, printTransform: boolean = false): string {
+  const indent = '  '.repeat(depth);
+  let result = `${indent}${this.type}: '${this.name ?? 'unnamed'}'\n`;
+  if (printTransform) {
+    result += `${indent}  - Position: (${this.position.x.toFixed(2)}, ${this.position.y.toFixed(2)}, ${this.position.z.toFixed(2)})\n`;
+    result += `${indent}  - Rotation: (${this.rotation.x.toFixed(2)}, ${this.rotation.y.toFixed(2)}, ${this.rotation.z.toFixed(2)})\n`;
+    result += `${indent}  - Scale: (${this.scale.x.toFixed(2)}, ${this.scale.y.toFixed(2)}, ${this.scale.z.toFixed(2)})\n`;
+  }
+  if (this instanceof THREE.Mesh) {
+    result += `${indent}  - ${this.geometry.type}: '${this.geometry.name ?? 'unnamed'}'\n`;
+    result += `${indent}  - Vertices: ${this.geometry.attributes.position?.count ?? 0}\n`;
+    if (this.material) {
+      const materialIndent = indent + '  ';
+      if (Array.isArray(this.material)) {
+        this.material.forEach(m => result += printMaterial(materialIndent, m));
+      } else {
+        result += printMaterial(materialIndent, this.material);
+      }
+    }
+  }
+  this.children.forEach(child => result += child.printHierarchy(depth + 1, printTransform));
+  return result;
+};
+
+/**
+ * Builds a dot-separated path string representing this object's location in the hierarchy.
+ * Example: "PlayerActor.RootComponent.MeshComponent"
+ * Used for debugging and logging to identify specific objects.
+ */
+THREE.Object3D.prototype.getPathName = function () {
+  const myName = this.name || ClassRegistry.getClassOrConstructorName(this);
+  if (this.parent) {
+    return `${this.parent.getPathName()}.${myName}`;
+  } else {
+    return myName;
+  }
+};
+
+/**
+ * Creates a debug data structure for scene graph visualization tools.
+ * Recursively processes all children to build a complete tree representation.
+ * Includes transform data, visibility state, and UUIDs for debugging.
+ */
+THREE.Object3D.prototype.generateDebugNode = function (): SceneGraphDebugNode | null {
+
+  const myName = this.name || ClassRegistry.getClassOrConstructorName(this);
+  const children: (SceneGraphDebugNode | null)[] = [];
+  this.children.forEach((child: THREE.Object3D) => {
+    children.push(child.generateDebugNode());
+  });
+  return {
+    title: myName,
+    children,
+    data: {
+      uuid: this.uuid,
+      position: this.position.toArray(),
+      rotation: this.rotation.toArray(),
+      scale: this.scale.toArray(),
+      visible: this.visible,
+    }
+  };
+};
+
+/**
+ * Searches for the first object of the specified type in this subtree.
+ * Uses depth-first search, checking this object first then its children.
+ * Commonly used to find specific component types within an actor.
+ */
+THREE.Object3D.prototype.getComponent = function <T extends THREE.Object3D>(type: abstract new (...args: any[]) => T = SceneComponent as any): T | null {
+  if (this instanceof type) {
+    return this as T;
+  }
+
+  for (const child of this.children) {
+    const result = child.getComponent(type);
+    if (result) {
+      return result;
+    }
+  }
+  return null;
+};
+
+/**
+ * Collects all objects of the specified type in this subtree.
+ * Recursively searches the entire hierarchy including this object.
+ * Returns an array that may be empty if no matches are found.
+ */
+THREE.Object3D.prototype.getComponents = function <T extends THREE.Object3D>(type: abstract new (...args: any[]) => T = SceneComponent as any): T[] {
+  const results: T[] = [];
+  if (this instanceof type) {
+    results.push(this as T);
+  }
+
+  for (const child of this.children) {
+    results.push(...child.getComponents(type));
+  }
+  return results;
+};
+
+/**
+ * Convenience method to check if this object is hidden.
+ * Simply returns the inverse of the visible property.
+ */
+THREE.Object3D.prototype.isHidden = function (): boolean {
+  return !this.visible;
+};
+
+/**
+ * Sets the visibility of this object and optionally all its descendants.
+ * Useful for hiding entire branches of the scene graph at once.
+ */
+THREE.Object3D.prototype.setHidden = function (hidden: boolean, propagateToChildren: boolean = false): THREE.Object3D {
+  this.visible = !hidden;
+  if (propagateToChildren) {
+    this.children.forEach(child => {
+      child.setHidden(hidden, propagateToChildren);
+    });
+  }
+  return this;
+};
+
+/**
+ * Adds a position offset in local space.
+ * Directly modifies the position property without matrix calculations.
+ */
+THREE.Object3D.prototype.addLocalPosition = function (delta: THREE.Vector3): THREE.Object3D {
+  this.position.x += delta.x;
+  this.position.y += delta.y;
+  this.position.z += delta.z;
+  return this;
+};
+
+/**
+ * Adds a rotation offset in local space.
+ * Converts Euler angles to quaternion and multiplies with current rotation.
+ */
+THREE.Object3D.prototype.addLocalRotation = function (delta: THREE.Euler): THREE.Object3D {
+  this.quaternion.multiply(new THREE.Quaternion().setFromEuler(delta));
+  return this;
+};
+
+/**
+ * Sets the local position relative to the parent.
+ * If useAbsolutePosition is true, interprets as world position.
+ */
+THREE.Object3D.prototype.setLocalPosition = function (pos: THREE.Vector3): THREE.Object3D {
+  this.position.copy(pos);
+  return this;
+};
+
+/**
+ * Sets the local rotation using Euler angles.
+ * If useAbsoluteRotation is true, interprets as world rotation.
+ */
+THREE.Object3D.prototype.setLocalRotation = function (rot: THREE.Euler): THREE.Object3D {
+  this.quaternion.setFromEuler(rot);
+  return this;
+};
+
+/**
+ * Sets the local rotation using a quaternion.
+ * If useAbsoluteRotation is true, interprets as world rotation.
+ */
+THREE.Object3D.prototype.setLocalQuaternion = function (quaternion: THREE.Quaternion): THREE.Object3D {
+  this.quaternion.copy(quaternion);
+  return this;
+};
+
+/**
+ * Sets the local scale relative to the parent.
+ * If useAbsoluteScale is true, interprets as world scale.
+ */
+THREE.Object3D.prototype.setLocalScale = function (scale: THREE.Vector3): THREE.Object3D {
+  this.scale.copy(scale);
+  return this;
+};
+
+/**
+ * Sets multiple transform properties at once in local space.
+ * Only modifies the properties that are provided in the transform object.
+ */
+THREE.Object3D.prototype.setLocalTransform = function (transform: { position?: THREE.Vector3, rotation?: THREE.Euler, scale?: THREE.Vector3 }): THREE.Object3D {
+  if (transform.position) {
+    this.setLocalPosition(transform.position);
+  }
+  if (transform.rotation) {
+    this.setLocalRotation(transform.rotation);
+  }
+  if (transform.scale) {
+    this.setLocalScale(transform.scale);
+  }
+  return this;
+};
+
+
+/**
+ * Sets the position in world space, automatically converting to local space if parented.
+ * Handles the matrix math to transform from world to local coordinates.
+ */
+THREE.Object3D.prototype.setWorldPosition = function (pos: THREE.Vector3): THREE.Object3D {
+  if (this.useAbsolutePosition) {
+    // When using absolute position, store world position directly
+    this.position.copy(pos);
+  } else if (this.parent) {
+    // Convert the world position to local position
+    const localPos = pos.clone();
+    // Get the parent's world matrix inverse to convert to local space
+    const parentWorldMatrixInverse = new THREE.Matrix4();
+    parentWorldMatrixInverse.copy(this.parent.matrixWorld).invert();
+    // Apply the inverse matrix to get local position
+    localPos.applyMatrix4(parentWorldMatrixInverse);
+    // Set the local position
+    this.position.copy(localPos);
+  } else {
+    this.setLocalPosition(pos);
+  }
+  return this;
+};
+
+/**
+ * Sets the rotation in world space using Euler angles.
+ * Internally converts to quaternion and delegates to setWorldQuaternion.
+ */
+THREE.Object3D.prototype.setWorldRotation = function (rot: THREE.Euler): THREE.Object3D {
+  this.setWorldQuaternion(new THREE.Quaternion().setFromEuler(rot));
+  return this;
+};
+
+/**
+ * Sets the rotation in world space using a quaternion.
+ * Calculates the required local rotation to achieve the desired world rotation.
+ */
+THREE.Object3D.prototype.setWorldQuaternion = function (quaternion: THREE.Quaternion): THREE.Object3D {
+  if (this.useAbsoluteRotation) {
+    // When using absolute rotation, store world rotation directly
+    this.quaternion.copy(quaternion);
+  } else if (this.parent) {
+    // Get the parent's world quaternion
+    const parentWorldQuat = new THREE.Quaternion();
+    this.parent.getWorldQuaternion(parentWorldQuat);
+    // Invert parent's world quaternion
+    parentWorldQuat.invert();
+    // Calculate local quaternion by multiplying world quaternion by inverted parent quaternion
+    const localQuaternion = quaternion.clone().premultiply(parentWorldQuat);
+    // Set the local quaternion
+    this.quaternion.copy(localQuaternion);
+  } else {
+    this.setLocalQuaternion(quaternion);
+  }
+  return this;
+};
+
+/**
+ * Sets the scale in world space, compensating for parent scaling.
+ * Calculates the local scale needed to achieve the desired world scale.
+ */
+THREE.Object3D.prototype.setWorldScale = function (scale: THREE.Vector3): THREE.Object3D {
+  if (this.useAbsoluteScale) {
+    // When using absolute scale, store world scale directly
+    this.scale.copy(scale);
+  } else if (this.parent) {
+    const parentWorldScale = new THREE.Vector3();
+    this.parent.getWorldScale(parentWorldScale);
+    this.scale.set(scale.x / parentWorldScale.x, scale.y / parentWorldScale.y, scale.z / parentWorldScale.z);
+  } else {
+    this.setLocalScale(scale);
+  }
+  return this;
+};
+
+/**
+ * Sets multiple transform properties at once in world space.
+ * Delegates to individual world setters for each provided property.
+ */
+THREE.Object3D.prototype.setWorldTransform = function (transform: { position?: THREE.Vector3, rotation?: THREE.Euler, scale?: THREE.Vector3 }): THREE.Object3D {
+  if (transform.position) {
+    this.setWorldPosition(transform.position);
+  }
+  if (transform.rotation) {
+    this.setWorldRotation(transform.rotation);
+  }
+  if (transform.scale) {
+    this.setWorldScale(transform.scale);
+  }
+  return this;
+};
+
+/**
+ * Adds a position offset in world space.
+ * Transforms the world delta to local space before applying.
+ */
+THREE.Object3D.prototype.addWorldPosition = function (delta: THREE.Vector3): THREE.Object3D {
+  if (this.useAbsolutePosition) {
+    // When using absolute position, position is already in world space
+    this.position.add(delta);
+  } else if (this.parent) {
+    this.updateMatrixWorld(true);
+    // Convert the delta from world space to local space
+    // We need to transform the direction only, not apply the full matrix
+    const worldDelta = delta.clone();
+
+    // Get parent's world rotation and scale to transform the delta
+    const parentWorldQuat = new THREE.Quaternion();
+    const parentWorldScale = new THREE.Vector3();
+    const parentWorldPos = new THREE.Vector3();
+    this.parent.matrixWorld.decompose(parentWorldPos, parentWorldQuat, parentWorldScale);
+
+    // Apply inverse scale
+    worldDelta.divide(parentWorldScale);
+
+    // Apply inverse rotation
+    parentWorldQuat.invert();
+    worldDelta.applyQuaternion(parentWorldQuat);
+
+    // Apply the local translation
+    this.position.add(worldDelta);
+  } else {
+    this.addLocalPosition(delta);
+  }
+  return this;
+};
+
+/**
+ * Adds a rotation offset in world space.
+ * Applies the rotation in world coordinates then converts back to local.
+ */
+THREE.Object3D.prototype.addWorldRotation = function (delta: THREE.Euler): THREE.Object3D {
+  if (this.useAbsoluteRotation) {
+    // When using absolute rotation, quaternion is already in world space
+    const deltaQuat = new THREE.Quaternion().setFromEuler(delta);
+    this.quaternion.premultiply(deltaQuat);
+  } else if (this.parent) {
+    this.updateMatrixWorld(true);
+    const currentWorldQuat = new THREE.Quaternion();
+    this.getWorldQuaternion(currentWorldQuat);
+    currentWorldQuat.premultiply(new THREE.Quaternion().setFromEuler(delta));
+    const parentWorldQuat = new THREE.Quaternion();
+    this.parent.getWorldQuaternion(parentWorldQuat);
+    parentWorldQuat.invert();
+    this.quaternion.copy(currentWorldQuat.premultiply(parentWorldQuat));
+  } else {
+    this.addLocalRotation(delta);
+  }
+  return this;
+};
+
+/**
+ * Gets all world transform components as a single object.
+ * Convenient for getting position, rotation, and scale in one call.
+ */
+THREE.Object3D.prototype.getWorldTransform = function (): { position: THREE.Vector3, rotation: THREE.Euler, scale: THREE.Vector3 } {
+  return {
+    position: this.getWorldPosition(),
+    rotation: this.getWorldRotation(),
+    scale: this.getWorldScale(),
+  };
+};
+
+/**
+ * Gets the world position, extracting it from the world matrix.
+ * Updates world matrix if needed to ensure accuracy.
+ */
+THREE.Object3D.prototype.getWorldPosition = function (target?: THREE.Vector3): THREE.Vector3 {
+  target ??= new THREE.Vector3();
+  // For absolute position, just return the position directly
+  if (this.useAbsolutePosition) {
+    return target.copy(this.position);
+  }
+  this.updateWorldMatrix(true, false);
+  return target.setFromMatrixPosition(this.matrixWorld);
+};
+
+/**
+ * Gets the world rotation as Euler angles.
+ * Internally gets world quaternion and converts to Euler.
+ */
+THREE.Object3D.prototype.getWorldRotation = function (target?: THREE.Euler): THREE.Euler {
+  target ??= new THREE.Euler();
+  // For absolute rotation, convert quaternion to Euler directly
+  if (this.useAbsoluteRotation) {
+    return target.setFromQuaternion(this.quaternion);
+  }
+  return target.setFromQuaternion(this.getWorldQuaternion());
+};
+
+/**
+ * Gets the world scale by decomposing the world matrix.
+ * Extracts scale component from the transformation matrix.
+ */
+THREE.Object3D.prototype.getWorldScale = function (target?: THREE.Vector3): THREE.Vector3 {
+  target ??= new THREE.Vector3();
+  // For absolute scale, just return the scale directly
+  if (this.useAbsoluteScale) {
+    return target.copy(this.scale);
+  }
+  this.updateWorldMatrix(true, false);
+  this.matrixWorld.decompose(tempPosition, tempQuaternion, target);
+  return target;
+};
+
+/**
+ * Gets the world rotation as a quaternion by decomposing the world matrix.
+ * More precise than Euler angles for rotation calculations.
+ */
+THREE.Object3D.prototype.getWorldQuaternion = function (target?: THREE.Quaternion): THREE.Quaternion {
+  target ??= new THREE.Quaternion();
+  // For absolute rotation, just return the quaternion directly
+  if (this.useAbsoluteRotation) {
+    return target.copy(this.quaternion);
+  }
+  this.updateWorldMatrix(true, false);
+  this.matrixWorld.decompose(tempPosition, target, tempScale);
+  return target;
+};
+
+/**
+ * Checks if this object is marked as transient (temporary/non-persistent).
+ * Transient objects are excluded from world serialization.
+ */
+THREE.Object3D.prototype.isTransient = function (): boolean {
+  // Object3D is serialized as scene graph so if the parent is transient then the children won't be serialized
+  // effectively making them transient as well
+  return this.userData.isTransient ?? this.parent?.isTransient() ?? false;
+};
+
+/**
+ * Marks this object as transient or persistent.
+ * Transient flag is stored in userData to persist across operations.
+ */
+THREE.Object3D.prototype.setTransient = function (transient: boolean): THREE.Object3D {
+  this.userData.isTransient = transient;
+  return this;
+};
+
+/**
+ * Returns a description of this object for UI/debugging purposes.
+ * Base implementation returns empty object; components override for custom descriptions.
+ */
+THREE.Object3D.prototype.describe = function (options?: ComponentDescriptionOptions): Record<string, any> {
+  return {};
+};
+
+/**
+ * Temporarily overrides materials for visual effects (e.g., highlighting).
+ * Base implementation just propagates to children; Mesh overrides to actually swap materials.
+ */
+THREE.Object3D.prototype.setOverrideMaterial = function (material: THREE.Material | null, recursive: boolean): THREE.Object3D {
+  if (recursive) {
+    this.children.forEach(child => child.setOverrideMaterial(material, true));
+  }
+  return this;
+};
+
+/**
+ * Called when entering play mode, propagates to all children.
+ * Components override this to initialize gameplay logic.
+ */
+THREE.Object3D.prototype.beginPlay = function (): void {
+  this.children.forEach(child => child.beginPlay());
+};
+
+/**
+ * Called when exiting play mode, propagates to all children.
+ * Components override this to clean up gameplay resources.
+ */
+THREE.Object3D.prototype.endPlay = function (): void {
+  this.children.forEach(child => child.endPlay());
+};
+
+/**
+ * Update called before physics simulation each frame.
+ * Components override this for pre-physics updates like input handling.
+ */
+THREE.Object3D.prototype.tickPrePhysics = function (deltaTime: number): void {
+  this.children.forEach(child => child.tickPrePhysics(deltaTime));
+};
+
+/**
+ * Update called after physics simulation each frame.
+ * Components override this for post-physics updates like visual synchronization.
+ */
+THREE.Object3D.prototype.tickPostPhysics = function (deltaTime: number): void {
+  this.children.forEach(child => child.tickPostPhysics(deltaTime));
+};
+
+/**
+ * Updates physics configuration for this object and optionally its children.
+ * Components with physics override this to actually update their physics bodies.
+ */
+THREE.Object3D.prototype.replacePhysicsOptions = function (newOptions: ComponentPhysicsOptions, propagateToChildren: boolean = false): THREE.Object3D {
+  if (propagateToChildren) {
+    this.children.forEach(child => child.replacePhysicsOptions(newOptions, true));
+  }
+  return this;
+};
+
+/**
+ * Overrides the physics options for this object and optionally its children.
+ * @param newOptions The new physics configuration
+ * @param propagateToChildren Whether to apply to all descendants
+ */
+THREE.Object3D.prototype.overridePhysicsOptions = function (newOptions: ComponentPhysicsOptions, propagateToChildren: boolean = false): THREE.Object3D {
+  if (propagateToChildren) {
+    this.children.forEach(child => child.overridePhysicsOptions(newOptions, true));
+  }
+  return this;
+};
+
+// Override add method to handle lifecycle events
+/**
+ * Extended add method that automatically calls beginPlay on added objects
+ * if they're being added to an active (playing) actor.
+ */
+const originalAdd = THREE.Object3D.prototype.add;
+
+THREE.Object3D.prototype.add = function (...objects: THREE.Object3D[]): THREE.Object3D {
+  const actor = this.getActor();
+  if (actor) {
+    if (!ensure(!actor.isPlayEnded())) {
+      return this;
+    }
+  }
+
+  originalAdd.call(this, ...objects);
+
+  if (actor?.isPlaying()) {
+    objects.forEach(obj => obj.beginPlay());
+  }
+
+  return this;
+};
+
+// Override remove method to handle lifecycle events
+/**
+ * Extended remove method that automatically calls endPlay on removed objects
+ * if they're being removed from an active (playing) actor.
+ */
+const originalRemove = THREE.Object3D.prototype.remove;
+
+THREE.Object3D.prototype.remove = function (...objects: THREE.Object3D[]): THREE.Object3D {
+  const actor = this.getActor();
+  if (actor) {
+    if (!ensure(!actor.isPlayEnded())) {
+      return this;
+    }
+  }
+
+  originalRemove.call(this, ...objects);
+
+  if (actor?.isPlaying()) {
+    objects.forEach(obj => obj.endPlay());
+  }
+
+  return this;
+};
+
+/**
+ * Mesh-specific override material implementation.
+ * Saves the original material and swaps it with the override, or restores the original.
+ */
+THREE.Mesh.prototype.setOverrideMaterial = function (material: THREE.Material | null, recursive: boolean): THREE.Mesh {
+  if (material) {
+    this.userData.__savedMaterial__ = this.material;
+    this.material = material;
+  } else {
+    const savedMaterial = this.userData.__savedMaterial__;
+    if (savedMaterial) {
+      this.material = savedMaterial;
+    }
+  }
+  THREE.Object3D.prototype.setOverrideMaterial.call(this, material, recursive);
+  return this;
+};
+
+/**
+ * Serializes this material for saving/loading.
+ * Uses the WorldSerializer to handle material-specific properties.
+ */
+THREE.Material.prototype.asExportedObject = function (includeDefaults: boolean): any {
+  return WorldSerializer.exportObject(this, includeDefaults);
+};
+
+/**
+ * Checks if two vectors are approximately equal within a tolerance.
+ * Useful for comparing positions/scales where floating point precision matters.
+ */
+THREE.Vector3.prototype.almostEquals = function (other: THREE.Vector3Like, epsilon: number = 0.00001): boolean {
+  epsilon ??= 0.00001;
+  return Math.abs(this.x - other.x) < epsilon &&
+    Math.abs(this.y - other.y) < epsilon &&
+    Math.abs(this.z - other.z) < epsilon;
+};
+
+/**
+ * Checks if two Euler rotations are approximately equal within a tolerance.
+ * Useful for comparing rotations where floating point precision matters.
+ * Note: Compares raw angles, doesn't account for equivalent rotations.
+ */
+THREE.Euler.prototype.almostEquals = function (other: THREE.Euler, epsilon: number = 0.00001): boolean {
+  epsilon ??= 0.00001;
+  return Math.abs(this.x - other.x) < epsilon &&
+    Math.abs(this.y - other.y) < epsilon &&
+    Math.abs(this.z - other.z) < epsilon;
+};
+
+// Store the original updateMatrixWorld method
+const originalUpdateMatrixWorld = THREE.Object3D.prototype.updateMatrixWorld;
+const originalUpdateWorldMatrix = THREE.Object3D.prototype.updateWorldMatrix;
+
+/**
+ * Override updateWorldMatrix to handle absolute transform properties.
+ * This method is called by getWorldPosition/Rotation/Scale and needs to respect absolute transforms.
+
+======================== Default Implementation ========================
+
+updateWorldMatrix( updateParents, updateChildren ) {
+  const parent = this.parent;
+  if ( updateParents === true && parent !== null ) {
+    parent.updateWorldMatrix( true, false );
+  }
+
+  if ( this.matrixAutoUpdate ) this.updateMatrix();
+
+  if ( this.matrixWorldAutoUpdate === true ) {
+    if ( this.parent === null ) {
+      this.matrixWorld.copy( this.matrix );
+    } else {
+      this.matrixWorld.multiplyMatrices( this.parent.matrixWorld, this.matrix );
+    }
+  }
+
+  // make sure descendants are updated
+
+  if ( updateChildren === true ) {
+    const children = this.children;
+    for ( let i = 0, l = children.length; i < l; i ++ ) {
+      const child = children[ i ];
+      child.updateWorldMatrix( false, true );
+    }
+  }
+}
+*/
+THREE.Object3D.prototype.updateWorldMatrix = function(updateParents?: boolean, updateChildren?: boolean): void {
+  const parent = this.parent;
+  if (updateParents && parent) {
+    parent.updateWorldMatrix(true, false);
+  }
+
+  if (this.matrixAutoUpdate) {
+    this.updateMatrix();
+  }
+
+  if (this.matrixWorldAutoUpdate) {
+    calculateMatrixWorld(this);
+  }
+
+  if (updateChildren) {
+    for (const child of this.children) {
+      child.updateWorldMatrix(false, true);
+    }
+  }
+};
+
+/**
+ * Override updateMatrixWorld to handle absolute transform properties.
+ * When useAbsolutePosition/Rotation/Scale are true, the object maintains
+ * its world transform regardless of parent transformations.
+
+======================== Default Implementation ========================
+
+updateMatrixWorld( force ) {
+  if ( this.matrixAutoUpdate ) this.updateMatrix();
+  if ( this.matrixWorldNeedsUpdate || force ) {
+    if ( this.matrixWorldAutoUpdate === true ) {
+      if ( this.parent === null ) {
+        this.matrixWorld.copy( this.matrix );
+      } else {
+        this.matrixWorld.multiplyMatrices( this.parent.matrixWorld, this.matrix );
+      }
+    }
+
+    this.matrixWorldNeedsUpdate = false;
+    force = true;
+  }
+
+  // make sure descendants are updated if required
+
+  const children = this.children;
+
+  for ( let i = 0, l = children.length; i < l; i ++ ) {
+    const child = children[ i ];
+    child.updateMatrixWorld( force );
+  }
+}
+*/
+
+THREE.Object3D.prototype.updateMatrixWorld = function(force?: boolean): void {
+  if (this.matrixAutoUpdate) {
+    this.updateMatrix();
+  }
+  if (this.matrixWorldNeedsUpdate || force) {
+    if (this.matrixWorldAutoUpdate) {
+      calculateMatrixWorld(this);
+    }
+    this.matrixWorldNeedsUpdate = false;
+    force = true;
+  }
+
+  for (const child of this.children) {
+    child.updateMatrixWorld(force);
+  }
+};
+
+function calculateMatrixWorld(object: THREE.Object3D): void {
+  if (!object.parent) {
+    object.matrixWorld.copy(object.matrix);
+  } else {
+    if (object.useAbsolutePosition || object.useAbsoluteRotation || object.useAbsoluteScale) {
+      // Get parent's world transform for non-absolute components
+      const parentPos = new THREE.Vector3();
+      const parentQuat = new THREE.Quaternion();
+      const parentScale = new THREE.Vector3();
+      object.parent.matrixWorld.decompose(parentPos, parentQuat, parentScale);
+
+      // Determine final world position
+      let finalWorldPos: THREE.Vector3;
+      if (object.useAbsolutePosition) {
+        // Use position as world position directly
+        finalWorldPos = object.position.clone();
+      } else {
+        // Transform local position by parent's rotation and scale, then add parent's position
+        finalWorldPos = object.position.clone();
+        // Apply parent's rotation
+        finalWorldPos.applyQuaternion(parentQuat);
+        // Apply parent's scale
+        finalWorldPos.multiply(parentScale);
+        // Add parent's position
+        finalWorldPos.add(parentPos);
+      }
+
+      // Determine final world rotation
+      let finalWorldQuat: THREE.Quaternion;
+      if (object.useAbsoluteRotation) {
+        // Use quaternion as world rotation directly
+        finalWorldQuat = object.quaternion.clone();
+      } else {
+        // Combine with parent rotation
+        finalWorldQuat = parentQuat.clone();
+        finalWorldQuat.multiply(object.quaternion);
+      }
+
+      // Determine final world scale
+      let finalWorldScale: THREE.Vector3;
+      if (object.useAbsoluteScale) {
+        // Use scale as world scale directly
+        finalWorldScale = object.scale.clone();
+      } else {
+        // Multiply with parent scale
+        finalWorldScale = object.scale.clone();
+        finalWorldScale.multiply(parentScale);
+      }
+      // Compose world matrix from the computed components
+      object.matrixWorld.compose(finalWorldPos, finalWorldQuat, finalWorldScale);
+    } else {
+      object.matrixWorld.multiplyMatrices(object.parent.matrixWorld, object.matrix);
+    }
+  }
+}