From 56bfd1b3c421310b7ca48bc69bc34b2b7ea9be21 Mon Sep 17 00:00:00 2001
From: luzhuang <wz84888@antgroup.com>
Date: Tue, 12 May 2026 19:55:36 +0800
Subject: [PATCH] refactor(loader): rename v2 scene.entities to
 scene.rootEntities (#2997)

* refactor(loader): rename v2 scene.entities to scene.roots
---
 .../resources/parser/HierarchyParser.ts       |  2 +-
 .../resources/scene/SceneParser.ts            |  2 +-
 packages/loader/src/schema/SceneSchema.ts     |  2 +-
 tests/src/loader/SceneFormatV2.test.ts        | 24 +++++++++----------
 4 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/packages/loader/src/resource-deserialize/resources/parser/HierarchyParser.ts b/packages/loader/src/resource-deserialize/resources/parser/HierarchyParser.ts
index f95bb44e7..2216ea3b4 100644
--- a/packages/loader/src/resource-deserialize/resources/parser/HierarchyParser.ts
+++ b/packages/loader/src/resource-deserialize/resources/parser/HierarchyParser.ts
@@ -54,7 +54,7 @@ export abstract class HierarchyParser<T extends Scene | PrefabResource, V extend
       .catch(this._reject);
   }
 
-  /** Root entity indices for this hierarchy (scene.entities or [prefab.root]). */
+  /** Root entity indices for this hierarchy (scene.rootEntities or [prefab.root]). */
   protected abstract _getRootIndices(): number[];
   protected abstract _handleRootEntity(index: number): void;
   protected abstract _clearAndResolve(): Scene | PrefabResource;
diff --git a/packages/loader/src/resource-deserialize/resources/scene/SceneParser.ts b/packages/loader/src/resource-deserialize/resources/scene/SceneParser.ts
index fcc90a7a7..c585251d6 100644
--- a/packages/loader/src/resource-deserialize/resources/scene/SceneParser.ts
+++ b/packages/loader/src/resource-deserialize/resources/scene/SceneParser.ts
@@ -27,7 +27,7 @@ export class SceneParser extends HierarchyParser<Scene, ParserContext> {
   }
 
   protected override _getRootIndices(): number[] {
-    return (this.data as SceneFile).scene.entities;
+    return (this.data as SceneFile).scene.rootEntities;
   }
 
   protected override _handleRootEntity(index: number): void {
diff --git a/packages/loader/src/schema/SceneSchema.ts b/packages/loader/src/schema/SceneSchema.ts
index d72dbd659..659f4b618 100644
--- a/packages/loader/src/schema/SceneSchema.ts
+++ b/packages/loader/src/schema/SceneSchema.ts
@@ -17,7 +17,7 @@ export enum SpecularMode {
 export interface SceneFile extends HierarchyFile {
   scene: {
     name?: string;
-    entities: number[];
+    rootEntities: number[];
     background: {
       mode: BackgroundMode;
       color: Vec4Tuple;
diff --git a/tests/src/loader/SceneFormatV2.test.ts b/tests/src/loader/SceneFormatV2.test.ts
index 2f463fed1..95cdc3a69 100644
--- a/tests/src/loader/SceneFormatV2.test.ts
+++ b/tests/src/loader/SceneFormatV2.test.ts
@@ -372,7 +372,7 @@ describe("SceneParser v2 entity tree", () => {
       entities,
       components,
       scene: {
-        entities: rootEntities,
+        rootEntities,
         background: {
           mode: 0,
           color: [0.25, 0.25, 0.25, 1]
@@ -392,7 +392,7 @@ describe("SceneParser v2 entity tree", () => {
       entities: [{ name: "Entity" }],
       components: [],
       scene: {
-        entities: [0],
+        rootEntities: [0],
         background: {
           mode: BackgroundMode.SolidColor,
           color: [0.25, 0.25, 0.25, 1]
@@ -630,7 +630,7 @@ describe("SceneParser v2 entity tree", () => {
       entities: [{ name: "Root", components: [0] }],
       components: [{ type: "CallOrderComponent" }],
       scene: {
-        entities: [0],
+        rootEntities: [0],
         background: { mode: BackgroundMode.SolidColor, color: [0, 0, 0, 1] },
         ambient: {
           diffuseMode: DiffuseMode.SolidColor,
@@ -907,7 +907,7 @@ describe("applySceneData scene property parsing", () => {
       await applySceneData(
         scene,
         {
-          entities: [0],
+          rootEntities: [0],
           background: { mode: BackgroundMode.SolidColor, color: [0, 0, 0, 1] },
           ambient: {
             diffuseMode: DiffuseMode.SphericalHarmonics,
@@ -952,7 +952,7 @@ describe("applySceneData scene property parsing", () => {
       await applySceneData(
         scene,
         {
-          entities: [0],
+          rootEntities: [0],
           background: {
             mode: BackgroundMode.Sky,
             color: [0, 0, 0, 1],
@@ -988,7 +988,7 @@ describe("applySceneData scene property parsing", () => {
       await applySceneData(
         scene,
         {
-          entities: [0],
+          rootEntities: [0],
           background: {
             mode: BackgroundMode.Texture,
             color: [0, 0, 0, 1],
@@ -1014,7 +1014,7 @@ describe("applySceneData scene property parsing", () => {
       applySceneData(
         scene,
         {
-          entities: [0],
+          rootEntities: [0],
           background: {
             mode: BackgroundMode.Texture,
             color: [0, 0, 0, 1],
@@ -1032,7 +1032,7 @@ describe("applySceneData scene property parsing", () => {
     await applySceneData(
       scene,
       {
-        entities: [0],
+        rootEntities: [0],
         background: { mode: BackgroundMode.SolidColor, color: [0, 0, 0, 1] },
         shadow: {
           castShadows: false,
@@ -1066,7 +1066,7 @@ describe("applySceneData scene property parsing", () => {
     await applySceneData(
       scene,
       {
-        entities: [0],
+        rootEntities: [0],
         background: { mode: BackgroundMode.SolidColor, color: [0, 0, 0, 1] },
         fog: {
           fogMode: FogMode.ExponentialSquared,
@@ -1095,7 +1095,7 @@ describe("applySceneData scene property parsing", () => {
     await applySceneData(
       scene,
       {
-        entities: [0],
+        rootEntities: [0],
         background: { mode: BackgroundMode.SolidColor, color: [0, 0, 0, 1] },
         ambientOcclusion: {
           enabledAmbientOcclusion: true,
@@ -1128,7 +1128,7 @@ describe("applySceneData scene property parsing", () => {
     await applySceneData(
       scene,
       {
-        entities: [0],
+        rootEntities: [0],
         background: {
           mode: BackgroundMode.SolidColor,
           color: [0.5, 0.6, 0.7, 1]
@@ -1150,7 +1150,7 @@ describe("applySceneData scene property parsing", () => {
     await applySceneData(
       scene,
       {
-        entities: [0],
+        rootEntities: [0],
         background: { mode: BackgroundMode.SolidColor, color: [0, 0, 0, 1] }
       },
       engine.resourceManager,