unity-smart

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

| rotRange | float | No | 0 | Rotation randomization range (degrees) |

| scaleMin | float | No | 1 | Minimum uniform scale |

| scaleMax | float | No | 1 | Maximum uniform scale |

Returns: { success, randomized }

---

smart_replace_objects

Replace selected objects with a prefab (preserving transforms). Requires objects selected in Hierarchy first.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| prefabPath | string | Yes | - | Asset path to the replacement prefab |

Returns: { success, replaced, prefab }

---

smart_select_by_component

Select all objects that have a specific component.

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| componentName | string | Yes | - | Component type name to search for |

Returns: { success, selected, component }

---

Exact Signatures

Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.