Quick Flow

• 기준은 Unity 6.5 (6000.5)이며, 재현 가능한 CI·빌드·테스트의 기준선은 공식 Unity command line입니다. 열린 Editor 상태를 조작하는 unity-cli나 MCP는 그 기준선을 대체하지 않고, 개발 중 조회·짧은 도구 호출을 덧붙이는 계층입니다.
• 자동화는 읽기 전용 확인 -> 제한된 변경 -> 공식 batch 검증 순서로 넓힙니다. exec, scene/asset 수정, arbitrary C# 실행은 모두 프로젝트를 바꿀 수 있는 쓰기 권한입니다.
• 외부 도구는 release/tag를 pin하고 빈 프로젝트에서 Unity Editor 버전·패키지·클라이언트 연결을 확인합니다. tool이 “성공”을 돌려도 Unity Console 오류와 Git diff가 없다는 뜻은 아닙니다.

# CI 기준선: static Editor method를 실행하고 실패는 non-zero로 끝냅니다.
"$UNITY" -batchmode -projectPath "$PROJECT" \
  -executeMethod BuildTools.BuildPlayer -quit -logFile "$LOG"

# Test Framework: -runTests와 -batchmode, 결과 파일을 함께 둡니다.
# Unity 6.5에서는 -quit을 함께 쓰면 진행 중인 테스트가 끝나기 전에 종료될 수 있습니다.
"$UNITY" -runTests -batchmode -projectPath "$PROJECT" \
  -testPlatform EditMode -testResults "$RESULTS"

공식 Command Line

• **-projectPath <path>**는 열 프로젝트를 고릅니다. 공백이 있는 경로는 따옴표로 묶습니다. CI가 다른 project를 열면 결과물·Library·test result가 모두 엉뚱한 위치에 생길 수 있습니다.
• **-batchmode**는 수동 입력 없이 실행하는 모드입니다. test/build 자동화에 기본으로 두고, 모든 Console 출력은 **-logFile <path>**에 남깁니다. macOS와 Linux에서 Editor 실행 파일 경로도 runner가 설치한 Unity 버전과 일치하는지 확인합니다.
• **-executeMethod Namespace.Class.Method**는 project open 뒤 static method를 실행합니다. method는 Editor 폴더의 assembly에 있어야 하고 static이어야 합니다. 예외를 던지거나 EditorApplication.Exit(nonZero)를 호출해야 shell이 실패를 감지합니다. instance method나 Runtime assembly method를 지정하면 CI entry point가 되지 않습니다.
• -runTests, -testPlatform, **-testResults**는 Test Framework runner에 넘깁니다. 결과 XML을 artifact로 보관해야 CI 화면의 exit code만으로 놓친 실패를 다시 확인할 수 있습니다. Unity 6.5 문서는 -runTests와 -quit을 함께 주면 테스트가 끝나기 전에 Editor가 종료될 수 있다고 경고하므로, test command에는 -quit을 기계적으로 붙이지 않습니다.
• command line argument와 Editor version은 함께 고정합니다. Unity 업그레이드 때는 한 번의 local batch run으로 Library migration, package resolve, build profile, return code, result XML 경로를 확인한 뒤 CI image를 바꿉니다.

unity-cli와 MCP 연결

• unity-cli는 실행 중인 Editor에 로컬 connector를 통해 연결하는 third-party CLI입니다. 2026-08-10에 확인한 upstream README는 binary 설치 뒤 com.youngwoocho02.unity-cli-connector git package를 추가하고, status, console, editor, test, exec 같은 명령을 제공합니다. Connector URL은 tag를 붙여 pin하고 CLI와 Connector의 version mismatch를 무시하지 않습니다.
• unity-cli status와 unity-cli console --type error,warning은 읽기 전용 출발점입니다. unity-cli exec는 UnityEditor와 loaded assembly를 포함한 arbitrary C#을 실행할 수 있으므로, one-off 편의 기능이 아니라 full write 권한으로 취급합니다. 실행 전 Git status를 확인하고, 변경 뒤 Console과 scene/asset diff를 검사합니다.
• MCP는 특정 제품명이 아니라 protocol입니다. 예로 CoplayDev unity-mcp의 2026-08-10 README는 Unity 2021.3 LTS부터 6.x, Python 3.10+, MCP client 연결을 요구하고 v10.0.0 package tag 설치를 안내합니다. 다른 MCP server는 설치 방법·tool 이름·권한 model이 다르므로 이 수치를 일반화하지 않습니다.
• MCP server를 연결할 때는 tool catalog에서 read-only query와 write tool을 분리합니다. asset delete, script edit, scene mutation, build 실행을 처음부터 모두 허용하지 말고, project 범위·허용 tool group·실행 후 검증 명령을 명시합니다. server가 domain reload 뒤 재연결되는지도 실제 프로젝트에서 확인합니다.

읽기 전용: status, console read, scene/asset query
제한된 쓰기: 명시한 menu command, 테스트 실행, 특정 build method
고위험 쓰기: arbitrary C# exec, asset 삭제, scene 대량 수정

고위험 쓰기는 Git clean/branch 확인 -> 실행 -> Console 확인 -> diff 검토 순서

실패와 복구

• Editor가 compiling·domain reload·play mode transition 중이면 interactive tool의 응답이 늦거나 실패할 수 있습니다. retry를 무한 반복하지 말고 status, Console, Editor busy state를 확인하고 기다립니다. CI는 같은 작업을 새 process의 official command line으로 재현할 수 있어야 합니다.
• 여러 Unity instance가 열려 있으면 CLI/MCP가 다른 프로젝트에 붙을 위험이 있습니다. --project 또는 server의 project routing을 명시하고, command output의 project path와 Unity version을 매번 확인합니다.
• tool update는 기능 추가가 아니라 compatibility 변경일 수 있습니다. Connector package, CLI binary, MCP server, client config를 한꺼번에 갱신하지 말고 하나씩 pin을 바꿔 smoke test와 Unity batch test를 통과시킵니다.