/smart

name: unity-smart
description: AI-powered scene queries, layout and auto-binding. AI

> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Querying scene objects by condition or proximity
• Auto-arranging objects
• Auto-wiring references
• 按条件或邻近关系查询场景对象、自动排布对象、自动连线引用

Unity Smart Skills

Operating Mode

• **Approval**：本模块 Mixed —— 只读查询 skill `smart_scene_query` / `smart_scene_query_spatial`（标 `ReadOnly = true`, `Mode = SkillMode.SemiAuto`）可直接执行；其余布局/绑定/变换类 skill (`smart_scene_layout` / `smart_reference_bind` / `smart_align_to_ground` / `smart_distribute` / `smart_snap_to_grid` / `smart_randomize_transform` / `smart_select_by_component`) 为 `SkillMode.FullAuto`，需用户 grant 单次执行返结果。
• **Auto / Bypass**：直接执行。
• **含 NeverInSemi 高危 skill**：`smart_replace_objects`（Operation.Modify|Delete，会替换并删除原对象）。该 skill 在 Approval/Auto 下返 `MODE_FORBIDDEN`，仅 Bypass 或 Allowlist 命中可调。

**DO NOT** (common hallucinations):

• `smart_create` / `smart_build` do not exist → smart skills are query/layout tools, not creation tools
• `smart_search` / `smart_query` do not exist → use `smart_scene_query` (component property filters) or `smart_scene_query_spatial` (spatial region filters)
• `smart_move` does not exist → use `smart_snap_to_grid` or `smart_align_to_ground`

**Routing**:

• For creating objects → use `gameobject` module
• For simple object search → use `gameobject_find` or `scene_find_objects`
• For complex scene queries (SQL-like) → `smart_scene_query` (this module)

Skills

smart_scene_query

Find objects based on component property values (SQL-like).

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `componentName` | string | Yes | - | Component type (Light, Camera, MeshRenderer) | | `propertyName` | string | Yes | - | Property to query (intensity, enabled, etc.) | | `op` | string | No | "==" | ==, !=, >, <, >=, <=, contains | | `value` | string | No | null | Value to compare | | `limit` | int | No | 50 | Max results | | `query` | string | No | null | Unsupported shorthand; if provided alone returns a guidance error |

**Example**:

# Find all lights with intensity > 2
call_skill("smart_scene_query", componentName="Light", propertyName="intensity", op=">", value="2")

---

smart_scene_layout

Organize selected objects into a layout.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `layoutType` | string | No | "Linear" | Linear, Grid, Circle, Arc | | `axis` | string | No | "X" | X, Y, Z, -X, -Y, -Z | | `spacing` | float | No | 2.0 | Space between items (or radius) | | `columns` | int | No | 3 | For Grid layout | | `arcAngle` | float | No | 180 | For Arc layout (degrees) | | `lookAtCenter` | bool | No | false | Rotate to face center |

**Example**:

# Arrange selected objects in a circle
call_skill("smart_scene_layout", layoutType="Circle", spacing=5)

---

smart_reference_bind

Auto-fill a List/Array field with matching objects.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `targetName` | string | Yes | - | Target GameObject | | `componentName` | string | Yes | - | Component on target | | `fieldName` | string | Yes | - | Field to fill | | `sourceTag` | string | No | null | Find by tag | | `sourceName` | string | No | null | Find by name contains | | `appendMode` | bool | No | false | Append instead of replace |

**Example**:

# Fill GameManager.spawns with all SpawnPoint tagged objects
call_skill("smart_reference_bind", targetName="GameManager", componentName="GameController", fieldName="spawns", sourceTag="SpawnPoint")

---

`smart_scene_query_spatial`

Find objects within a sphere/box region, optionally filtered by component.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `x` | float | Yes | - | Center X coordinate | | `y` | float | Yes | - | Center Y coordinate | | `z` | float | Yes | - | Center Z coordinate | | `radius` | float | No | 10 | Search sphere radius | | `componentFilter` | string | No | null | Only include objects with this component | | `limit` | int | No | 50 | Max results |

**Returns:** `{ success, count, center, radius, results }`

---

`smart_align_to_ground`

Raycast selected objects downward to align them to the ground. Requires objects selected in Hierarchy first.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `maxDistance` | float | No | 100 | Maximum raycast distance | | `alignRotation` | bool | No | false | Align rotation to surface normal |

**Returns:** `{ success, aligned, total }`

---

`smart_distribute`

Evenly distribute selected objects between first and last positions. Requires at least 3 objects selected in Hierarchy first.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `axis` | string | No | "X" | X, Y, Z, -X, -Y, -Z |

**Returns:** `{ success, distributed, axis }`

---

`smart_snap_to_grid`

Snap selected objects to a grid.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `gridSize` | float | No | 1 | Grid cell size |

**Returns:** `{ success, snapped, gridSize }`

---

`smart_randomize_transform`

Randomize position/rotation/scale of selected objects within ranges.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `posRange` | float | No | 0 | Position randomization range |