@directivegames/genesys.js 3.1.24

package/src/systems/WorldSerialization.ts

@@ -0,0 +1,1211 @@
+/**
+ * WorldSerialization converts game objects to and from plain JSON structures.
+ *
+ * Detailed explanation:
+ * - Provides `WorldSerializationContext` which handles constructor mapping, default values and external references.
+ * - Defines schemas for actors, components and full worlds so exports can be validated before saving.
+ * - Includes helpers to construct objects from serialized data, wiring up scene hierarchies automatically.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Use `exportObject` or the static load helpers when persisting or loading scenes and prefabs.
+ * - Register additional constructors with `ClassRegistry` before loading to ensure custom classes instantiate correctly.
+ * - Avoid serializing transient runtime data like DOM elements or temporary THREE objects.
+ */
+import * as THREE from 'three';
+import { z } from 'zod';
+
+import { SceneComponent } from '../components/SceneComponent.js';
+import { SerializationVersion } from '../const.js';
+import { MaterialUtils } from '../materials.js';
+import { AssetPath } from '../storage/storageProvider.js';
+import { resourceManager } from '../utils/ResourceManager.js';
+import { loadPrefabTemplateInstance } from '../utils/serialization/prefab.js';
+import { Dumper, DumperFlags, Loader, LoaderFlags } from '../utils/serialization/serializer.js';
+import { deepDiff, deepMerge, deepRemoveEmptyObjects, replace_uuids, shortUUID } from '../utils/Utils.js';
+
+import { ClassRegistry } from './ClassRegistry.js';
+
+import type { Actor } from '../actors/Actor.js';
+import type { World } from '../game/World.js';
+import type { SerializedData } from '../utils/serialization/serializer.js';
+
+
+const serializationVersionKey = '$version';
+const externalRefKey: string = '@external';
+const internalRefKey: string = '@ref';
+
+const objectSchema = z.object({
+  // optional for an internal ref object
+  class: z.string().optional(),
+  uuid: z.string().optional(),
+  prefabName: z.string().optional(),
+  parentPrefabName: z.string().optional(),
+  [serializationVersionKey]: z.nativeEnum(SerializationVersion).optional(),
+  ctor: z.union([
+    z.record(z.any()),
+    z.array(z.any())
+  ]).optional(),
+  properties: z.record(z.string(), z.any()).optional(),
+}).strict();
+
+const componentSchema = objectSchema.extend({
+}).strict();
+
+const sceneComponentSchema: z.ZodType<any> = z.lazy(() =>
+  componentSchema.extend({
+    children: z.array(sceneComponentSchema).optional(),
+  }).strict()
+);
+
+const actorSchema = objectSchema.extend({
+}).strict();
+
+const sceneResourcesSchema = z.object({
+  lightmap: z.object({
+    metadataPath: z.string(),
+    texturePath: z.string(),
+  }).optional(),
+  navMesh: z.object({
+    path: z.string(),
+  }).optional(),
+}).strict();
+
+const worldSchema = objectSchema.extend({
+  actors: z.array(actorSchema).optional(),
+  prefabs: z.record(z.string(), actorSchema).optional(),
+  resources: sceneResourcesSchema.optional(),
+}).strict();
+
+type Handler<T> = (obj: T, includeDefaults: boolean) => any;
+
+/**
+ * The serialized object format.
+ */
+export interface SerializedObject {
+  class?: string,
+  uuid?: string,
+  prefabName?: string,
+  parentPrefabName?: string,
+  ctor?: Record<string, any> | any[],
+  properties?: Record<string, any>,
+}
+
+/**
+ * The serialized scene component format.
+ */
+export interface SerializedSceneComponent extends SerializedObject {
+  children?: SerializedSceneComponent[],
+}
+
+/**
+ * The serialized actor format.
+ */
+export interface SerializedActor extends SerializedObject {
+}
+
+/**
+ * Scene resources configuration.
+ */
+export interface SceneResources {
+  lightmap?: {
+    metadataPath: string;
+    texturePath: string;
+  };
+  navMesh?: {
+    path: string;
+  };
+}
+
+/**
+ * The serialized world format.
+ */
+export interface SerializedWorld extends SerializedObject {
+  actors?: SerializedActor[],
+  prefabs?: Record<string, SerializedActor>,
+  resources?: SceneResources,
+}
+
+export function isLegacyData(data: any) {
+  // no data, considered new, because we can load prefab without having to provide prefab data
+  if (data === undefined) return false;
+
+  const version = data?.[serializationVersionKey];
+  if (version !== undefined) {
+    // version clearly says it's legacy or new
+    return version < SerializationVersion.V1;
+  }
+
+  // now we are in a state where we have a bunch of data, but without $version field
+  return true;
+}
+
+/**
+ * An object that can be serialized.
+ */
+export interface ISerializable {
+  export(context: WorldSerializationContext, includeDefaults: boolean): SerializedObject;
+}
+
+export class WorldSerializationContext {
+  // Debug flag to enable call stack tracking for exports
+  public static DEBUG_EXPORT_STACK = false;
+
+  // Flag to enable precision normalization for numbers (reduces file size)
+  public static ENABLE_PRECISION_NORMALIZATION = true;
+
+  // Flag to enable compact format for Vector3/Euler with type tags (further reduces file size)
+  public static ENABLE_COMPACT_VECTORS = true;
+
+  private static constructorHandlersRegistered: boolean = false;
+  private static constructorHandlers: Map<object, Handler<any>> = new Map();
+  private static classDefaultObjects: Map<object, any> = new Map();
+
+  private exportedObjects: Map<string, any> = new Map();
+  // Map that stores the call stacks for each exported object (when debug is enabled)
+  private exportCallStacks: Map<string, string> = new Map();
+
+  private static externalObjects: Map<string, any> = new Map();
+
+  // Loading context state
+  private constructedObjects = new WeakSet();
+  private loadedObjectsByUUID = new Map<string, any>();
+  private loadedPrefabData = new Map<string, any>();
+  private currentPrefabRegistry: Record<string, SerializedActor> = {};
+  private isEditor: boolean = false;
+
+  public static get ExternalObjects(): Map<string, any> {
+    if (!this.externalObjects.size) {
+      this.externalObjects.set('DefaultTexture', MaterialUtils.DefaultTexture);
+      this.externalObjects.set('DefaultMaterial', MaterialUtils.DefaultMaterial);
+      this.externalObjects.set('MeshWorldSpaceNormalMaterial', MaterialUtils.MeshWorldSpaceNormalMaterial);
+
+      for (const [k, v] of this.externalObjects) {
+        v.export = (context: WorldSerializationContext, includeDefaults: boolean) => ({
+          [externalRefKey]: k,
+        });
+        v.isExternal = true;
+      }
+    }
+    return this.externalObjects;
+  }
+
+  /**
+   * Exports an object to a serializable format.
+   * @param object - The object to export
+   * @param asPrefab - Whether it's exported as a prefab or regular storage
+   * @param inlineToPrefab - Whether to inline to the actor's prefab itself, as against to creating a new prefab that is dependent on the actor's prefab
+   * @returns The serialized object
+   */
+  public exportObject(object: any, asPrefab: boolean, inlineToPrefab: boolean = false): any {
+    const flags = (
+      DumperFlags.None
+      | (asPrefab ? DumperFlags.AsPrefab : 0)
+      | (inlineToPrefab ? DumperFlags.Inline : 0)
+    );
+    const dumper = new Dumper({flags});
+    const data = dumper.dump(object);
+    return data;
+  }
+
+  private static addConstructorHandler<T>(type: new (...args: any[]) => T, handler: Handler<T>) {
+    this.constructorHandlers.set(type.prototype, handler);
+  }
+
+  private static getDefaultObject(obj: any): any {
+    type Constructor<T> = new () => T;
+    const ctor = obj.constructor as Constructor<any>;
+    if (!this.classDefaultObjects.has(ctor)) {
+      try {
+        this.classDefaultObjects.set(ctor, new ctor());
+      } catch (error) {
+        // If we can't create a default object (e.g., due to arrays with null/undefined),
+        // store null to indicate this class doesn't support default comparison
+        this.classDefaultObjects.set(ctor, null);
+      }
+    }
+    return this.classDefaultObjects.get(ctor);
+  }
+
+  private removeDefaultProperties(obj: any, properties: Record<string, any>): Record<string, any> {
+    let defaultObject = WorldSerializationContext.getDefaultObject(obj);
+    // If the object is a component and its actor is a prefab, compare against the prefab defaults instead of class defaults
+    if (obj instanceof SceneComponent) {
+      const actor = obj.getActor();
+      const prefabName = actor?.getPrefabName();
+      const prefabInheritanceChain = actor?.getPrefabInheritanceChain();
+      if (prefabName && prefabInheritanceChain) {
+        try {
+          // Use the stored inheritance chain to load the prefab template actor
+          const prefabTemplateActor = WorldSerializer.loadPrefabTemplateActor(prefabName, prefabInheritanceChain);
+          const actorComponents = actor?.getComponents() ?? [];
+          const prefabComponents = prefabTemplateActor?.getComponents() ?? [];
+          const componentIndex = actorComponents.indexOf(obj);
+          if (componentIndex >= 0 && componentIndex < prefabComponents.length) {
+            defaultObject = prefabComponents[componentIndex];
+          }
+        } catch (error) {
+          // If we can't load the prefab template actor, fall back to class defaults
+          console.warn(`⚠️ Could not load prefab template actor for comparison: ${error}. Using class defaults.`);
+        }
+      }
+    }
+
+    if (defaultObject === null) {
+      return properties;
+    }
+
+    return WorldSerializationContext.removeDefaultPropertiesCommon(obj, properties, defaultObject);
+  }
+
+  private static removeDefaultPropertiesStatic(obj: any, properties: Record<string, any>): Record<string, any> {
+    const defaultObject = WorldSerializationContext.getDefaultObject(obj);
+    return WorldSerializationContext.removeDefaultPropertiesCommon(obj, properties, defaultObject);
+  }
+
+  private static removeDefaultPropertiesCommon(obj: any, properties: Record<string, any>, defaultObject: any): Record<string, any> {
+
+    for (const [k, instanceValue] of Object.entries(properties)) {
+      const defaultValue = (defaultObject as any)[k];
+      if (instanceValue && instanceValue.equals && instanceValue.equals(defaultValue)) {
+        delete properties[k];
+        continue;
+      }
+      if (instanceValue === defaultValue) {
+        delete properties[k];
+        continue;
+      }
+      if (typeof instanceValue === 'object' && instanceValue && Object.keys(instanceValue).length === 0) {
+        delete properties[k];
+        continue;
+      }
+    }
+    return properties;
+  }
+
+  private static getDebugName(obj: any): string {
+    if (obj.getPathName) {
+      return obj.getPathName();
+    }
+    if (obj.name) {
+      return obj.name;
+    }
+    if (obj.class) {
+      return obj.class;
+    }
+    const className = ClassRegistry.getClassName(obj);
+    if (className) {
+      return className;
+    }
+    if (obj.constructor) {
+      return obj.constructor.name;
+    }
+    return obj.toString();
+  }
+
+  /**
+   * Normalizes a number to reduce precision artifacts and file size.
+   * - Rounds near-zero values to 0
+   * - Rounds near-integer values to integers
+   * - Limits decimal precision to 6 places
+   */
+  private static normalizeNumber(n: number): number {
+    if (!this.ENABLE_PRECISION_NORMALIZATION) {
+      return n;
+    }
+
+    // Handle near-zero values
+    if (Math.abs(n) < 1e-10) {
+      return 0;
+    }
+
+    // Check if close to an integer
+    const rounded = Math.round(n);
+    if (Math.abs(n - rounded) < 1e-10) {
+      return rounded;
+    }
+
+    // Limit precision to 6 decimal places
+    return Math.round(n * 1000000) / 1000000;
+  }
+
+  /**
+   * Normalizes an array of numbers for more compact serialization.
+   */
+  private static normalizeNumberArray(arr: number[]): number[] {
+    if (!this.ENABLE_PRECISION_NORMALIZATION) {
+      return arr;
+    }
+    return arr.map(n => this.normalizeNumber(n));
+  }
+
+  private static registerConstructorHandlers() {
+    if (this.constructorHandlersRegistered) {
+      return;
+    }
+
+    function getObjectParameters(obj: any, fields: string[], includeDefaults: boolean): any {
+      const result: any = {};
+      for (const field of fields) {
+        const value = obj[field];
+        if (value === undefined || value === null) {
+          continue;
+        }
+        if (value instanceof THREE.Texture) {
+          // continue;
+        }
+        result[field] = value;
+      }
+      if (!includeDefaults) {
+        // For static context, we can't access instance prefab data, so use class defaults only
+        return WorldSerializationContext.removeDefaultPropertiesStatic(obj, result);
+      }
+      return result;
+    }
+
+    // core classes
+    this.addConstructorHandler(THREE.Vector2, (obj, includeDefaults) => {
+      return this.normalizeNumberArray([obj.x, obj.y]);
+    });
+    this.addConstructorHandler(THREE.Vector3, (obj, includeDefaults) => {
+      return this.normalizeNumberArray([obj.x, obj.y, obj.z]);
+    });
+    this.addConstructorHandler(THREE.Vector4, (obj, includeDefaults) => {
+      return this.normalizeNumberArray([obj.x, obj.y, obj.z, obj.w]);
+    });
+    this.addConstructorHandler(THREE.Color, (obj, includeDefaults) => {
+      return this.normalizeNumberArray([obj.r, obj.g, obj.b]);
+    });
+    this.addConstructorHandler(THREE.Euler, (obj, includeDefaults) => {
+      return this.normalizeNumberArray([obj.x, obj.y, obj.z]);
+    });
+    this.addConstructorHandler(THREE.Quaternion, (obj, includeDefaults) => {
+      return this.normalizeNumberArray([obj.x, obj.y, obj.z, obj.w]);
+    });
+    this.addConstructorHandler(THREE.Matrix2, (obj, includeDefaults) => { return obj.elements; });
+    this.addConstructorHandler(THREE.Matrix3, (obj, includeDefaults) => { return obj.elements; });
+    this.addConstructorHandler(THREE.Matrix4, (obj, includeDefaults) => { return obj.elements; });
+    this.addConstructorHandler(THREE.Box2, (obj, includeDefaults) => { return [obj.min, obj.max]; });
+    this.addConstructorHandler(THREE.Box3, (obj, includeDefaults) => { return [obj.min, obj.max]; });
+    this.addConstructorHandler(THREE.Sphere, (obj, includeDefaults) => { return [obj.center, obj.radius]; });
+    this.addConstructorHandler(THREE.Plane, (obj, includeDefaults) => { return [obj.normal, obj.constant]; });
+
+    // geometry classes
+    this.addConstructorHandler(THREE.BoxGeometry, (obj, includeDefaults) => { return [obj.parameters.width, obj.parameters.height, obj.parameters.depth]; });
+    this.addConstructorHandler(THREE.SphereGeometry, (obj, includeDefaults) => { return [obj.parameters.radius, obj.parameters.widthSegments, obj.parameters.heightSegments]; });
+    this.addConstructorHandler(THREE.CylinderGeometry, (obj) => { return [obj.parameters.radiusTop, obj.parameters.radiusBottom, obj.parameters.height, obj.parameters.radialSegments, obj.parameters.heightSegments, obj.parameters.openEnded]; });
+    this.addConstructorHandler(THREE.PlaneGeometry, (obj, includeDefaults) => { return [obj.parameters.width, obj.parameters.height]; });
+    this.addConstructorHandler(THREE.CapsuleGeometry, (obj, includeDefaults) => { return [obj.parameters.radius, obj.parameters.height, obj.parameters.capSegments, obj.parameters.radialSegments]; });
+    this.addConstructorHandler(THREE.ConeGeometry, (obj, includeDefaults) => { return [obj.parameters.radius, obj.parameters.height, obj.parameters.radialSegments, obj.parameters.heightSegments]; });
+    this.addConstructorHandler(THREE.CircleGeometry, (obj, includeDefaults) => { return [obj.parameters.radius, obj.parameters.segments, obj.parameters.thetaStart, obj.parameters.thetaLength]; });
+    this.addConstructorHandler(THREE.TorusGeometry, (obj, includeDefaults) => { return [obj.parameters.radius, obj.parameters.tube, obj.parameters.radialSegments, obj.parameters.tubularSegments]; });
+    this.addConstructorHandler(THREE.TorusKnotGeometry, (obj, includeDefaults) => { return [obj.parameters.radius, obj.parameters.tube, obj.parameters.radialSegments, obj.parameters.tubularSegments, obj.parameters.radialSegments, obj.parameters.tubularSegments]; });
+    this.addConstructorHandler(THREE.TubeGeometry, (obj, includeDefaults) => { return [obj.parameters.path, obj.parameters.tubularSegments, obj.parameters.radius, obj.parameters.radialSegments, obj.parameters.closed]; });
+    this.addConstructorHandler(THREE.DodecahedronGeometry, (obj, includeDefaults) => { return [obj.parameters.radius, obj.parameters.detail]; });
+    this.addConstructorHandler(THREE.EdgesGeometry, (obj, includeDefaults) => { return [obj.parameters.geometry, obj.parameters.thresholdAngle]; });
+    this.addConstructorHandler(THREE.ExtrudeGeometry, (obj, includeDefaults) => { return [obj.parameters.shapes, obj.parameters.options]; });
+    this.addConstructorHandler(THREE.IcosahedronGeometry, (obj, includeDefaults) => { return [obj.parameters.radius, obj.parameters.detail]; });
+    this.addConstructorHandler(THREE.LatheGeometry, (obj, includeDefaults) => { return [obj.parameters.points, obj.parameters.segments, obj.parameters.phiStart, obj.parameters.phiLength]; });
+    this.addConstructorHandler(THREE.OctahedronGeometry, (obj, includeDefaults) => { return [obj.parameters.radius, obj.parameters.detail]; });
+    this.addConstructorHandler(THREE.PolyhedronGeometry, (obj, includeDefaults) => { return [obj.parameters.vertices, obj.parameters.indices, obj.parameters.radius, obj.parameters.detail]; });
+    this.addConstructorHandler(THREE.RingGeometry, (obj, includeDefaults) => { return [obj.parameters.innerRadius, obj.parameters.outerRadius, obj.parameters.thetaSegments, obj.parameters.phiSegments]; });
+    this.addConstructorHandler(THREE.ShapeGeometry, (obj, includeDefaults) => { return [obj.parameters.shapes, obj.parameters.curveSegments]; });
+    this.addConstructorHandler(THREE.TetrahedronGeometry, (obj, includeDefaults) => { return [obj.parameters.radius, obj.parameters.detail]; });
+    this.addConstructorHandler(THREE.WireframeGeometry, (obj, includeDefaults) => { return [obj.parameters.geometry]; });
+
+    // lights
+    this.addConstructorHandler(THREE.AmbientLight, (obj, includeDefaults) => { return [obj.color, obj.intensity]; });
+    this.addConstructorHandler(THREE.DirectionalLight, (obj, includeDefaults) => { return [obj.color, obj.intensity]; });
+    this.addConstructorHandler(THREE.HemisphereLight, (obj, includeDefaults) => { return [obj.color, obj.intensity]; });
+    this.addConstructorHandler(THREE.PointLight, (obj, includeDefaults) => { return [obj.color, obj.intensity, obj.distance, obj.decay]; });
+    this.addConstructorHandler(THREE.LightProbe, (obj, includeDefaults) => { return [obj.sh, obj.intensity]; });
+    this.addConstructorHandler(THREE.RectAreaLight, (obj, includeDefaults) => { return [obj.color, obj.intensity, obj.width, obj.height]; });
+    this.addConstructorHandler(THREE.SpotLight, (obj, includeDefaults) => { return [obj.color, obj.intensity, obj.distance, obj.angle, obj.penumbra, obj.decay]; });
+
+    // fog
+    this.addConstructorHandler(THREE.Fog, (obj, includeDefaults) => { return [obj.color, obj.near, obj.far]; });
+    this.addConstructorHandler(THREE.FogExp2, (obj, includeDefaults) => { return [obj.color, obj.density]; });
+
+    // material classes
+    // see MaterialParameters
+    const MaterialParametersFields: string[] = [
+      'alphaHash', 'alphaTest', 'alphaToCoverage', 'blendAlpha', 'blendColor',
+      'blendDst', 'blendDstAlpha', 'blendEquation', 'blendEquationAlpha',
+      'blending', 'blendSrc', 'blendSrcAlpha', 'clipIntersection', 'clippingPlanes',
+      'clipShadows', 'colorWrite', 'defines', 'depthFunc', 'depthTest',
+      'depthWrite', 'name', 'opacity', 'polygonOffset', 'polygonOffsetFactor',
+      'polygonOffsetUnits', 'precision', 'premultipliedAlpha', 'forceSinglePass',
+      'allowOverride', 'dithering', 'side', 'shadowSide', 'toneMapped',
+      'transparent', 'vertexColors', 'visible', 'format', 'stencilWrite',
+      'stencilFunc', 'stencilRef', 'stencilWriteMask', 'stencilFuncMask',
+      'stencilFail', 'stencilZFail', 'stencilZPass', 'userData'
+    ];
+
+    const MeshStandardMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'color', 'roughness', 'metalness', 'map', 'lightMap', 'lightMapIntensity', 'aoMap', 'aoMapIntensity',
+      'emissive', 'emissiveIntensity', 'emissiveMap', 'bumpMap', 'bumpScale', 'normalMap',
+      'normalMapType', 'normalScale', 'displacementMap', 'displacementScale', 'displacementBias',
+      'roughnessMap', 'metalnessMap', 'alphaMap', 'envMap', 'envMapRotation', 'envMapIntensity',
+      'wireframe', 'wireframeLinewidth', 'fog', 'flatShading'
+    ];
+
+    const LineBasicMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'color', 'fog', 'linewidth', 'linecap', 'linejoin'
+    ];
+
+    const LineDashedMaterialParametersFields: string[] = [
+      ...LineBasicMaterialParametersFields,
+      'scale', 'dashSize', 'gapSize'
+    ];
+
+    const MeshBasicMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'color', 'opacity', 'map', 'lightMap', 'lightMapIntensity', 'aoMap', 'aoMapIntensity',
+      'specularMap', 'alphaMap', 'fog', 'envMap', 'envMapRotation', 'combine', 'reflectivity', 'refractionRatio',
+      'wireframe', 'wireframeLinewidth', 'wireframeLinecap', 'wireframeLinejoin'
+    ];
+
+    const MeshDepthMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'map', 'alphaMap', 'depthPacking', 'displacementMap', 'displacementScale', 'displacementBias',
+      'wireframe', 'wireframeLinewidth'
+    ];
+
+    const MeshDistanceMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'map', 'alphaMap', 'displacementMap', 'displacementScale', 'displacementBias',
+      'farDistance', 'nearDistance', 'referencePosition'
+    ];
+
+    const MeshLambertMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'bumpMap', 'bumpScale', 'color', 'displacementMap', 'displacementScale', 'displacementBias',
+      'emissive', 'emissiveIntensity', 'emissiveMap', 'flatShading', 'map', 'lightMap', 'lightMapIntensity',
+      'normalMap', 'normalScale', 'aoMap', 'aoMapIntensity', 'specularMap', 'alphaMap', 'envMap',
+      'envMapRotation', 'combine', 'reflectivity', 'refractionRatio', 'wireframe', 'wireframeLinewidth',
+      'wireframeLinecap', 'wireframeLinejoin', 'fog'
+    ];
+
+    const MeshMatcapMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'color', 'matcap', 'map', 'bumpMap', 'bumpScale', 'normalMap', 'normalMapType', 'normalScale',
+      'displacementMap', 'displacementScale', 'displacementBias', 'alphaMap', 'fog', 'flatShading'
+    ];
+
+    const MeshNormalMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'bumpMap', 'bumpScale', 'normalMap', 'normalMapType', 'normalScale', 'displacementMap',
+      'displacementScale', 'displacementBias', 'wireframe', 'wireframeLinewidth', 'flatShading'
+    ];
+
+    const MeshPhongMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'color', 'specular', 'shininess', 'opacity', 'map', 'lightMap', 'lightMapIntensity', 'aoMap', 'aoMapIntensity',
+      'emissive', 'emissiveIntensity', 'emissiveMap', 'bumpMap', 'bumpScale', 'normalMap', 'normalMapType', 'normalScale',
+      'displacementMap', 'displacementScale', 'displacementBias', 'specularMap', 'alphaMap', 'envMap', 'envMapRotation',
+      'combine', 'reflectivity', 'refractionRatio', 'wireframe', 'wireframeLinewidth', 'wireframeLinecap', 'wireframeLinejoin',
+      'fog', 'flatShading'
+    ];
+
+    const MeshPhysicalMaterialParametersFields: string[] = [
+      ...MeshStandardMaterialParametersFields,
+      'anisotropyRotation', 'anisotropyMap', 'clearcoatMap', 'clearcoatRoughness', 'clearcoatRoughnessMap',
+      'clearcoatNormalScale', 'clearcoatNormalMap', 'ior', 'reflectivity', 'iridescenceMap', 'iridescenceIOR',
+      'iridescenceThicknessRange', 'iridescenceThicknessMap', 'sheenColor', 'sheenColorMap', 'sheenRoughness',
+      'sheenRoughnessMap', 'transmissionMap', 'thickness', 'thicknessMap', 'attenuationDistance',
+      'attenuationColor', 'specularIntensity', 'specularIntensityMap', 'specularColor', 'specularColorMap',
+      'anisotropy', 'clearcoat', 'iridescence', 'dispersion', 'sheen', 'transmission'
+    ];
+
+    const MeshToonMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'color', 'opacity', 'gradientMap', 'map', 'lightMap', 'lightMapIntensity', 'aoMap', 'aoMapIntensity',
+      'emissive', 'emissiveIntensity', 'emissiveMap', 'bumpMap', 'bumpScale', 'normalMap', 'normalMapType', 'normalScale',
+      'displacementMap', 'displacementScale', 'displacementBias', 'alphaMap', 'wireframe', 'wireframeLinewidth',
+      'wireframeLinecap', 'wireframeLinejoin', 'fog'
+    ];
+
+    const ShaderMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'uniforms', 'uniformsGroups', 'vertexShader', 'fragmentShader', 'linewidth', 'wireframe', 'wireframeLinewidth',
+      'lights', 'clipping', 'fog', 'extensions', 'glslVersion'
+    ];
+
+    const ShadowMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'color', 'fog'
+    ];
+
+    const PointsMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'color', 'map', 'alphaMap', 'size', 'sizeAttenuation', 'fog'
+    ];
+
+    const SpriteMaterialParametersFields: string[] = [
+      ...MaterialParametersFields,
+      'color', 'map', 'alphaMap', 'rotation', 'sizeAttenuation', 'fog'
+    ];
+
+    this.addConstructorHandler(THREE.MeshStandardMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, MeshStandardMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.LineBasicMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, LineBasicMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.LineDashedMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, LineDashedMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.MeshBasicMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, MeshBasicMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.MeshDepthMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, MeshDepthMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.MeshDistanceMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, MeshDistanceMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.MeshLambertMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, MeshLambertMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.MeshMatcapMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, MeshMatcapMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.MeshNormalMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, MeshNormalMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.MeshPhongMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, MeshPhongMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.MeshPhysicalMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, MeshPhysicalMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.MeshToonMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, MeshToonMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.RawShaderMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, ShaderMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.ShaderMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, ShaderMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.ShadowMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, ShadowMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.PointsMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, PointsMaterialParametersFields, includeDefaults); });
+    this.addConstructorHandler(THREE.SpriteMaterial, (obj, includeDefaults) => { return getObjectParameters(obj, SpriteMaterialParametersFields, includeDefaults); });
+
+    this.constructorHandlersRegistered = true;
+  }
+
+  // Loading methods
+  /**
+   * Sets whether the context is in editor mode
+   */
+  public setEditorMode(isEditor: boolean): void {
+    this.isEditor = isEditor;
+  }
+
+  /**
+   * Loads an actor from serialized data.
+   * @param actorData - The serialized actor data
+   * @param prefabs - A map of prefab names to their serialized data
+   * @returns The loaded actor
+   */
+  public async loadActor(data: Record<string, any>, prefabs: Record<string, SerializedActor> = {}): Promise<Actor | null> {
+    if (!isLegacyData(data)) {
+      const loader = new Loader({flags: this.isEditor ? LoaderFlags.None : LoaderFlags.WithoutEditor});
+      return loader.load(data as SerializedData) as Actor;
+    }
+
+    // support legacy data
+    const actorData = data as SerializedActor;
+    this.currentPrefabRegistry = prefabs;
+    const instanceData = WorldSerializer.parseActorData(actorData);
+    const prefabData = await this.resolvePrefab(instanceData, prefabs);
+    const actor = await this.buildActor(instanceData, prefabData);
+    if (actor && instanceData.prefabName) {
+      console.warn('⚠️ Instantiating from legacy prefab. Please resave the prefab asset!');
+    }
+    return actor;
+  }
+
+  /**
+   * Loads an actor from serialized data, synchronous version.
+   * @param actorData - The serialized actor data
+   * @param prefabs - A map of prefab names to their serialized data
+   * @returns The loaded actor
+   */
+  public loadActorSync(data: Record<string, any>, prefabs: Record<string, SerializedActor> = {}): Actor | null {
+    if (!isLegacyData(data)) {
+      const loader = new Loader({flags: this.isEditor ? LoaderFlags.None : LoaderFlags.WithoutEditor});
+      return loader.load(data as SerializedData) as Actor;
+    }
+
+    // support legacy data
+    const actorData = data as SerializedActor;
+    this.currentPrefabRegistry = prefabs;
+    const instanceData = WorldSerializer.parseActorData(actorData);
+    const prefabData = this.resolvePrefabSync(instanceData, prefabs);
+    const actor = this.buildActorSync(instanceData, prefabData);
+    if (actor && instanceData.prefabName) {
+      console.warn('⚠️ Instantiating from legacy prefab. Please resave the prefab asset!');
+    }
+    return actor;
+  }
+
+  /**
+   * Loads world data into an existing world instance.
+   * @param world - The target world to load data into
+   * @param data - The raw world data to load
+   */
+  public async loadWorld(world: World, data: Record<string, any>): Promise<void> {
+    if (!isLegacyData(data)) {
+      // New format, use Loader
+      const loader = new Loader();
+      await loader.loadToInstanceAsync(data as SerializedData, world);
+      return;
+    }
+
+    const worldData = data as SerializedWorld;
+    const parsedData = WorldSerializer.parseWorldData(worldData);
+    const actors = [];
+    if (parsedData.uuid) {
+      (world as any).uuid = parsedData.uuid;
+    }
+
+    if (this.isEditor && parsedData.properties?.editorData) {
+      try {
+        world.editorData = structuredClone(parsedData.properties.editorData);
+      } catch (error) {
+        console.error('❌ Failed to load world editor data:', error);
+      }
+    }
+
+    // Load post-processing configuration
+    if (parsedData.properties?.postProcessConfiguration) {
+      try {
+        world.setPostProcessConfiguration(parsedData.properties.postProcessConfiguration);
+      } catch (error) {
+        console.error('❌ Failed to load post-processing configuration:', error);
+      }
+    }
+
+    // Load scene resource references
+    if (parsedData.resources) {
+      world.sceneResources = parsedData.resources;
+    }
+
+    if (parsedData.actors) {
+      for (const actorData of parsedData.actors) {
+        try {
+          const actor = await this.loadActor(actorData, parsedData.prefabs);
+          if (actor) {
+            actors.push(actor);
+          }
+        }
+        catch (error) {
+          console.error(`Failed to load actor: ${actorData.uuid}, class: ${actorData.class}. Error: ${error}`, error instanceof Error ? error.stack : undefined);
+        }
+      }
+    }
+    // add all the actors in the end to make sure the loading is atomic
+    world.addActors(...actors);
+  }
+
+  /**
+   * Imports an object from serialized data.
+   * @param objectData - The serialized object data
+   * @returns The imported object
+   */
+  public importObject(data: Record<string, any>): any {
+    if (!isLegacyData(data)) {
+      const loader = new Loader({flags: this.isEditor ? LoaderFlags.None : LoaderFlags.WithoutEditor});
+      return loader.load(data as SerializedData);
+    }
+
+    const objectData = data as SerializedObject;
+    return this.construct(objectData);
+  }
+
+  private getPrefabName(instanceData: SerializedActor): string | null {
+    if (instanceData.prefabName) {
+      return instanceData.prefabName;
+    }
+    const ctor = instanceData.ctor as Record<string, any>;
+    if (ctor?.prefabName) {
+      return ctor.prefabName;
+    }
+    return null;
+  }
+
+  /**
+   * Gets the parent prefab name from actor data
+   */
+  private getParentPrefabName(actorData: SerializedActor): string | null {
+    return actorData.parentPrefabName ?? null;
+  }
+
+  /**
+   * Resolves the complete prefab inheritance chain, detecting circular dependencies
+   * @param prefabName - The starting prefab name
+   * @param prefabs - Available prefab data
+   * @param visited - Set of visited prefab names to detect cycles
+   * @returns Array of prefab data in inheritance order (base → derived)
+   */
+  private async resolvePrefabInheritanceChain(
+    prefabName: string,
+    prefabs: Record<string, SerializedActor>,
+    visited: Set<string> = new Set()
+  ): Promise<SerializedActor[]> {
+    if (visited.has(prefabName)) {
+      throw new Error(`🔄 Circular prefab dependency detected: ${Array.from(visited).join(' → ')} → ${prefabName}`);
+    }
+
+    visited.add(prefabName);
+
+    // Load the current prefab data
+    let prefabData: SerializedActor | undefined = prefabs[prefabName];
+    prefabData ??= this.loadedPrefabData.get(prefabName);
+    prefabData ??= await resourceManager.loadJsonObject(AssetPath.fromString(prefabName));
+
+    if (!prefabData) {
+      throw new Error(`❌ Prefab ${prefabName} not found`);
+    }
+
+    this.loadedPrefabData.set(prefabName, prefabData);
+
+    // Check if this prefab has a parent
+    const parentPrefabName = this.getParentPrefabName(prefabData);
+    if (parentPrefabName) {
+      // Recursively resolve parent chain
+      const parentChain = await this.resolvePrefabInheritanceChain(parentPrefabName, prefabs, new Set(visited));
+      visited.delete(prefabName);
+      return [...parentChain, prefabData];
+    } else {
+      visited.delete(prefabName);
+      return [prefabData];
+    }
+  }
+
+  /**
+   * Synchronous version of resolvePrefabInheritanceChain
+   */
+  private resolvePrefabInheritanceChainSync(
+    prefabName: string,
+    prefabs: Record<string, SerializedActor>,
+    visited: Set<string> = new Set()
+  ): SerializedActor[] {
+    if (visited.has(prefabName)) {
+      throw new Error(`🔄 Circular prefab dependency detected: ${Array.from(visited).join(' → ')} → ${prefabName}`);
+    }
+
+    visited.add(prefabName);
+
+    // Load the current prefab data
+    let prefabData: SerializedActor | undefined = prefabs[prefabName];
+    prefabData ??= this.loadedPrefabData.get(prefabName);
+
+    if (!prefabData) {
+      throw new Error(`❌ Prefab ${prefabName} not found`);
+    }
+
+    this.loadedPrefabData.set(prefabName, prefabData);
+
+    // Check if this prefab has a parent
+    const parentPrefabName = this.getParentPrefabName(prefabData);
+    if (parentPrefabName) {
+      // Recursively resolve parent chain
+      const parentChain = this.resolvePrefabInheritanceChainSync(parentPrefabName, prefabs, new Set(visited));
+      visited.delete(prefabName);
+      return [...parentChain, prefabData];
+    } else {
+      visited.delete(prefabName);
+      return [prefabData];
+    }
+  }
+
+  private async resolvePrefab(instanceData: SerializedActor, prefabs: Record<string, SerializedActor>): Promise<any | null> {
+    const prefabName = this.getPrefabName(instanceData);
+    if (!prefabName) return null;
+
+    // Resolve the complete inheritance chain
+    const inheritanceChain = await this.resolvePrefabInheritanceChain(prefabName, prefabs);
+
+    // Apply inheritance by merging from base to derived
+    let resolvedPrefabData: SerializedActor = inheritanceChain[0];
+
+    for (let i = 1; i < inheritanceChain.length; i++) {
+      const childPrefab = inheritanceChain[i];
+      resolvedPrefabData = deepMerge(resolvedPrefabData, childPrefab);
+    }
+
+    // Always remove UUID from prefab data - UUIDs are instance-specific, not part of prefab definition
+    // The instance UUID will be applied to the actor during construction, but should not be stored in prefab data
+    delete resolvedPrefabData.uuid;
+    return resolvedPrefabData;
+  }
+
+  private resolvePrefabSync(instanceData: SerializedActor, prefabs: Record<string, SerializedActor>): any | null {
+    const prefabName = this.getPrefabName(instanceData);
+    if (!prefabName) return null;
+
+    // Resolve the complete inheritance chain
+    const inheritanceChain = this.resolvePrefabInheritanceChainSync(prefabName, prefabs);
+
+    // Apply inheritance by merging from base to derived
+    let resolvedPrefabData: SerializedActor = inheritanceChain[0];
+
+    for (let i = 1; i < inheritanceChain.length; i++) {
+      const childPrefab = inheritanceChain[i];
+      resolvedPrefabData = deepMerge(resolvedPrefabData, childPrefab);
+    }
+
+    // Always remove UUID from prefab data - UUIDs are instance-specific, not part of prefab definition
+    // The instance UUID will be applied to the actor during construction, but should not be stored in prefab data
+    delete resolvedPrefabData.uuid;
+    return resolvedPrefabData;
+  }
+
+  private async buildActor(instanceData: SerializedActor, prefabData: SerializedActor | null): Promise<Actor | null> {
+    // use a copy of the data to avoid modifying the original data which could be part of the world data (that we shouldn't modify)
+    const prefabDataCopy = prefabData ? structuredClone(prefabData) : null;
+    let resolvedData: SerializedActor;
+    if (prefabDataCopy) {
+      resolvedData = deepMerge(prefabDataCopy, instanceData);
+    } else {
+      resolvedData = structuredClone(instanceData);
+    }
+
+    if (prefabDataCopy) {
+      // the instance data may contain an irrelevant class name, use the prefab class instead
+      resolvedData.class = prefabDataCopy.class;
+    }
+
+    if (!resolvedData.ctor) {
+      throw new Error('Actor data is invalid, missing ctor');
+    }
+
+    if (Array.isArray(resolvedData.ctor)) {
+      throw new Error('Actor data is invalid, ctor is an array');
+    }
+
+
+    // Skip editor only actor in game
+    if (resolvedData.properties?.editorOnly && !this.isEditor) {
+      return null;
+    }
+
+    if (resolvedData.ctor.rootComponent) {
+      resolvedData.ctor.rootComponent = this.loadSceneObject(null, resolvedData.ctor.rootComponent);
+      if (!resolvedData.ctor.rootComponent) {
+        // Skip editor only root component in game (skips the actor)
+        return null;
+      }
+    }
+
+    {
+      // TEMP hack to load the components from the now deprecated ctor.components field
+      const sceneComponents = resolvedData.ctor.sceneComponents ?? [];
+      const components = resolvedData.ctor.components ?? [];
+      resolvedData.ctor.sceneComponents = [...sceneComponents, ...components];
+    }
+
+    // Construct actor
+    const actor = this.construct(resolvedData) as Actor;
+
+    const prefabName = this.getPrefabName(instanceData);
+
+    if (prefabName && prefabDataCopy) {
+      // Store the entire prefab registry for this actor so it can resolve inheritance chains later
+      // Ensure prefab data doesn't contain instance-specific UUID
+      const cleanPrefabData = JSON.parse(JSON.stringify(prefabDataCopy));
+      delete cleanPrefabData.uuid;
+      actor.setPrefab(prefabName, cleanPrefabData, this.currentPrefabRegistry);
+    }
+
+    return actor;
+  }
+
+  private buildActorSync(instanceData: SerializedActor, prefabData: SerializedActor | null): Actor | null {
+    // use a copy of the data to avoid modifying the original data which could be part of the world data (that we shouldn't modify)
+    const prefabDataCopy = prefabData ? structuredClone(prefabData) : null;
+    let resolvedData: SerializedActor;
+    if (prefabDataCopy) {
+      resolvedData = deepMerge(prefabDataCopy, instanceData);
+    } else {
+      resolvedData = structuredClone(instanceData);
+    }
+
+    if (prefabDataCopy) {
+      // the instance data may contain an irrelevant class name, use the prefab class instead
+      resolvedData.class = prefabDataCopy.class;
+    }
+
+    if (!resolvedData.ctor) {
+      throw new Error('Actor data is invalid, missing ctor');
+    }
+
+    if (Array.isArray(resolvedData.ctor)) {
+      throw new Error('Actor data is invalid, ctor is an array');
+    }
+
+    // Skip editor only actor in game
+    if (resolvedData.properties?.editorOnly && !this.isEditor) {
+      return null;
+    }
+
+    if (resolvedData.ctor.rootComponent) {
+      resolvedData.ctor.rootComponent = this.loadSceneObject(null, resolvedData.ctor.rootComponent);
+      if (!resolvedData.ctor.rootComponent) {
+        // Skip editor only root component in game (skips the actor)
+        return null;
+      }
+    }
+
+    {
+      // TEMP hack to load the components from the now deprecated ctor.components field
+      const sceneComponents = resolvedData.ctor.sceneComponents ?? [];
+      const components = resolvedData.ctor.components ?? [];
+      resolvedData.ctor.sceneComponents = [...sceneComponents, ...components];
+    }
+
+    // Construct actor
+    const actor = this.construct(resolvedData) as Actor;
+
+    const prefabName = this.getPrefabName(instanceData);
+
+    if (prefabName && prefabDataCopy) {
+      // Store the entire prefab registry for this actor so it can resolve inheritance chains later
+      // Ensure prefab data doesn't contain instance-specific UUID
+      const cleanPrefabData = JSON.parse(JSON.stringify(prefabDataCopy));
+      delete cleanPrefabData.uuid;
+      actor.setPrefab(prefabName, cleanPrefabData, this.currentPrefabRegistry);
+    }
+
+    return actor;
+  }
+
+  private construct(objectData: any): any {
+    if (objectData === null || objectData === undefined) {
+      return objectData;
+    }
+    if (objectData[externalRefKey]) {
+      return WorldSerializationContext.ExternalObjects.get(objectData[externalRefKey]);
+    }
+    if (objectData[internalRefKey]) {
+      // Resolve internal reference to already loaded object
+      const refUUID = objectData[internalRefKey];
+      const referencedObject = this.loadedObjectsByUUID.get(refUUID);
+      if (!referencedObject) {
+        console.warn(`Referenced object with uuid ${refUUID} not found in loaded objects`);
+      }
+      return referencedObject;
+    }
+    if (Array.isArray(objectData)) {
+      // Check for compact vector format with type tags
+      if (objectData.length >= 2 && typeof objectData[objectData.length - 1] === 'string') {
+        const typeTag = objectData[objectData.length - 1];
+        switch (typeTag) {
+          case 'v2':
+            return new THREE.Vector2(objectData[0], objectData[1]);
+          case 'v':  // v for Vector3 (most common)
+          case 'v3': // Keep v3 for backward compatibility
+            return new THREE.Vector3(objectData[0], objectData[1], objectData[2]);
+          case 'v4':
+            return new THREE.Vector4(objectData[0], objectData[1], objectData[2], objectData[3]);
+          case 'e':
+            return new THREE.Euler(objectData[0], objectData[1], objectData[2]);
+          case 'q':
+            return new THREE.Quaternion(objectData[0], objectData[1], objectData[2], objectData[3]);
+          case 'c':
+            return new THREE.Color(objectData[0], objectData[1], objectData[2]);
+          case 'ia':
+            return new Int32Array(objectData.slice(0, objectData.length - 1));
+          case 'fa':
+            return new Float32Array(objectData.slice(0, objectData.length - 1));
+        }
+      }
+      // array value, construct each value
+      return objectData.map(v => v != null ? this.construct(v) : null).filter(v => v != null);
+    } else if (typeof objectData === 'object') {
+      if (this.constructedObjects.has(objectData)) {
+        // return the object as-is if it's already constructed
+        return objectData;
+      }
+      const className = this.construct(objectData.class);
+      if (className) {
+        // object value needs construction, construct it
+        const object = ClassRegistry.constructObject(className, true, this.construct(objectData.ctor));
+        const properties = this.construct(objectData.properties);
+        if (properties) {
+          if (properties.editorOnly && !this.isEditor) {
+            return null; // Skip editor only objects in game
+          }
+          if (properties.position) {
+            object.position.copy(properties.position);
+            delete properties.position;
+          }
+          if (properties.rotation) {
+            object.rotation.copy(properties.rotation);
+            delete properties.rotation;
+          }
+          if (properties.scale) {
+            object.scale.copy(properties.scale);
+            delete properties.scale;
+          }
+          if (properties.tags && typeof object.setTags === 'function') {
+            object.setTags(properties.tags);
+            delete properties.tags;
+          }
+          if (properties.hiddenInGame !== undefined && typeof object.setHiddenInGame === 'function') {
+            object.setHiddenInGame(properties.hiddenInGame);
+            delete properties.hiddenInGame;
+          }
+          if (properties.editorOnly !== undefined && typeof object.setEditorOnly === 'function') {
+            object.setEditorOnly(properties.editorOnly);
+            delete properties.editorOnly;
+          }
+
+          Object.assign(object, properties);
+        }
+        if (objectData.uuid) {
+          (object as any).uuid = objectData.uuid;
+          // Store the object for potential reference resolution
+          this.loadedObjectsByUUID.set(objectData.uuid, object);
+        }
+        this.constructedObjects.add(object);
+        return object;
+      } else {
+        // regular object value, construct each property
+        const expandedObject: Record<string, any> = {};
+        for (const [k, v] of Object.entries(objectData)) {
+          expandedObject[k] = this.construct(v);
+        }
+        this.constructedObjects.add(expandedObject);
+        return expandedObject;
+      }
+    } else {
+      // none of the above, most likely just a primitive value
+      return objectData;
+    }
+  }
+
+  private loadSceneObject(parent: THREE.Object3D | null, sceneObjectData: any): THREE.Object3D | null {
+    const sceneObject = this.construct(sceneObjectData) as THREE.Object3D;
+    if (!sceneObject) {
+      return null;
+    }
+    if (parent) {
+      parent.add(sceneObject);
+    }
+    for (const childData of sceneObjectData.children ?? []) {
+      this.loadSceneObject(sceneObject, childData);
+    }
+    return sceneObject;
+  }
+}
+
+/**
+ * Handles loading and parsing of world data into the engine.
+ * Provides functionality to convert serialized world data into
+ * runtime objects and components.
+ */
+export class WorldSerializer {
+  /**
+   * Exports an object to a serializable format.
+   * @param object - The object to export
+   * @param includeDefaults - Whether to include default values
+   * @returns The serialized object
+   */
+  public static exportObject(object: any, includeDefaults: boolean): object {
+    let data = new WorldSerializationContext().exportObject(object, false);
+    if (typeof data === 'object' && !(serializationVersionKey in data)) {
+      data = {
+        [serializationVersionKey]: SerializationVersion.Legacy,
+        ...data
+      };
+    }
+    return data;
+  }
+
+  public static exportAsPrefab(obj: any, inlineToPrefab: boolean = false): object {
+    const asPrefab = true;
+    const data = new WorldSerializationContext().exportObject(obj, asPrefab, inlineToPrefab);
+    return data;
+  }
+
+  /**
+   * Validates and parses raw actor data against the defined schema.
+   * @param actorData - The raw actor data object to parse
+   * @returns The validated actor data object
+   */
+  public static parseActorData(actorData: SerializedActor) {
+    return actorSchema.parse(actorData);
+  }
+
+  /**
+   * Loads an actor from serialized data.
+   * @param actorData - The serialized actor data
+   * @param prefabs - A map of prefab names to their serialized data
+   * @returns The loaded actor
+   */
+  public static async loadActor(actorData: SerializedActor, prefabs: Record<string, SerializedActor> = {}, isEditor?: boolean): Promise<Actor | null> {
+    const context = new WorldSerializationContext();
+    context.setEditorMode(isEditor ?? false);
+    const loadedActor = context.loadActor(actorData, prefabs);
+    return loadedActor;
+  }
+
+  /**
+   * Loads an actor from serialized data, synchronous version.
+   * @param actorData - The serialized actor data
+   * @param prefabs - A map of prefab names to their serialized data. It must be provided if actorData contains a prefabName
+   * @returns The loaded actor
+   */
+  public static loadActorSync(actorData: SerializedActor, prefabs: Record<string, SerializedActor> = {}, isEditor?: boolean): Actor | null {
+    const context = new WorldSerializationContext();
+    context.setEditorMode(isEditor ?? false);
+    return context.loadActorSync(actorData, prefabs);
+  }
+
+
+
+  /**
+   * Validates and parses raw world data against the defined schema.
+   * @param worldData - The raw world data object to parse
+   * @returns The validated world data object
+   */
+  public static parseWorldData(worldData: SerializedWorld): SerializedWorld {
+    return worldSchema.parse(worldData);
+  }
+
+  /**
+   * Loads world data into an existing world instance.
+   * Creates actors, components, and scene hierarchies based on the provided data.
+   * @param world - The target world to load data into
+   * @param worldData - The raw world data to load
+   * @param isEditor - Whether the world is being loaded in the editor
+   */
+  public static async loadWorld(world: World, worldData: SerializedWorld, isEditor?: boolean): Promise<void> {
+    const context = new WorldSerializationContext();
+    context.setEditorMode(isEditor ?? false);
+    return context.loadWorld(world, worldData);
+  }
+
+  public static importObject(objectData: SerializedObject, isEditor?: boolean): any {
+    const context = new WorldSerializationContext();
+    context.setEditorMode(isEditor ?? false);
+    return context.importObject(objectData);
+  }
+
+  /**
+   * Creates prefab data from an actor
+   * @param actor - The actor to create prefab data from
+   * @param inlineToPrefab - whether to inline to the actor's prefab itself, as against to creating a new prefab that is dependent on the actor's prefab
+   * @returns The prefab data
+   */
+  public static createPrefabDataFromActor(actor: Actor, inlineToPrefab: boolean = false): any {
+    return WorldSerializer.exportAsPrefab(actor, inlineToPrefab);
+  }
+
+  /** Creates prefab data from an actor with a parent prefab  */
+  public static createPrefabDataFromActorWithParent(
+    actor: Actor,
+    parentPrefabName: string
+  ): SerializedActor {
+    const prefabData = actor.asExportedObject();
+    replace_uuids(prefabData, { deleteKey: true });
+    delete prefabData.prefabName;
+    prefabData.parentPrefabName = parentPrefabName;
+    return prefabData;
+  }
+
+  /** Loads the template actor from a prefab */
+  public static loadPrefabTemplateActor(prefabName: string, prefabs: Record<string, any>, isEditor: boolean = true): Actor {
+    const prefabData = prefabs[prefabName];
+    if (isLegacyData(prefabData)) {
+      const prefab = WorldSerializer.loadActorSync({
+        prefabName,
+      }, prefabs, isEditor);
+      if (!prefab) {
+        throw new Error('Failed to load prefab template actor');
+      }
+      if (prefab.getPrefabName() === prefabName) {
+        prefab.clearPrefab(); // Clear prefab reference to avoid circular dependency.
+      }
+      return prefab;
+    }
+    return loadPrefabTemplateInstance(prefabName, prefabs, {withoutEditor: !isEditor});
+  }
+}