Hz Unity Placement

Unity Object Placement with Bounding Boxes

This skill ensures that when placing, moving, or positioning Unity GameObjects relative to other objects, proper bounding box calculations are used to prevent overlaps and ensure accurate placement.

When to use this skill

Use this skill automatically whenever:

• Placing an object relative to another (on top of, beside, above, below, in front of, behind)
• Moving objects to specific positions near other objects
• Instantiating prefabs in relation to existing scene objects
• Positioning imported models relative to scene objects
• Any spatial relationship between GameObjects is specified

Automatic Triggers (invoke WITHOUT user asking)

IMPORTANT: Proactively invoke this skill immediately when you detect ANY of these patterns:

Placement Language Triggers

• User says "place X on Y" or "put X on Y"
• User says "place X next to Y" or "put X beside Y"
• User says "place X to the left/right of Y"
• User says "place X in front of/behind Y"
• User says "place X above/below Y"
• User says "position X near/around Y"
• User says "arrange X on/around Y"
• User requests "X meters/units to the left/right/front/back of Y"

Multi-Object Scenarios

• Before ANY GameObject position modification involving multiple objects and spatial relationships
• When importing models that will be positioned relative to existing objects
• When arranging/organizing multiple objects in a scene
• When setting up object hierarchies with spatial relationships

Distance-Based Placement

• User specifies distances: "2 meters to the left", "0.5 units above", etc.
• Combine specified distance with bounding box calculations
• Example: "1 meter to the right" = refMax.x + 1.0 + targetExtents.x

Example Scenarios

Auto-Invoke Skill (Do These Immediately)

Example 1: "Place all objects on the tables"

• Action: Invoke unity-placement skill immediately
• Why: Multiple objects being placed relative to tables

Example 2: "Put the mug on the table"

• Action: Invoke unity-placement skill
• Why: Single object placement with "on" relationship

Example 3: "Place the lamp next to the clock"

• Action: Invoke unity-placement skill
• Why: "next to" indicates horizontal spatial relationship
• Process: Get both bounds, place lamp beside clock using refMax.x + targetExtents.x

Example 4: "Position the book 0.5 meters to the left of the pen"

• Action: Invoke unity-placement skill
• Why: Distance-based placement with spatial relationship
• Process: Get bounds, calculate: penMin.x - 0.5 - bookExtents.x

Don't Invoke Skill (Direct Operations)

Example 1: "Move object to [5, 10, 3]"

• Why: Direct coordinates provided, no relative positioning

Example 2: "Set the cube's position to (0, 0, 0)"

• Why: Absolute position, no reference object

Core principle

ALWAYS get bounding box information before calculating positions.

Never assume object sizes - always retrieve actual bounds from Renderer or Collider components on the live Editor.

Driving the Editor

Read and write the scene through unity-cli rather than editing .unity YAML — raw-file edits are invisible to the running Editor and easily hit the wrong scene.

unity status --format json          # look for state "ready"

See the unity-cli skill for connecting, --project-path, and Safe Mode recovery. On a Unity MCP server instead, the same steps apply — use whatever scene-inspection and transform tools it exposes.

Instructions

Step 1: Identify the objects involved

When the user requests object placement:

1. Identify the target object (the one being placed/moved)
2. Identify the reference object (the one it's being placed relative to)
3. Note the desired spatial relationship (on, beside, above, etc.)

Step 2: Get bounding box information

For BOTH objects, locate them and read their bounds:

unity command find_gameobjects --name Cube --format json

bounds is a computed property, not a serialized field, so get_component_properties does not return it — a MeshRenderer read gives you m_Materials, m_CastShadows and friends, and no bounds at all. Reading bounds always means a script:

// AgentScripts/GetBounds.cs
using System.Text;
using UnityEngine;

public static class GetBounds
{
    public static string Run(string[] names)
    {
        var sb = new StringBuilder();
        foreach (var name in names)
        {
            var go = GameObject.Find(name);
            if (go == null) { sb.AppendLine($"{name}: NOT FOUND"); continue; }

            if (!TryGetBounds(go, out var b, out var src))
            {
                sb.AppendLine($"{name}: NO Renderer or Collider - bounds unknown");
                continue;
            }

            sb.AppendLine($"{name} [{src}] center={b.center} size={b.size} extents={b.extents} min={b.min} max={b.max}");
        }
        return sb.ToString();
    }

    // Root renderer/collider first; otherwise the union of the children's, which is what an
    // imported model needs since its renderers sit on child GameObjects.
    private static bool TryGetBounds(GameObject go, out Bounds bounds, out string source)
    {
        bounds = default;
        source = null;

        var r = go.GetComponent<Renderer>();
        if (r != null) { bounds = r.bounds; source = "Renderer"; return true; }

        var col = go.GetComponent<Collider>();
        if (col != null) { bounds = col.bounds; source = "Collider"; return true; }

        foreach (var cr in go.GetComponentsInChildren<Renderer>())
        {
            if (source == null) { bounds = cr.bounds; source = "child Renderers"; }
            else bounds.Encapsulate(cr.bounds);
        }
        if (source != null) return true;

        foreach (var cc in go.GetComponentsInChildren<Collider>())
        {
            if (source == null) { bounds = cc.bounds; source = "child Colliders"; }
            else bounds.Encapsulate(cc.bounds);
        }
        return source != null;
    }
}

unity command run_script --file AgentScripts/GetBounds.cs --entry GetBounds.Run \
  --args '[["Cube","Table"]]' --format json

--args spreads the JSON array as positional parameters, so a single string[] parameter needs a nested array. '["Cube","Table"]' is read as two arguments and fails with "expects 1 argument(s) but 2 were provided".

Understanding bounds types in Unity:

Always prefer world-space bounds (Renderer.bounds or Collider.bounds) for placement. These already account for the object's position, rotation, and scale — no manual conversion needed.

Step 3: Use world bounds directly (or convert from local)

If using world-space bounds (preferred — from Renderer.bounds or Collider.bounds):

The values are ready to use directly:

worldCenter = bounds.center    // already in world space
worldMin = bounds.min          // already in world space
worldMax = bounds.max          // already in world space
size = bounds.size             // world-space AABB dimensions
extents = bounds.extents       // half of size

If using local bounds (from Renderer.localBounds or manual component data):

Convert to world space by adding the object's position:

worldCenter = position + localBounds.center
worldMin = worldCenter - (localBounds.size / 2)
worldMax = worldCenter + (localBounds.size / 2)

Note on rotation: Local bounds ignore rotation. If converting from local bounds on a rotated object, the calculated AABB will not reflect the actual world-space footprint. Prefer world-space bounds whenever possible.

Store these values for each object:

• worldCenter: [x, y, z]
• size: [width, height, depth]
• extents: [width/2, height/2, depth/2]

Step 4: Calculate placement position

Based on the spatial relationship, calculate the target position:

On top of (object A on top of object B):

targetY = B.worldMax.y + A.extents.y
targetX = B.worldCenter.x
targetZ = B.worldCenter.z
newPosition = [targetX, targetY, targetZ]

Beside (object A beside object B, +X direction):

targetX = B.worldMax.x + A.extents.x
targetY = B.worldCenter.y
targetZ = B.worldCenter.z
newPosition = [targetX, targetY, targetZ]

In front of (object A in front of object B, +Z direction):

targetX = B.worldCenter.x
targetY = B.worldCenter.y
targetZ = B.worldMax.z + A.extents.z
newPosition = [targetX, targetY, targetZ]

Above (floating above, with gap):

gap = 0.5  // or specified distance
targetY = B.worldMax.y + gap + A.extents.y
targetX = B.worldCenter.x
targetZ = B.worldCenter.z
newPosition = [targetX, targetY, targetZ]

Next to / Beside with distance (object A next to object B, with specified gap):

gap = user_specified_distance  // e.g., 0.5 meters
// Right side (+X):
targetX = B.worldMax.x + gap + A.extents.x
// Left side (-X):
targetX = B.worldMin.x - gap - A.extents.x
targetY = B.worldCenter.y  // or B.worldMin.y + A.extents.y for ground level
targetZ = B.worldCenter.z
newPosition = [targetX, targetY, targetZ]

X meters/units to the left/right/front/back:

// "2 meters to the right of B"
targetX = B.worldMax.x + 2.0 + A.extents.x

// "1.5 units to the left of B"
targetX = B.worldMin.x - 1.5 - A.extents.x

// "0.5 meters in front of B"
targetZ = B.worldMax.z + 0.5 + A.extents.z

// "1 unit behind B"
targetZ = B.worldMin.z - 1.0 - A.extents.z

Step 5: Apply the position

set_transform writes localPosition, not world position. Verified: on a child of a parent at world x=10, --position "[1,0,0]" yields localPosition (1,0,0) / position (11,0,0). Every formula above produces a world position, so:

• Unparented object — local and world are the same, apply the computed value directly:

  unity command set_transform --target Cube --position "[0,1.05,2]" --format json
  unity command save_scene --format json

  Array parameters take a JSON array in one argument. --position 0 1.05 2 is rejected with INVALID_COMMAND_ARGS.

• Parented object — convert first, or set transform.position in a script, which is world-space by definition:

  // AgentScripts/SetWorldPosition.cs
  using UnityEditor;
  using UnityEditor.SceneManagement;
  using UnityEngine;
  
  public static class SetWorldPosition
  {
      public static string Run(string name, float x, float y, float z)
      {
          var go = GameObject.Find(name);
          if (go == null) return $"ERROR: '{name}' not found.";
  
          Undo.RecordObject(go.transform, "Place object");
          go.transform.position = new Vector3(x, y, z);
          EditorSceneManager.MarkSceneDirty(go.scene);
          return $"{name}: world={go.transform.position} local={go.transform.localPosition}";
      }
  }

  unity command run_script --file AgentScripts/SetWorldPosition.cs \
    --entry SetWorldPosition.Run --args '["Cube", 0, 1.05, 2]' --format json
  unity command save_scene --format json

The script returns both spaces, which is the only way to confirm what landed — get_component_properties --type Transform exposes only m_LocalPosition, so it cannot tell world from local.

Step 6: Verify placement

After placement, inform the user:

• The calculated position
• The bounds that were used
• Any adjustments made
• Suggest they check the Scene view — or metavr capture screenshot once it's running on a headset

Common placement patterns

On top (stacking)

• Use reference object's top surface (worldMax.y)
• Add target object's half-height (extents.y)
• Align centers horizontally (X, Z match)

Beside (horizontal adjacency)

• Use reference object's side surface (worldMax.x or worldMin.x)
• Add target object's half-width (extents.x)
• Align centers vertically (Y matches) and depth-wise (Z matches)

In front / Behind

• Use reference object's front/back surface (worldMax.z or worldMin.z)
• Add target object's half-depth (extents.z)
• Align centers (X, Y match)