@directivegames/genesys.js 3.1.24

package/src/utils/serialization/serializer.ts

@@ -0,0 +1,1111 @@
+import * as THREE from 'three';
+
+import { SerializationVersion } from '../../const.js';
+import { ClassRegistry } from '../../systems/ClassRegistry.js';
+
+import { getAllPropertiesFromProto, getDefaultObject, getDefaultObjectFromName } from './cdo.js';
+import {
+  getClassForDeserialization,
+  getClassSerializeName,
+} from './clsAlias.js';
+import { instantiatePrefab } from './prefab.js';
+import { PrefabManager } from './prefabManager.js';
+import { ISerializableObjectTag } from './serializable.js';
+import {
+  getDeserializeFn,
+  getSerializeFn,
+  getStaticDeserializeFn
+} from './specializationUtils.js';
+import './specialization.js';  // make sure specializations are registered
+
+import type { PropertyMetadata } from './decorator.js';
+import type { ISerializableObject } from './serializable.js';
+
+
+type RefType = number;
+type Ref = { $ref: RefType };
+type ClassInfo = { $class: string, $ctorArgs?: any[] };
+export type PrefabInfo = { $path: string };
+export type BaseInfo = ClassInfo | PrefabInfo;
+type Meta = { editorOnly?: boolean }
+type SerializedSubObject = { $id?: RefType, $value: any, $base?: BaseInfo, $meta?: Meta };
+type RootSerializedData = { $root: any, $objects?: SerializedSubObject[] };
+export type SerializedData = { $version: number } & RootSerializedData;
+
+const VERSION = SerializationVersion.V1;
+const UNREGISTERED_CLASS_PREFIX = 'UNREGISTERED.';
+
+function isClassInfo(baseInfo: BaseInfo): baseInfo is ClassInfo {
+  return '$class' in baseInfo;
+}
+
+function isPrefabInfo(baseInfo: BaseInfo): baseInfo is PrefabInfo {
+  return '$path' in baseInfo;
+}
+
+function isSerializableObject(obj: any): obj is ISerializableObject {
+  return obj && typeof obj === 'object' && obj[ISerializableObjectTag] === true;
+}
+
+const DumpValueResult = {
+  Dumped: 0,
+  SkippedTransient: 1,
+  SkippedEqualToDefaultValue: 2,
+  SkippedOtherwise: 3,
+} as const;
+
+type DumpValueResult = typeof DumpValueResult[keyof typeof DumpValueResult];
+
+type CtorArgProperty = {
+  name?: string;
+  value: any;
+  metadata?: PropertyMetadata;
+}
+
+
+/**
+ * The serialized data will either be $root + $objects, or $prefab + $diff
+ * if it's $prefab + $diff, the prefab data can be another prefab, forming a chain of prefabs
+ *
+ * A typical result of serialized (SerializedData) would look something like this:
+ * {
+ *   $prefab: {
+ *    $path: '@engine/prefabs/Prefab1.prefab.json'
+ *   },
+ *   $diff: {
+ *     // only the differences from the prefab1
+ *   }
+ * }
+ * Once all prefabs with paths are resolved, the final expanded data would look like this:
+ * {
+ *   $prefab: {
+ *    $path: '@engine/prefabs/Prefab1.prefab.json',
+ *    $data: {
+ *      // yet another prefab data here
+ *     $prefab: {
+ *       $path: '@engine/prefabs/Prefab2.prefab.json',
+ *       $data: {
+ *         // a prefab that's based on Actor instead of another prefab
+ *         $root: {
+ *           $class: 'ENGINE.Actor', ...
+ *         },
+ *         $objects: [
+ *           // serialized objects here
+ *         ]
+ *       }
+ *     },
+ *     $diff: {
+ *       // only the differences from the prefab2
+ *     }
+ *    }
+ *   },
+ *   $diff: {
+ *     // only the differences from the prefab1
+ *   }
+ * }
+ */
+
+// make sure it's kept in sync with RefType
+function _isRef(v: any): v is { $ref: RefType } {
+  return v && typeof v === 'object' && typeof v.$ref === 'number';
+}
+
+function getAllProperties(obj: any): Map<string, PropertyMetadata> {
+  let proto = Object.getPrototypeOf(obj);
+  return getAllPropertiesFromProto(proto);
+}
+
+function shouldSerializeRespectingMetadata(obj: any): boolean {
+  const properties = getAllProperties(obj);
+  const hasDecoratedProperties = properties.size > 0;
+  if (hasDecoratedProperties) {
+    return true;
+  }
+
+  const className = ClassRegistry.getClassName(obj);
+  const isClassRegistered = !!className;
+  return isClassRegistered;
+}
+
+class Serializer {
+  protected get isDumping(): boolean {return false;}
+
+}
+
+/**
+ * Dumper serializes objects into a structured format, handling references and class instances.
+ * If an object is referenced more than once, it will be assigned an ID and stored in the $objects array as SerializedObject[].
+ * If an object is a class instance, it will be stored with its class name, constructor arguments, and properties, basically an inlined `SerializedObject`
+ * otherwise, it will be inlined directly.
+ * The output format is `SerializedData`, with always a $root field, and optionally a $objects array.
+ * The following are possible outputs:
+ * plain objects: {a: 1, b: {x: 2, y: 3}} -> {$root: {a: 1, b: {x: 2, y:3}}}
+ * with shared/circular references: {a: obj1, b: obj1, c: {x: 1}} -> {$root: {a: {$ref: 1}, b: {$ref: 1}, c: {x: 1}}, $objects: [{ $id: 1, $value: {fields of obj1...} }]}
+ * with class: THREE.Vector3(1,2,3) -> {$root: { $class: 'THREE.Vector3', x:1, y:2, z:3 }}
+ * ENGINE.Actor({data: 3, position: new THREE.Vector3(1, 2, 3)}) -> {
+ *  $root: {
+ *    $class: 'ENGINE.Actor',
+ *    $ctorArgs: [ {data: 3, position: {$class: 'THREE.Vector3', x:1, y:2, z:3}} ],
+ *    actor properties...
+ * }
+ */
+
+export const DumperFlags = {
+  None: 0,
+  AsPrefab: 1 << 0,
+  Inline: 2 << 0  // work with AsPrefab, if exists, object will be dumped to modify its prefab, instead of a new prefab based on its prefab.
+} as const;
+export type DumperFlags = typeof DumperFlags[keyof typeof DumperFlags];
+
+export interface DumperOptions {
+  flags?: DumperFlags,
+}
+
+export const LoaderFlags = {
+  None: 0,
+  WithoutEditor: 1 << 0,
+} as const;
+export type LoaderFlags = typeof LoaderFlags[keyof typeof LoaderFlags];
+
+export interface LoaderOptions {
+  flags?: LoaderFlags,
+  ctorArgsOverrides?: Record<string, any>[] | Record<string, any>
+}
+
+export class Dumper extends Serializer {
+  private seen = new WeakMap<any, RefType>();
+  private objects: SerializedSubObject[] = [];
+  private idCounter = 1;
+  private currentRecord: SerializedSubObject | null = null;
+  private defaultValues: any = null;
+  private refCount = new Map<RefType, number>();
+  private pathStack: string[] = [];
+  private flags: DumperFlags;
+
+  constructor(options?: DumperOptions) {
+    super();
+    this.flags = options?.flags ?? DumperFlags.None;
+    if (this.hasFlags(DumperFlags.Inline)) {
+      // make sure AsPrefab is also set
+      this.flags |= DumperFlags.AsPrefab;
+    }
+  }
+
+  protected override get isDumping(): boolean { return true; }
+
+  public hasFlags(flags: DumperFlags): boolean {
+    return (this.flags & flags) === flags;
+  }
+
+  public get dumpingAsPrefab() {
+    return this.hasFlags(DumperFlags.AsPrefab);
+  }
+
+  public dump(obj: any): SerializedData {
+    if (this.idCounter > 1 || this.objects.length > 0 || this.currentRecord) {
+      throw new Error('Dumper instances cannot be reused.');
+    }
+
+    let realPrefabPath: any;
+    if (this.hasFlags(DumperFlags.Inline) && obj.$prefab) {
+      // modify existing prefab to its parent
+      realPrefabPath = obj.$prefab;
+      const baseInfo = PrefabManager.getPrefabBaseInfo(realPrefabPath.$path);
+      if (baseInfo && isPrefabInfo(baseInfo)) {
+        obj.$prefab = baseInfo;
+      } else if (baseInfo && isClassInfo(baseInfo)) {
+        delete obj.$prefab;
+      }
+    }
+
+    try {
+      const exported = this._dump(obj);
+      const objects = this.objects;
+
+      // result with all data fields serialized
+      const rootData: RootSerializedData = {
+        $root: exported,
+      };
+      if (objects.length > 0) {
+        rootData.$objects = objects;
+      }
+
+      // optimize to make objects that are only referenced once inlined
+      const optimizedExpandedResult = this._optimize(rootData);
+
+      // generate diff against base data if applicable
+      // const diff = deepDiff(expandedBaseData, optimizedExpandedResult);
+      const result: SerializedData = {
+        $version: VERSION,
+        ...optimizedExpandedResult
+      };
+
+      return result;
+    } finally {
+      if (realPrefabPath) {
+        obj.$prefab = realPrefabPath;
+      }
+    }
+  }
+
+  private _optimize(serializedData: RootSerializedData): RootSerializedData {
+    // flatten the objects that are only referenced once
+    const objectsMap = new Map<RefType, SerializedSubObject>();
+    if (serializedData.$objects) {
+      for (const record of serializedData.$objects) {
+        objectsMap.set(record.$id!, record);
+      }
+    }
+
+    // step 1: inline objects that are only referenced once
+    const inlineObject = (obj: any): any => {
+      if (typeof obj !== 'object' || obj === null) {
+        return;
+      }
+
+      for (const [k, v] of Object.entries(obj)) {
+        if (_isRef(v)) {
+          const refId = v.$ref;
+          const refCount = this.refCount.get(refId)!;
+          if (refCount === 1) {
+            const record = objectsMap.get(refId)!;
+            if (record.$value && typeof record.$value === 'object' && !Array.isArray(record.$value)) {
+              const { $value = {}, $id, ...rest } = record;
+              obj[k] = {
+                ...rest,
+                ...$value,
+              };
+            } else {
+              obj[k] = record.$value;
+            }
+          }
+        }
+
+        inlineObject(obj[k]);
+      }
+    };
+
+    // start inlining from the root
+    inlineObject(serializedData);
+
+    // step 2: rebuild the $objects array
+    if (serializedData.$objects) {
+      serializedData.$objects = serializedData.$objects?.filter(record => {
+        const refCount = this.refCount.get(record.$id!)!;
+        return refCount > 1;
+      });
+
+      if (serializedData.$objects.length === 0) {
+        delete serializedData.$objects;
+      }
+    }
+
+    // step 3: optional, reassign IDs to be sequential, this is mainly to make tests easier compose expected output
+    const idMap = new Map<RefType, RefType>();
+    let newIdCounter = 1;
+    if (serializedData.$objects) {
+      for (const record of serializedData.$objects) {
+        const oldId = record.$id!;
+        const newId = newIdCounter++;
+        idMap.set(oldId, newId);
+        record.$id = newId;
+      }
+    }
+
+    const remapRefs = (obj: any) => {
+      if (typeof obj !== 'object' || obj === null) {
+        return;
+      }
+
+      for (const [k, v] of Object.entries(obj)) {
+        if (_isRef(v)) {
+          v.$ref = idMap.get(v.$ref)!;
+          if (!v.$ref) {
+            throw new Error(`Dumper: remapRefs failed to find new ID for ref ${v.$ref}`);
+          }
+        }
+        remapRefs(obj[k]);
+      }
+    };
+
+    // remap refs in the root object
+    remapRefs(serializedData);
+
+    // step 4: replace { $base: {$class: '...' } } with just {$bc: '...'} for smaller size
+    const shortenClassBaseInfoWithoutCtorArgs = (obj: any) => {
+      if (typeof obj !== 'object' || obj === null) {
+        return;
+      }
+      for (const [k, v] of Object.entries(obj)) {
+        if (v && typeof v === 'object' && '$base' in v) {
+          const baseInfo = v.$base as BaseInfo;
+          if (isClassInfo(baseInfo) && !('$ctorArgs' in baseInfo)) {
+            (v as any).$bc = baseInfo.$class;
+            delete v.$base;
+          }
+        }
+        shortenClassBaseInfoWithoutCtorArgs(v);
+      }
+    };
+    shortenClassBaseInfoWithoutCtorArgs(serializedData);
+
+
+    // step 5: handle float numbers to reduce size
+    const processNumbers = (obj: any) => {
+      if (typeof obj !== 'object' || obj === null) {
+        return;
+      }
+
+      for (const [k, v] of Object.entries(obj)) {
+        if (typeof v === 'number') {
+          if (Number.isInteger(v)) {
+            obj[k] = v;
+          } else {
+            obj[k] = Math.round(v * 1000000) / 1000000;
+          }
+        } else {
+          processNumbers(obj[k]);
+        }
+      }
+    };
+
+    processNumbers(serializedData);
+
+    return serializedData;
+  }
+
+  // instanceKey is the key in the parent object, used for getting the value on prefab
+  // return true if anything is dumped
+  public dumpValue(key: string, value: any, instanceKey?: string, metadata?: PropertyMetadata): DumpValueResult {
+    if (metadata?.transient) {
+      // skip transient properties
+      return DumpValueResult.SkippedTransient;
+    }
+    if (metadata?.transientOnPrefab && this.dumpingAsPrefab) {
+      // skip transientOnPrefab properties when dumping as prefab
+      return DumpValueResult.SkippedTransient;
+    }
+    if (value
+      && typeof value === 'object'
+      && (value[ISerializableObjectTag] === true || value instanceof THREE.Object3D)
+      && value.isTransient
+      && value.isTransient()
+    ) {
+      // transient object, skip it
+      return DumpValueResult.SkippedTransient;
+    }
+
+    const isCtorArgs = (metadata: PropertyMetadata) => {
+      return !!metadata?.ctorArg || metadata?.ctorArgIndex !== undefined;
+    };
+    if (metadata && isCtorArgs(metadata) && metadata.ctorArg !== 'ctorArgAndProperty') {
+      // already dumped as ctorArgs
+      return DumpValueResult.SkippedOtherwise;
+    }
+    if (this.defaultValues) {
+      const defaultValue = this.defaultValues[key];
+      if (value === null || typeof value !== 'object') {
+        if (value === defaultValue) {
+        // skip if values strictly equals to base instance value
+          return DumpValueResult.SkippedEqualToDefaultValue;
+        }
+      } else {
+        // object type, do a deep comparison
+        if (
+          defaultValue
+          && Object.getPrototypeOf(value) === Object.getPrototypeOf(defaultValue)
+          && JSON.stringify(value) === JSON.stringify(defaultValue)
+        ) {
+          return DumpValueResult.SkippedEqualToDefaultValue;
+        }
+      }
+    }
+
+    return this._dumpTo(key, value, this.currentRecord!.$value, instanceKey, metadata) ? DumpValueResult.Dumped : DumpValueResult.SkippedOtherwise;
+  }
+
+  // [value, propertyName, propertyMetadata]
+  public dumpCtorArgs(args: CtorArgProperty[]): void {
+    const baseInfo =  this.currentRecord!.$base;
+    if (!baseInfo || !(baseInfo as ClassInfo).$class)
+    {
+      // only dump ctor args if $class is present
+      // So this would skip
+      // - an instance whose base is a prefab
+      // - an instance whose base is a class that's not registered,
+      return;
+    }
+
+    const classInfo = this.currentRecord!.$base as ClassInfo;
+    classInfo.$ctorArgs = [];
+    for (let i = 0; i < args.length; i++) {
+      // TODO: cannot skip dumping ctor args (`args[i].name ?? null` for base's corresponding filed) for now,
+      // as it will dump a `{}` if the ctor args are same as base, but it would cause big issue when loading
+      // should the base (cdo)'s corresponding ctor args be passed into instances? or do a deep copy? what if there are complex object in ctor args?
+      this._dumpTo(String(i), args[i].value, classInfo.$ctorArgs,  /*args[i].name ??*/ null, args[i].metadata);
+    }
+  }
+
+  public removeDumpedValue(key: string) {
+    if (key in this.currentRecord!.$value) {
+      delete this.currentRecord!.$value[key];
+    }
+  }
+
+  private _dumpTo(key: string, value: any, target: any, instanceKey?: string | null, metadata?: PropertyMetadata): boolean {
+    let dumped = false;
+    this.pathStack.push(key);
+    // const fullPath = this.pathStack.join('.');
+    // console.log('dumping key:', fullPath);
+    if (value !== undefined) {
+      // NOTE: if instanceKey is undefined, use `key`; but if `instanceKey` is null, don't use any key to get default values
+      const propertyName = instanceKey !== null ? (instanceKey ?? key) : null;
+      const defaultValues = propertyName ? this.defaultValues?.[propertyName] : undefined;
+      target[key] = this._dump(value, defaultValues, metadata?.serialize);
+      dumped = true;
+    }
+    this.pathStack.pop();
+    return dumped;
+  }
+
+  public dumpProperties(obj: any) {
+    if (!shouldSerializeRespectingMetadata(obj)) {
+      const isArray = Array.isArray(obj);
+      // no decorated properties, do a deep dump
+      let outputIndex = 0;
+      const entries = isArray
+        ? obj.map((val, i) => [i, val] as const)
+        : Object.entries(obj);
+
+      for (const [key, val] of entries) {
+        if (!isArray && (key as string).startsWith('$')) continue;  // skip special properties, such as $prefab
+
+        // this has no problem with object, but with array, it can result in `undefined` entries, due to either skipping transient properties or default values
+        const dumpKey = isArray ? String(outputIndex) : key as string;
+        const dumpResult = this.dumpValue(dumpKey, val);
+        if (isArray && dumpResult !== DumpValueResult.SkippedTransient) {
+          // don't increase index if skipped due to transient
+          outputIndex += 1;
+        }
+        // TODO: should always dump for array, otherwise [1,2,3,4] changed to [1,2,999,4] will dump only [999], making loader yield incorrect result ([1,2,3,4,999])
+        // Should simply do the following
+        // `const dumped = this.dumpValue(key as string, val);`
+        // however we have an issue here `dumpValue` skips dumping and return undefined for
+        // both a value that equals default value, or a value that doesn't need to dump at all (i.e. transient object)
+        // [1, 2, 3, 4] -> [1, 2, 999, 4] dumps [undefined, undefined, 999, undefined]
+        // [GlobalParticleManager, Actor, Actor] dumps [undefined, {...}, {...}]
+        // and further more, `undefined` becomes `null` once stringified. we need to fix this
+      }
+
+      // if obj is an array, and it has default values, let's only record the "diff" here
+      if (isArray && Object.keys(this.defaultValues).length > 0) {
+        const dumpedArray = this.currentRecord!.$value;
+        this.currentRecord!.$value = {};
+        for (const [key, val] of Object.entries(dumpedArray)) {
+          if (val !== undefined) {
+            this.currentRecord!.$value[key] = val;
+          }
+        }
+      }
+      return;
+    }
+
+    const properties = getAllProperties(obj);
+    const isCtorArgs = (metadata: PropertyMetadata) => {
+      return !!metadata?.ctorArg || metadata?.ctorArgIndex !== undefined;
+    };
+
+    // first dump ctorArgs if exist
+    const ctorArgsMeta: Map<string, PropertyMetadata> = new Map(
+      [...properties].filter(([key, metadata]) => isCtorArgs(metadata))
+    );
+
+    // warning if multiple properties have same ctorArgIndex, the order is not guaranteed
+    if (ctorArgsMeta.size > 1) {
+      const indexSet = new Set<number>(
+        [...ctorArgsMeta.values()].map(meta => meta.ctorArgIndex ?? 0)
+      );
+      if (indexSet.size < ctorArgsMeta.size) {
+        console.warn('Dumper: Multiple properties have the same ctorArgIndex, the order is not guaranteed.');
+      }
+    }
+
+    if (ctorArgsMeta.size > 0) {
+      const ctorArgsArray: CtorArgProperty[] = [];
+      const sortedCtorArgs = [...ctorArgsMeta].sort((a, b) => {
+        const indexA = a[1].ctorArgIndex ?? 0;
+        const indexB = b[1].ctorArgIndex ?? 0;
+        return indexA - indexB;
+      });
+      for (const [key, metadata] of sortedCtorArgs) {
+        ctorArgsArray.push({ name: key, value: obj[key], metadata });
+      }
+      this.dumpCtorArgs(ctorArgsArray);
+    }
+
+    // then dump other properties
+    for (const [key, metadata] of properties) {
+      this.dumpValue(key, obj[key], key, metadata);
+    }
+  }
+
+  public markEditorOnly() {
+    if (!this.currentRecord?.$meta) {
+      this.currentRecord!.$meta = {};
+    }
+    this.currentRecord!.$meta.editorOnly = true;
+  }
+
+  private getId(obj: any): RefType {
+    if (!this.seen.has(obj)) {
+      const newId = this.idCounter++;
+      this.seen.set(obj, newId);
+      this.refCount.set(newId, 0);
+    }
+    return this.seen.get(obj)!;
+  }
+
+  // valuesOverriddenByPrefab comes from the outer prefab, i.e. from the component data in an actor prefab
+  private _dump(obj: any, valuesOverriddenByPrefab?: any, customSerialize?: (obj: any, dumper: Dumper) => any): Ref | any {
+    if (typeof obj !== 'object' || obj === null) {
+      return obj;
+    }
+
+    // Already serialized → return a reference
+    if (this.seen.has(obj)) {
+      const refId = this.getId(obj);
+      if (this.refCount.get(refId) === undefined || this.refCount.get(refId) === 0) {
+        throw new Error('Dumper: refCount for object does not exist at this point, this should not happen.');
+      }
+      this.refCount.set(refId, this.refCount.get(refId)! + 1);
+      return { $ref: refId };
+    }
+
+    const defaultValues: any = {};
+    Object.assign(defaultValues, getDefaultObject(obj));
+    Object.assign(defaultValues, valuesOverriddenByPrefab);
+
+    const refId = this.getId(obj);
+    const record: SerializedSubObject = { $id: refId, $value: Array.isArray(obj) ? [] : {} };
+
+    let baseInfo: BaseInfo | null = null;
+    const prefabPath = obj.$prefab?.$path;
+    if (prefabPath) {
+      baseInfo = { $path: prefabPath };
+    }
+    else {
+      const clsName = getClassSerializeName(obj);
+      if (clsName) {
+        baseInfo = { $class: clsName };  // placeholder for ctorArgs
+      } else {
+        // if it's an unregistered class
+        if (typeof obj === 'object' && obj !== null && !Array.isArray(obj)) {
+          const proto = Object.getPrototypeOf(obj);
+          if (proto !== Object.prototype && proto !== String.prototype && proto !== Number.prototype && proto !== Boolean.prototype) {
+            baseInfo = { $class: `${UNREGISTERED_CLASS_PREFIX}${obj.constructor.name}` };
+          }
+        }
+      }
+    }
+
+    if (baseInfo) {
+      record.$base = baseInfo;
+    }
+
+    // actual dumping
+    const prevRecord = this.currentRecord;
+    this.currentRecord = record;
+
+    const prevBaseInstance = this.defaultValues;
+    this.defaultValues = defaultValues;
+
+    // push the record first to handle circular references
+    this.objects.push(record);
+    this.refCount.set(refId, this.refCount.get(refId)! + 1);
+
+    if (customSerialize) {
+      customSerialize(obj, this);
+    } else if (isSerializableObject(obj) && obj.serialize) {
+      obj.serialize(this);
+    } else {
+      const serializeFn = getSerializeFn(obj);
+      if (serializeFn) {
+        serializeFn(obj, this);
+      } else {
+        this.dumpProperties(obj);
+      }
+    }
+    this.currentRecord = prevRecord;
+    this.defaultValues = prevBaseInstance;
+
+    return { $ref: refId };
+  }
+}
+
+export class Loader extends Serializer {
+  private objMap = new Map<RefType, any>();
+  private currentObjectRecord: any = null;
+  private objectsData = new Map<RefType, SerializedSubObject>();
+  private pathStack: string[] = [];
+  private flags: LoaderFlags;
+  private ctorArgsOverrides: Record<string, any>;
+
+  constructor(options?: LoaderOptions) {
+    super();
+    this.flags = options?.flags ?? LoaderFlags.None;
+    this.ctorArgsOverrides = Array.isArray(options?.ctorArgsOverrides) ? options.ctorArgsOverrides : (options?.ctorArgsOverrides ? [options?.ctorArgsOverrides] : []);
+  }
+
+  // public API
+  public load(data: SerializedData): any {
+    return this.loadToInstance(data);
+  }
+
+  public async loadAsync(data: SerializedData): Promise<any> {
+    return this.loadToInstanceAsync(data);
+  }
+
+  public loadToInstance(data: SerializedData, target?: Record<string, any> | any[]): any {
+    const startTime = performance.now();
+    this._prepareLoader(data);
+    const result = this._load(data.$root, '$root', target);
+    const endTime = performance.now();
+    console.log(`Loader.loadToInstance execution time: ${endTime - startTime}ms`);
+    return result;
+  }
+
+  public async loadToInstanceAsync(data: SerializedData, target?: Record<string, any> | any[]): Promise<any> {
+    const startTime = performance.now();
+    this._prepareLoader(data);
+
+    // collect and load all prefab data first
+    const traverseAndLoadPrefabs = async (data: any): Promise<void> => {
+      if (data && typeof data === 'object') {
+        if (data.$base && isPrefabInfo(data.$base)) {
+          const prefabPath = data.$base.$path;
+          const prefabData = await PrefabManager.getOrLoadPrefabData(prefabPath);
+          // traverse the prefab data
+          await traverseAndLoadPrefabs(prefabData);
+        }
+
+        for (const value of Object.values(data)) {
+          await traverseAndLoadPrefabs(value);
+        }
+      }
+    };
+    await traverseAndLoadPrefabs(data);
+
+    const result = this._load(data.$root, '$root', target);
+    const endTime = performance.now();
+    console.log(`Loader.loadToInstanceAsync execution time: ${endTime - startTime}ms`);
+    return result;
+  }
+
+  public hasFlags(flags: LoaderFlags): boolean {
+    return (this.flags & flags) === flags;
+  }
+  // end public API
+
+  private _prepareLoader(data: SerializedData) {
+    if (this.objMap.size > 0 || this.objectsData.size > 0 || this.currentObjectRecord || this.pathStack.length > 0) {
+      throw new Error('Loader instances cannot be reused.');
+    }
+
+    if (data.$objects) {
+      for (const record of data.$objects) {
+        this.objectsData.set(record.$id!, record);
+      }
+    }
+
+    // convert $bc -> {$base: {$class: ...} }
+    const extractClassBaseInfoWithoutCtorArgs = (obj: any) => {
+      if (typeof obj !== 'object' || obj === null) {
+        return;
+      }
+      for (const [k, v] of Object.entries(obj)) {
+        if (v && typeof v === 'object' && '$bc' in v) {
+          const className = v.$bc;
+          (v as any).$base = { $class: className };
+          delete v.$bc;
+        }
+        extractClassBaseInfoWithoutCtorArgs(v);
+      }
+    };
+    extractClassBaseInfoWithoutCtorArgs(data);
+  }
+
+  private findInstance(id: RefType | null): any | null {
+    if (id !== null && this.objMap.has(id)) {
+      return this.objMap.get(id) ?? null;
+    }
+    return null;
+  }
+
+  private containsReference(data: any, id: RefType | null): boolean {
+    if (id === null) return false;
+    if (typeof data !== 'object' || data === null) {
+      return false;
+    }
+    if (_isRef(data)) {
+      return data.$ref === id;
+    }
+    for (const value of Object.values(data)) {
+      if (this.containsReference(value, id)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private findOrCreateInstance(baseInfo: BaseInfo | undefined, propertiesData: any, id: RefType | null): NonNullable<any> {
+    // Already created
+    const existingInstance = this.findInstance(id);
+    if (existingInstance) {
+      return existingInstance;
+    }
+
+    if (baseInfo && isPrefabInfo(baseInfo)) {
+      try {
+        return instantiatePrefab(baseInfo.$path);
+      } catch (error) {
+        if (error instanceof Error) {
+          // Could happen due to prefab renames, we don't want to crash the game/editor
+          console.warn(`Loader: Failed to instantiate prefab at path ${baseInfo.$path}: ${error.message}. Creating plain object instead.`);
+          return {};
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    // If it's a class instance
+    const clsName = baseInfo && isClassInfo(baseInfo) ? baseInfo.$class : undefined;
+    const ctorArgsData = baseInfo && isClassInfo(baseInfo) ? baseInfo.$ctorArgs : undefined;
+    const isIdValid = id !== null;
+    if (clsName) {
+      const cls = getClassForDeserialization(clsName);
+      if (!cls) {
+        // class not found, leave a warning here
+        console.warn(`Loader: Class not found for name ${clsName}, creating plain object instead.`);
+      }
+      else {
+        const makeCtorArgs = (): any[] => {
+          const defaultCtorArgs: any[] = [];
+          const ctorArgs = (this._load(ctorArgsData, '$ctorArgs', defaultCtorArgs) ?? []) as any[] ;
+          if (this.pathStack.length === 1 && this.pathStack[0] === '$root') {
+            // TODO: how do we know the root object's ctor args? what if a user makes an Actor, whose constructor takes 3 args, like `new Actor(a,options,b)`?
+            // In that case a user when instantiating a prefab will never know what type they're actually dealing with
+            // for now I just assume that each element in this.ctorArgsOverrides corresponds to each of the constructor args
+            // one way to fix this is to make Dumper yell if Actor/Component contains more than one args
+            const overrides = this.ctorArgsOverrides;
+            for (let i = 0; i < overrides.length; i++) {
+              const o = overrides[i];
+              if (o === undefined) continue;
+
+              if (o === null || Array.isArray(o) || typeof o !== 'object') {
+                // override is a primitive, just replace the ctor arg directly
+                ctorArgs[i] = o;
+              }
+              else {
+                let target = ctorArgs[i];
+                if (target === null || Array.isArray(target) || typeof target !== 'object') {
+                  target = {};
+                  ctorArgs[i] = target;
+                }
+
+                Object.assign(target, o);
+              }
+            }
+          }
+          return ctorArgs;
+        };
+
+        if (isIdValid) {
+          // if ctorArgs data contains reference to itself,
+          // must create a placeholder instance first to handle circular references (by ctorArgs)
+          // this happens because we allow passing instances to ctor args, check the following example:
+          // class A { constructor(public b: B) {} }
+          // class B { constructor(public a: A) {} }
+          // const a = new A();
+          // const b = new B(a);
+          // a.b = b;
+          // When deserializing B, we need to create a placeholder for it first, so that A can be constructed and populated properly
+          let placeholder: any = null;
+          if (this.containsReference(ctorArgsData, id)) {
+            placeholder = Object.create(cls.prototype);
+            this.objMap.set(id, placeholder);
+          }
+
+          // recursively load ctor args
+          const ctorArgs = makeCtorArgs();
+
+          // Now construct the real instance
+          const instance = new cls(...ctorArgs);
+
+          if (placeholder){
+            // Replace the placeholder with the actual instance, but we have no idea if there is anything referencing the placeholder already
+            // so it must be mutated in place
+            Object.assign(placeholder, instance);
+            return placeholder;
+          } else {
+            this.objMap.set(id, instance);
+            return instance;
+          }
+        }
+        else {
+          // no $id, meaning it's not a referenced object, just create it directly
+          const ctorArgs = makeCtorArgs();
+          const instance = new cls(...ctorArgs);
+          return instance;
+        }
+      }
+    }
+
+    const instance = Array.isArray(propertiesData) ? [] : {};
+    if (isIdValid) {
+      this.objMap.set(id, instance);
+    }
+    return instance;
+  }
+
+  private _populate(value: any, key: string, target: any, baseInfo: BaseInfo | null, metadata?: PropertyMetadata): void {
+    const prevObjectRecord = this.currentObjectRecord;
+    this.currentObjectRecord = value;
+
+    // target ??= Array.isArray(value) ? [] : {};
+
+    if (metadata?.deserialize) {
+      // if metadata has custom deserialize function, use it
+      metadata.deserialize(target, this);
+    } else if (isSerializableObject(target) && target.deserialize) {
+      // If it's a class instance and implements ISerializableObject, call its serialize method
+      target.deserialize(this);
+    } else {
+      const deserializeFn = getDeserializeFn(target);
+      if (deserializeFn) {
+        deserializeFn(target, this);
+      } else {
+        this.loadProperties(target);
+      }
+    }
+
+    if (baseInfo && isPrefabInfo(baseInfo) && baseInfo.$path) {
+      target.$prefab = { $path: baseInfo.$path };
+    }
+
+    this.currentObjectRecord = prevObjectRecord;
+  }
+
+  private _matchesExisting(existing: any, refId: RefType | undefined, className: string | null, dataValue: any): boolean {
+    if (refId !== undefined && this.objMap.has(refId)) {
+      // if it's a referenced object, must match by identity
+      return this.objMap.get(refId) === existing;
+    }
+    if (Array.isArray(existing) && Array.isArray(dataValue)) {
+      return true;
+    }
+    if (className) {
+      const cls = getClassForDeserialization(className);
+      if (cls) {
+        // registered class
+        if (!(existing instanceof cls)) return false;
+        const existingInstanceClsName = getClassSerializeName(existing);
+        if (existingInstanceClsName !== className) return false;
+
+        // There should be an absolute truth here to tell if the serialized data matches the existing instance
+        // For now I can only guess
+        if (existing.name && dataValue?.name && existing.name !== dataValue.name) {
+          return false;
+        }
+
+        // return true here for now
+        return true;
+      } else {
+        if (className.startsWith(UNREGISTERED_CLASS_PREFIX)) {
+          // unregistered class, just check the constructor name
+          const expectedCtorName = className.substring(UNREGISTERED_CLASS_PREFIX.length);
+          return existing.constructor.name === expectedCtorName;
+        }
+      }
+    } else if (typeof existing === 'object' && existing !== null && !Array.isArray(existing)) {
+      // plain object, return true because we have no way to tell its default state, so basically treating the existing instance as "default"
+      return true;
+    }
+
+    return false;
+  }
+
+  // target is the existing object to resolve into if it's able to
+  // it is required so as to avoid re-creating objects that are already present
+  public loadValue(key: string, target?: any, metadata?: PropertyMetadata): any {
+    return this._load(this.currentObjectRecord[key], key, target, metadata);
+  }
+
+  private _findClass(baseInfo: BaseInfo, seen?: Set<string>): string | null {
+    if (isClassInfo(baseInfo)) {
+      return baseInfo.$class;
+    }
+
+    seen ??= new Set<string>();
+
+    const prefabPath = isPrefabInfo(baseInfo) ? baseInfo.$path : null;
+    if (prefabPath) {
+      if (seen.has(prefabPath)) {
+        throw new Error(`Loader: Circular prefab reference detected for prefab ${prefabPath}, aborting class lookup.`);
+      }
+      seen.add(prefabPath);
+      const baseInfo = PrefabManager.getPrefabBaseInfo(prefabPath);
+      if (baseInfo) {
+        return this._findClass(baseInfo, seen);
+      }
+    }
+
+    return null;
+  }
+
+  // key is only for path tracking, but it's required just to be clear
+  private _load(serializedValue: any, key: string, target?: any, metadata?: PropertyMetadata): any {
+    const _internalLoad = (serializedValue: any, key: string, target: any, metadata: PropertyMetadata) => {
+      if (Array.isArray(serializedValue) || Array.isArray(target)) {
+        // if `serializedValue` is array, `target` may or may not be an array. Usually it's not, but if calling `loadInstanceTo(data, [])`, then it can can be an array
+        if (Array.isArray(serializedValue)) {
+          const result = serializedValue.map((v, index) => this._load(serializedValue[index], String(index), Array.isArray(target) ? target[index] : undefined));
+          if (Array.isArray(target)) {
+          // push into the items that's not already present
+            const seen = new Set(target);
+            target.push(...result.filter(item => !seen.has(item)));
+            return target;
+          }
+          return result;
+        }
+        else if (serializedValue && typeof serializedValue === 'object'){
+          // target is an array, but serializedValue is not. It means we have a default value being array,
+          // and `serializedValue` is a delta, that contains { index -> overriddenValue }
+          const result = target;
+          for (const [k, v] of Object.entries(serializedValue)) {
+            result[k] = this._load(serializedValue[k], String(k), result[k]);
+          }
+          return result;
+        }
+      }
+      else if (!serializedValue || typeof serializedValue !== 'object') {
+        return serializedValue;
+      } else {
+        // handle object, two possible cases for `serializedValue`:
+        // a ref obj: { $ref: 1 }
+        // full serialized object: { $value: {...}, $class?: 'ClassName', $ctorArgs?: [...] }, note $class and $ctorArgs are optional
+        // it's always two steps: instantiate the object (findOrCreateInstance), then populate its properties (_populate)
+
+        let referencedObject: SerializedSubObject | null = null;
+        if (_isRef(serializedValue)) {
+          const refId = serializedValue.$ref;
+          const record = this.objectsData.get(refId);
+          if (!record) throw new Error(`Loader: No object record found for ref ${refId}`);
+          referencedObject = record;
+        }
+
+        const existingInstance = this.findInstance(referencedObject?.$id ?? null);
+        if (existingInstance) {
+          return existingInstance;
+        }
+
+        const data = referencedObject ? referencedObject.$value : serializedValue;
+        const meta = referencedObject ? referencedObject.$meta : serializedValue.$meta;
+        if (meta?.editorOnly && this.hasFlags(LoaderFlags.WithoutEditor)) {
+          return null;
+        }
+        const baseInfo: BaseInfo | undefined = referencedObject ? referencedObject.$base : serializedValue.$base;
+
+        // if the instance doesn't exist yet, and it's not required to populate value onto a given target
+        // we can give user a chance to construct and populate an instance using `data`, `cls` and `ctorArgsData`
+        // but for now let's only use it internally by specialization
+        if (!target) {
+          const cls: string | undefined = baseInfo && isClassInfo(baseInfo) ? baseInfo.$class : undefined;
+          const staticDeserializeFn = getStaticDeserializeFn(cls);
+          if (staticDeserializeFn) {
+            let instance;
+            if (typeof data !== 'object' || data === null) {
+              instance = staticDeserializeFn(data);
+            }
+            else {
+              // extract data for user in case it contains complex type
+              const extracted: any = Array.isArray(data) ? [] : {};
+              for (const [k, v] of Object.entries(data)) {
+                if (k.startsWith('$')) continue;
+                extracted[k] = this._load(v, k);
+              }
+              instance = staticDeserializeFn(extracted);
+            }
+
+            if (instance) {
+            // it's important to always add to objMap to prevent circular reference issues
+              if (referencedObject && !this.objMap.has(referencedObject.$id!)) {
+                this.objMap.set(referencedObject.$id!, instance);
+              }
+              return instance;
+            }
+          }
+        }
+
+        // should we directly load into target, or should we create a new instance
+        // this is common case for loading into a component on actor, which is also created in the actor's ctor
+        const cls = baseInfo ? this._findClass(baseInfo) : null;
+        const result = target && this._matchesExisting(target, referencedObject?.$id, cls, serializedValue) ?
+          target :
+          // objMap is set in findOrCreateInstance
+          this.findOrCreateInstance(
+            baseInfo,
+            serializedValue,  // pass the whole object for properties, though we could remove $class and $ctorArgs for clarity
+            referencedObject?.$id ?? null
+          );
+
+        // must do it prior to _populate to avoid circular reference issues
+        if (referencedObject && !this.objMap.has(referencedObject.$id!)) {
+          this.objMap.set(referencedObject.$id!, result);
+        }
+
+        this._populate(data, key, result, baseInfo ?? null, metadata);
+        return result;
+      }
+    };
+
+    this.pathStack.push(key);
+    // // skip the first $root
+    // const fullPath = this.pathStack.slice(1).join('.');
+    // console.log('loading key:', fullPath);
+    const loaded = _internalLoad(serializedValue, key, target, metadata ?? {});
+    this.pathStack.pop();
+    return loaded;
+  }
+
+  public loadProperties(obj: any) {
+    if (!shouldSerializeRespectingMetadata(obj)) {
+      const modifiedKeys = new Set();
+      for (const [key, val] of Object.entries(this.currentObjectRecord)) {
+        if (key.startsWith('$')) continue;  // skip the special fields
+        modifiedKeys.add(key);
+        const loaded = this._load(this.currentObjectRecord[key], key, obj[key]);
+        if (loaded === obj[key]) continue;  // skip assignment if same
+        obj[key] = loaded;
+      }
+      return;
+    }
+
+    const properties = getAllProperties(obj);
+    for (const [key, metadata] of properties) {
+      if (key in this.currentObjectRecord) {
+        if (metadata?.editorOnly && this.hasFlags(LoaderFlags.WithoutEditor)) {
+          // skip editorOnly properties when not loading with editor
+          // but should I mark the property as undefined on the object?
+          continue;
+        }
+        // don't worry about transient properties here, they are already skipped when dumping
+        const val = this.currentObjectRecord[key];
+        const result = this._load(val, key, obj[key], metadata);
+        if (result !== obj[key]) {
+          obj[key] = result;
+        }
+      }
+    }
+  }
+}