DOCSEARCHbyAlgolia
Submit Docs

UnitySkills Documentation

repository·main·Indexed 23 days ago

https://github.com/besty0728/unity-skills

An AI-driven automation engine for Unity (version 2.4.2) that exposes editor capabilities via a REST API. It enables AI agents like Claude Code and Cursor to manipulate Unity scenes, assets, and configurations using a toolkit of 776 REST skills. Key features include transactional atomicity with automatic rollbacks, multi-instance control, a multi-tier permission system (Approval, Auto, and Bypass modes), dry run and planning capabilities, and a JSONL-based audit trail. Compatible with Unity 2022.3+ and Unity 6.

Tokens
220.1K
Snippets
358
Records
1.1K
Agent score
80%

What's inside UnitySkills

  1. Overview of UnitySkills

    main

    UnitySkills is a REST API-based, AI-driven automation engine for the Unity Editor. It allows AI agents to control Unity scenes directly through a comprehensive toolkit of 'Skills'.

    Key capabilities include:

    • 776 REST Skills: A toolkit containing functional source modules and advisory design modules, supporting batch operations.
    • Transactional Atomicity: Failed operations automatically roll back to keep scenes safe.
    • Multi-Instance Control: Supports controlling multiple Unity projects simultaneously via automatic port discovery.
    • Governance & Safety: Features a multi-tier permission system, pre-execution dry runs, and a JSONL-based audit trail.
    • Stability: Includes automatic recovery after Domain Reloads and configurable request timeouts (default 15 minutes).

    Compatibility Note: The official maintenance baseline is Unity 2022.3+ and Unity 6. While some 2021 compatibility logic may exist, future work focuses on 2022.3+.

  2. Overview of available UnitySkills categories

    main

    UnitySkills provides a wide range of specialized modules for Unity development. Most modules support *_batch operations for high-performance bulk processing.

    Key categories include:

    • Core Systems: GameObject, Component, Asset, Prefab, Transform, Physics, Script, and Scene management.
    • Rendering & Visuals: URP, ShaderGraph, Material, PostProcess, Cinemachine, Volume, and Light.
    • UI: UI Toolkit (UXML/USS), Canvas, Button, and Layout tools.
    • Advanced Workflows: YooAsset (Hot-update), HybridCLR (Hot-update), Behavior (Behavior Trees), and Netcode (Multiplayer).
    • Development Tools: Editor (Play mode capture, undo/redo), Debug, Console, Profiler, and Validation.
    • Specialized: XR (VR/AR), ProBuilder (Level design), NavMesh (AI pathfinding), and DOTween/PrimeTween (Animation).

    Additionally, the unity-skills/skills/ directory contains 24 advisory design modules to help AI agents make decisions regarding architecture, performance, and maintainability before writing code.

  3. Design rules for Unity Netcode for GameObjects 2.x

    main

    This module provides source-anchored design rules for com.unity.netcode.gameobjects 2.x. It is intended for use when writing or reviewing multiplayer code, designing server/distributed authority, wiring RPCs or NetworkVariables, or debugging netcode issues.

    Note on Versioning: These rules target version 2.x (validated against 2.11.0, Unity 6000.0+). Features like the universal [Rpc] attribute, SendTo.Authority, and RpcInvokePermission are not available in 1.x.

  4. Design rules for Cysharp UniTask 2.5.10

    main

    This module provides source-anchored design rules for using UniTask 2.5.10 in Unity (2018.4+). It is intended for developers writing or reviewing asynchronous code involving async UniTask signatures, PlayerLoopTiming, CancellationToken handling, and task composition.

    When to use this module

    Load this module when working with:

    • async UniTask, async UniTask<T>, or async UniTaskVoid method signatures.
    • Chaining methods like .Forget(), .AttachExternalCancellation(token), or .SuppressCancellationThrow().
    • Timing methods: UniTask.Yield, UniTask.NextFrame, UniTask.Delay, UniTask.WaitForEndOfFrame, UniTask.WaitForFixedUpdate.
    • Predicate methods: UniTask.WaitUntil, UniTask.WaitWhile, UniTask.WaitUntilValueChanged, UniTask.WaitUntilCanceled.
    • Composition: UniTask.WhenAll, UniTask.WhenAny, UniTask.WhenEach.
    • Thread switching: UniTask.SwitchToMainThread, UniTask.SwitchToThreadPool, UniTask.Run.
    • Conversions: AsyncOperation.ToUniTask(), UnityWebRequest.SendWebRequest().ToUniTask(), Coroutine.ToUniTask().
    • Lifecycle/Triggers: this.GetCancellationTokenOnDestroy(), GetAsyncStartTrigger().
    • Manual completion: UniTaskCompletionSource / UniTaskCompletionSource<T>.
    • Async streams: IUniTaskAsyncEnumerable<T>, UniTaskAsyncEnumerable, AsyncReactiveProperty<T>, Channel<T>.
    • WebGL: Specific async code paths where Task.Run or SwitchToThreadPool are forbidden.

  5. Manage Unity AssetDatabase with unity-asset skills

    main

    The unity-asset skill module allows you to manage the Unity AssetDatabase, including importing, deleting, moving/renaming, duplicating, finding, and querying asset metadata.

    Key Concepts

    • BATCH-FIRST: Always use *_batch versions of skills when operating on 2 or more assets to improve efficiency.
    • Operating Modes:
      • asset_find, asset_get_info, and asset_get_labels are SkillMode.SemiAuto and can execute directly.
      • Write-based skills (e.g., asset_move, asset_duplicate, asset_set_labels) use SkillMode.FullAuto and require permission (grant).
      • High Risk: asset_import and asset_delete (and its batch version) are considered high-risk and will return MODE_FORBIDDEN in Approval/Auto modes unless explicitly allowed or in Bypass mode.

    Common Pitfalls to Avoid

    • Do not use asset_create: Use asset_create_folder for folders, material_create for materials, or script_create for scripts.
    • Do not use asset_rename: Use asset_move with a new destination path.
    • Do not use asset_search: Use asset_find with searchFilter syntax.
    • Do not use asset_copy: Use asset_duplicate.

  6. Use Unity PostProcess Skills for URP/HDRP

    main

    The unity-postprocess module provides skills for configuring modern Scriptable Render Pipeline (SRP) post-processing on URP or HDRP VolumeProfiles. Use these skills to add, remove, or tune effects like bloom, tonemapping, color grading, and vignette.

    Important Constraints:

    • Do not use this module for the legacy PPv2 (com.unity.postprocessing) package.
    • Do not use this module for general Volume container or profile management; use the volume module for those tasks instead.
    • Dependency: This module requires com.unity.render-pipelines.core (SRP_CORE). If the package is missing, skills will return a diagnostic error: { error: "Scriptable Render Pipeline Core package … is not installed." }.

  7. Browse the Unity Documentation Index

    main
    The Unity Documentation Index provides categorized access to Unity-related skills and documentation. You can navigate through various specialized domains such as 2D, 3D, Animation, Physics, and Shaders to find specific technical guidance and skill sets.

  8. Use Cinemachine Skills for Virtual Camera Control

    main

    The unity-cinemachine module allows for the creation, configuration, and tuning of Cinemachine Virtual Cameras (VCam, FreeLook, ClearShot, StateDriven) and their associated Body, Aim, and Noise pipelines. It supports both Cinemachine 2.x and 3.x via a runtime reflection adapter (CinemachineAdapter).

    Key Capabilities

    • Creation & Configuration: Create virtual cameras and configure follow/look-at targets, lens settings, and pipeline components.
    • Inspection: Query existing camera properties and list components.
    • Automation: Handles the API differences between Cinemachine 2.x (CinemachineVirtualCamera) and 3.x (CinemachineCamera) automatically.

    Prerequisites

    • You must have the com.unity.cinemachine package installed (CM 2.x or 3.x). If not installed, all skills will return { error = "Cinemachine 未安装..." }. It is recommended to verify installation using package_* skills first.
    name: unity-cinemachine
description: Set up Cinemachine Virtual Cameras — VCam/FreeLook/ClearShot/StateDriven cameras and the Body/Aim/Noise pipeline. Use when creating or tuning Cinemachine cameras, configuring follow/look-at or noise, or building cinematic camera behavior, even if the user just says "虚拟相机" or "运镜".

  9. Use Unity Volume Skills for SRP (URP/HDRP)

    main

    The unity-volume module provides skills for working with the Scriptable Render Pipeline (SRP) Volume framework in Unity 2022.3+. It allows you to create and load VolumeProfile assets, and manage global or local Volume GameObjects and their components.

    Key Usage Scenarios:

    • Creating or loading VolumeProfile assets.
    • Adding global or local Volumes to a scene.
    • Managing VolumeComponent overrides (adding, removing, or modifying parameters).

    Important Routing Note:

    • Use this module for Volume container/profile CRUD operations.
    • For high-level modern post-processing effects (e.g., Bloom, DOF, Tonemapping), prefer the postprocess module instead.

  10. Use the Unity UI Toolkit (UITK) module

    main

    The unity-uitoolkit module is designed for authoring runtime or editor UIs using Unity's UI Toolkit. It provides tools for managing UXML (structure), USS (styling), UIDocument (scene attachment), and PanelSettings (rendering).

    Requirements & Constraints:

    • Unity Version: Requires Unity 2022.3+.
    • Compatibility: Do not mix this with UGUI/Canvas (ui_*) skills. UI Toolkit uses UIDocument, not Canvas.
    • Localization: Match visible UI text to the user's language (e.g., Chinese labels for Chinese conversations), but keep USS class names and CSS variables in English.
    • USS Limitations: USS is not full CSS. Unsupported features include display:grid, box-shadow, calc(), @media, ::before, z-index, and gradients.

  12. Manage Unity scenes with unity-scene skills

    main

    The unity-scene module allows you to control Unity scenes, which are the containers for all GameObjects. You can create, load (single or additive), save, unload, and switch active scenes, as well as query scene information and hierarchy structures.

    Operating Modes & Risk Levels

    • Approval Mode: Some read-only skills like scene_get_info or scene_get_hierarchy are SemiAuto and execute directly. Others like scene_screenshot or scene_unload require explicit grant.
    • High Risk: scene_create, scene_load, and scene_save are marked as RiskLevel="high" because they can overwrite or change entire scene files. In Approval or Auto modes, these return MODE_FORBIDDEN and require Bypass or Allowlist permissions.

    Common Pitfalls to Avoid

    • Deleting/Renaming: There are no scene_delete or scene_rename skills. To delete a scene file, use asset_delete. To rename, use asset_move.
    • Listing Scenes: Do not use a non-existent scene_list. Use scene_get_loaded for currently loaded scenes, or asset_find with t:Scene to find all scene assets in the project.
    • Advanced Searching: scene_find_objects is for simple name/tag/component filtering. For regex, layer, or path-based searches, use gameobject_find instead.