Skip to content

hi5jeff/Aibridge4Unity / com.aibridge.unity/Documentation~

unity-bridge

Verified

Drive the open Unity Editor from this session via the AI Bridge file channel (.aibridge/in,out) — read scene/selection as data, capture screenshots, build/modify/wire objects, lay out UGUI, animate, write & compile C#, run Play mode, and more. Use this WHENEVER the task touches Unity (scene, GameObjects, selection, components, UI, prefabs, sprites, animation, Console, Play mode) — do NOT take screenshots of the screen, use computer-use, or look for a Unity MCP server; control the real Editor through the .aibridge channel.

FileKindSize
AI-USAGE.mdmarkdown2.9 KB
PRESENTATION_RULES.mdmarkdown3.3 KB
SKILL.mdskill md9.3 KB
---
name: unity-bridge
description: Drive the open Unity Editor from this session via the AI Bridge file channel (.aibridge/in,out) — read scene/selection as data, capture screenshots, build/modify/wire objects, lay out UGUI, animate, write & compile C#, run Play mode, and more. Use this WHENEVER the task touches Unity (scene, GameObjects, selection, components, UI, prefabs, sprites, animation, Console, Play mode) — do NOT take screenshots of the screen, use computer-use, or look for a Unity MCP server; control the real Editor through the .aibridge channel.
---

# Unity Bridge — driving the Unity Editor

> **⚠️ Building UI / presentation / animation / effects? FIRST read [`PRESENTATION_RULES.md`](./PRESENTATION_RULES.md)
> (next to this file) — hard rules: editable prefabs (no hardcoded coords), non-destructive prefab edits,
> native-size sprites, no git on the user's project, real Unity game-feel. Violating them costs rework.**

The **AI Bridge** package runs inside the open Unity Editor and exposes commands over a plain file
channel. You operate Unity by writing a request file and reading the reply. No MCP, no ports.

## Channel protocol

- Root: `<project>/.aibridge/` (here: `D:/AI/unity_test/testgame/.aibridge/`).
- **Send:** write `in/<id>.json` — `{ "id": "<unique>", "command": "<name>", ...fields }`.
- **Receive:** read `out/<id>.json` — `{ "id", "command", "ok", "error", "result" }`.
- Request fields are **flat** (top level), not nested under "args".
- The bridge polls ~2×/sec. After writing, wait ~1–2s, then read `out/<id>.json`.
- Use a unique `id` per request so replies never collide.

Bash idiom:
```bash
cd <project>/.aibridge
printf '{ "id":"x1", "command":"scene.dump" }' > in/x1.json
sleep 2 && cat out/x1.json
```

If `out/<id>.json` never appears: Unity may be recompiling or unfocused. Ask the user to focus
Unity, check the Console for `[AIBridge]`, and retry. **You cannot trigger a recompile yourself** —
after editing any C# in the project, ask the user to focus Unity so it compiles.

## The user's pointer — `selection.json`

When the user says "this / here / the selected one", they mean what they pointed at in Unity:
- **Pinned:** read `.aibridge/selection.json` (written by the *AI Reference* window — scene objects
  and/or Project-window assets, or a clicked point, with an optional `note`).
- **Live:** call `selection.get` for whatever is selected right now.

Selected **assets** (sprites, prefabs, materials…) appear under `assets[]` (with `assetPath`) in both
`selection.json` and `selection.get` — feed `assetPath` into `reference.wire` `targetAssetPath`.

### Editing what the user selected — and **Prefab Mode** (important)

To change the exact thing the user picked, pass `path: "@selection"` to `object.modify` / `component.set`.
It targets `Selection.activeGameObject` directly, so it works **anywhere — including inside an open Prefab
Mode stage**, which a scene-path lookup cannot reach.

⚠️ **Prefab Mode is a separate stage the bridge's scene-path lookup does NOT see.** When the user has a
prefab open in Prefab Mode (they double-clicked it):
- `selection.get` *can* read their selection (you know what they picked), **but** a plain scene path like
  `"Dex/BgImage"` won't resolve, and **editing the prefab asset on disk (`prefab.modify`) will NOT show** —
  Unity doesn't refresh the open stage, and the user's later save can overwrite your disk edit.
- **Do this instead:** edit `path: "@selection"` (reaches the live stage object the user sees), or ask the
  user to **exit Prefab Mode** first. After an `@selection` edit they persist it with Ctrl+S in Prefab Mode.
- Plain paths for `object.modify` / `component.set` also auto-fall back to the open Prefab stage.

Tell-tale: you edit a prefab but the user keeps seeing the OLD value, and `selection.get` returns the same
`entityId` every call → they're looking at a stale Prefab Mode stage. Switch to `@selection`.

## Commands

| Command | Fields | Returns |
|---|---|---|
| `ping` | — | `message`, `unityVersion` |
| `scene.dump` | `includeInactive?`, `maxObjects?` | scene objects: `path`, `worldPosition`, `rect` (if UI), `components` |
| `selection.get` | — | currently selected objects (same shape) |
| `reference.wire` | `sourcePath`, `sourceComponent`, `field`, then ONE of: `targetPath`(+`targetComponent?`) / `targetAssetPath` | what was wired |
| `gameobject.create` | `name`, `parentPath?`, `primitive?`, `position?{x,y,z}`, `components?[]` | created object |
| `component.add` | `path`, `component` | updated component list |
| `object.modify` | `path`, `ops:[{property,value}]` | `applied`, `errors`, object state |
| `gameobject.delete` | `path` | deleted path |
| `screenshot.annotated` | `width?`, `height?`, `annotate?`, `maxLabels?` | `imagePath` (read it!), `objects[{screenRect, worldPosition}]` |
| `screenshot.gameview` | `max?` | real Game View PNG incl. overlay UI (`imagePath` — read it). Use to *see* UI. |
| `console.get` | `maxEntries?`, `logTypeFilter?`, `lastMinutes?`, `includeStackTrace?` | recent Console logs (script/runtime; not compiler errors) |
| `console.read` | `max?`, `typeFilter?` | the real Console (errors/warnings), survives reloads — use for compile diagnostics |
| `console.clear` | — | clear the Console + log buffer (wipe stale errors before a fresh check) |
| `component.set` | `path`, `component`, `componentIndex?`, `ops:[{field,value}]` | set value fields (color/number/bool/string/vector/enum) |
| `gameobject.duplicate` | `path`, `name?`, `setPosition?`, `position?` | clone a GameObject (with components) |
| `prefab.create` | `path`, `assetPath` | save a GameObject as a prefab asset |
| `prefab.instantiate` | `assetPath`, `name?`, `parentPath?`, `setPosition?`, `position?` | spawn a prefab instance |
| `refresh` | `save?`, `recompile?` | import + recompile changed scripts (you can compile your own edits) |
| `editor.play` | `action` (enter/exit/toggle/pause/resume/step) | run the game; poll `status` for isPlaying, then `screenshot.gameview` |
| `scene.create` / `scene.open` / `scene.save` / `scene.list` / `scene.close` | `path`, `additive?`, `force?` (open/create); `path?` (save) | multi-scene management (single/additive; force discards unsaved) |
| `status` | — | `isCompiling`/`isPlaying`/… + last compile `compileMessages` (poll after refresh) |
| `menu.execute` | `menuPath` | run any Editor menu item by path (e.g. `Tools/AI Bridge/Configure Claude Code`) |
| `asset.find` | `filter`, `folder?`, `max?` | find assets by Unity search (`t:Sprite`, `t:Prefab`, …) |
| `asset.reimport` | `path` | force-reimport an asset/folder (regenerate importer-derived assets) |
| `sprite.set` | `path`, `assetPath`, `component?` | assign a sprite to a SpriteRenderer/Image (auto-imports as Sprite) |
| `audio.add` | `path`, `clip?`, `loop?`, `volume?`, `playOnAwake?`, `spatialBlend?` | add/configure an AudioSource + assign a clip |
| `particle.create` | `name?`, `parentPath?`, `position?`, `preset` (burst/explosion/stream/sparkle), `color?`, `size?`, `lifetime?`, `count?` | create a particle effect (plays in Play mode) |
| `ui.create` | `kind` (image/text/button/canvas), `name?`, `parentPath?`, `anchor?`, `x/y/width/height?`, `text?`, `fontSize?`, `color?`, `sprite?` | turnkey UGUI (auto Canvas + EventSystem) |
| `prefab.modify` | `prefabPath`, `edits:[{path, ops?, addChild?, duplicateAs?}]` | **non-destructive** in-place prefab edit: patch text/sprite/color/active/rect/`Type.member`; `addChild` (image/text/empty, `index` for layering); `ops:addComponent` | 
| `ui.buildPrefabFromSpec` | `specPath`(.ui.json), `outPrefab`, `spriteRoots[]`, `fontResource` | a node-tree spec → a UGUI prefab (then tune with `prefab.modify`) |
| `ui.makeScrollable` | `prefabPath`, `node`, `vertical?`, `horizontal?`, `width?`, `height?` | wrap a layout container in a ScrollRect (viewport = node's size) so a list scrolls instead of overflowing |
| `compile` | — | force a script recompile even while the Editor is unfocused (poll `status`) |

Notes:
- **Paths** are `Root/Child/Leaf` within the active scene (the shape `scene.dump` emits) — or **`@selection`**
  to target the current Editor selection (the only way to reach a node inside an open Prefab Mode stage).
- `object.modify` properties: `name`, `active`, `position`, `localPosition`, `rotation` (euler),
  `localRotation`, `scale`; UI: `anchoredPosition`, `sizeDelta`, `anchorMin`, `anchorMax`, `pivot`.
  Vector values are comma-separated, e.g. `"1,2,0"`.
- For a **prefab asset**, prefer `prefab.modify` (non-destructive, snapshots & restores untouched
  transforms). Don't do it while the user has that prefab open in Prefab Mode — use `@selection` instead.
- `reference.wire` is for object-reference fields only; for primitive values use the Inspector/scripts.
- All edits register **Undo** (the user can Ctrl+Z). Full evolving command list: `README.md` / `CHANGELOG.md`.

## Recommended loop

1. **Orient** — `scene.dump` for data, and/or `screenshot.annotated` then **read the PNG** at
   `result.imagePath` to see the scene.
2. **Resolve "this"** — `selection.get` or read `selection.json`.
3. **Act** — `gameobject.create` / `component.add` / `reference.wire` / `object.modify` / `gameobject.delete`.
4. **Verify** — `screenshot.annotated` again and read the PNG to confirm the change looks right; don't
   assume — look.

Full field reference: `Packages/com.aibridge.unity/README.md`.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall