feat(loader): support path-based cross-prefab entity/component refs

packages/loader/src/resource-deserialize/resources/parser/HierarchyParser.ts

@@ -97,7 +97,13 @@ export abstract class HierarchyParser<T extends Scene | PrefabResource, V extend
       for (let i = 0, l = entities.length; i < l; i++) {
         entityMap.set(entitiesConfig[i].id, entities[i]);
       }
-
+      // Build rootIds in serialization order (not async completion order)
+      const rootIds = this.context.rootIds;
+      for (let i = 0, l = entitiesConfig.length; i < l; i++) {
+        if (!entitiesConfig[i].parent && !(entitiesConfig[i] as IStrippedEntity).strippedId) {
+          rootIds.push(entitiesConfig[i].id);
+        }
+      }
       return entities;
     });
   }
@@ -238,8 +244,6 @@ export abstract class HierarchyParser<T extends Scene | PrefabResource, V extend
   private _parseEntity(entityConfig: IEntity, engine: Engine): Promise<Entity> {
     const transform = entityConfig.transform;
     const entity = new Entity(engine, entityConfig.name, transform ? Loader.getClass(transform.class) : Transform);
-    if (!entityConfig.parent) this.context.rootIds.push(entityConfig.id);
-
     this._addEntityPlugin(entityConfig.id, entity);
     return Promise.resolve(entity);
   }
@@ -259,8 +263,6 @@ export abstract class HierarchyParser<T extends Scene | PrefabResource, V extend
               ? prefabResource.instantiate()
               : prefabResource.instantiateSceneRoot();
           const instanceContext = new ParserContext<IHierarchyFile, Entity>(engine, ParserType.Prefab, null);
-          if (!entityConfig.parent) this.context.rootIds.push(entityConfig.id);
-
           this._generateInstanceContext(entity, instanceContext, "");
 
           this._prefabContextMap.set(entity, instanceContext);

packages/loader/src/resource-deserialize/resources/parser/ReflectionParser.ts

@@ -121,10 +121,13 @@ export class ReflectionParser {
           return resource;
         });
       } else if (ReflectionParser._isComponentRef(value)) {
-        return Promise.resolve(this._context.components.get(value.componentId) ?? null);
+        const entity = this._resolveEntityByPath(value.entityPath);
+        if (!entity) return Promise.resolve(null);
+        const type = Loader.getClass(value.componentType);
+        if (!type) return Promise.resolve(null);
+        return Promise.resolve(entity.getComponents(type, [])[value.componentIndex] ?? null);
       } else if (ReflectionParser._isEntityRef(value)) {
-        // entity reference
-        return Promise.resolve(this._context.entityMap.get(value.entityId));
+        return Promise.resolve(this._resolveEntityByPath(value.entityPath));
       } else if (ReflectionParser._isSignalRef(value)) {
         return this.parseSignal(value);
       } else if (originValue) {
@@ -183,6 +186,17 @@ export class ReflectionParser {
     }
   }
 
+  private _resolveEntityByPath(entityPath: number[]): Entity | null {
+    const { rootIds, entityMap } = this._context;
+    if (!entityPath.length || entityPath[0] >= rootIds.length) return null;
+    let entity = entityMap.get(rootIds[entityPath[0]]);
+    for (let i = 1; i < entityPath.length; i++) {
+      if (!entity || entityPath[i] >= entity.children.length) return null;
+      entity = entity.children[entityPath[i]];
+    }
+    return entity;
+  }
+
   private static _isClass(value: any): value is IClass {
     return value["class"] !== undefined;
   }
@@ -196,11 +210,11 @@ export class ReflectionParser {
   }
 
   private static _isEntityRef(value: any): value is IEntityRef {
-    return value["entityId"] !== undefined;
+    return Array.isArray(value["entityPath"]) && value["componentType"] === undefined;
   }
 
   private static _isComponentRef(value: any): value is IComponentRef {
-    return value["ownerId"] !== undefined && value["componentId"] !== undefined;
+    return Array.isArray(value["entityPath"]) && value["componentType"] !== undefined;
   }
 
   private static _isSignalRef(value: any): value is ISignalRef {

packages/loader/src/resource-deserialize/resources/schema/BasicSchema.ts

@@ -105,11 +105,12 @@ export type IBasicType =
 
 export type IAssetRef = { key?: string; url: string };
 
-export type IEntityRef = { entityId: string };
+export type IEntityRef = { entityPath: number[] };
 
 export type IComponentRef = {
-  ownerId: string;
-  componentId: string;
+  entityPath: number[];
+  componentType: string;
+  componentIndex: number;
 };
 
 export type ISignalRef = {

tests/src/loader/PrefabResource.test.ts

@@ -1,10 +1,19 @@
 import { expect, beforeAll, afterAll, describe, it } from "vitest";
 import { WebGLEngine } from "@galacean/engine-rhi-webgl";
 import type { IHierarchyFile } from "@galacean/engine-loader";
+import { Loader, MeshRenderer, Script } from "@galacean/engine-core";
 import { PrefabParser } from "../../../packages/loader/src/prefab/PrefabParser";
 
 let engine: WebGLEngine;
 
+class DiceScript extends Script {
+  skinMesh: MeshRenderer = null;
+  numMesh: MeshRenderer = null;
+}
+
+Loader.registerClass("MeshRenderer", MeshRenderer);
+Loader.registerClass("DiceScript", DiceScript);
+
 beforeAll(async () => {
   const canvas = document.createElement("canvas");
   canvas.width = 256;
@@ -52,3 +61,149 @@ describe("PrefabResource refCount", () => {
     expect(prefab.refCount).toBe(0);
   });
 });
+
+describe("Cross-prefab IComponentRef (path-based)", () => {
+  it("should resolve component ref inside nested prefab instance via entityPath", async () => {
+    // 1. nested prefab (dice.prefab): single root entity with MeshRenderer
+    const nestedPrefabData: IHierarchyFile = {
+      entities: [
+        {
+          id: "0",
+          name: "diceRoot",
+          components: [{ id: "mesh-comp", class: "MeshRenderer" }],
+          children: []
+        }
+      ]
+    };
+    const nestedPrefab = await PrefabParser.parse(engine, "dice.prefab", nestedPrefabData);
+    // @ts-ignore — register to resourceManager so getResourceByRef can find it
+    engine.resourceManager._objectPool["dice.prefab"] = nestedPrefab;
+
+    // 2. outer prefab (DiceNode.prefab)
+    //    resolved tree: DiceNode(root=[0]) -> [0]dice(nested)
+    //    skinMesh crosses nested prefab boundary via entityPath
+    const outerPrefabData: IHierarchyFile = {
+      entities: [
+        {
+          id: "root",
+          name: "DiceNode",
+          components: [
+            {
+              id: "script-comp",
+              class: "DiceScript",
+              props: {
+                skinMesh: { entityPath: [0, 0], componentType: "MeshRenderer", componentIndex: 0 }
+              }
+            }
+          ],
+          children: ["dice-inst"]
+        },
+        {
+          id: "dice-inst",
+          name: "dice",
+          parent: "root",
+          components: [],
+          assetUrl: "dice.prefab",
+          modifications: [],
+          removedEntities: [],
+          removedComponents: []
+        }
+      ]
+    };
+
+    const outerPrefab = await PrefabParser.parse(engine, "DiceNode.prefab", outerPrefabData);
+    const root = outerPrefab.instantiate();
+    const script = root.getComponent(DiceScript);
+
+    // skinMesh should point to the MeshRenderer inside nested prefab instance
+    expect(script.skinMesh).not.toBeNull();
+    expect(script.skinMesh).toBeInstanceOf(MeshRenderer);
+    expect(script.skinMesh.entity.name).toBe("dice");
+
+    root.destroy();
+    // @ts-ignore
+    delete engine.resourceManager._objectPool["dice.prefab"];
+  });
+
+  it("should resolve both local and cross-prefab refs, and survive clone independently", async () => {
+    const nestedPrefabData: IHierarchyFile = {
+      entities: [
+        {
+          id: "0",
+          name: "diceRoot",
+          components: [{ id: "mesh-comp", class: "MeshRenderer" }],
+          children: []
+        }
+      ]
+    };
+    const nestedPrefab = await PrefabParser.parse(engine, "dice.prefab", nestedPrefabData);
+    // @ts-ignore
+    engine.resourceManager._objectPool["dice.prefab"] = nestedPrefab;
+
+    // resolved tree: DiceNode(root=[0]) -> [0]numCube, [1]dice(nested)
+    const outerPrefabData: IHierarchyFile = {
+      entities: [
+        {
+          id: "root",
+          name: "DiceNode",
+          components: [
+            {
+              id: "script-comp",
+              class: "DiceScript",
+              props: {
+                numMesh: { entityPath: [0, 0], componentType: "MeshRenderer", componentIndex: 0 },
+                skinMesh: { entityPath: [0, 1], componentType: "MeshRenderer", componentIndex: 0 }
+              }
+            }
+          ],
+          children: ["num-cube", "dice-inst"]
+        },
+        {
+          id: "num-cube",
+          name: "numCube",
+          parent: "root",
+          components: [{ id: "num-mesh-comp", class: "MeshRenderer" }]
+        },
+        {
+          id: "dice-inst",
+          name: "dice",
+          parent: "root",
+          components: [],
+          assetUrl: "dice.prefab",
+          modifications: [],
+          removedEntities: [],
+          removedComponents: []
+        }
+      ]
+    };
+
+    const outerPrefab = await PrefabParser.parse(engine, "DiceNode.prefab", outerPrefabData);
+
+    const instance1 = outerPrefab.instantiate();
+    const instance2 = outerPrefab.instantiate();
+
+    const script1 = instance1.getComponent(DiceScript);
+    const script2 = instance2.getComponent(DiceScript);
+
+    // instance1: numMesh -> numCube's MeshRenderer, skinMesh -> dice's MeshRenderer
+    const numMesh1 = instance1.children[0].getComponent(MeshRenderer);
+    const skinMesh1 = instance1.children[1].getComponent(MeshRenderer);
+    expect(script1.numMesh).toBe(numMesh1);
+    expect(script1.skinMesh).toBe(skinMesh1);
+
+    // instance2: independent refs
+    const numMesh2 = instance2.children[0].getComponent(MeshRenderer);
+    const skinMesh2 = instance2.children[1].getComponent(MeshRenderer);
+    expect(script2.numMesh).toBe(numMesh2);
+    expect(script2.skinMesh).toBe(skinMesh2);
+
+    // refs across instances are independent
+    expect(script1.numMesh).not.toBe(script2.numMesh);
+    expect(script1.skinMesh).not.toBe(script2.skinMesh);
+
+    instance1.destroy();
+    instance2.destroy();
+    // @ts-ignore
+    delete engine.resourceManager._objectPool["dice.prefab"];
+  });
+});