fix(world): preserve structured spawn hierarchy

Author: NeoXider

Assets/CoreAI/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+- **Structured world spawning.** `world_command` `spawn`, `spawn_batch`, and `change` expose
+  `worldPositionStays` (default `false`). Parented transforms are local by default; callers can pass `true`
+  to preserve world space. The tool contract now recommends named `empty` roots and meaningful child
+  hierarchies for compound objects. The visual benchmark executor now preserves those parent relationships
+  in generated scene prefabs instead of flattening every spawned object under the benchmark root.
+
 ## 5.5.0 - R6 resilience, benchmark v2 tooling, CI/package gates (2026-07-11)
 
 - **Benchmark: model-authored castles export as prefabs.** Every G6 free-build run now saves the built scene

Assets/CoreAI/Docs/LLM_TOOLS.md

@@ -30,14 +30,14 @@ agent.WithTool(new ComponentLlmTool(componentExecutor, settings, logger));
 | `inventory` | `InventoryLlmTool` | `IInventoryProvider` | Game inventory read/grant. |
 | compatibility | `CompatibilityLlmTool` | `CompatibilityChecker` | Crafting compatibility. |
 | game config | `GameConfigLlmTool` | `GameConfigPolicy.CreateLlmTool(store, roleId)` | Per-role config slots. |
-| `world_command` | `WorldLlmTool` | `ICoreAiWorldCommandExecutor` | Native world edits. `spawn` accepts registered prefab keys or built-in primitives (`cube`, `sphere`, `cylinder`, `capsule`, `plane`, `empty`) when `AllowWorldPrimitives` is on; spawn can ALSO set rotation (`fx/fy/fz` degrees) and uniform `scale` in one call. Models can also move, rotate, scale, and parent objects. Models usually edit the world via Lua `coreai_world_*` instead, so this is optional. |
+| `world_command` | `WorldLlmTool` | `ICoreAiWorldCommandExecutor` | Native world edits. `spawn` accepts registered prefab keys or built-in primitives (`cube`, `sphere`, `cylinder`, `capsule`, `plane`, `empty`) when `AllowWorldPrimitives` is on; spawn can set transform and parent in one call. Parented coordinates are local by default; `worldPositionStays=true` preserves world space. Models usually edit the world via Lua `coreai_world_*` instead, so this is optional. |
 | `component_command` | `ComponentLlmTool` | `ICoreAiComponentCommandExecutor` | Add/remove/configure supported Unity components through a curated catalog, no reflection. |
 | scene query | `SceneLlmTool` | scene | `unity_*`-style scene inspection as a native tool (alternative to Full-tier Lua). |
 | `capture_camera` | `CameraLlmTool` | a `Camera` + a **vision-capable model** | Renders a camera to JPEG. Attach the captured `DataContent` (`CameraLlmTool.CaptureCameraImageContent`) to a user message; `MeaiOpenAiChatClient` serializes it to OpenAI `image_url`. See **Vision / multimodal** below for the host send path and autonomous-tool wiring. |
 
 ### World and component commands
 
-`world_command` now works without a prefab registry for simple spawn requests when `ICoreAISettings.AllowWorldPrimitives` is enabled (default). `prefabKey` may be a registered prefab key or one of the built-in primitive keys: `cube`, `sphere`, `cylinder`, `capsule`, `plane`, `empty`. During spawn you can ALSO set rotation (fx/fy/fz degrees) and uniform scale in one call, or use separate rotate/set_scale actions later. The action list includes moving, rotating, scaling, and parenting objects.
+`world_command` works without a prefab registry for simple spawn requests when `ICoreAISettings.AllowWorldPrimitives` is enabled (default). `prefabKey` may be a registered prefab key or one of the built-in primitive keys: `cube`, `sphere`, `cylinder`, `capsule`, `plane`, `empty`. During spawn, position, rotation, scale and parent can be supplied in one call. With a parent, coordinates are local by default (`worldPositionStays=false`); set it to `true` to preserve a world transform. For compound objects, create an `empty` root first and parent the named parts beneath it instead of leaving a flat scene hierarchy.
 
 `component_command` is separate from `world_command` and uses a curated catalog instead of reflection. Actions are `add`, `remove`, `set`, and `list_components`. Supported `componentType` values are `rigidbody`, `rigidbody2d`, `boxcollider`, `spherecollider`, `capsulecollider`, `meshcollider`, `light`, `audiosource`, `camera`, `linerenderer`, `trailrenderer`, `textmesh`, `meshrenderer`, and `particlesystem`. For `set`, pass `propertyName` plus the matching value field: `floatValue`, `boolValue` (`0` / `1`), `stringValue`, or `x` / `y` / `z`.
 

Assets/CoreAI/Docs/TOOL_CALLING_BEST_PRACTICES.md

@@ -241,6 +241,10 @@ Guidelines that follow from this:
   `list_prefabs` lets the model learn valid `prefabKey` values before spawning,
   the same way `list_animations` and `list_objects` let it learn valid
   `animationName`/`targetName` values.
+- **Spawn meaningful hierarchies for compound objects.** Create a named `empty` root before its parts,
+  then set the parent on posts, roofs, props and decorations. Parented coordinates are local by default;
+  use `worldPositionStays=true` only when an existing world transform must be preserved. This costs no
+  extra parent call when the parent is supplied during `spawn` or per `spawn_batch` item.
 
 ## Verification Checklist
 

Assets/CoreAIBenchmark/Tests/PlayMode/Benchmarks/GameCreationBenchmarkHarness.cs

@@ -399,6 +399,7 @@ public sealed class RecordedWorldCommand
             public float FloatValue;
             public float Fx, Fy, Fz;
             public float ScaleX, ScaleY, ScaleZ;
+            public bool WorldPositionStays;
             public bool HasPosition, HasRotation, HasScale;
             public bool HasX, HasY, HasZ;
             public bool HasFx, HasFy, HasFz;
@@ -446,6 +447,7 @@ public bool TryExecute(ApplyAiGameCommand cmd)
                         ScaleX = env.scaleX,
                         ScaleY = env.scaleY,
                         ScaleZ = env.scaleZ,
+                        WorldPositionStays = env.worldPositionStays,
                         HasPosition = env.hasPosition,
                         HasRotation = env.hasRotation,
                         HasScale = env.hasScale,
@@ -627,8 +629,9 @@ protected override void OnCommand(RecordedWorldCommand cmd)
                             bool expected = ExpectedNames.Count == 0 || ExpectedNames.Contains(key);
                             UnityEngine.GameObject go = BuildVisual(
                                 key, cmd.PrefabKeyOrName, new UnityEngine.Vector3(cmd.X, cmd.Y, cmd.Z),
-                                expected, false);
-                            ApplyInlineTransform(go, cmd);
+                                expected, false, cmd.StringValue, cmd.WorldPositionStays);
+                            ApplyInlineTransform(go, cmd, !string.IsNullOrWhiteSpace(cmd.StringValue)
+                                && !cmd.WorldPositionStays);
                             _objects[key] = go;
                         }
                     }
@@ -662,15 +665,18 @@ protected override void OnCommand(RecordedWorldCommand cmd)
                     else if (action == "change"
                              && _objects.TryGetValue(name, out UnityEngine.GameObject ch) && ch != null)
                     {
-                        // 'change' is the current unified update action (position/rotation/scale/parent);
-                        // without this the scene screenshot silently showed the object's original spawn
-                        // transform even when the model correctly repositioned/rescaled/rotated it afterward.
-                        if (cmd.X != 0f || cmd.Y != 0f || cmd.Z != 0f)
+                        bool hasParent = TryResolveParent(cmd.StringValue, out UnityEngine.Transform parent);
+                        bool localTransform = hasParent && !cmd.WorldPositionStays;
+                        if (localTransform)
                         {
-                            ch.transform.position = new UnityEngine.Vector3(cmd.X, cmd.Y, cmd.Z);
+                            ch.transform.SetParent(parent, false);
                         }
 
-                        ApplyInlineTransform(ch, cmd);
+                        ApplyInlineTransform(ch, cmd, localTransform);
+                        if (hasParent && cmd.WorldPositionStays)
+                        {
+                            ch.transform.SetParent(parent, true);
+                        }
                     }
                     else if (action == "set_color"
                              && _objects.TryGetValue(name, out UnityEngine.GameObject col) && col != null
@@ -697,16 +703,38 @@ protected override void OnCommand(RecordedWorldCommand cmd)
                 }
             }
 
-            private static void ApplyInlineTransform(UnityEngine.GameObject go, RecordedWorldCommand cmd)
+            private static void ApplyInlineTransform(
+                UnityEngine.GameObject go, RecordedWorldCommand cmd, bool localTransform)
             {
                 if (go == null || cmd == null)
                 {
                     return;
                 }
 
-                if (cmd.Fx != 0f || cmd.Fy != 0f || cmd.Fz != 0f)
+                if (cmd.HasPosition || cmd.X != 0f || cmd.Y != 0f || cmd.Z != 0f)
                 {
-                    go.transform.rotation = UnityEngine.Quaternion.Euler(cmd.Fx, cmd.Fy, cmd.Fz);
+                    UnityEngine.Vector3 position = new(cmd.X, cmd.Y, cmd.Z);
+                    if (localTransform)
+                    {
+                        go.transform.localPosition = position;
+                    }
+                    else
+                    {
+                        go.transform.position = position;
+                    }
+                }
+
+                if (cmd.HasRotation || cmd.Fx != 0f || cmd.Fy != 0f || cmd.Fz != 0f)
+                {
+                    UnityEngine.Quaternion rotation = UnityEngine.Quaternion.Euler(cmd.Fx, cmd.Fy, cmd.Fz);
+                    if (localTransform)
+                    {
+                        go.transform.localRotation = rotation;
+                    }
+                    else
+                    {
+                        go.transform.rotation = rotation;
+                    }
                 }
 
                 if (cmd.FloatValue > 0f || cmd.ScaleX > 0f || cmd.ScaleY > 0f || cmd.ScaleZ > 0f)
@@ -781,19 +809,35 @@ private static float Safe(float v)
             }
 
             private UnityEngine.GameObject BuildVisual(
-                string key, string prefabKey, UnityEngine.Vector3 pos, bool expected, bool ghost)
+                string key, string prefabKey, UnityEngine.Vector3 pos, bool expected, bool ghost,
+                string parentName = "", bool worldPositionStays = false)
             {
                 (UnityEngine.PrimitiveType prim, UnityEngine.Vector3 scale) = ShapeFor(prefabKey);
-                UnityEngine.GameObject go = UnityEngine.GameObject.CreatePrimitive(prim);
+                bool isEmpty = string.Equals(prefabKey?.Trim(), "empty", StringComparison.OrdinalIgnoreCase);
+                if (isEmpty)
+                {
+                    scale = UnityEngine.Vector3.one;
+                }
+                UnityEngine.GameObject go = isEmpty
+                    ? new UnityEngine.GameObject()
+                    : UnityEngine.GameObject.CreatePrimitive(prim);
                 go.name = ghost ? $"ghost:{key}" : key;
                 UnityEngine.Collider col = go.GetComponent<UnityEngine.Collider>();
                 if (col != null)
                 {
                     UnityEngine.Object.DestroyImmediate(col);
                 }
 
-                go.transform.SetParent(Root, false);
-                go.transform.position = pos;
+                bool hasParent = TryResolveParent(parentName, out UnityEngine.Transform parent);
+                go.transform.SetParent(hasParent ? parent : Root, hasParent && worldPositionStays);
+                if (hasParent && !worldPositionStays)
+                {
+                    go.transform.localPosition = pos;
+                }
+                else
+                {
+                    go.transform.position = pos;
+                }
                 go.transform.localScale = scale;
 
                 UnityEngine.Color objColor =
@@ -837,6 +881,20 @@ private UnityEngine.GameObject BuildVisual(
                 return go;
             }
 
+            private bool TryResolveParent(string parentName, out UnityEngine.Transform parent)
+            {
+                parent = null;
+                if (string.IsNullOrWhiteSpace(parentName)
+                    || !_objects.TryGetValue(parentName.Trim(), out UnityEngine.GameObject parentObject)
+                    || parentObject == null)
+                {
+                    return false;
+                }
+
+                parent = parentObject.transform;
+                return true;
+            }
+
             /// <summary>Adds a faint placeholder for every expected object the model never spawned, so the
             /// picture shows what is MISSING. Cosmetic, runs after grading.</summary>
             public void AddMissingGhosts()

Assets/CoreAIBenchmark/Tests/PlayMode/Benchmarks/VisualBenchmarkWorldExecutorPlayModeTests.cs

@@ -0,0 +1,81 @@
+#if !COREAI_NO_LUA
+#if !COREAI_NO_LLM && !UNITY_WEBGL
+using CoreAI.Ai;
+using CoreAI.Infrastructure.World;
+using CoreAI.Messaging;
+using Newtonsoft.Json;
+using NUnit.Framework;
+using UnityEngine;
+using static CoreAI.Tests.PlayMode.Benchmarks.GameCreationBenchmarkHarness;
+
+namespace CoreAI.Tests.PlayMode.Benchmarks
+{
+    public sealed class VisualBenchmarkWorldExecutorPlayModeTests
+    {
+        [Test]
+        public void SpawnAndChange_HonorParentCoordinateSpace()
+        {
+            VisualBenchmarkWorldExecutor executor = new() { HideLabels = true };
+            try
+            {
+                Execute(executor, Spawn("group", "empty", 10f, 0f, 0f));
+                Execute(executor, Spawn("local", "cube", 1f, 2f, 3f, "group"));
+                Execute(executor, Spawn("world", "cube", 2f, 3f, 4f, "group", true));
+
+                Transform group = executor.Root.Find("group");
+                Transform local = group.Find("local");
+                Transform world = group.Find("world");
+                Assert.That(local.localPosition, Is.EqualTo(new Vector3(1f, 2f, 3f)));
+                Assert.That(world.position, Is.EqualTo(new Vector3(2f, 3f, 4f)));
+
+                CoreAiWorldCommandEnvelope change = new()
+                {
+                    action = "change",
+                    targetName = "world",
+                    stringValue = "group",
+                    x = 4f,
+                    y = 5f,
+                    z = 6f,
+                    hasPosition = true
+                };
+                Execute(executor, change);
+
+                Assert.That(world.localPosition, Is.EqualTo(new Vector3(4f, 5f, 6f)));
+            }
+            finally
+            {
+                executor.Cleanup();
+            }
+        }
+
+        private static CoreAiWorldCommandEnvelope Spawn(
+            string name, string prefab, float x, float y, float z,
+            string parent = "", bool worldPositionStays = false)
+        {
+            return new CoreAiWorldCommandEnvelope
+            {
+                action = "spawn",
+                targetName = name,
+                prefabKeyOrName = prefab,
+                stringValue = parent,
+                worldPositionStays = worldPositionStays,
+                x = x,
+                y = y,
+                z = z,
+                hasPosition = true
+            };
+        }
+
+        private static void Execute(
+            VisualBenchmarkWorldExecutor executor, CoreAiWorldCommandEnvelope envelope)
+        {
+            Assert.IsTrue(executor.TryExecute(new ApplyAiGameCommand
+            {
+                CommandTypeId = AiGameCommandTypeIds.WorldCommand,
+                JsonPayload = JsonConvert.SerializeObject(envelope)
+            }));
+        }
+    }
+}
+#endif
+#endif

Assets/CoreAIBenchmark/Tests/PlayMode/Benchmarks/VisualBenchmarkWorldExecutorPlayModeTests.cs.meta

@@ -4,6 +4,11 @@ Unity host: **CoreAI.Source** build, EditMode / PlayMode tests, Editor menus, do
 
 ## [Unreleased]
 
+- **Structured world spawning.** Added `worldPositionStays` to `world_command` `spawn`, `spawn_batch`, and
+  `change`. The default is `false`, so parented position/rotation values are local; `true` preserves the
+  world transform. Batch items can override the call-level default. Tool guidance now recommends named
+  `empty` roots for wells, stalls, buildings, and other compound objects.
+
 ## 5.5.0 - R6 resilience, benchmark v2 tooling, CI/package gates (2026-07-11)
 
 - **R6 resilience wiring.** `LlmPipelineInstaller` now composes `Timeout( Logging( RetryingStreaming( routed )))`,

Assets/CoreAiUnity/CHANGELOG.md

@@ -165,7 +165,14 @@ unsupported failure when `SecureLuaEnvironment.IsSupported` is `false`.
 }
 ```
 
-`prefabKey` and `targetName` are required. Position, rotation (`fx/fy/fz`), uniform `scale`, per-axis `scaleX/scaleY/scaleZ`, and parent (`stringValue`) are optional. `scale` is a uniform fallback; use per-axis scale for meter-accurate dimensions.
+`prefabKey` and `targetName` are required. Position, rotation (`fx/fy/fz`), uniform `scale`, per-axis
+`scaleX/scaleY/scaleZ`, parent (`stringValue`), and `worldPositionStays` are optional. When a parent is set,
+coordinates are local by default (`worldPositionStays: false`); `true` preserves world space. Without a
+parent, local and world coordinates are identical. `scale` is a uniform fallback; use per-axis scale for
+meter-accurate dimensions.
+
+For compound objects, create a named `empty` root first and parent related pieces beneath it instead of
+leaving every piece at scene root.
 
 `prefabKey` may be a registered prefab key or a built-in primitive key (`cube`, `sphere`, `cylinder`, `capsule`, `plane`, `empty`) when `AllowWorldPrimitives` is enabled. Registered prefabs take precedence.
 

Assets/CoreAiUnity/Docs/JSON_COMMAND_FORMAT.md

@@ -229,15 +229,16 @@ Since **v1.5.0**, `ToolExecutionPolicy`, `SmartToolCallingChatClient`, `LoggingL
 | `scale` | float | Optional uniform scale fallback. |
 | `scaleX`, `scaleY`, `scaleZ` | float | Optional per-axis scale for meter-accurate dimensions. |
 | `stringValue` | string | Scene name, search query, parent name, HTML colour, or clip key depending on action. |
+| `worldPositionStays` | bool | Parenting policy for `spawn`/`change`. Default `false`: coordinates are local to the named parent. `true`: preserve world transform. |
 | `animationName` | string | Animation name. |
 | `textToDisplay` | string | Text to display. |
 | `volume` | float | Audio volume. |
 
 **Examples:**
 
 ```json
-// Spawn with optional position, rotation, non-uniform scale, and parent
-{"name": "world_command", "arguments": {"action": "spawn", "prefabKey": "cube", "targetName": "wall_1", "x": 0, "y": 1, "z": 0, "fy": 90, "scaleX": 8, "scaleY": 2, "scaleZ": 0.5, "stringValue": "CastleRoot"}}
+// Spawn with optional local position, rotation, non-uniform scale, and parent
+{"name": "world_command", "arguments": {"action": "spawn", "prefabKey": "cube", "targetName": "wall_1", "x": 0, "y": 1, "z": 0, "fy": 90, "scaleX": 8, "scaleY": 2, "scaleZ": 0.5, "stringValue": "CastleRoot", "worldPositionStays": false}}
 
 // Change only supplied fields
 {"name": "world_command", "arguments": {"action": "change", "targetName": "wall_1", "x": 2, "fy": 180, "scaleY": 3, "stringValue": "none"}}
@@ -256,6 +257,11 @@ Since **v1.5.0**, `ToolExecutionPolicy`, `SmartToolCallingChatClient`, `LoggingL
 ```
 
 **When to use:** Creator / Designer AI that dynamically drives the world. For scene inspection and instance-level scene operations, use `scene_tool`; it is separate from `world_command`.
+
+For compound spawned objects, create a named `empty` root first and parent related pieces beneath it. Use
+local coordinates (the default) for parts such as posts, roofs and props; use `worldPositionStays: true`
+only when attaching an already world-positioned object. This keeps the hierarchy meaningful and lets the
+whole object move as one unit.
 ### 5. Component command tool
 
 **Purpose:** Add, remove, configure, and list Unity components on existing GameObjects through a curated catalog. This tool does not use reflection.