REST API-based AI-driven Unity Editor Automation Engine Let AI control Unity scenes directly through Skills
๐ We are now indexed by DeepWiki!
Got questions? Check out the AI-generated docs โ
> The current official maintenance baseline is **Unity 2022.3+**. Some Unity 2021 compatibility logic may still remain in the codebase, but future feature work, regression testing, and adaptation will focus on **2022.3+ / Unity 6**.
## ๐ค Acknowledgments
This project is a deep refactoring and feature extension based on the excellent concept of [unity-mcp](https://github.com/CoplayDev/unity-mcp).
---
## ๐ Core Features
- ๐ ๏ธ **726 REST Skills Comprehensive Toolkit**: Includes 51 functional source modules plus 19 advisory design modules, with Batch operations for multi-object control.
- โก **Revolutionary Efficiency Boost (v2.0.1+)**: Schema caching + exponential backoff polling + BATCH-FIRST guidance โ **Token consumption โ 96%**, **simple tasks 4-6 calls โ 1 call (โ 75-83%)**. Current: v2.0.5.
- ๐ **Three-Tier Permission Modes (v1.9.0+)**: Approval / Auto / Bypass with dual approval channels (Dialog / Panel), aligned with Claude Code permission modes; zero-impact upgrade for existing users.
- ๐ค **4 Major IDEs Native Support**: Claude Code / Antigravity / Codex / Cursor โ one-click install and use.
- ๐ก๏ธ **Transactional Atomicity**: Failed operations auto-rollback, leaving scenes clean and safe.
- ๐ **Multi-Instance Simultaneous Control**: Automatic port discovery and global registry for controlling multiple Unity projects at once.
- ๐ **Ultra-Stable Long Connections**: Configurable request timeout (default 15 minutes), automatic recovery after Domain Reload, with retry hints during script compilation/asset updates.
- ๐ก๏ธ **Anti-Hallucination Guardrails**: Each Skill module includes DO NOT lists and routing rules to prevent calls to nonexistent commands or parameter errors.
---
## ๐ Operating Modes (v1.9.0+)
UnitySkills ships with a true server-side permission system aligned with Claude Code permission modes. All mode switching happens in the Unity panel (**Window > UnitySkills > Server**) โ chat trigger words are no longer supported.
| Mode | Default | Behavior | Use Case |
|:-----|:-------:|:---------|:---------|
| **Approval** | โ | AI must request โ user approves โ execute (returns `MODE_RESTRICTED` + grant token) | Manual control, sensitive projects |
| **Auto** | New installs | AI runs FullAuto skills directly; server only blocks auto-detected high-risk ops (NeverInSemi) | Day-to-day development |
| **Bypass** | Existing installs (upgrade) | All skills run unrestricted; only `ConfirmationToken` gate remains for high-risk ops | Automation, CI, fast iteration |
**Two approval channels under Approval mode**:
- **Dialog** (default) โ AI explains intent + grant token, user agrees in chat, AI replays the token via `POST /permission/grant`
- **Panel** (opt-in) โ grant token only takes effect after user clicks **[Approve]** in the Unity panel; AI-issued grants without panel approval return `GRANT_PENDING_APPROVAL`
**Zero-impact upgrade for existing users**: the plugin detects legacy `UnitySkills_*` EditorPrefs keys and keeps **Bypass** as the default, preserving the previous Full-Auto behavior with no action required. New installations default to **Auto** โ FullAuto skills run directly, only NeverInSemi (Delete / MayEnterPlayMode / MayTriggerReload / high-risk) operations are blocked. Switch to **Approval** in the Server tab if you need per-skill manual gating.
> โ Chat trigger words (e.g. `"full auto"` / `"semi-auto"`) are no longer recognized. Switch modes in **Window > UnitySkills > Server**.
>
> ๐ Audit log: `Library/UnitySkillsAudit.jsonl` (per-project, jsonl, auto-rolls at 1MB, keeps 3 files) records every grant / revoke / restricted hit / call. Open **Window > UnitySkills > Audit Log** to browse, filter, delete individual entries (โ), or wipe everything (๐ Clear All) โ deletions themselves are appended as `audit_deleted` / `audit_cleared` events so the log stays auditable.
>
> ๐ The Skill Installer card shows a **per-scope uninstall** button that auto-adapts: disabled when nothing's installed, a single button labeled with its scope when only one is installed, and a dropdown (`Uninstall โพ`) listing Project / Global when both are installed.
>
> 19 advisory design modules (architecture, performance, design patterns, testability, package-specific source rules, etc.) are available in all modes and loaded on demand.
---
## ๐๏ธ Quick Install Supported IDE/Terminals
This project has been deeply optimized for the following environments to ensure a continuous and stable development experience (tools not listed below are not necessarily unsupported โ they just lack a quick installer; use ***Custom Installation*** to the corresponding directory):
| AI Terminal | Support Status | Special Features |
| :--- | :---: | :--- |
| **Antigravity** | โ Supported | Open Agent Skills standard via `.agents/skills/` (workspace) and `~/.gemini/antigravity/skills/` (global). |
| **Claude Code** | โ Supported | Intelligent Skill intent recognition, supports complex multi-step automation. |
| **Codex** | โ Supported | Supports `$skill` explicit invocation and implicit intent recognition. Shares `.agents/skills/` with Antigravity in workspace mode. |
| **Cursor** | โ Supported | Auto-discovers `.cursor/skills/` and `.agents/skills/`; supports `/skill-name` explicit invocation; visible in Settings โ Rules. |
---
## ๐ Quick Start
> **Overview**: Install Unity Plugin โ Start UnitySkills Server โ AI Uses Skills
### 1. Install Unity Plugin
Add via Unity Package Manager using Git URL:
**Stable Version (main)**:
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity
```
**Beta Version (beta)**:
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#beta
```
**Specific Version** (e.g., v1.6.0):
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity#v1.6.0
```
> ๐ฆ All version packages are available on the [Releases](https://github.com/Besty0728/Unity-Skills/releases) page
### 2. Start Server
In Unity, click menu: `Window > UnitySkills > Start Server`
> โณ `script_*`, `debug_force_recompile`, `debug_set_defines`, some asset reimports, and package changes may trigger compilation or Domain Reload. Temporary REST unavailability during that window is expected; wait a moment and retry.
### 3. One-Click AI Skills Configuration
1. Open `Window > UnitySkills > Skill Installer`.
2. Select the corresponding terminal icon (Claude / Antigravity / Codex / Cursor).
3. Click **"Install"** to complete the environment configuration without manual code copying.
> The installer copies the `unity-skills~/` template directory from the package to the target location.
>
> Installer output files (generated in target directory):
> - `SKILL.md`
> - `skills/`
> - `references/`
> - `scripts/unity_skills.py`
> - `scripts/agent_config.json` (contains Agent identifier)
> **Codex Note**: Antigravity and Codex share `.agents/skills/` in workspace mode โ installing once for either makes the skill available to both. Codex auto-discovers skills in `.agents/skills/`; no `AGENTS.md` declaration needed.
๐ For complete installation and usage instructions, see: [Setup Guide](docs/SETUP_GUIDE.md) | [ๅฎ่ฃ ๆๅ](docs/SETUP_GUIDE_CN.md)
4. Manual Skills Installation (Optional)
If one-click installation is not supported or preferred, follow this **standard procedure** for manual deployment (applicable to all tools supporting Skills):
#### โ Standard Installation Method A
1. **Custom Installation**: In the installation interface, select the "Custom Path" option to install Skills to any directory you specify (e.g., `Assets/MyTools/AI`) for easier project management.
#### โ Standard Installation Method B
1. **Locate Skills Source Directory**: The `SkillsForUnity/unity-skills~/` directory in the UPM package is the distributable Skills template (root directory contains `SKILL.md`).
2. **Find the Tool's Skills Root Directory**: Different tools have different paths; refer to the tool's documentation first.
3. **Copy Completely**: Copy the entire contents of `unity-skills~/` to the tool's Skills root directory (rename to `unity-skills/`).
4. **Create agent_config.json**: Create an `agent_config.json` file in the `unity-skills/scripts/` directory:
```json
{"agentId": "your-agent-name", "installedAt": "2026-02-11T00:00:00Z"}
```
Replace `your-agent-name` with the name of your AI tool (e.g., `claude-code`, `antigravity`, `codex`, `cursor`).
5. **Directory Structure Requirements**: After copying, maintain the structure as follows (example):
- `unity-skills/SKILL.md`
- `unity-skills/skills/`
- `unity-skills/references/`
- `unity-skills/scripts/unity_skills.py`
- `unity-skills/scripts/agent_config.json`
6. **Restart the Tool**: Let the tool reload the Skills list.
7. **Verify Loading**: Trigger the Skills list/command in the tool (or execute a simple skill call) to confirm availability.
#### ๐ Common Tool Directory Reference
The following are verified default directories (if the tool has a custom path configured, use that instead):
- Claude Code: `~/.claude/skills/`
- Antigravity: `~/.gemini/antigravity/skills/` (global) or `.agents/skills/` (workspace)
- OpenAI Codex: `~/.agents/skills/` (global) or `.agents/skills/` (workspace, shared with Antigravity)
- Cursor: `~/.cursor/skills/` (global) or `.cursor/skills/` (workspace); also auto-discovers `.agents/skills/`
#### ๐งฉ Other Tools Supporting Skills
If you're using other tools that support Skills, install according to the Skills root directory specified in that tool's documentation. As long as the **standard installation specification** is met (root directory contains `SKILL.md` and maintains `skills/`, `references/`, and `scripts/` structure), it will be correctly recognized.
---
