/hz-unity-placement

name: hz-unity-placement
license: Apache-2.0
description: Ensures accurate object placement in Unity projects targeting Meta VR and Horizon OS by using Renderer and Collider bounds when objects are added, moved, or positioned relative to other objects.

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) {