Unity Perception

Unity Perception Skills

Guardrails

Mode: Semi-Auto (available by default)

DO NOT (common hallucinations):

• perception_analyze does not exist → use scene_summarize or script_analyze
• perception_scan / perception_describe do not exist
• scene_context ≠ editor_get_context: scene_context exports full hierarchy+components, editor_get_context returns current selection+editor state

Routing:

• For current editor state (selection, play mode) → use editor module's editor_get_context
• For object search → use scene_find_objects (scene module) or gameobject_find (gameobject module, Full-Auto)
• For script dependency analysis → script_dependency_graph (this module)

Skills

scene_summarize

Get a structured summary of the current scene.

Returns:

{
  "sceneName": "Main",
  "stats": {
    "totalObjects": 156,
    "activeObjects": 142,
    "rootObjects": 12,
    "maxHierarchyDepth": 5,
    "lights": 3,
    "cameras": 2,
    "canvases": 1
  },
  "topComponents": [{"component": "MeshRenderer", "count": 45}, ...]
}

hierarchy_describe

Get a text tree of the scene hierarchy.

Returns:

Scene: Main
────────────────────────────────────────
► Main Camera 📷
► Directional Light 💡
► Environment
  ├─ Ground ▣
  ├─ Trees
    ├─ Tree_001 ▣
    ├─ Tree_002 ▣
► Canvas 🖼
  ├─ StartButton 🔘

script_analyze

Analyze a MonoBehaviour script's public API.

Returns:

{
  "script": "PlayerController",
  "fields": [{"name": "speed", "type": "float", "isSerializable": true}],
  "properties": [{"name": "IsGrounded", "type": "bool", "canWrite": false}],
  "methods": [{"name": "Jump", "returnType": "void", "parameters": ""}],
  "unityCallbacks": ["Start", "Update", "OnCollisionEnter"]
}

scene_spatial_query

Find objects within a radius of a point, or near another object.

Returns:

{
  "center": {"x": 0, "y": 0, "z": 0},
  "radius": 10,
  "totalFound": 5,
  "results": [{"name": "Enemy", "path": "Enemies/Enemy", "distance": 3.2, "position": {"x": 1, "y": 0, "z": 3}}]
}

scene_materials

Get an overview of all materials and shaders used in the current scene.

Returns:

{
  "totalMaterials": 12,
  "totalShaders": 4,
  "shaders": [{"shader": "Standard", "materialCount": 5, "materials": [{"name": "Ground", "userCount": 3}]}]
}

scene_context

Generate a comprehensive scene snapshot for AI coding assistance (hierarchy, components, script fields, references, UI layout).

Returns:

{
  "sceneName": "Main",
  "totalObjects": 156,
  "exportedObjects": 85,
  "truncated": true,
  "objects": [
    {
      "path": "Canvas/MainPanel/StartButton",
      "name": "StartButton",
      "active": true,
      "tag": "Untagged",
      "layer": "UI",
      "components": [
        {"type": "RectTransform", "props": {"anchoredPosition": "(120, -50)", "sizeDelta": "(200, 60)"}},
        {"type": "Button", "props": {"interactable": true, "transition": "ColorTint"}},
        {"type": "PlayerUIController", "kind": "MonoBehaviour", "fields": {"speed": {"type": "Float", "value": 5.5}, "target": {"type": "GameObject", "value": "Player/Body"}}}
      ],
      "children": ["Canvas/MainPanel/StartButton/Text"]
    }
  ],
  "references": [
    {"from": "Canvas/MainPanel/StartButton:PlayerUIController.target", "to": "Player/Body"}
  ],
  "codeDependencies": [
    {"from": "PlayerUIController.Start", "to": "HealthSystem", "type": "GetComponent", "detail": "GetComponent<HealthSystem>()"}
  ]
}

scene_export_report

Export complete scene structure and script dependency report as markdown file. Includes: hierarchy tree (built-in components name only, user scripts marked with *), user script fields with values, deep C# code-level dependencies (10 patterns: GetComponent<T>, FindObjectOfType<T>, SendMessage, field references, Singleton access, static member access, new T(), generic type args, inheritance/interface, typeof/is/as type checks), and merged dependency graph with risk ratings.

Returns:

{
  "success": true,
  "savedTo": "Assets/Docs/SceneReport.md",
  "objectCount": 156,
  "userScriptCount": 5,
  "referenceCount": 12,
  "codeReferenceCount": 4
}

Markdown output sections:

1. Hierarchy — tree with component names, user scripts marked *
2. Script Fields — only user scripts (non-Unity namespace), with field values and reference targets
3. Code Dependencies — C# source analysis (comments stripped): GetComponent<T>, FindObjectOfType<T>, SendMessage, field references, inheritance (multi-class), static access (PascalCase only). Method-level location in From column.
4. Dependency Graph — table with columns: From | To | Type | Source | Detail. Source = scene (serialized reference) or code (source analysis). From shows ClassName.MethodName for code deps.

scene_dependency_analyze

Analyze object dependency graph and impact of changes. Use ONLY when user explicitly asks about dependency/impact analysis, safe to delete/disable, refactoring impact, or reference checks.

Returns:

{
  "sceneName": "Main",
  "totalReferences": 12,
  "objectsAnalyzed": 5,
  "analysis": [
    {
      "path": "Canvas/HUD/HealthBar",
      "risk": "medium",
      "dependedByCount": 3,
      "dependedBy": [
        {"source": "Player", "script": "PlayerController", "field": "healthUI", "fieldType": "Slider"}
      ],
      "dependsOnCount": 0,
      "dependsOn": null
    }
  ],
  "savedTo": "Assets/Docs/deps.md",
  "markdown": null
}

script_dependency_graph

Given an entry script, return its N-hop dependency closure as structured JSON. Shows which scripts to read to understand or safely modify a feature.

Returns:

{
  "success": true,
  "entryScript": "PlayerController",
  "totalScriptsReached": 5,
  "maxHops": 2,
  "scripts": [
    {
      "name": "PlayerController",
      "hop": 0,
      "kind": "MonoBehaviour",
      "baseClass": "MonoBehaviour",
      "filePath": "Assets/Scripts/PlayerController.cs",
      "dependsOn": ["HealthSystem", "InputManager"],
      "dependedBy": ["EnemyAI"],
      "fields": [{"name": "health", "type": "HealthSystem", "serializable": true}],
      "unityCallbacks": ["Start", "Update"]
    }
  ],
  "edges": [
    {"from": "PlayerController", "to": "HealthSystem", "type": "FieldReference", "detail": "field:HealthSystem"}
  ],
  "suggestedReadOrder": ["InputManager", "HealthSystem", "EnemyAI", "PlayerController"]
}

scene_tag_layer_stats

Get Tag/Layer usage stats and find potential issues (untagged objects, unused layers).

No parameters.

Returns:

{
  "success": true,
  "totalObjects": 156,
  "untaggedCount": 120,
  "tags": [{"tag": "Untagged", "count": 120}, {"tag": "Player", "count": 5}],
  "layers": [{"layer": "Default", "count": 140}, {"layer": "UI", "count": 16}],
  "emptyDefinedLayers": ["Water", "PostProcessing"]
}

scene_performance_hints

Diagnose scene performance issues with prioritized actionable suggestions.

No parameters.

Returns:

{
  "success": true,
  "hintCount": 2,
  "hints": [
    {"priority": 1, "category": "Lighting", "issue": "6 shadow-casting lights", "suggestion": "Reduce to ≤4 or use baked lighting", "fixSkill": "light_set_properties"},
    {"priority": 2, "category": "Batching", "issue": "150 non-static renderers", "suggestion": "Mark static objects with optimize_set_static_flags", "fixSkill": "optimize_set_static_flags"}
  ]
}