Skip to content

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

unity-bridge

Unverified

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 (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:

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

CommandFieldsReturns
ping—message, unityVersion
scene.dumpincludeInactive?, maxObjects?scene objects: path, worldPosition, rect (if UI), components
selection.get—currently selected objects (same shape)
reference.wiresourcePath, sourceComponent, field, then ONE of: targetPath(+targetComponent?) / targetAssetPathwhat was wired
gameobject.createname, parentPath?, primitive?, position?{x,y,z}, components?[]created object
component.addpath, componentupdated component list
object.modifypath, ops:[{property,value}]applied, errors, object state
gameobject.deletepathdeleted path
screenshot.annotatedwidth?, height?, annotate?, maxLabels?imagePath (read it!), objects[{screenRect, worldPosition}]
screenshot.gameviewmax?real Game View PNG incl. overlay UI (imagePath — read it). Use to see UI.
console.getmaxEntries?, logTypeFilter?, lastMinutes?, includeStackTrace?recent Console logs (script/runtime; not compiler errors)
console.readmax?, 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.setpath, component, componentIndex?, ops:[{field,value}]set value fields (color/number/bool/string/vector/enum)
gameobject.duplicatepath, name?, setPosition?, position?clone a GameObject (with components)
prefab.createpath, assetPathsave a GameObject as a prefab asset
prefab.instantiateassetPath, name?, parentPath?, setPosition?, position?spawn a prefab instance
refreshsave?, recompile?import + recompile changed scripts (you can compile your own edits)
editor.playaction (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.closepath, additive?, force? (open/create); path? (save)multi-scene management (single/additive; force discards unsaved)
status—isCompiling/isPlaying/… + last compile compileMessages (poll after refresh)
menu.executemenuPathrun any Editor menu item by path (e.g. Tools/AI Bridge/Configure Claude Code)
asset.findfilter, folder?, max?find assets by Unity search (t:Sprite, t:Prefab, …)
asset.reimportpathforce-reimport an asset/folder (regenerate importer-derived assets)
sprite.setpath, assetPath, component?assign a sprite to a SpriteRenderer/Image (auto-imports as Sprite)
audio.addpath, clip?, loop?, volume?, playOnAwake?, spatialBlend?add/configure an AudioSource + assign a clip
particle.createname?, parentPath?, position?, preset (burst/explosion/stream/sparkle), color?, size?, lifetime?, count?create a particle effect (plays in Play mode)
ui.createkind (image/text/button/canvas), name?, parentPath?, anchor?, x/y/width/height?, text?, fontSize?, color?, sprite?turnkey UGUI (auto Canvas + EventSystem)
prefab.modifyprefabPath, 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.buildPrefabFromSpecspecPath(.ui.json), outPrefab, spriteRoots[], fontResourcea node-tree spec → a UGUI prefab (then tune with prefab.modify)
ui.makeScrollableprefabPath, 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: 318kUpdated Claude CodeCodexUnverifiedInstall
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: 196kUpdated 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: 196kUpdated 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: 196kUpdated Claude CodeCodexVerifiedInstall