liyingsong99/AIBridge

English | 中文

AIBridge는 AI 코딩 어시스턴트에게 Unity Editor로 연결되는 안정적인 CLI 브릿지(bridge)를 제공하는 Unity 패키지입니다. 이를 통해 에이전트(agent)는 실제 Unity 에셋 경로를 확인하고, 씬(scene)과 프리팹(prefab)을 검사하며, Unity API를 통해 오브젝트를 편집하고, Unity 컴파일(compilation)을 실행하며, 콘솔(Console) 로그를 읽고, 배치 워크플로(batch workflows)를 실행하며, 테스트를 수행하고, 시각적 검증을 위한 스크린샷 또는 GIF를 캡처할 수 있습니다.

이 패키지는 어시스턴트가 단순히 파일만 편집하는 것이 아니라, Editor 내부에서 변경 사항을 검증해야 하는 AI 보조 Unity 개발을 위해 설계되었습니다.

많은 Unity 자동화 도구들은 라이브 소켓(live socket) 또는 MCP 세션에 의존합니다. AIBridge는 파일 기반의 명령 요청(command requests)과 결과 파일(result files)을 사용하므로, 스크립트 재컴파일(script recompilation), 도메인 재로드(domain reloads), 에디터 포커스 변경(editor focus changes) 및 재시작 상황에서도 작업이 유지될 수 있습니다.

차원 (Dimension)	AIBridge	지속성 브릿지 (Persistent bridge)
연결 모델 (Connection model)	파일 기반 요청 및 결과	라이브 세션 (Live session)
...

• Unity 2019.4 이상.
• 번들로 포함된 CLI를 위한 .NET 8.0 런타임 (Runtime).
• compile unity, asset, scene, inspector, prefab, screenshot, get_logs와 같은 Unity 측 명령을 실행하려면 Unity Editor가 실행 중이어야 합니다.

다음 Git URL을 사용하여 Unity Package Manager로 설치하십시오:

또한 이 리포지토리(repository)를 Unity 프로젝트의 Packages 폴더로 클론(clone)할 수도 있습니다.

• Unity Editor에서 Tools > AIBridge Settings를 엽니다.
• Skills Installation 섹션을 엽니다.
• 사용하는 AI 도구를 선택합니다.
• Install Selected Integrations를 클릭합니다.
• 선택 사항으로 Install Unity Project AGENTS.md Template을 클릭하여 루트(root)에 AGENTS.md를 생성합니다.

설치된 통합 기능(integrations)에는 고정된 CLI 경로, 스킬 라우팅 규칙(Skill routing rules), Unity 컴파일 체크, 콘솔 진단(Console diagnostics), C# 호환성 규칙 및 워크플로 체크리스트가 포함됩니다. 명령 참조(Command references)는 설치된 각 스킬(Skill)의 references/ 디렉토리 아래에 생성됩니다.

AIBridge가 CLI 캐시를 복사한 후, Unity 프로젝트 루트에서 명령을 실행하십시오:

$CLI = "./.aibridge/cli/AIBridgeCLI.exe"

macOS/Linux에서는 프로젝트 설정에 따라 번들된 플랫폼 실행 파일을 사용하거나 dotnet으로 DLL을 실행하십시오.

대부분의 명령은 다음 형식을 사용합니다:

$CLI <command> <action> [options]

CLI 전용 헬퍼(helpers)는 약간 다릅니다: focus는 액션(action)이 없으며, multi는 --cmd 또는 --stdin을 사용합니다.

$CLI focus
$CLI editor log --message "Hello" --logType Warning
$CLI editor get_state
...

Unity 검증을 위해 compile unity를 사용하십시오. compile dotnet은 추가적인 솔루션 빌드 확인용일 뿐이며, Unity 컴파일(compilation)을 대체하는 것이 아닙니다.

get_logs는 설정(Settings) 창의 기본값과 선택적인 정규 표현식(regex) 필터링을 지원합니다:

• 로그(Logs) 탭에서 기본 최소 로그 레벨(log level)과 선택적인 글로벌 정규 표현식 필터를 설정할 수 있습니다.
• --logType을 생략하면, get_logs는 설정 창의 기본 레벨 필터를 사용합니다.
• --regex를 전달하면, 해당 정규 표현식이 결과를 반환하기 전에 로그 메시지 텍스트에 적용됩니다.
• 글로벌 정규 표현식 필터는 로그 탭에서 활성화할 수 있으며, --regex가 제공되지 않을 때마다 적용됩니다.

$CLI asset search --mode script --keyword "Player" --format paths
$CLI asset find --filter "t:Prefab" --format paths
$CLI asset get_path --guid "abc123..."
...

$CLI gameobject create --name "MyCube" --primitiveType Cube
$CLI gameobject find --withComponent "Rigidbody" --maxResults 20
$CLI gameobject set_active --path "Player" --active true
...

$CLI inspector get_components --path "Player"
$CLI inspector get_properties --path "Player" --componentName "Transform"
$CLI inspector find_property --path "Player" --componentName "Rigidbody" --keyword "mass"
...

간단한 프리팹(prefab) 필드 편집의 경우, assetPath + objectPath + componentName과 함께 inspector set_property를 사용하십시오. 여러 단계의 프리팹 편집이 필요한 경우, prefab patch --ops <file>을 사용하고 먼저 --dryRun true를 실행하십시오.

PowerShell JSON 팁:

$values = (@{ 'm_LocalPosition.x' = 0; 'm_LocalPosition.y' = 1 } | ConvertTo-Json -Compress) -replace '"', '\"'
& "./.aibridge/cli/AIBridgeCLI.exe" inspector set_properties --assetPath 'Assets/Prefabs/Player.prefab' --componentName Transform --values $values

$CLI batch from_text --text "call editor log 'Hello'\ndelay 1000"
$CLI batch from_file --file ".aibridge/scripts/setup_scene.txt"
$CLI multi --cmd "editor log --message Step1&get_logs --logType Error --count 1"$

multi --stdin

긴 스크립트나 JSON 기반 명령의 경우 다음을 사용하세요:

$script = @'
editor log --message "Start"
delay 1000
...

$CLI gameview get_resolution
$CLI gameview set_resolution --width 1920 --height 1080
$CLI gameview list_resolutions
...

게임 뷰 스크린샷 및 GIF 캡처는 Play Mode가 필요합니다.

• 실제 Unity 에셋 또는 오브젝트 경로를 확인합니다.
• 씬(scene), 프리팹(prefab), 컴포넌트(component) 또는 SerializedProperty 상태를 검사합니다.
• Unity 인식 명령이나 소스 편집을 통해 가장 작은 안전한 변경 사항을 적용합니다.
• 실행
  compile unity

. - 읽기
get_logs --logType Error

. - 시각적 변경에는 스크린샷 또는 GIF를 사용합니다.

Editor/ Unity Editor 명령, 설정 창(settings window), 통합 기능, 프리팹 패치
Runtime/ 런타임 브릿지 계약 및 경량 런타임 데이터
Tools~/ AIBridgeCLI 소스 및 번들링된 플랫폼 바이너리
...

MIT 라이선스. LICENSE 참조.

이슈(Issues)와 풀 리퀘스트(pull requests)를 환영합니다. Unity 관련 동작을 변경할 때는 관련 CLI 예제, Skill 참고 자료, 그리고 검증 노트를 업데이트하세요.