Unity ADR

Use this when architecture choices may be revisited later or when multiple plausible options exist.

Output Format

• Decision
• Context
• Options considered
• Chosen option
• Why this option won
• Consequences
• Revisit triggers

Example Use Cases

• Coroutine vs UniTask
• Direct reference vs event-driven communication
• ScriptableObject config vs in-scene authoring
• One assembly vs multiple asmdef
• Runtime logic in MonoBehaviour vs pure C# service

Guardrails

Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).

• Keep ADRs short.
• Record only decisions that materially affect code generation or architecture direction.

Unity Animator Skills

Control Unity's Mecanim system — create Animator Controllers, add layers' states / transitions / parameters, assign controllers to GameObjects, set parameters at runtime, and play states.

Operating Mode

• Approval：查询类 skill（animator_get_parameters / animator_get_info / animator_list_states，源码标 SkillMode.SemiAuto）直接执行；其余变更类（create_controller / add_parameter / set_parameter / play / assign_controller / add_state / add_transition，标 SkillMode.FullAuto）需用户 grant，grant 后服务端一步执行返结果。
• Auto / Bypass：所有 skill 直接执行；Auto 走 AI 自我评估，Bypass 全放行。
• 本模块不含 Delete / PlayMode / Reload / 高危 skill，无 Bypass-only 拦截项。
• animator_set_parameter / animator_play 作用于场景中已挂 Animator 的 GameObject；如果当前不在 Play mode，状态机只在 Editor 预览模式推进，效果与 runtime 不完全等价。

DO NOT (common hallucinations):

• animator_create_clip / animator_add_clip do not exist → AnimationClips are created via Unity Editor or asset import
• animator_set_speed does not exist → use component_set_property on Animator component with propertyName="speed"

Routing:

• For Timeline animation → use timeline module
• For component properties on Animator → use component module
• For animation import settings → use importer module

Skills Overview

Parameter Types

Skills

animator_create_controller

Create a new Animator Controller.

Returns: {success, name, path}

animator_add_parameter

Add a parameter to a controller.

animator_get_parameters

Get all parameters from a controller.

Returns: {controller, parameters: [{name, type, defaultFloat, defaultInt, defaultBool}]}

animator_set_parameter

Set a parameter value at runtime (supports name/instanceId/path).

*At least one identifier required. Use the appropriate value for paramType (trigger doesn't need a value).

animator_play

Play a specific animation state (supports name/instanceId/path).

*At least one identifier required.

animator_get_info

Get Animator component information (supports name/instanceId/path).

Returns: {gameObject, instanceId, hasController, controllerPath, speed, applyRootMotion, updateMode, cullingMode, layerCount, parameterCount}

animator_assign_controller

Assign a controller to a GameObject (supports name/instanceId/path).

*At least one identifier required.

animator_list_states

List all states in a controller layer.

Returns: {controller, layer, layerName, stateCount, states: [{name, tag, speed, hasMotion}]}

animator_add_state

Add a state to an Animator Controller layer.

Returns: {success, controller, stateName, layer}

animator_add_transition

Add a transition between two states in an Animator Controller.

Returns: {success, from, to, layer, hasExitTime, duration}

Example: Complete Animation Setup

import unity_skills

# 1. Create controller
unity_skills.call_skill("animator_create_controller",
    name="PlayerController",
    folder="Assets/Animations"
)

# 2. Add parameters
unity_skills.call_skill("animator_add_parameter",
    controllerPath="Assets/Animations/PlayerController.controller",
    paramName="Speed", paramType="float", defaultFloat=0
)
unity_skills.call_skill("animator_add_parameter",
    controllerPath="Assets/Animations/PlayerController.controller",
    paramName="IsGrounded", paramType="bool", defaultBool=True
)
unity_skills.call_skill("animator_add_parameter",
    controllerPath="Assets/Animations/PlayerController.controller",
    paramName="Jump", paramType="trigger"
)

# 3. Assign to character
unity_skills.call_skill("animator_assign_controller",
    name="Player",
    controllerPath="Assets/Animations/PlayerController.controller"
)

# 4. Control at runtime
unity_skills.call_skill("animator_set_parameter",
    name="Player", paramName="Speed", paramType="float", floatValue=5.0
)

# Trigger jump
unity_skills.call_skill("animator_set_parameter",
    name="Player", paramName="Jump", paramType="trigger"
)

# Play specific state
unity_skills.call_skill("animator_play", name="Player", stateName="Idle")

Best Practices

1. Create controller before adding parameters
2. Use meaningful parameter names
3. Triggers reset automatically after firing
4. Set parameters before playing states
5. Use layers for independent animations (body + face)
6. States must exist in controller before playing

Exact Signatures

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

Unity Architecture Advisor

Use this before generating lots of gameplay scripts or when the user asks for a cleaner architecture.

Workflow

1. Identify scope: prototype, small game, or long-lived project.
2. Define the core loop and the minimum runtime systems needed.
3. Recommend the smallest architecture that fits the scope.
4. Separate:
   • scene/bootstrap layer
   • gameplay/domain logic
   • data/config assets
   • view/presentation layer
5. Call out what should stay simple now vs what is worth abstracting.

Output Format

When using this skill, structure the advice as:

• Project tier: prototype / small-game / long-lived
• Recommended modules: 3-7 modules with one-line responsibilities
• Scene/bootstrap plan: where composition and initialization happen
• Data ownership: what belongs in scene objects, ScriptableObjects, or pure C# classes
• Communication rules: direct refs, interfaces, events, or commands
• Performance risks: only the hot paths that matter
• Do now / skip now: avoid over-engineering

Default Guidance

• Prefer thin MonoBehaviour scripts as composition bridges.
• Put reusable gameplay rules in plain C# classes when possible.
• Use ScriptableObject for authored config and shared static data, not as a default dump for runtime state.
• Keep dependencies explicit. Avoid hidden global state unless the project size clearly justifies a small service layer.
• Favor simple module boundaries over framework-heavy architecture.

Explicit Execution Order and Entry Guards

Most "random" gameplay bugs trace back to two silent assumptions: that scripts run in a predictable order, and that Update runs only when its data is ready. Neither is true unless you make them so.

Make startup order explicit

Do not rely on Script Execution Order panels or accidental Awake ordering. Prefer these patterns in order of preference:

• One Bootstrap script as the single entry point. It owns the initialization sequence and calls sub.Init() on the managers it creates. Only this one script has [DefaultExecutionOrder(-10000)].
• Pull, don't push: a subscriber that needs data calls source.GetValue() on demand or subscribes to an event. A publisher that pushes into others during its own Awake creates hidden order dependencies.
• Reserve [DefaultExecutionOrder(n)] for load-bearing singletons only (Bootstrap, InputRouter, SceneController). If more than 3-4 scripts need it, the architecture is wrong, not the ordering.

The analogous ECS pattern — [UpdateBefore(typeof(BarSystem))] / [UpdateAfter] — works because the framework validates contradictions at sort time. In MonoBehaviour code the compiler won't catch them; be conservative. Source: EntitiesSamples/Docs/systems.md:32 — "if the ordering attributes of a group's children create a contradiction, an exception is thrown".

Make update preconditions explicit

Every Update / LateUpdate / FixedUpdate should open with guard clauses that early-return when the system is not ready. Prefer the cheapest check first:

void Update() {
    if (!_isInitialized) return;       // construction-time
    if (_dataSource == null) return;   // dependency-level
    if (_paused) return;               // gameplay-state
    // real work here
}

A missing guard is the difference between "doesn't run yet" (safe) and "runs with stale/null data and silently corrupts state" (debug nightmare). The ECS equivalent is state.RequireForUpdate<Config>() in OnCreate, which turns the precondition into a system-level invariant. Source: Dots101/Entities101/Assets/HelloCube/3. Prefabs/SpawnSystem.cs:17-19 — the system does not update unless a Spawner entity exists.

Guardrails

Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).

• Do not start from a giant reusable framework unless the project truly needs it.
• Do not add layers just to satisfy textbook SOLID wording.
• Prefer a small architecture that can grow, not an impressive one that slows iteration.

Load Related Advisory Modules When Needed

• Pattern choice: see ../patterns/SKILL.md
• Async / Update / UniTask decisions: see ../async/SKILL.md
• Inspector-facing field design: see ../inspector/SKILL.md
• Script quality review: see ../scriptdesign/SKILL.md

Unity asmdef Advisor

Use this skill when the project is large enough that compile boundaries and dependency direction matter.

Recommend Only When Worth It

asmdef is usually worth discussing when:

• the project has multiple domains/systems
• editor code and runtime code are mixed
• compile times are becoming noticeable
• tests should be isolated cleanly

Output Format

• Whether asmdef is justified now
• Proposed assemblies
• Allowed dependency direction
• Editor/runtime/test split
• Migration steps
• Risks or churn to avoid

Default Guidance

• Prefer a few meaningful assemblies over many tiny ones.
• Split editor code from runtime first.
• Keep the dependency graph directional and shallow.

Guardrails

Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).

• Do not introduce asmdef fragmentation for a tiny prototype.
• Do not create circular dependencies or force everything through a shared dumping-ground assembly.

Unity Asset Skills

BATCH-FIRST: Use *_batch skills when operating on 2+ assets.

Operating Mode

• Approval：本模块 Mixed —— asset_find / asset_get_info / asset_get_labels 标 SkillMode.SemiAuto，可直接执行；写类 skill (asset_move / asset_move_batch / asset_duplicate / asset_create_folder / asset_refresh / asset_reimport* / asset_set_labels) 走默认 SkillMode.FullAuto，需 grant。
• Auto / Bypass：FullAuto 直接执行。
• 含 NeverInSemi 高危 skill：asset_import (标 RiskLevel = "high" —— 写入项目)；asset_delete / asset_delete_batch (Operation.Delete)。这些在 Approval/Auto 下返 MODE_FORBIDDEN，仅 Bypass 或 Allowlist 命中可调。

DO NOT (common hallucinations):

• asset_create does not exist → use asset_create_folder (folders), material_create (materials), script_create (scripts)
• asset_rename does not exist → use asset_move with new path
• asset_search does not exist → use asset_find with searchFilter syntax (e.g. t:Texture2D player)
• asset_copy does not exist → use asset_duplicate

Routing:

• For texture/model/audio import settings → use importer module (SkillMode.FullAuto)
• For material creation → use material module (SkillMode.FullAuto)
• For script creation → use script module

Skills Overview

No batch needed:

• asset_duplicate - Duplicate single asset
• asset_find - Search assets (returns list)
• asset_create_folder - Create folder
• asset_refresh - Refresh AssetDatabase
• asset_get_info - Get asset information
• asset_reimport - Force reimport asset
• asset_reimport_batch - Reimport multiple assets

Skills

asset_import

Import an external file into the project.

asset_import_batch

Import multiple external files.

items currently expects a JSON string, not a native array.

Returns: {success, totalItems, successCount, failCount, results: [{success, sourcePath, destinationPath}]}

import json

unity_skills.call_skill("asset_import_batch", items=json.dumps([
    {"sourcePath": "C:/Downloads/tex1.png", "destinationPath": "Assets/Textures/tex1.png"},
    {"sourcePath": "C:/Downloads/tex2.png", "destinationPath": "Assets/Textures/tex2.png"}
]))

asset_delete

Delete an asset from the project.

asset_delete_batch

Delete multiple assets.

items currently expects a JSON string, not a native array.

Returns: {success, totalItems, successCount, failCount, results: [{success, path}]}

import json

unity_skills.call_skill("asset_delete_batch", items=json.dumps([
    {"path": "Assets/Textures/old1.png"},
    {"path": "Assets/Textures/old2.png"}
]))

asset_move

Move or rename an asset.

asset_move_batch

Move multiple assets.

items currently expects a JSON string, not a native array.

Returns: {success, totalItems, successCount, failCount, results: [{success, sourcePath, destinationPath}]}

import json

unity_skills.call_skill("asset_move_batch", items=json.dumps([
    {"sourcePath": "Assets/Old/mat1.mat", "destinationPath": "Assets/New/mat1.mat"},
    {"sourcePath": "Assets/Old/mat2.mat", "destinationPath": "Assets/New/mat2.mat"}
]))

asset_duplicate

Duplicate an asset.

asset_find

Find assets by search filter.

Search Filter Syntax:

Returns: {count, totalFound, assets: [{path, name, type}]}

asset_create_folder

Create a folder in the project.

asset_refresh

Refresh the AssetDatabase after external changes.

No parameters.

asset_get_info

Get information about an asset.

asset_reimport

Force reimport of an asset.

asset_reimport_batch

Reimport multiple assets matching a pattern.

asset_set_labels

Set labels on an asset (overwrites existing labels).

Returns: {success, assetPath, labels: [...]}

asset_get_labels

Get the labels currently attached to an asset.

Returns: {success, assetPath, labels: [...]}

Minimal Example

import unity_skills

# GOOD: 1 API call instead of 4
unity_skills.call_skill("asset_move_batch", items=[
    {"sourcePath": "Assets/tex1.png", "destinationPath": "Assets/Textures/tex1.png"},
    {"sourcePath": "Assets/tex2.png", "destinationPath": "Assets/Textures/tex2.png"},
    {"sourcePath": "Assets/tex3.png", "destinationPath": "Assets/Textures/tex3.png"},
    {"sourcePath": "Assets/tex4.png", "destinationPath": "Assets/Textures/tex4.png"}
])

Best Practices

1. Organize assets in logical folders
2. Use consistent naming conventions
3. Refresh after external file changes
4. Use search filters for efficiency
5. Backup before bulk delete operations

Exact Signatures

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

Unity Async Strategy

Use this skill when the user is deciding how runtime work should be scheduled or cleaned up.

Guardrails

Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).

• Do not recommend UniTask just because it looks more advanced than coroutine.
• Prefer the simplest scheduling model that fits the use case.

Decision Ladder

1. First ask whether the task needs per-frame work at all.
2. If not, prefer events, callbacks, or explicit method calls.
3. If a short Unity-bound sequence is needed, prefer coroutine.
4. Recommend UniTask only when:
   • the project already uses it, or
   • the user explicitly wants it and accepts the dependency.
5. Use Update only for true continuous simulation, polling, or input loops that cannot be event-driven.

Specific Guidance

• Avoid many unrelated Update methods if a more event-driven flow works.
• Cache references used in hot paths.
• Always define lifecycle ownership:
  • who starts the work
  • who cancels or stops it
  • when it is cleaned up
• In MonoBehaviour, prefer OnEnable / OnDisable / OnDestroy for subscribe-unsubscribe symmetry.
• Use IDisposable mainly for pure C# lifetimes, temporary subscriptions, or scope-based cleanup helpers, not as a cargo-cult replacement for Unity lifecycle methods.

Output Format

• Recommended scheduling model
• Why it fits
• Lifecycle / cancellation owner
• Hot-path risks
• Why the heavier alternative is unnecessary, if applicable

Unity Batch Skills

Batch workflow orchestration for query, preview, execution, reports, and async jobs.

Operating Mode

本模块共 22 个 skill，按 Operation 区分为两类：

• 18 个 SemiAuto（query / preview / report / job 查询类）：batch_query_gameobjects / batch_query_components / batch_query_assets / batch_preview_rename / batch_preview_set_property / batch_preview_replace_material / batch_report_get / batch_report_list / job_status / job_progress / job_logs / job_list / batch_fix_missing_scripts / batch_standardize_naming / batch_set_render_layer / batch_replace_material / batch_validate_scene_objects / batch_cleanup_temp_objects。Approval 模式下可直接执行。
• 4 个 FullAuto（Execute 类，C# 未标 Mode 走默认 SkillMode.FullAuto）：batch_execute / job_wait / job_cancel / batch_retry_failed。Approval 模式下首次调用返 MODE_RESTRICTED，走 grant 协议。
• Auto / Bypass：两类都直接执行。不含 NeverInSemi 高危 skill（无 Delete/MayEnterPlayMode/MayTriggerReload 标记）。

注意：batch_execute(confirmToken) 本身放行，但它执行的 preview 内容可能包括对场景对象的删除/改属性等高影响动作 —— 请确保 batch_preview_* 返回的 sample/risk 字段已审阅。confirmToken 一次性消费、过期需重新 preview。

DO NOT (common hallucinations):

• Always call a batch_preview_* skill first — batch_execute requires a confirmToken from a preview, it cannot be called directly
• batch_run does not exist → use batch_execute(confirmToken)
• job_poll / job_result do not exist → use job_status to check and retrieve async job results
• batch_delete / batch_move do not exist → use asset module for asset-level operations

Routing:

• For asset-level bulk operations (move, copy, delete) → asset module
• For workflow session/task undo tracking → workflow module
• For scene object validation → batch_validate_scene_objects (this module)
• For async job polling → job_status / job_wait (this module)

Skills

batch_query_gameobjects

Query GameObjects with unified batch filters. queryJson supports name/path/instanceId/tag/layer/active/componentType/sceneName/parentPath/prefabSource/includeInactive/limit.

batch_query_components

Query components with unified batch filters. Optional componentType narrows the result.

batch_query_assets

Query project assets by type, path pattern, and labels. Read-only.

batch_preview_rename

Preview batch renaming. mode supports prefix / suffix / replace / regex_replace.

batch_preview_set_property

Preview setting a component property or field across queried targets.

batch_preview_replace_material

Preview replacing Renderer materials across queried targets.

batch_execute

Execute a previously previewed batch operation by confirmToken. Large operations return a jobId.

batch_report_get

Get a batch execution report by reportId.

batch_report_list

List recent batch reports.

job_status

Get status for an asynchronous UnitySkills job.

job_progress

Get fine-grained progress events for a job via incremental polling. Use offset to fetch only new events since the last call (pass previous totalCount as next offset).

Note: Also exposed as HTTP GET /jobs/{id}/progress and Python client.get_job_progress(job_id, offset) — all three paths share the same response shape.

Response fields: jobId, status, totalCount, offset, events[] (timestamp ms, progress, stage, description), terminal.

job_logs

Get structured logs for a UnitySkills job.

job_list

List recent UnitySkills jobs.

job_wait

Wait for a UnitySkills job to finish or until timeoutMs elapses.

job_cancel

Cancel a UnitySkills job if the job supports cancellation.

batch_fix_missing_scripts

Preview batch removal of missing scripts. Execute with batch_execute(confirmToken).

batch_standardize_naming

Preview standardizing names by trimming whitespace and normalizing separators. Execute with batch_execute(confirmToken).

batch_set_render_layer

Preview setting GameObject layers in batch. Execute with batch_execute(confirmToken).

batch_replace_material

Preview replacing materials in batch. Execute with batch_execute(confirmToken).

batch_validate_scene_objects

Analyze scene objects for missing scripts, missing references, duplicate names, and empty objects.

batch_cleanup_temp_objects

Preview deleting temporary helper objects by common temp-name patterns. Execute with batch_execute(confirmToken).

batch_retry_failed

Re-run only the failed items from a previous batch execution report. Returns a new jobId and originalReportId.

Exact Signatures

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

Unity Gameplay Blueprints

Use this skill when starting a new mini-game or vertical slice and a lightweight architecture skeleton is more useful than raw code volume.

Supported Blueprint Styles

• 2D platformer
• top-down shooter
• endless runner
• puzzle / interaction game
• tower defense
• clicker / incremental
• card / turn-based prototype

Output Format

• Core loop
• Recommended scenes
• Recommended modules
• Initial script list
• Data/config assets
• UI responsibilities
• What to deliberately keep simple

Guardrails

Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).

• Provide the smallest viable blueprint, not a giant reusable framework.
• Prefer a short script inventory over “future-proof” template sprawl.

Bookmark Skills

Save and recall Scene View camera positions.

Guardrails

Operating Mode (v1.9 three-tier):

• Approval (default): bookmark_set / bookmark_goto / bookmark_list 都标 SkillMode.SemiAuto，Approval 模式下可直接执行，无需走 grant 协议。与 workflow 模块文档保持一致（C# WorkflowSkills.cs 内三者均为 SemiAuto）。
• Auto / Bypass: SemiAuto and FullAuto run directly.
• Auto-forbidden in this module: bookmark_delete (SkillOperation.Delete). Reachable only under Bypass mode or via a user-managed Allowlist entry; the grant flow returns MODE_FORBIDDEN. Bookmarks themselves are in-memory only — bookmark_delete only removes the entry, no asset I/O.

DO NOT (common hallucinations):

• bookmark_save does not exist → use bookmark_set
• bookmark_load / bookmark_restore do not exist → use bookmark_goto
• bookmark_remove does not exist → use bookmark_delete
• Bookmarks save Scene View position + current selection, not scene state

Routing:

• For workflow snapshots (object state undo) → use workflow module
• For scene save/load → use scene module

Skills

bookmark_set

Save current Scene View camera position as a bookmark. Parameters:

• bookmarkName (string): Bookmark name.

bookmark_goto

Move Scene View camera to a saved bookmark. Parameters:

• bookmarkName (string): Bookmark name.

bookmark_list

List all saved bookmarks. Parameters: None.

bookmark_delete

Delete a saved bookmark. Parameters:

• bookmarkName (string): Bookmark name.

Exact Signatures

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

Camera Skills

Control the Scene View camera and Game Cameras (creation, transform, properties, screenshot, culling, orthographic toggle).

Operating Mode

• Approval (default): mutating skills (camera_set_transform, camera_create, camera_set_properties, camera_set_culling_mask, camera_screenshot, camera_sceneview_screenshot, camera_set_orthographic, camera_align_view_to_object, camera_look_at) need user grant; grant triggers a single server-side execution that returns the result.
• Auto / Bypass: those skills execute directly.
• Query skills (camera_get_info, camera_get_properties, camera_list) are SkillMode.SemiAuto — they run in all three modes without grant.
• This module contains no Delete / PlayMode / Reload / high-risk skills (no NeverInSemi).

Guardrails

DO NOT (common hallucinations):

• camera_move / camera_rotate do not exist → use camera_set_transform (Scene View) or gameobject_set_transform (Game Camera)
• camera_set_fov does not exist → use camera_set_properties with fieldOfView parameter
• camera_* skills control two different cameras: camera_set_transform/camera_look_at/camera_align_view_to_object control the Scene View camera; camera_create/camera_set_properties/camera_screenshot control Game Cameras
• camera_delete does not exist → use gameobject_delete on the camera GameObject

Routing:

• For Cinemachine virtual cameras → use cinemachine module
• For Game Camera component properties → camera_set_properties / camera_get_properties (this module)
• For screenshots → three options: scene_screenshot (scene module) = the Game View final composite (all cameras + UI; Play mode = live runtime frame); camera_screenshot (this module) = a single Game Camera off-screen render; camera_sceneview_screenshot (this module) = the editor Scene View (developer viewport, incl. grid/gizmos)

Skills

camera_align_view_to_object

Align Scene View camera to look at an object. Parameters:

• name (string, optional): Target GameObject name.
• instanceId (int, optional): Target GameObject instance ID.
• path (string, optional): Target GameObject hierarchy path.

camera_get_info

Get Scene View camera position and rotation. Parameters: None.

camera_set_transform

Set Scene View camera position/rotation manually. Parameters:

• posX, posY, posZ (float): Position.
• rotX, rotY, rotZ (float): Rotation (Euler).
• size (float, optional): Orthographic size or pivot distance (default 5).
• instant (bool, optional): Move instantly (default true).

camera_look_at

Focus Scene View camera on a world-space point. Parameters:

• x, y, z (float): Target point.
• Does not support targetName or GameObject lookup. For object focus, use camera_align_view_to_object.

camera_create

Create a new Game Camera.

Returns: { success, name, instanceId }

camera_get_properties

Get Game Camera properties (supports name/instanceId/path).

Returns: { success, name, fieldOfView, nearClipPlane, farClipPlane, orthographic, orthographicSize, depth, cullingMask, clearFlags, backgroundColor, rect }

camera_set_properties

Set Game Camera properties (FOV, clip planes, clear flags, background color, depth).

Returns: { success, name }

camera_set_culling_mask

Set Game Camera culling mask by layer names (comma-separated).

Returns: { success, cullingMask }

camera_screenshot

Capture a screenshot from a Game Camera to file.

Returns: { success, path, width, height }

camera_sceneview_screenshot

Capture the editor Scene View (the developer's editing viewport — can overlook the whole scene incl. off-camera objects). Distinct from scene_screenshot (Game View / player camera) and camera_screenshot (one Game Camera). By default captures the full Scene View incl. grid/gizmos/selection (on-screen read); auto-falls back to a clean offscreen render if the editor build lacks the internal API. The Scene View window must be open and visible for the overlay capture.

Returns: { success, path, width, height, mode, note } — mode is "screen_with_overlays" or "offscreen_clean".

camera_set_orthographic

Switch Game Camera between orthographic and perspective mode.

Returns: { success, orthographic, orthographicSize }

camera_list

List all cameras in the scene.

Returns: { count, cameras: [{ name, instanceId, path, depth, orthographic, enabled }] }

Exact Signatures

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

Cinemachine Skills

Control Cinemachine Virtual Cameras and brain settings. Works with Cinemachine 2.x and 3.x through a runtime reflection adapter (CinemachineAdapter / CinemachineSkills).

Operating Mode

• Approval：查询类 skill（cinemachine_inspect_vcam / cinemachine_list_components / cinemachine_get_brain_info，源码标 SkillMode.SemiAuto）直接执行；其余配置/创建类（cinemachine_create_vcam / cinemachine_set_targets / cinemachine_set_lens / cinemachine_configure_body / cinemachine_configure_aim 等，标 SkillMode.FullAuto）需用户 grant，grant 后服务端一步执行返结果。
• Auto / Bypass：未被禁列表拦截的 skill 直接执行。
• 本模块含 Delete 类 skill：cinemachine_set_component（替换/移除 pipeline component）、cinemachine_target_group_remove_member、cinemachine_remove_extension 标记为 SkillOperation.Delete，被 IsForbiddenInSemi 静态拦截 —— 仅 Bypass 模式或加入 Allowlist 才能调用。
• 包依赖：必须安装 com.unity.cinemachine 包（CM 2.x 或 3.x）。未安装时所有 skill 返回 { error = "Cinemachine 未安装..." } 的 stub —— 调用方应先用 package_* 系列 skill 确认安装状态。
• 反射脆弱性：CM2 ↔ CM3 之间 API 名变化大（CinemachineVirtualCamera → CinemachineCamera，CinemachineComponentBase 改名等）。本模块通过 CinemachineAdapter 反射桥接，遇 CM 早期预览版（< 3.0.0-pre.5）可能因 API 漂移返回失败 —— 优先用 cinemachine_inspect_vcam 探测当前可用字段，再决定 propertyName。

DO NOT (common hallucinations):

• cinemachine_create does not exist → use cinemachine_create_vcam for virtual cameras
• cinemachine_set_target / cinemachine_set_follow / cinemachine_set_lookat do not exist → use cinemachine_set_targets (sets both Follow and LookAt in one call)
• cinemachine_add_brain does not exist → CinemachineBrain is auto-added to Main Camera on first VCam creation
• Cinemachine 2.x uses CinemachineVirtualCamera; Cinemachine 3.x uses CinemachineCamera — skills handle this automatically

Additional compatibility notes:

• CM3 priority access should use Priority.Value as the lowest common API when writing compatibility code.
• Early CM3 previews before 3.0.0-pre.5 changed core camera APIs significantly and are outside the current support baseline.

Routing:

• For basic Game Camera operations → use camera module
• For Scene View camera → use camera module's camera_set_transform/camera_look_at
• For camera animation sequences → use timeline module with Cinemachine track

Skills

cinemachine_create_vcam

Create a new Virtual Camera. Parameters:

• name (string): Name of the VCam GameObject.
• folder (string): Parent folder path (default: "Assets/Settings").

cinemachine_inspect_vcam

Deeply inspect a VCam, returning fields and tooltips. Parameters:

• vcamName (string, optional): Name of the VCam GameObject.
• instanceId (int, optional): VCam instance ID.
• path (string, optional): VCam hierarchy path.

cinemachine_set_vcam_property

Set any property on VCam or its pipeline components. Parameters:

• vcamName (string): Name of the VCam.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.
• componentType (string): "Main" (VCam itself), "Lens", or Component name (e.g. "OrbitalFollow").
• propertyName (string): Field or property name.
• value (object): New value.
• fov (float, optional): Lens FOV shortcut. When supplied without propertyName, routes to cinemachine_set_lens.
• nearClip (float, optional): Lens near clip shortcut.
• farClip (float, optional): Lens far clip shortcut.
• orthoSize (float, optional): Lens orthographic size shortcut.

cinemachine_set_targets

Set Follow and LookAt targets. Parameters:

• vcamName (string): Name of the VCam.
• instanceId (int, optional): VCam Instance ID (preferred for precision).
• path (string, optional): VCam hierarchy path.
• followName (string, optional): GameObject name to follow.
• lookAtName (string, optional): GameObject name to look at.

cinemachine_set_component

Switch VCam pipeline component (Body/Aim/Noise). Parameters:

• vcamName (string): Name of the VCam.
• stage (string): "Body", "Aim", or "Noise".
• componentType (string): Type name (e.g. "OrbitalFollow", "Composer") or "None" to remove.

cinemachine_add_component

DEPRECATED — Use cinemachine_set_component instead for proper pipeline control (Body/Aim/Noise stages). Add a Cinemachine component (legacy, supports CM2 and CM3). Parameters:

• vcamName (string): Name of the VCam.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.
• componentType (string): Type name (e.g., "OrbitalFollow").

cinemachine_set_lens

Quickly configure Lens settings (FOV, Near, Far, OrthoSize). Parameters:

• vcamName (string): Name of the VCam.
• fov (float, optional): Field of View.
• nearClip (float, optional): Near Clip Plane.
• farClip (float, optional): Far Clip Plane.
• orthoSize (float, optional): Orthographic Size.

cinemachine_list_components

List all available Cinemachine component names. Parameters:

• None.

cinemachine_impulse_generate

Trigger an Impulse at location or via Source. Parameters:

• sourceParams (string, optional): JSON string for parameters, e.g., {"velocity": {"x": 0, "y": -1, "z": 0}}.

cinemachine_get_brain_info

Get info about the Active Camera and Blend. Parameters:

• None.

cinemachine_create_target_group

Create a CinemachineTargetGroup. Parameters:

• name (string): Name of the new TargetGroup GameObject.

cinemachine_target_group_add_member

Add or update a member in a TargetGroup. Parameters:

• groupName (string): Name of the TargetGroup.
• targetName (string): Name of the member GameObject.
• weight (float): Member weight (default 1).
• radius (float): Member radius (default 1).

cinemachine_target_group_remove_member

Remove a member from a TargetGroup. Parameters:

• groupName (string): Name of the TargetGroup.
• targetName (string): Name of the member GameObject.

cinemachine_set_spline

Assign a SplineContainer to a VCam's SplineDolly component (Body stage). Parameters:

• vcamName (string): Name of the VCam.
• splineName (string): Name of the GameObject with SplineContainer.

cinemachine_add_extension

Add a CinemachineExtension to a VCam. Parameters:

• vcamName (string): Name of the VCam.
• extensionName (string): Type name of the extension (e.g., "CinemachineStoryboard", "CinemachineImpulseListener").

cinemachine_remove_extension

Remove a CinemachineExtension from a VCam. Parameters:

• vcamName (string): Name of the VCam.
• extensionName (string): Type name of the extension.

cinemachine_set_active

Force activation of a VCam (SOLO) by setting highest priority. Parameters:

• vcamName (string): Name of the VCam to activate.

cinemachine_create_mixing_camera

Create a Cinemachine Mixing Camera. Parameters:

• name (string): Name of the new GameObject.

cinemachine_mixing_camera_set_weight

Set the weight of a child camera within a Mixing Camera. Parameters:

• mixerName (string, optional): Name of the Mixing Camera.
• mixerInstanceId (int, optional): Mixing Camera instance ID.
• mixerPath (string, optional): Mixing Camera hierarchy path.
• mixerEntityId (string, optional): Mixing Camera entity ID (Unity 6000.4+, preferred).
• childName (string, optional): Name of the child VCam.
• childInstanceId (int, optional): Child VCam instance ID.
• childPath (string, optional): Child VCam hierarchy path.
• childEntityId (string, optional): Child VCam entity ID (Unity 6000.4+, preferred).
• weight (float): Weight value, usually 0.0–1.0 (default 1).

cinemachine_create_clear_shot

Create a Cinemachine Clear Shot Camera. Parameters:

• name (string): Name of the new GameObject.

cinemachine_create_state_driven_camera

Create a Cinemachine State Driven Camera. Parameters:

• name (string): Name of the new GameObject.
• targetAnimatorName (string, optional): Name of the GameObject with the Animator to bind.

cinemachine_state_driven_camera_add_instruction

Add a state mapping instruction to a State Driven Camera. Parameters:

• cameraName (string, optional): Name of the State Driven Camera.
• cameraInstanceId (int, optional): State Driven Camera instance ID.
• cameraPath (string, optional): State Driven Camera hierarchy path.
• cameraEntityId (string, optional): State Driven Camera entity ID (Unity 6000.4+, preferred).
• stateName (string): Name of the animation state (e.g., "Run").
• childCameraName (string, optional): Name of the child VCam to activate for this state.
• childInstanceId (int, optional): Child VCam instance ID.
• childPath (string, optional): Child VCam hierarchy path.
• childEntityId (string, optional): Child VCam entity ID (Unity 6000.4+, preferred).
• minDuration (float, optional): Minimum duration in seconds (default 0).
• activateAfter (float, optional): Delay in seconds before activation (default 0).

cinemachine_set_noise

Configure Noise settings (Basic Multi Channel Perlin). Parameters:

• vcamName (string): Name of the VCam.
• amplitudeGain (float): Noise Amplitude.
• frequencyGain (float): Noise Frequency.

cinemachine_set_priority

Set explicit priority value for a Virtual Camera. Higher priority wins activation. Parameters:

• vcamName (string, optional): VCam name. Provide one of name/instanceId/path.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.
• priority (int): Priority value (default 10).

cinemachine_set_blend

Set default blend or per-camera-pair blend on the CinemachineBrain. Leave fromCamera/toCamera empty for default blend. Parameters:

• style (string): Blend style — Cut/EaseInOut/EaseIn/EaseOut/HardIn/HardOut/Linear (default EaseInOut).
• time (float): Blend duration in seconds (default 2).
• fromCamera (string, optional): Source VCam name for per-pair blend.
• toCamera (string, optional): Destination VCam name for per-pair blend.

cinemachine_set_brain

Configure CinemachineBrain properties: update method, default blend, debug display. Parameters:

• updateMethod (string, optional): FixedUpdate/LateUpdate/SmartUpdate/ManualUpdate.
• blendUpdateMethod (string, optional): FixedUpdate/LateUpdate.
• defaultBlendStyle (string, optional): Blend style name (see cinemachine_set_blend).
• defaultBlendTime (float, optional): Default blend duration in seconds.
• showDebugText (bool, optional): Show Cinemachine debug text overlay.
• showCameraFrustum (bool, optional): Draw active camera frustum gizmo.
• ignoreTimeScale (bool, optional): Ignore Time.timeScale for blends.

cinemachine_create_sequencer

Create a Sequencer camera (CM3) or BlendList camera (CM2) that plays child cameras in sequence. Parameters:

• name (string): Name of the new GameObject.
• loop (bool): Whether to loop the sequence (default false).

cinemachine_sequencer_add_instruction

Add a child camera instruction to a Sequencer/BlendList camera. Parameters:

• sequencerName (string, optional): Sequencer camera name.
• sequencerInstanceId (int, optional): Sequencer Instance ID.
• sequencerPath (string, optional): Sequencer hierarchy path.
• sequencerEntityId (string, optional): Sequencer entity ID (Unity 6000.4+, preferred).
• childCameraName (string, optional): Child VCam name.
• childInstanceId (int, optional): Child VCam Instance ID.
• childPath (string, optional): Child VCam hierarchy path.
• childEntityId (string, optional): Child VCam entity ID (Unity 6000.4+, preferred).
• hold (float): Duration to hold on this child in seconds (default 2).
• blendStyle (string): Blend style to use entering this child (default EaseInOut).
• blendTime (float): Blend duration in seconds (default 2).

Provide at least one identifier for each of sequencer and child camera.

cinemachine_create_freelook

Create a FreeLook camera. CM2 uses CinemachineFreeLook; CM3 builds CinemachineCamera + OrbitalFollow(ThreeRing) + RotationComposer. Parameters:

• name (string): Name of the new GameObject.
• followName (string, optional): GameObject to follow.
• lookAtName (string, optional): GameObject to look at.

cinemachine_configure_camera_manager

Configure ClearShot/StateDriven/Sequencer camera manager properties in one call. Applies only the properties whose matching component exists on the target. Parameters:

• cameraName (string, optional): Camera manager name. Provide one of name/instanceId/path.
• cameraInstanceId (int, optional): Camera manager Instance ID.
• cameraPath (string, optional): Camera manager hierarchy path.
• activateAfter (float, optional): ClearShot — delay before activation.
• minDuration (float, optional): ClearShot — minimum duration on a shot.
• randomizeChoice (bool, optional): ClearShot — randomize shot selection.
• animatorName (string, optional): StateDriven — name of the GameObject carrying the Animator.
• layerIndex (int, optional): StateDriven — Animator layer index.
• defaultBlendStyle (string, optional): Default blend style (shared by ClearShot/StateDriven).
• defaultBlendTime (float, optional): Default blend duration in seconds.
• loop (bool, optional): Sequencer — loop playback.

cinemachine_configure_body

Configure the Body stage component (Follow, OrbitalFollow, ThirdPersonFollow, PositionComposer, FramingTransposer, etc.) in one call. Only fields matching the active component are applied. Parameters:

• vcamName (string, optional): VCam name. Provide one of name/instanceId/path.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.

Follow / Transposer:

• offsetX / offsetY / offsetZ (float, optional): Follow offset vector.
• bindingMode (string, optional): Binding/target attachment mode (e.g. LockToTarget, WorldSpace).
• dampingX / dampingY / dampingZ (float, optional): Positional damping.

OrbitalFollow / OrbitalTransposer:

• orbitStyle (string, optional): Sphere or ThreeRing.
• radius (float, optional): Sphere orbit radius.
• topHeight / topRadius (float, optional): Top ring parameters.
• midHeight / midRadius (float, optional): Middle ring parameters.
• bottomHeight / bottomRadius (float, optional): Bottom ring parameters.

ThirdPersonFollow:

• shoulderX / shoulderY / shoulderZ (float, optional): Shoulder offset.
• verticalArmLength (float, optional): Vertical arm length.
• cameraSide (float, optional): 0 = left, 1 = right.

PositionComposer / FramingTransposer:

• cameraDistance (float, optional): Distance between camera and target.
• screenX / screenY (float, optional): On-screen target position (0–1).
• deadZoneWidth / deadZoneHeight (float, optional): Dead zone size (0–1).

cinemachine_configure_aim

Configure the Aim stage component (RotationComposer, Composer, PanTilt, POV, etc.) in one call. Only fields matching the active component are applied. Parameters:

• vcamName (string, optional): VCam name. Provide one of name/instanceId/path.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.

Composer / RotationComposer:

• screenX / screenY (float, optional): Target on-screen position.
• deadZoneWidth / deadZoneHeight (float, optional): Dead zone size.
• softZoneWidth / softZoneHeight (float, optional): Soft zone size.
• horizontalDamping / verticalDamping (float, optional): Composition damping.
• lookaheadTime / lookaheadSmoothing (float, optional): Target lookahead tuning.
• centerOnActivate (bool, optional): Re-center on activation.

PanTilt / POV:

• referenceFrame (string, optional): Reference frame for pan/tilt axes.
• panValue / tiltValue (float, optional): Explicit pan/tilt values.

Target offset:

• targetOffsetX / targetOffsetY / targetOffsetZ (float, optional): Offset from target pivot.

cinemachine_configure_extension

Configure a Cinemachine extension (CinemachineConfiner, CinemachineDeoccluder/Collider, CinemachineFollowZoom, CinemachineGroupFraming, etc.). If extensionName is omitted, the first extension on the VCam is used. Parameters:

• vcamName (string, optional): VCam name. Provide one of name/instanceId/path.
• instanceId (int, optional): VCam Instance ID.
• path (string, optional): VCam hierarchy path.
• extensionName (string, optional): Extension type name (e.g. CinemachineConfiner).

Confiner:

• boundingShapeName (string, optional): Name of the bounding shape GameObject.
• damping (float, optional): Damping applied when confining.
• slowingDistance (float, optional): Slow-down distance inside the bounding shape.

Deoccluder / Collider:

• cameraRadius (float, optional): Camera collision radius.
• strategy (string, optional): Deocclusion strategy name.
• maximumEffort (int, optional): Maximum raycast iterations.
• smoothingTime (float, optional): Smoothing time for occlusion changes.

FollowZoom:

• width (float, optional): Target width in world units.
• fovMin / fovMax (float, optional): FOV clamp range.

GroupFraming:

• framingMode (string, optional): Framing mode name.
• framingSize (float, optional): Desired framing size.
• sizeAdjustment (string, optional): Size adjustment strategy name.

cinemachine_configure_impulse_source

Configure CinemachineImpulseSource definition (shape, duration, gains). If no source is specified, the first CinemachineImpulseSource in the scene is used. Parameters:

• sourceName (string, optional): Source name. Provide one of name/instanceId/path; omit all to pick the first source.
• sourceInstanceId (int, optional): Source Instance ID.
• sourcePath (string, optional): Source hierarchy path.
• amplitudeGain (float, optional): Amplitude gain multiplier.
• frequencyGain (float, optional): Frequency gain multiplier.
• impactRadius (float, optional): Impact radius in world units.
• duration (float, optional): Signal duration in seconds.
• dissipationRate (float, optional): Dissipation rate over distance.

Minimal Example

import unity_skills

# Create a vcam that follows and looks at the player
unity_skills.call_skill("cinemachine_create_vcam", name="PlayerCam")
unity_skills.call_skill("cinemachine_set_targets", vcamName="PlayerCam", followName="Player", lookAtName="Player")

Exact Signatures

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

Unity Cleaner Skills

Safety: cleaner_delete_assets uses a two-step confirmToken handshake. Call without confirmToken to preview; call again with the returned token (5-minute TTL) to actually delete. There is no dryRun parameter.

Guardrails

Operating Mode (v1.9 three-tier):

• Approval (default): all analyze/query skills (cleaner_find_unused_assets, cleaner_find_duplicates, cleaner_find_missing_references, cleaner_get_asset_usage, cleaner_find_empty_folders, cleaner_find_large_assets, cleaner_get_dependency_tree) are SemiAuto — run directly.
• Auto / Bypass: SemiAuto and FullAuto run directly.
• Auto-forbidden in this module: cleaner_delete_assets, cleaner_delete_empty_folders (both carry SkillOperation.Delete). In Approval/Auto these return MODE_FORBIDDEN — they are reachable only under Bypass mode or via a user-managed Allowlist entry; the grant flow does not unlock them.
• cleaner_fix_missing_scripts is an Execute | Modify operation (it replaces missing component references with null in place, no asset deletion), so it does not trigger the NeverInSemi gate. In Auto / Bypass it runs directly; in Approval it still requires the standard grant handshake before execution.
• cleaner_delete_assets additionally uses a two-step confirmToken handshake even when the mode gate allows it — preview first (no token), then confirm with the returned token (5-minute TTL).

DO NOT (common hallucinations):

• cleaner_delete / cleaner_remove do not exist → cleaner skills only find/report; use asset_delete to actually remove
• cleaner_fix does not exist → use cleaner_fix_missing_scripts specifically for missing script references
• cleaner_scan / cleaner_find_unused do not exist → use specific skills: cleaner_find_unused_assets, cleaner_find_duplicates, cleaner_find_missing_references, cleaner_find_empty_folders, cleaner_find_large_assets

Routing:

• To delete found assets → use asset module's asset_delete / asset_delete_batch
• For project validation → use validation module

Skills Overview

Skills

cleaner_find_unused_assets

Find potentially unused assets of a specific type.

Returns: {success, assetType, potentiallyUnusedCount, assets: [{path, name, type, sizeBytes}]}

# Find unused materials
result = call_skill("cleaner_find_unused_assets", assetType="Material")

# Find unused textures in a specific folder
result = call_skill("cleaner_find_unused_assets", 
    assetType="Texture2D", searchPath="Assets/Textures")

cleaner_find_duplicates

Find duplicate files by MD5 hash.

Returns: {success, duplicateGroupCount, totalWastedBytes, totalWastedMB, groups: [{count, sizeBytes, wastedBytes, files}]}

# Find duplicate textures
result = call_skill("cleaner_find_duplicates", assetType="Texture2D")
print(f"Wasted space: {result['totalWastedMB']:.2f} MB")

cleaner_find_missing_references

Find components with missing scripts or null references.

Returns: {success, issueCount, missingScripts, missingReferences, issues: [{type, gameObject, path, ...}]}

# Scan for all missing references
result = call_skill("cleaner_find_missing_references")
print(f"Missing scripts: {result['missingScripts']}")
print(f"Missing references: {result['missingReferences']}")

cleaner_delete_assets

Delete specified assets with two-step confirmation.

⚠️ Safety First: Deletion requires TWO calls - first preview, then confirm.

Step 1 - Preview (no confirmToken):

Returns: {action: "preview", confirmToken, assetsToDelete, message}

Step 2 - Confirm (with confirmToken):

Returns: {action: "deleted", deletedCount, results}

# Step 1: Preview what will be deleted
preview = call_skill("cleaner_delete_assets", 
    paths=["Assets/Unused/mat1.mat", "Assets/Unused/mat2.mat"])
print(preview['message'])  # Shows: "⚠️ PREVIEW ONLY - 2 assets will be deleted..."
print(preview['assetsToDelete'])  # Full list with sizes

# Step 2: Confirm deletion using token (expires in 5 minutes)
if input("Proceed? (y/n): ") == 'y':
    result = call_skill("cleaner_delete_assets", 
        confirmToken=preview['confirmToken'])
    print(result['message'])  # "Successfully deleted 2 assets"

cleaner_get_asset_usage

Find what objects reference a specific asset.

Returns: {success, asset, usedByCount, usedBy: [{path, name, type}]}

# Check what uses a texture
result = call_skill("cleaner_get_asset_usage",
    assetPath="Assets/Textures/player.png")

cleaner_find_empty_folders

Find empty folders in the project.

Returns: { success, count, folders }

# Find empty folders
result = call_skill("cleaner_find_empty_folders")
print(f"Found {result['count']} empty folders")

cleaner_find_large_assets

Find largest assets by file size.

Returns: { success, count, assets: [{ path, sizeBytes, sizeMB }] }

# Find top 10 largest assets over 1 MB
result = call_skill("cleaner_find_large_assets", limit=10, minSizeBytes=1048576)
for a in result['assets']:
    print(f"{a['sizeMB']:.2f} MB - {a['path']}")

cleaner_delete_empty_folders

Delete all empty folders.

Returns: { success, deleted, total }

# Delete all empty folders
result = call_skill("cleaner_delete_empty_folders")
print(f"Deleted {result['deleted']} of {result['total']} empty folders")

cleaner_fix_missing_scripts

Remove missing script components from GameObjects.

Returns: { success, removedComponents }

# Remove all missing script components
result = call_skill("cleaner_fix_missing_scripts")
print(f"Removed {result['removedComponents']} missing script components")

cleaner_get_dependency_tree

Get dependency tree for an asset.

Returns: { success, assetPath, dependencyCount, dependencies: [{ path, type }] }

# Get full dependency tree for a prefab
result = call_skill("cleaner_get_dependency_tree",
    assetPath="Assets/Prefabs/Player.prefab")
print(f"Dependencies: {result['dependencyCount']}")

Example Workflow: Clean Project

import unity_skills

# 1. Find all missing references and fix them
missing = unity_skills.call_skill("cleaner_find_missing_references")
for issue in missing['issues']:
    if issue['type'] == 'MissingScript':
        print(f"⚠️ Missing script on: {issue['path']}")

# 2. Find duplicate textures
dupes = unity_skills.call_skill("cleaner_find_duplicates", assetType="Texture2D")
if dupes['totalWastedMB'] > 10:
    print(f"🗑️ {dupes['totalWastedMB']:.1f} MB wasted on duplicates")

# 3. Find unused materials
unused = unity_skills.call_skill("cleaner_find_unused_assets", assetType="Material")
print(f"📦 {unused['potentiallyUnusedCount']} potentially unused materials")

# 4. Preview cleanup
paths_to_delete = [a['path'] for a in unused['assets'][:5]]
preview = unity_skills.call_skill("cleaner_delete_assets", 
    paths=paths_to_delete)
print(f"Would free: {preview['totalMB']:.2f} MB")
# To actually delete, call again with preview['confirmToken'] within 5 minutes.

Exact Signatures

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

Unity Component Skills

BATCH-FIRST: Use *_batch skills when operating on 2+ objects to reduce API calls from N to 1.

Operating Mode

• Approval：本模块 Mixed —— component_list / component_get_properties 标 SkillMode.SemiAuto，可直接执行；写类 skill (component_add / component_set_property / component_set_enabled / component_copy 等) 标 SkillMode.FullAuto，需 grant 单次执行返结果。
• Auto / Bypass：FullAuto 直接执行。
• 含 NeverInSemi 高危 skill：component_remove / component_remove_batch（Operation.Delete）。这些在 Approval/Auto 下返 MODE_FORBIDDEN，仅 Bypass 或 Allowlist 命中可调。

DO NOT (common hallucinations):

• component_create / component_get do not exist → use component_add (add) and component_get_properties (read)
• component_find does not exist → use component_list to list components on an object
• componentType is case-sensitive — Rigidbody not rigidbody, BoxCollider not boxcollider
• Custom scripts need exact class name; if namespaced, use Namespace.ClassName

Routing:

• To create a C# component script → use script module's script_create first, then component_add
• To set multiple properties at once → use component_set_property_batch
• To enable/disable a component → component_set_enabled (not component_set_property)

Object Targeting: All single-object skills accept name (string), instanceId (int, preferred), and path (string, hierarchy path). Provide at least one.

Skills Overview

Other Skills (no batch):

• component_list - List all components on an object
• component_get_properties - Get component property values
• component_set_enabled - Enable/disable a component (Behaviour, Renderer, Collider)
• component_copy - Copy a component from one object to another
• component_get_serialized_properties - List Inspector SerializedProperty paths
• component_copy_exact - Copy a component and verify serialized fields match

Single-Object Skills

component_add

Add a component to a GameObject.

*At least one identifier required

Returns: {success, gameObject, instanceId, component, fullTypeName} (returns {warning, gameObject, instanceId} instead if a single-instance component already exists)

component_remove

Remove a component from a GameObject.

Returns: {success, gameObject, removed} (removed is the requested componentType string)

component_list

List all components on a GameObject.

Returns: {gameObject, instanceId, path, componentCount, components: [{type, fullType, enabled, keyProperties?}]} (keyProperties only present when includeProperties=true)

component_set_property

Set a component property value.

Provide one of: value (basic types), referencePath/referenceName (scene objects), or assetPath (project assets).

value type examples:

# float / int / bool / string
call_skill("component_set_property", name="Obj", componentType="Rigidbody", propertyName="mass", value=2.5)
call_skill("component_set_property", name="Obj", componentType="Rigidbody", propertyName="useGravity", value=False)

# Vector3 (JSON object with x, y, z)
call_skill("component_set_property", name="Obj", componentType="Transform", propertyName="localPosition",
           value={"x": 1, "y": 2, "z": 3})

# Color (JSON object with r, g, b, a — values 0-1)
call_skill("component_set_property", name="Obj", componentType="Light", propertyName="color",
           value={"r": 1, "g": 0.5, "b": 0, "a": 1})

# Enum (use string name)
call_skill("component_set_property", name="Obj", componentType="Rigidbody", propertyName="interpolation",
           value="Interpolate")

Returns: {success, gameObject, component, property, valueSet, valueType} (valueSet is the string form of the actual value applied; valueType is the resolved target type name)

component_get_properties

Get all properties of a component.

Returns: {gameObject, component, fullTypeName, properties: [{name, type, fullType, value, canWrite}], fields: [{name, type, fullType, value, isSerializable}]}

component_get_serialized_properties

List Inspector serialized properties on a component via SerializedObject.

Returns: {success, gameObject, component, fullTypeName, properties}

component_set_serialized_property

Set an Inspector serialized property by propertyPath.

Provide value for scalar properties, or a scene/project reference for ObjectReference fields.

Returns: {success, gameObject, component, propertyPath, valueSet}

Batch Skills

component_add_batch

Add components to multiple objects.

Returns: {success, totalItems, successCount, failCount, results: [{success, gameObject, componentType, added}]}

unity_skills.call_skill("component_add_batch", items=[
    {"name": "Enemy1", "componentType": "Rigidbody"},
    {"name": "Enemy2", "componentType": "Rigidbody"},
    {"name": "Enemy3", "componentType": "Rigidbody"}
])

component_remove_batch

Remove components from multiple objects.

Returns: {success, totalItems, successCount, failCount, results: [{success, gameObject, componentType, removed}]}

unity_skills.call_skill("component_remove_batch", items=[
    {"instanceId": 12345, "componentType": "BoxCollider"},
    {"instanceId": 12346, "componentType": "BoxCollider"}
])

component_set_property_batch

Set properties on multiple objects.

Returns: {success, totalItems, successCount, failCount, results: [{success, gameObject, componentType, property, oldValue, newValue}]}

unity_skills.call_skill("component_set_property_batch", items=[
    {"name": "Enemy1", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0},
    {"name": "Enemy2", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0}
])

component_set_serialized_property_batch

Set Inspector serialized properties on multiple components.

Item properties: name, instanceId, path, componentType, propertyPath, value, referenceName, referenceInstanceId, referencePath, assetPath, objectType

Returns: {success, totalItems, successCount, failCount, results}

Common Component Types

Physics

Rendering

Audio

UI

Example: Efficient Physics Setup

import unity_skills

# BAD: 6 API calls
unity_skills.call_skill("component_add", name="Box1", componentType="Rigidbody")
unity_skills.call_skill("component_add", name="Box2", componentType="Rigidbody")
unity_skills.call_skill("component_add", name="Box3", componentType="Rigidbody")
unity_skills.call_skill("component_set_property", name="Box1", componentType="Rigidbody", propertyName="mass", value=2.0)
unity_skills.call_skill("component_set_property", name="Box2", componentType="Rigidbody", propertyName="mass", value=2.0)
unity_skills.call_skill("component_set_property", name="Box3", componentType="Rigidbody", propertyName="mass", value=2.0)

# GOOD: 2 API calls
unity_skills.call_skill("component_add_batch", items=[
    {"name": "Box1", "componentType": "Rigidbody"},
    {"name": "Box2", "componentType": "Rigidbody"},
    {"name": "Box3", "componentType": "Rigidbody"}
])
unity_skills.call_skill("component_set_property_batch", items=[
    {"name": "Box1", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0},
    {"name": "Box2", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0},
    {"name": "Box3", "componentType": "Rigidbody", "propertyName": "mass", "value": 2.0}
])

Best Practices

1. Add colliders before Rigidbody for physics
2. Use component_list to verify additions
3. Check property names with component_get_properties first
4. Some properties are read-only (will fail to set)
5. Use full type names for custom scripts (e.g., "MyNamespace.MyScript")

Additional Skills

component_copy

Copy a component from one GameObject to another.

*At least one source identifier and one target identifier required

Returns: { success, source, target, componentType }

component_copy_exact

Copy a component from one GameObject to another and verify serialized Inspector fields match.

Returns: { success, source, target, componentType, verified, mismatchCount, mismatches? }

component_set_enabled

Enable or disable a component (Behaviour, Renderer, Collider, etc.).

*At least one identifier required

Returns: { success, gameObject, componentType, enabled }

Exact Signatures

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

Unity Console Skills

Work with the Unity console - capture logs, write messages, and debug your project.

Operating Mode

• Approval: 只读 skill（console_get_logs / console_get_stats，标 SkillMode.SemiAuto）直接执行；其余 skill（console_start_capture / console_stop_capture / console_clear / console_log / console_export / console_set_pause_on_error / console_set_collapse / console_set_clear_on_play，默认 SkillMode.FullAuto）需用户 grant，grant 后一步执行返结果。
• Auto / Bypass: 直接执行。
• 本模块不含 Delete / PlayMode / Reload / RiskLevel=high 类 skill —— 没有 IsForbiddenInSemi 拦截，不需要 Bypass 才能跑的高危操作。

DO NOT (common hallucinations):

• console_filter does not exist → use console_get_logs with filter parameter
• console_read does not exist → use console_get_logs
• console_write does not exist → use console_log
• Do not confuse with debug_get_logs — console_get_logs reads captured buffer, debug_get_logs reads all console entries

Routing:

• For compilation errors specifically → use debug module's debug_check_compilation
• For error stack traces → use debug module's debug_get_stack_trace
• For console settings (collapse, clear-on-play) → console_set_collapse / console_set_clear_on_play (this module)

Skills Overview

Skills

console_start_capture

Start capturing Unity console logs.

No parameters.

console_stop_capture

Stop capturing logs.

No parameters.

console_get_logs

Get Unity Console logs (reads existing console history directly; if console_start_capture is active, returns captured buffer with timestamps instead).

Returns (two shapes depending on mode):

• Capture mode (console_start_capture active): {count, logs: [{type, message, time}], source: "capture"} — time formatted HH:mm:ss.fff
• Direct mode (default, reads Unity Console history): {count, logs: [{type, message, file, line}], source: "console"} — type is Error / Warning / Log, file / line from Unity's LogEntry

console_clear

Clear the Unity console.

No parameters.

console_log

Write a custom log message.

console_set_pause_on_error

Enable or disable Error Pause in Play mode.

Returns: { success, enabled }

console_export

Export console logs to a file. Uses captured buffer when console_start_capture is active; otherwise reads directly from Unity Console history (no setup needed).

Returns: { success, path, count, source }

console_get_stats

Get log statistics (count by type). Uses captured buffer when console_start_capture is active; otherwise reads directly from Unity Console history.

No parameters.

Returns (two shapes depending on mode):

• Capture mode (buffer present, i.e. console_start_capture was called or buffer is non-empty): {success, total, source: "capture", logs, warnings, errors, exceptions, asserts}
• Direct mode (no capture buffer, reads Unity Console history): {success, total, source: "console", logs, warnings, errors} — exceptions / asserts are not reported in direct mode (folded into errors)

console_set_collapse

Set console log collapse mode.

Returns: { success, setting, enabled }

console_set_clear_on_play

Set clear on play mode.

Returns: { success, setting, enabled }

Example Usage

import unity_skills

# Start capturing logs before play mode
unity_skills.call_skill("console_start_capture")

# Enter play mode
unity_skills.call_skill("editor_play")
# ... gameplay generates logs ...
unity_skills.call_skill("editor_stop")

# Get all captured logs
logs = unity_skills.call_skill("console_get_logs")
for log in logs['logs']:
    print(f"[{log['type']}] {log['message']}")

# Get only errors
errors = unity_skills.call_skill("console_get_logs", type="Error")
if errors['count'] > 0:
    print(f"Found {errors['count']} errors!")

# Write custom log
unity_skills.call_skill("console_log",
    message="AI Agent: Task completed",
    type="Log"
)

# Write warning
unity_skills.call_skill("console_log",
    message="AI Agent: Performance issue detected",
    type="Warning"
)

# Clear and stop
unity_skills.call_skill("console_clear")
unity_skills.call_skill("console_stop_capture")

Best Practices

1. Start capture before play mode for runtime logs
2. Filter by Error to quickly find problems
3. Use custom logs to mark AI agent actions
4. Clear console before starting new capture session
5. Stop capture when done to free resources

Exact Signatures

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

Debug Skills

Debug utilities for error checking and diagnostics.

Operating Mode

• Approval: 只读类 skill（unity_diagnose / debug_get_errors / debug_get_logs / debug_check_compilation / debug_get_system_info / debug_get_stack_trace / debug_get_assembly_info / debug_get_defines / debug_get_memory_info，全部标 SkillMode.SemiAuto）直接执行；debug_force_recompile / debug_set_defines 默认 SkillMode.FullAuto，需用户 grant，grant 后一步执行返结果。
• Auto / Bypass: 直接执行。
• 本模块含 Reload 类高危 skill：debug_force_recompile（标 MayTriggerReload=true）必然触发 Domain Reload；debug_set_defines 修改 PlayerSettings 的 scripting defines 也会触发重编译 —— 这些 skill 在 Approval / Auto 下会被 IsForbiddenInSemi 自动拦截，仅 Bypass 或 Allowlist 命中可执行，调用后服务端会短暂不可用。

DO NOT (common hallucinations):

• debug_compile / debug_recompile do not exist → use debug_force_recompile
• debug_run does not exist → use editor_play (editor module)
• debug_clear does not exist → use console_clear (console module)
• debug_set_defines triggers Domain Reload — server will be temporarily unavailable

Routing:

• For runtime console logs → use console module's console_get_logs / console_start_capture
• For play mode control → use editor module
• For script compile feedback → use script module's script_get_compile_feedback

Skills

unity_diagnose

Aggregated Editor health snapshot — call this FIRST when triaging problems. Combines console errors, compile state, recent workflow tasks, recent jobs, and server stats in a single response. Avoids chaining 4-5 individual skills.

Parameters:

• errorLimit (int, optional, default 20, range 1-200): Max console entries to return.
• includeWarnings (bool, optional, default true): Include warnings (false = errors only).
• includeRecentJobs (bool, optional, default true): Include the 10 most recent async jobs.

Returns: { summary: { healthy, consoleErrorCount, consoleWarningCount, isCompiling, serverRunning, hint }, compile, console, workflow, server, recentJobs }

debug_get_logs

Get console logs filtered by type and content. Parameters:

• type (string, optional): Filter by type (Error/Warning/Log). Default: Error.
• filter (string, optional): Filter by content.
• limit (int, optional): Max entries. Default: 50.

debug_get_errors

Get only active errors and exceptions from console. Parameters:

• limit (int, optional): Max entries. Default: 50.

debug_check_compilation

Check if there are any compilation errors. Parameters: None.

debug_force_recompile

Force Unity to recompile all scripts. Parameters: None.

debug_get_system_info

Get system and Unity environment information. Parameters: None.

debug_get_stack_trace

Get stack trace for a log entry by index.

Returns: { index, message, stackTrace }

debug_get_assembly_info

Get project assembly information.

Parameters: None.

Returns: { success, count, assemblies }

debug_get_defines

Get scripting define symbols for current platform.

Parameters: None.

Returns: { success, buildTargetGroup, defines }

debug_set_defines

Set scripting define symbols for current platform.

Returns: { success, buildTargetGroup, defines, serverAvailability }

debug_get_memory_info

Get memory usage information.

Parameters: None.

Returns: { success, totalAllocatedMB, totalReservedMB, totalUnusedReservedMB, monoUsedSizeMB, monoHeapSizeMB }

Exact Signatures

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

Decal Skills

URP Decal Projector creation and configuration (URP only; HDRP decal APIs are not covered here).

Operating Mode

• Query skills (decal_get_info, decal_find_all) are SkillMode.SemiAuto — they run in all three modes without grant.
• Mutating skills (decal_create, decal_set_properties, decal_set_properties_batch, decal_ensure_renderer_feature) are SkillMode.FullAuto — under Approval they need user grant (grant triggers one server-side execute returning the result); under Auto / Bypass they execute directly.
• decal_delete carries SkillOperation.Delete and is auto-forbidden in Approval / Auto modes (NeverInSemi). Only Bypass or the user-managed Allowlist can run it.

URP Package Stub

This module is compiled against com.unity.render-pipelines.universal (URP). When URP is not installed, every skill returns a stub { error: "Universal Render Pipeline package … is not installed." } (RenderPipelineSkillsCommon.NoURP()). The stub is a diagnostic payload, not a permission denial — it does not require grant and is not treated as NeverInSemi.

Guardrails

Routing:

• For renderer feature management in general: urp
• For DecalProjector scene operations: this module

Runtime-first rules:

• Call decal_ensure_renderer_feature before assuming the current URP renderer is decal-ready
• Use decal_get_info / decal_find_all to discover real projector state before editing
• decal_set_properties_batch expects items to be a JSON array string
• This module targets the URP Decal workflow first; do not assume HDRP decal APIs are covered here

Skills

decal_create

Create a Decal Projector.

decal_get_info

Inspect a Decal Projector.

decal_set_properties

Modify Decal Projector properties.

decal_find_all

List Decal Projectors in the scene.

decal_delete

Delete a Decal Projector GameObject.

decal_set_properties_batch

Batch-edit Decal Projectors.

decal_ensure_renderer_feature

Ensure the target URP renderer has a DecalRendererFeature.

Exact Signatures

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

DOTween Skills

DOTween Free/Pro support for project diagnostics, settings, module/API discovery, and runtime script generation. DOTween Pro-only DOTweenAnimation editor-time configuration remains available through dotween_pro_* skills.

Guardrails

Operating Mode (v1.9 three-tier):

• Approval (default): query/diagnostic skills (dotween_get_status, dotween_settings_get, dotween_settings_find, dotween_settings_validate, dotween_list_modules, dotween_list_shortcuts, dotween_pro_get_animation, dotween_pro_list_animations) run directly. Mutators (settings configure, script generators, all other dotween_pro_*) are FullAuto — on MODE_RESTRICTED, run the grant protocol.
• Auto / Bypass: SemiAuto and FullAuto run directly.
• Auto-forbidden in this module: dotween_generate_tween_script, dotween_generate_sequence_script, dotween_generate_lifetime_script (all carry MayTriggerReload = true, RiskLevel = "high" because writing a new .cs triggers script compilation + Domain Reload). Reachable only under Bypass mode or via a user-managed Allowlist entry; the grant flow returns MODE_FORBIDDEN.
• When DOTween Free/Pro is missing, the DOTweenPresenceDetector does not add the DOTWEEN / DOTWEEN_PRO defines, so most skills return a "not installed" diagnostic instead of executing. The dotween_pro_* family additionally requires Pro because DG.Tweening.DOTweenAnimation is Pro-only.

Prerequisites:

• DOTween Free or Pro must be installed. DOTweenPresenceDetector adds DOTWEEN / DOTWEEN_PRO defines automatically after install.
• Free skills work with DOTween Free and Pro: status, settings read/find/validate/configure, module/shortcut listing, runtime script generation.
• dotween_pro_* skills require DOTween Pro because DG.Tweening.DOTweenAnimation is Pro-only.

Do not confuse Free with Pro:

• Free skills do not create or emulate DOTweenAnimation components.
• Runtime tween generation creates .cs scripts only; it does not auto-attach scripts to scene objects because Unity may need a Domain Reload first.
• For source-level runtime API design rules, load dotween-design.

Free Skills

Diagnostics and settings

• dotween_get_status — report DOTween/Pro install status, DOTweenSettings.asset path, and visible module count.
• dotween_settings_find — list project assets named DOTweenSettings.
• dotween_settings_get — read common DOTweenSettings.asset fields.
• dotween_settings_validate — report missing settings, duplicate settings, invalid capacities, and notable SafeMode warnings.
• dotween_settings_configure — edit Resources/DOTweenSettings.asset; parameters: defaultEaseType?, defaultAutoKill?, defaultLoopType?, safeMode?, logBehaviour?, tweenersCapacity?, sequencesCapacity?.

API discovery

• dotween_list_modules — list loaded DG.Tweening.DOTweenModule*, ShortcutExtensions, TweenExtensions, and TweenSettingsExtensions types. Optional: includeMethods=false, methodLimit=20.
• dotween_list_shortcuts — list public extension methods. Optional filters: targetType, methodPrefix, limit=100.

Runtime script generation

All generation skills require className, default folder=Assets/Scripts/DOTween, optional namespaceName, and never overwrite existing files.

• dotween_generate_tween_script — create one runtime tween MonoBehaviour.
• dotween_generate_sequence_script — create one runtime Sequence MonoBehaviour; optional stepsJson array of {op:"Append|Join|AppendInterval", tweenKind, duration}.
• dotween_generate_lifetime_script — create a lifecycle-safe wrapper with SetLink(gameObject) by default and KillTween() on disable/destroy.

Common parameters: targetKind=Transform, tweenKind=DOMove, duration=1, ease=OutQuad, loops=1, autoPlay=true, useSetLink=true.

Supported v1 targetKind / tweenKind pairs:

• Transform: DOMove, DOLocalMove, DORotate, DOLocalRotate, DOScale, DOPunchPosition, DOShakePosition
• RectTransform: DOAnchorPos, DOSizeDelta
• CanvasGroup: DOFade
• Graphic / Image: DOColor, DOFade
• Generic: DOTween.To

Example:

dotween_generate_tween_script className=HeroPanelIntro targetKind=RectTransform tweenKind=DOAnchorPos duration=0.35 ease=OutBack

Sequence example:

dotween_generate_sequence_script className=ButtonPop targetKind=Transform stepsJson='[
  {"op":"Append","tweenKind":"DOScale","duration":0.12},
  {"op":"AppendInterval","duration":0.05},
  {"op":"Join","tweenKind":"DOPunchPosition","duration":0.25}
]'

Pro Skills

dotween_pro_add_animation

Add one DOTweenAnimation to a GameObject and configure all core fields. Parameters: target / animationType / endValueV3? / endValueFloat? / endValueColor? / endValueV2? / endValueString? / endValueRect? / duration=1 / ease="OutQuad" / loops=1 / loopType="Yoyo" / delay=0 / isRelative=false / isFrom=false / autoPlay=true / autoKill=true / id?

dotween_pro_batch_add_animation

Add the same animation to multiple GameObjects. Parameters: targetsJson (JSON string array) + all params of dotween_pro_add_animation.

dotween_pro_stagger_animations

Batch-add with incrementing delay — UI cascade entrance pattern. Parameters: targetsJson / animationType / endValueV3? / endValueFloat? / endValueColor? / endValueV2? / duration=0.5 / ease="OutBack" / loops=1 / loopType="Yoyo" / baseDelay=0 / staggerDelay=0.1 / isFrom=true / autoPlay=true / autoKill=true

dotween_pro_set_duration

Change duration on an existing DOTweenAnimation. Parameters: target, animationIndex=0, duration.

dotween_pro_set_ease

Change ease on an existing DOTweenAnimation. Parameters: target, animationIndex=0, ease="OutQuad", easeCurveJson?.

dotween_pro_set_loops

Change loops count and optional loopType. Parameters: target, animationIndex=0, loops, loopType?.

dotween_pro_set_animation_field

Generic setter for DOTweenAnimation fields except duration/ease/easeType/easeCurve/loops/loopType; use dedicated skills for those.

dotween_pro_get_animation

Read all serialized fields of one DOTweenAnimation. Parameters: target, animationIndex=0.

dotween_pro_list_animations

List DOTweenAnimation components on a target or across the scene. Parameters: target?, recursive=false.

dotween_pro_copy_animation

Copy all fields from sourceTarget[sourceIndex] to a new DOTweenAnimation on destTarget.

dotween_pro_remove_animation

Remove one DOTweenAnimation component by index.

animationType → endValue mapping

Exact Signatures

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

Unity Editor Skills

Observe and control the Unity Editor without parsing scene YAML.

Operating Mode

• Approval：本模块 Mixed —— editor_get_changes / editor_get_selection / editor_get_context / editor_get_state / editor_get_tags / editor_get_layers 标 SkillMode.SemiAuto，可直接执行；其余 editor_select / editor_undo / editor_redo / editor_execute_menu 默认 FullAuto，Approval 模式下需 grant。
• Auto / Bypass：FullAuto 直接执行。
• 含 NeverInSemi 高危 skill：editor_play / editor_play_capture / editor_stop / editor_pause（标 MayEnterPlayMode = true）。这些在 Approval/Auto 下返 MODE_FORBIDDEN，仅 Bypass 或 Allowlist 命中可调。

DO NOT (common hallucinations):

• editor_run does not exist → use editor_play to enter play mode
• editor_compile / editor_recompile do not exist → use debug_force_recompile
• editor_save does not exist → use editor_execute_menu with menuPath "File/Save"
• editor_execute_menu requires exact menu path — typos cause silent failure

Routing:

• For compilation check → use debug module's debug_check_compilation
• For console errors → use debug module's debug_get_errors
• For scene save → scene_save (scene module) or editor_execute_menu menuPath="File/Save"
• When file watching reports changes, or the AI resumes after the user edited Unity → call editor_get_changes before reading .unity YAML
• If editor_get_changes.dropped=true → its 500-entry retention window was exceeded; rebuild context with scene_context / scene_diff

Skills Overview

Skills

editor_play

Enter play mode. Warning: any unsaved scene changes made during Play mode will be lost when exiting.

Returns: {success, mode, jobId} — mode="playing", jobId returned from AsyncJobService so callers can poll entering_play_mode completion.

editor_play_capture

Enter Play Mode, observe errors for durationSeconds (default 10, range 1–300), optionally capture the Game View, then exit. Returns a Job whose result includes healthy, error aggregates, stoppedEarly, and screenshotPath.

editor_stop

Exit play mode.

Returns: {success, mode} — mode="stopped".

editor_pause

Toggle pause state.

Returns: {success, paused} — paused is the new boolean state.

editor_select

Select a GameObject.

*One identifier required

editor_get_selection

Get currently selected objects.

Returns: {count, objects: [{name, instanceId}]}

editor_get_context

Get full editor context including selection, assets, and scene info.

Returns:

• selectedGameObjects: Objects in Hierarchy (instanceId, path, tag, layer)
• selectedAssets: Assets in Project window (GUID, path, type, isFolder)
• activeScene: Current scene info (name, path, isDirty)
• focusedWindow: Name of focused editor window
• isPlaying, isCompiling: Editor state

editor_get_changes

Read the persistent change journal at Library/UnitySkills/editor_changes.jsonl. It captures scene object/component/property summaries plus imported, deleted, and moved asset paths across Domain Reloads. It never parses or returns raw .unity YAML.

Returns: {hasChanges, cursor, oldestSeq, dropped, truncated, changes}. Save cursor for the next call. dropped=true means older changes fell outside the 500-entry journal, so rebuild full scene context.

editor_undo

Undo the last action.

editor_redo

Redo the last undone action.

editor_get_state

Get current editor state.

Returns: {isPlaying, isPaused, isCompiling, timeSinceStartup, unityVersion, platform}

editor_execute_menu

Execute a menu command.

Common Menu Paths:

editor_get_tags

Get all available tags.

Returns: {tags: [string]}

editor_get_layers

Get all available layers.

Returns: {layers: [{index, name}]}

Pause On Error

Pause-on-error is provided by the console module, not the editor module.

Use console_set_pause_on_error from console/SKILL.md.

Example Usage

import unity_skills

# Check editor state before operations
state = unity_skills.call_skill("editor_get_state")
if state['isCompiling']:
    print("Wait for compilation to finish")

# On resume or after file-watch notification, inspect semantic changes first.
changes = unity_skills.call_skill("editor_get_changes", since=last_cursor)
last_cursor = changes["cursor"]

# Get full context (useful for understanding current state)
context = unity_skills.call_skill("editor_get_context", includeComponents=True)
for obj in context['selectedGameObjects']:
    print(f"Selected: {obj['name']} (ID: {obj['instanceId']})")

# Select and operate on object
unity_skills.call_skill("editor_select", name="Player")
selection = unity_skills.call_skill("editor_get_selection")

# Safe experimentation with undo
unity_skills.call_skill("gameobject_delete", name="TestObject")
unity_skills.call_skill("editor_undo")  # Restore if needed

# Execute menu command
unity_skills.call_skill("editor_execute_menu", menuPath="File/Save")

Best Practices

1. Check editor state before play mode operations
2. Don't modify scene during play mode (changes lost)
3. Use undo for safe experimentation
4. On resume, call editor_get_changes before reading scene files
5. Use editor_get_context to get instanceId for batch operations
6. Menu commands must match exact paths

Exact Signatures

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

Event Skills

Inspect and modify persistent listeners on UnityEvents (e.g. Button.onClick, Toggle.onValueChanged) — the same listeners you see in the Inspector's event drop slots.

Operating Mode

• Approval：查询类 skill（event_get_listeners / event_list_events / event_get_listener_count，源码标 SkillMode.SemiAuto）直接执行；其余变更/调用类（event_add_listener / event_set_listener / event_set_listener_state / event_invoke / event_add_listener_batch / event_copy_listeners，标 SkillMode.FullAuto）需用户 grant，grant 后服务端一步执行返结果。
• Auto / Bypass：未被禁列表拦截的 skill 直接执行。
• 本模块含 Delete 类 skill：event_remove_listener、event_clear_listeners 标记为 SkillOperation.Delete，被 IsForbiddenInSemi 静态拦截 —— 仅 Bypass 模式或加入 Allowlist 才能调用。
• event_invoke 只在 Play mode / runtime 下有效；编辑器空跑时仅触发 EditorAndRuntime 监听。event_add_listener 等写入的是 persistent listener（序列化到 prefab/scene），即可在编辑器时配置。

DO NOT (common hallucinations):

• event_create / event_trigger do not exist → UnityEvents are declared in component source code; this module only wires listeners
• event_subscribe does not exist → use event_add_listener
• event_remove does not exist → use event_remove_listener
• event_add_listener requires exact component type and method name on the target

Routing:

• For XR interaction events → use xr module's xr_add_interaction_event
• For C# event code → write via script module

Skills

event_get_listeners

Get persistent listeners of a UnityEvent. Parameters:

• name / instanceId / path: Target GameObject locator.
• componentName (string): Component name.
• eventName (string): Event field name (e.g. "onClick").

event_add_listener

Add a persistent listener to a UnityEvent (Editor time). Parameters:

• name / instanceId / path, componentName, eventName: Target event.
• targetObjectName, targetComponentName, methodName: Method to call.
• mode (string, optional): "RuntimeOnly", "EditorAndRuntime", "Off".
• argType (string, optional): "void", "int", "float", "string", "bool".
• floatArg, intArg, stringArg, boolArg: Argument value if needed.

event_remove_listener

Remove a persistent listener by index. Parameters:

• name / instanceId / path, componentName, eventName: Target event.
• index (int): Listener index.

event_invoke

Invoke a UnityEvent explicitly (Runtime only). Parameters:

• name / instanceId / path, componentName, eventName: Target event.

event_clear_listeners

Remove all persistent listeners from a UnityEvent.

Returns: { success, removed }

event_set_listener_state

Set a listener's call state (Off, RuntimeOnly, EditorAndRuntime).

Returns: { success, index, state }

event_set_listener

Replace a persistent listener at a specific index.

Returns: { success, index, target, targetType, method, state, argType }

event_list_events

List all UnityEvent fields on a component.

Returns: { success, component, count, events }

event_add_listener_batch

Add multiple listeners at once. items: JSON array of {targetObjectName, targetComponentName, methodName}.

Returns: { success, added, total }

event_copy_listeners

Copy listeners from one event to another.

Returns: { success, copied }

event_get_listener_count

Get the number of persistent listeners on a UnityEvent.

Returns: { success, count }

Exact Signatures

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

Unity GameObject Skills

BATCH-FIRST: Use *_batch skills when operating on 2+ objects to reduce API calls from N to 1.

Operating Mode

• Approval：本模块多为 SkillMode.FullAuto，调用需用户 grant；grant 后服务端一步执行并返结果。
• Auto / Bypass：直接执行。
• 含 NeverInSemi 高危 skill：gameobject_delete / gameobject_delete_batch（标记 Operation.Delete）。这些在 Approval/Auto 下返 MODE_FORBIDDEN，仅 Bypass 或用户 Allowlist 命中可调。

DO NOT (common hallucinations):

• gameobject_move / gameobject_rotate / gameobject_set_scale do not exist → use gameobject_set_transform (handles position, rotation, and scale together)
• gameobject_set_position does not exist → use gameobject_set_transform with posX/posY/posZ
• gameobject_add_component does not exist → use component_add (component module)
• gameobject_get_transform does not exist → use gameobject_get_info (returns position/rotation/scale)

Routing:

• To add/remove components → use component module
• To set material/color → use material module
• To search objects by name/tag/component → gameobject_find (this module) or scene_find_objects (scene module, SkillMode.SemiAuto)

Object Targeting: All single-object skills accept entityId (string, Unity 6000.4+ preferred — returned by all object skills), name (string), instanceId (int, Unity < 6000.4 preferred), and path (string, hierarchy path like "Parent/Child"). Provide at least one. Priority: entityId > instanceId > path > name. On Unity 6000.4+ use entityId — instanceId is reported as 0. When only name is shown in a parameter table, entityId, instanceId, and path are also accepted.

Skills Overview

Query Skills (no batch needed):

• gameobject_find - Find objects by name/tag/layer/component
• gameobject_get_info - Get detailed object information

Single-Object Skills

gameobject_create

Create a new GameObject (primitive or empty).

Returns: {success, name, entityId, instanceId, path, parent, position}

gameobject_delete

Delete a GameObject.

*At least one identifier required

gameobject_duplicate

Duplicate a GameObject.

Returns: {originalName, copyName, copyEntityId, copyInstanceId, copyPath}

gameobject_rename

Rename a GameObject.

Returns: {success, oldName, newName, entityId, instanceId}

gameobject_find

Find GameObjects matching criteria.

Returns: {count, objects: [{name, entityId, instanceId, path, tag, layer, position}]}

gameobject_get_info

Get detailed GameObject information.

Returns: {name, entityId, instanceId, path, tag, layer, active, position, rotation, scale, parent, parentPath, childCount, children: [{name, entityId, instanceId, path}], components}

gameobject_set_transform

Set position, rotation, and/or scale. Supports world / local / RectTransform spaces.

*At least one identifier required. RectTransform / anchored* / anchor* / pivot* / sizeDelta* / width / height only apply to UI elements; ignored on regular Transforms.

gameobject_set_parent

Set parent-child relationship.

*At least one child identifier required; omit all parent identifiers to unparent

Returns: {success, child, childEntityId, parent, parentEntityId, newPath}

gameobject_set_active

Enable or disable a GameObject.

*At least one identifier required

Returns: {success, name, entityId, active}

gameobject_set_sibling_index

Set a GameObject's sibling index — its position among its parent's children, or among the scene's root objects when unparented. index is clamped into the valid range (clamped: true reports it).

*At least one identifier required

Returns: {success, name, entityId, path, parent, previousIndex, index, clamped}

Batch Skills

gameobject_create_batch

Create multiple GameObjects in one call.

Item properties: name, primitiveType, x, y, z, rotX, rotY, rotZ, scaleX, scaleY, scaleZ, parentEntityId, parentName, parentInstanceId, parentPath

Returns: {success, totalItems, successCount, failCount, results: [{success, name, instanceId, path, position}]}

unity_skills.call_skill("gameobject_create_batch", items=[
    {"name": "Parent", "primitiveType": "Empty"},
    {"name": "Child1", "primitiveType": "Cube", "x": 0, "parentName": "Parent"},
    {"name": "Child2", "primitiveType": "Sphere", "x": 2, "parentName": "Parent"}
])

gameobject_delete_batch

Delete multiple GameObjects.

Returns: {success, totalItems, successCount, failCount, results: [{success, name}]}

# By names
unity_skills.call_skill("gameobject_delete_batch", items=["Cube1", "Cube2", "Cube3"])

# By instanceId (preferred for precision)
unity_skills.call_skill("gameobject_delete_batch", items=[
    {"instanceId": 12345},
    {"instanceId": 12346}
])

# By path
unity_skills.call_skill("gameobject_delete_batch", items=[
    {"path": "Environment/Cube1"},
    {"path": "Environment/Cube2"}
])

gameobject_duplicate_batch

Duplicate multiple GameObjects.

Returns: {success, totalItems, successCount, failCount, results: [{success, originalName, copyName, copyInstanceId, copyPath}]}

unity_skills.call_skill("gameobject_duplicate_batch", items=[
    {"instanceId": 12345},
    {"instanceId": 12346}
])

gameobject_rename_batch

Rename multiple GameObjects.

Returns: {success, totalItems, successCount, failCount, results: [{success, oldName, newName, instanceId}]}

unity_skills.call_skill("gameobject_rename_batch", items=[
    {"instanceId": 12345, "newName": "Enemy_01"},
    {"instanceId": 12346, "newName": "Enemy_02"}
])

gameobject_set_transform_batch

Set transforms for multiple objects.

Item properties (each item supports identifier + any subset of transform fields):

• Identifier: entityId / name / instanceId / path (at least one required)
• World: posX, posY, posZ, rotX, rotY, rotZ, scaleX, scaleY, scaleZ
• Local: localPosX, localPosY, localPosZ
• RectTransform (UI only): anchoredPosX, anchoredPosY, anchorMinX, anchorMinY, anchorMaxX, anchorMaxY, pivotX, pivotY, sizeDeltaX, sizeDeltaY, width, height

Returns: {success, totalItems, successCount, failCount, results: [{success, name, position, rotation, scale}]}

unity_skills.call_skill("gameobject_set_transform_batch", items=[
    {"name": "Cube1", "posX": 0, "posY": 1},
    {"instanceId": 12345, "posX": 2, "posY": 1},
    {"path": "Env/Cube3", "posX": 4, "posY": 1}
])

gameobject_set_active_batch

Toggle multiple objects. Each item supports identifier (entityId / name / instanceId / path) + active (bool).

Returns: {success, totalItems, successCount, failCount, results: [{success, name, active}]}

unity_skills.call_skill("gameobject_set_active_batch", items=[
    {"name": "Enemy1", "active": False},
    {"name": "Enemy2", "active": False}
])

gameobject_set_parent_batch

Parent multiple objects. Each item supports childEntityId/childName/childInstanceId/childPath and parentEntityId/parentName/parentInstanceId/parentPath.

Returns: {success, totalItems, successCount, failCount, results: [{success, child, parent}]}

unity_skills.call_skill("gameobject_set_parent_batch", items=[
    {"childName": "Wheel1", "parentName": "Car"},
    {"childInstanceId": 12345, "parentName": "Car"},
    {"childPath": "Wheels/Wheel3", "parentPath": "Vehicles/Car"}
])

gameobject_set_layer_batch

Set layer for multiple objects. Each item supports identifier (entityId / name / instanceId / path) + layer (string layer name) + optional recursive (bool, default false — propagates layer to children).

Returns: {success, totalItems, successCount, failCount, results: [{success, name, layer}]}

unity_skills.call_skill("gameobject_set_layer_batch", items=[
    {"name": "Enemy1", "layer": "Water"},
    {"name": "Enemy2", "layer": "Water"}
])

gameobject_set_tag_batch

Set tag for multiple objects. Each item supports identifier (entityId / name / instanceId / path) + tag (string tag name).

Returns: {success, totalItems, successCount, failCount, results: [{success, name, tag}]}

unity_skills.call_skill("gameobject_set_tag_batch", items=[
    {"name": "Enemy1", "tag": "Enemy"},
    {"name": "Enemy2", "tag": "Enemy"}
])

Minimal Example

import unity_skills

# GOOD: 3 API calls instead of 6
unity_skills.call_skill("gameobject_create_batch", items=[
    {"name": "Floor", "primitiveType": "Plane"},
    {"name": "Wall1", "primitiveType": "Cube"},
    {"name": "Wall2", "primitiveType": "Cube"}
])
unity_skills.call_skill("gameobject_set_transform_batch", items=[
    {"name": "Wall1", "posX": -5, "scaleY": 3},
    {"name": "Wall2", "posX": 5, "scaleY": 3}
])
unity_skills.call_skill("gameobject_set_tag_batch", items=[
    {"name": "Wall1", "tag": "Wall"},
    {"name": "Wall2", "tag": "Wall"}
])

Exact Signatures

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

Graphics Skills

Project-wide graphics and quality settings (GraphicsSettings + QualitySettings) for Unity 2022.3+. Works in Built-in, URP and HDRP — does not depend on any SRP package being installed.

Operating Mode

• Query skills (graphics_get_overview, graphics_get_quality_settings, graphics_get_render_pipeline_assets, graphics_list_always_included_shaders, graphics_get_shader_stripping) are SkillMode.SemiAuto — they run in all three modes without grant.
• Mutating skills (graphics_set_quality_level, graphics_set_default_render_pipeline, graphics_set_quality_render_pipeline, graphics_add_always_included_shader, graphics_remove_always_included_shader, graphics_set_shader_stripping) are SkillMode.FullAuto — under Approval they need user grant (grant triggers one server-side execute returning the result); under Auto / Bypass they execute directly.
• This module contains no Delete / PlayMode / Reload / high-risk skills (no NeverInSemi). graphics_remove_always_included_shader is a list mutation, not a SkillOperation.Delete.