emu-lab
# unity-emu-lab
[English](README.en.md) · [변경 기록](CHANGELOG.md)
Unity 빌드를 내 PC에서 실제로 띄워 **사람·AI 에이전트가 직접 자체 테스트**하는 도구.
- **Android**: 에뮬레이터에 설치해 앱 안(로그 마커·탭 입력)과 앱 밖(시스템 대화상자·알림창·알림 탭 복귀)을 확인한다.
- **WebGL**: 로컬 서버로 띄워 Chrome/Edge를 DevTools 프로토콜로 조종한다(PowerShell 스크립트만).
두 가지 형태로 쓴다.
| 형태 | 하는 일 | 실행 환경 |
|---|---|---|
| npm 패키지 `unity-emu-lab` (MCP 서버 + `emu-lab` CLI) | Android: 에뮬레이터 임대, 기동·놓기, 스모크, 앱 밖 알림 확인, 기기 시계, 스크린샷. APK를 받는다 | Node.js 22.18+, Windows·macOS·Linux |
| PowerShell 스크립트 (`scripts/`) | 위 기능 + Unity batchmode 빌드, 프로젝트 보호(`project-guard`), WebGL 스모크, SDK 설치·점검 | Windows PowerShell 5.1 |
둘은 같은 임대 파일(`~/.emu-lab/leases/<AVD>.json`)을 써서, 함께 돌아도 서로의 임대를 존중한다.
## npm 패키지 (MCP 서버 + CLI)
### 무엇이 다른가
기기 조작 MCP(`@mobilenext/mobile-mcp`, `appium-mcp` 등)는 스크린샷·탭을 AI에게 넘긴다. 이 패키지는 그 대신 다음을 한다.
- **여러 세션이 기기 하나를 나눠 쓰기**: 임대를 잡고·연장하고·놓는다. 남의 유효한 임대가 있으면 기기를 건드리기 전에 `BUSY`로 멈춘다. 놓을 때는 이 임대가 띄운 에뮬레이터만 끄고, 이 임대에서 설치한 앱만 지운다.
- **Unity 빌드 판정**: logcat의 준비 마커, 크래시·ANR과 「앱이 스스로 끝남」(안티치트·무결성·에뮬레이터 감지)을 구분한다. 설치 전에 APK의 ABI를 보고 ARM 전용 빌드를 먼저 알린다. 전체화면 첫 안내·권한 대화상자는 자동으로 누른다.
- **앱 밖 확인**: 알림이 시스템에 게시됐는지 → 알림창에 그려졌는지 → 탭하면 앱이 열리는지 본다. 기기 시계를 앞당겨 몇 시간 뒤 알림을 바로 확인하고, 끝나면(실패해도) 되돌린다.
mobile-mcp와 같이 써도 된다. 다만 둘 다 UiAutomation을 쓰므로 스모크·알림 확인이 도는 동안에는 mobile-mcp로 기기를 조작하지 않는다.
### 준비물
- [Node.js](https://nodejs.org/) 22.18 이상
- Android SDK의 `platform-tools`(adb)·`emulator`와 AVD 하나(기본 이름 `unity-test`). Windows는 `scripts\setup-android-sdk.ps1`로 만든다(아래 [처음 한 번](#처음-한-번)). 다른 AVD는 `--avd <이름>`(MCP는 `avd`)이나 `EMU_AVD`로 고른다.
- Unity 6 Android 플레이어는 ARM 라이브러리만 있다. API 35 `google_apis` x86_64 이미지(ARM 변환 내장)나 Apple Silicon의 arm64 이미지에서 돈다. Mono·ARMv7 전용 빌드는 못 돈다(스모크가 설치 전에 `ABI_MISMATCH`로 알린다).
### 설치와 등록
```bash
npm install -g unity-emu-lab
emu-lab status
```
`emu-lab status`는 아무것도 바꾸지 않고 임대·에뮬레이터·adb·SDK 경로와 그 출처를 보여 준다.
MCP 서버 명령은 `emu-lab serve`다(인자 없이 실행해도 표준 입력이 터미널이 아니면 서버로 뜬다). Windows에서는 `.cmd`를 바로 실행하지 못하는 클라이언트가 많아 `cmd /c`로 띄운다.
**Claude Code**
```bash
claude mcp add emu-lab -s user -- emu-lab serve # macOS·Linux
claude mcp add emu-lab -s user -- cmd /c emu-lab serve # Windows
```
**Codex** (`~/.codex/config.toml`)
```toml
[mcp_servers.emu-lab]
command = "emu-lab" # Windows: command = "cmd", args = ["/c", "emu-lab", "serve"]
args = ["serve"]
startup_timeout_sec = 60
```
**Cursor** (`~/.cursor/mcp.json`) / **Claude Desktop** (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"emu-lab": { "command": "cmd", "args": ["/c", "emu-lab", "serve"] }
}
}
```
위는 Windows 예다. macOS·Linux에서는 `"command": "emu-lab", "args": ["serve"]`로 쓴다. 설치 없이 `npx -y unity-emu-lab@<버전> serve`로 띄워도 된다(첫 실행은 내려받느라 느리다).
### 빠른 사용 (CLI)
```bash
emu-lab start # 임대를 잡고 에뮬레이터를 띄운다(이미 떠 있으면 다시 쓴다)
emu-lab smoke app.apk --ready-marker "<첫 화면 로그>" --no-tap-check --notif-delay 0
emu-lab release --uninstall # 기기 정리, 이 임대가 설치한 앱 제거, 이 임대가 띄운 에뮬레이터 종료
```
- 결과는 `~/.emu-lab/runs/<시각>-smoke-<pid>/`(`summary.json`, `logcat.txt`, `unity.txt`, PNG)에 쌓인다. `--out <폴더>`로 바꾼다.
- 스모크의 기본값은 이 저장소 샘플 앱의 로그 줄이다(`SMOKE_APP_READY`, `SMOKE_TAP count=1`, `SMOKE_NOTIF_SCHEDULED id=<n> title=<제목>`, `SMOKE_OPENED_FROM_NOTIFICATION`, 알림 20초). 다른 앱은 `--ready-marker`를 주고, 탭 로그가 없으면 `--no-tap-check`, 알림 예약 로그가 없으면 `--notif-delay 0`을 준다.
- 몇 시간 뒤 알림: `--notif-delay 7200 --time-travel 185`(비정확 알람은 최대 1시간 늦으니 예약 시간 + 60분 이상). 스모크가 끝나면 시계를 되돌린다.
- 따로 확인: `emu-lab notification --package <id> --title "<제목 일부>" --tap`, `emu-lab clock forward <분>` → `emu-lab clock reset`, `emu-lab screenshot [파일]`.
- 전체 옵션은 `emu-lab help`. 종료 코드는 0 성공, 1 실패·거부(`BUSY`, `NO_LEASE` 등), 2 사용법 오류.
- CLI는 임대 없이 기기 명령을 돌리면 `LEASE_NONE` 경고만 내고 진행한다(사람이 직접 돌릴 때). `--strict`면 거부한다. MCP 도구는 늘 엄격하다.
### MCP 도구
| 도구 | 하는 일 |
|---|---|
| `emu_status` | 임대(주인·만료·유효 여부), 에뮬레이터, 부팅 상태, adb·SDK 경로. 아무것도 바꾸지 않는다 |
| `emu_start` | 임대를 잡고(같은 주인이면 연장, 만료된 임대는 넘겨받기) 에뮬레이터를 띄워 부팅을 기다린다. 애니메이션·전체화면 안내를 끄고, 앞당겨진 시계를 되돌린다 |
| `emu_renew` | 내 임대 연장 |
| `emu_release` | Firebase 디버그 속성·앞당긴 시계를 되돌리고, (선택) 이 임대에서 설치한 앱을 지우고, 이 임대가 띄운 에뮬레이터만 끄고 임대를 지운다 |
| `emu_smoke` | APK 설치 → 실행 → 준비 마커 → 탭 → (선택) 알림 확인·탭 복귀. `summary.json` 키는 PowerShell 스모크와 같다 |
| `emu_check_notification` | 앱 밖 알림 확인(게시 → 알림창 → 탭 복귀). 시작 이후 게시된 알림만 인정한다 |
| `emu_clock` | `forward`(분) / `reset` |
| `emu_screenshot` | 지금 화면을 이미지로 돌려준다. 임대가 없어도 된다 |
| `emu_job` | 오래 걸린 도구의 결과 받기 |
- 기기를 바꾸는 도구는 이 세션의 유효한 임대가 있어야 돈다(`NO_LEASE`). 남의 임대면 `BUSY`: 기다리거나 사람에게 알린다. 남의 임대 풀기(`--any-owner`)·만료 임대 버리기(`--stale`)는 사람만 CLI로 한다.
- `emu_start`·`emu_smoke`·`emu_check_notification`·`emu_release`는 작업(job)으로 돈다. `wait_sec`(기본 50초)까지 기다렸다가 안 끝나면 `job_id`를 돌려주고, `emu_job`으로 이어 받는다. Codex처럼 도구 제한 시간이 짧은 클라이언트도 끊기지 않는다.
- 한 서버에서 한 AVD에 기기를 바꾸는 작업은 하나씩만 돈다(`JOB_RUNNING`).
- 서버가 닫히면(클라이언트 종료, Ctrl+C) 이 서버가 앞당긴 시계를 되돌린다. 강제 종료로 남은 시계는 다음 `start`·`release`가 되돌린다.
### 임대
- 파일: `<EMU_LAB_HOME>/leases/<AVD>.json`(기본 `~/.emu-lab`). 새로 잡을 때 「없을 때만 만들기」라 두 세션이 동시에 잡아도 하나만 이긴다. 넘겨받기·연장·놓기는 `<AVD>.json.lock`을 잠깐 잡고 한다.
- 주인: `--owner` → `EMU_OWNER` → Claude Code 세션 `claude:<앞 8자>` → Codex 스레드 `codex:<끝 8자>` → `사용자@PC`. 대소문자는 가리지 않는다(PowerShell과 같음). 기본 4시간, 같은 주인이 다시 `start`하면 연장한다.
- 놓기(`release`)는 읽은 임대가 그새 바뀌었으면(남이 넘겨받음) `LEASE_CHANGED`로 멈추고 아무것도 안 한다.
- PowerShell 스크립트와 같은 형식이라, 한쪽이 잡은 임대를 다른 쪽이 `BUSY`로 존중한다(Windows에서 양쪽으로 시험함).
### 경로와 환경 변수
| 변수 | 뜻 |
|---|---|
| `EMU_LAB_HOME` | 임대·결과·에뮬레이터 로그·설정 폴더(기본 `~/.emu-lab`) |
| `EMU_AVD` | AVD 이름(기본 `unity-test`) |
| `EMU_OWNER` | 임대 주인 |
| `EMU_ADB` | adb 경로 |
| `ANDROID_SDK_ROOT`, `ANDROID_AVD_HOME` | SDK·AVD 위치. macOS·Linux는 `ANDROID_HOME`도 읽는다 |
`<EMU_LAB_HOME>/config.json`에 `sdkRoot`·`avdHome`·`adb`를 적어 둘 수도 있다(PowerShell의 `local.settings.json`과 같은 키). 순서는 환경 변수 → `config.json` → 기본 위치(Windows `%USERPROFILE%\Android\Sdk`, macOS `~/Library/Android/sdk`, Linux `~/Android/Sdk`)다.
Windows는 `ANDROID_HOME`을 일부러 무시한다(Android Studio의 SDK를 건드리지 않으려고).
같은 PC에서 Unity로 Android 빌드도 하면 adb를 하나로 맞춘다(`EMU_ADB`나 `config.json`의 `adb`에 Unity 내장 adb `<에디터>/Editor/Data/PlaybackEngines/AndroidPlayer/SDK/platform-tools/adb`). 버전이 다른 adb 둘이 섞이면 서버가 꺼졌다 다시 떠 logcat이 끊긴다. Unity의 Android 빌드는 끝날 때 adb 서버를 끄므로, 스모크 중에는 같은 PC에서 Android 빌드를 돌리지 않는다.
### 검증 범위
2026-11-20, Windows 10 + Node.js 24.18: 기기 없는 시험 281개(가짜 adb), PowerShell 5.1 스크립트와의 임대 상호 시험(양쪽 BUSY), Unity 6000.6.0f1 샘플 APK(IL2CPP ARM64)의 패키지·ABI 읽기.
실제 에뮬레이터(Android 15, API 35 `google_apis` x86_64)로 하는 npm 패키지 확인은 아직이다(같은 환경에서 PowerShell 스크립트는 확인함). macOS·Linux는 기기 없는 시험(CI)만 돌린다. 에뮬레이터 PASS는 실기기 인증이 아니다.
### 개발
```bash
git clone https://github.com/cyKim0115/unity-emu-lab.git
cd unity-emu-lab
npm install
npm link # emu-lab이 이 폴더의 TypeScript 소스를 빌드 없이 실행한다
npm test # 가짜 adb로 도는 시험(기기·에뮬레이터를 건드리지 않음)
npm run typecheck
```
npm 패키지에는 `bin/`과 컴파일된 `dist/`만 들어간다(`npm publish`가 `prepack`에서 빌드). 배포 절차: `CHANGELOG.md`에 버전·날짜 → `npm version <patch|minor|major>` → `npm publish`(2FA) → `npm view unity-emu-lab version`으로 확인한 뒤 `git push --follow-tags`.
## PowerShell 스크립트 (Windows)
검증: 2026-11-04, Windows 10 + Windows PowerShell 5.1, Unity 6000.6.0f1, Android 15(API 35) `google_apis` x86_64 AVD, Chrome 156.
### 공유받은 분께: AI에게 맡기기
저장소는 Unity 프로젝트 폴더와 그 git 저장소 **밖**에 받는다(예: `git clone <url> %USERPROFILE%\unity-emu-lab`). 그 폴더에서 쓰는 AI(Claude Code·Cursor·Codex)에게 이렇게 말하면 된다.
> 이 저장소의 AGENTS.md 절차대로 내 PC에 설치하고, 샘플로 확인한 다음 `<내 Unity 프로젝트 경로>`에 붙여 Android(또는 WebGL) 빌드·테스트까지 해줘.
AI는 `AGENTS.md`를 따른다(Claude Code는 `CLAUDE.md`가 이를 불러온다). 아래는 **사람이 직접 하는 일**이다. AI가 `scripts\doctor.ps1` 결과의 `[HUMAN]` 줄로 알려 준다.
| 할 일 | 언제 |
|---|---|
| Unity Hub에서 프로젝트 버전 에디터 + **Android Build Support**(OpenJDK, Android SDK & NDK Tools) / **WebGL Build Support** 모듈 설치 | 없을 때 |
| 샘플 확인용 **Unity 6000.6.0f1**(정확한 버전, Hub 아카이브) + 쓸 대상 모듈 설치. 건너뛰려면 AI에게 「샘플 확인은 생략」 | 샘플로 먼저 확인할 때 |
| Android SDK 설치용 **JDK 17**: Unity 6 에디터(OpenJDK 17) + Android Build Support, 또는 Unity External Tools·`JAVA_HOME`의 JDK 17. 프로젝트가 2022.3이어도 필요 | JDK 17이 없을 때 |
| BIOS의 CPU 가상화, Windows 기능 **Windows 하이퍼바이저 플랫폼** 켜기(관리자, 재부팅) | Android 에뮬레이터 가속이 안 될 때 |
| **Android SDK 라이선스 동의**(AI가 묻는다. 약 1.5GB 다운로드, SDK 약 4.5GB + AVD 최대 약 10GB) | Android를 처음 쓸 때 |
| 오래 걸리는 단계를 기다리기: SDK 설치 5~20분, 샘플 첫 실행 3~6분, 프로젝트 빌드 최대 40분(기본 제한) | 설치·빌드 때 |
| (Claude Code에서 mobile-mcp를 쓸 때) `claude` 실행 중 프로젝트 MCP 승인 | 선택 |
| (Codex에서 mobile-mcp를 쓸 때) 전역 `~/.codex/config.toml`에 mobile-mcp 추가 승인(모든 Codex 세션에 적용) | 선택 |
| 다른 에뮬레이터(Android Studio 개인 AVD 등)가 떠 있으면 닫기. 스크립트는 AVD `unity-test`만 건드린다 | Android 테스트 때 |
| 빌드 전 사용자 프로젝트의 작업 중 변경을 커밋·stash할지, 빌드가 바꾼 파일을 되돌릴지 결정(AI가 묻는다) | 프로젝트에 붙일 때 |
필요한 것: Windows 10/11 x64(Windows on ARM은 WebGL만), RAM 16GB 이상 권장, 디스크 여유 약 20GB, Chrome 또는 Edge(WebGL), git, Node.js 20+(mobile-mcp를 쓸 때만).
Python·Node·Playwright 없이 PowerShell 5.1만으로 돈다.
### 구성
| 경로 | 역할 |
|---|---|
| `AGENTS.md`, `CLAUDE.md` | AI가 따를 설치·적용 절차와 규칙 |
| `package.json`, `src/`, `bin/`, `test/` | npm 패키지 `unity-emu-lab`(MCP 서버 + `emu-lab` CLI, 위 「npm 패키지」). `npm test`는 가짜 adb로 돈다 |
| `scripts/doctor.ps1` | 새 PC 사전 점검(바꾸는 것 없음). 가상화·Unity 모듈(External Tools 포함)·SDK·AVD 위치·디스크·브라우저·앱 가상화·이 저장소 위치·프로젝트 잠금·git을 `OK/TODO/HUMAN/WARN/FAIL`로 출력 |
| `scripts/setup-android-sdk.ps1` | 독립 Android SDK에 emulator·platform-tools·시스템 이미지 설치, AVD 생성. Unity에 딸린(또는 External Tools) JDK 17·cmdline-tools로 부트스트랩. `-SdkRoot`/`-AvdHome`은 `local.settings.json`(git 제외)에 남는다. `-Proxy host:port`. 끝 줄 `SETUP_DONE accel=ok`(0) 또는 `accel=missing`(2) |
| `scripts/start-emulator.ps1` | AVD 임대를 잡고(남이 잡고 있으면 `BUSY`로 멈춤, 같은 주인이면 연장) 부팅(기본 창 모드, 무음), 부팅 완료 대기, 애니메이션 끄기·전체화면 첫 안내 끄기, 이전 실행이 앞당겨 둔 시계 복구(`TIME_RESET`) |
| `scripts/release-emulator.ps1` | 임대 놓기: Firebase 디버그 모드·`log.tag.FA` 끄기, 앞당긴 시계 복구, (`-Uninstall`) 이 임대에서 설치한 앱 제거, 이 임대가 띄운 에뮬레이터만 끄기, 임대 파일 삭제. 남의 임대는 `-AnyOwner`, 시간이 지난 임대는 `-Stale`(사람만) |
| `scripts/build-unity.ps1` | Unity batchmode 빌드(`-Target Android\|WebGL`). `-Method`(빌드 메서드) 또는 `-BuildProfile`(Unity 6 빌드 프로필). 이번 빌드가 `-Out`에 새로 쓴 경우에만 `BUILD_OK`. 호출자가 죽으면 숨은 Unity도 끈다. 출력 기본값은 `artifacts\builds\<폴더>-<해시8>\`. `build-android.ps1`은 Android 단축 |
| `scripts/smoke-webgl.ps1` | WebGL 빌드를 로컬 서버로 띄우고 브라우저(임시 프로필, 무음)로 열어 준비 확인 → 캔버스 클릭 → 콘솔 오류·경고창·Unity 오류 배너 수집. 결과는 `artifacts\<시각>-webgl-<PID>\` |
| `scripts/serve-static.ps1`, `scripts/cdp.ps1` | 관리자 권한 없는 정적 서버(`.br`·`.gz`에 Content-Encoding), PowerShell 5.1용 DevTools 클라이언트 |
| `scripts/smoke-test.ps1` | 설치 → 실행 → 준비 마커 → 탭 → 홈 → 로컬 알림 확인 → 알림 탭 복귀. 결과는 `artifacts\<시각>-smoke-<PID>\` |
| `scripts/check-notification.ps1` | 앱 밖에서 알림 확인: `dumpsys notification` → 알림창 펼치기 + `uiautomator dump` → (옵션) 탭해서 앱 복귀 |
| `scripts/time-travel.ps1` | 기기 시계를 앞당겨 몇 시간 뒤 알림을 바로 확인. `-Reset`으로 복구(두 번 해도 된다) |
| `scripts/run-all.ps1` | 부팅 → 빌드 → 스모크 한 번에. 다른 대상의 옵션을 섞으면 시작 전에 멈춘다 |
| `scripts/watch-parent.ps1` | 감시 프로세스: 호출자가 강제 종료되면 서버·브라우저·logcat(`-Match`), 숨은 Unity(`-ChildPid`)를 끄고 기기 시계를 되돌린다(`-ResetClock`) |
| `sample/EmuSmoke` | 검증용 Unity 6.6 프로젝트(Mobile Notifications 2.5.0, OnGUI, `SMOKE_*` 로그 마커) |
| `scripts/project-guard.ps1` | 사용자 프로젝트 빌드 전후 보호: `Snapshot`(첫 빌드 전 한 번. 작업 중 변경 기록, 추적 파일만 패치 백업) → `Report`(빌드가 바꾼 것) → 동의 후 `Revert`(Report에 있던 빌드 변경만 되돌리고 새 파일은 백업으로 이동, 남길 파일은 `-Keep`). 두 번째 Snapshot은 그사이 변경이 있으면 `-Replace` 없이 멈추고, Unity가 프로젝트를 잡고 있거나 Report 뒤 내용·커밋이 바뀌면 Report·Revert가 멈춘다. Revert 뒤 기록은 보관 처리. 한글·공백·대괄호 경로, 하위 폴더 프로젝트 지원 |
| `templates/EmuProjectBuild.cs`, `templates/EmuLab.Editor.asmdef` | 빌드 메서드가 없는 사용자 프로젝트용 batchmode 빌드 진입점(Unity 2021.2+). 동의 후 두 파일을 **새 폴더** `Assets/EmuLab/Editor/`에 복사, 커밋하지 않음. 켜진 씬을 현재 설정으로 빌드하고, 그 빌드 동안만 AAB·Export Project·ABI별 분할을 끄고 되돌린다. 키스토어 암호가 없으면 디버그 서명. Mono 프로젝트는 `-EmuArm64`로 그 빌드만 IL2CPP + ARM64 |
| `.mcp.json`, `.cursor/mcp.json` | 에이전트용 `mobile-mcp`(1.0.12): 스크린샷·탭·스와이프·요소 목록·앱 설치. Codex는 전역 설정이라 사용자 승인 후 추가(`AGENTS.md`) |
Unity 에디터는 `UNITY_EDITOR_ROOT`, Unity Hub 설치 위치(Preferences > Installs), 기본 위치(`C:\Program Files\Unity\Hub\Editor`), Hub에 「Locate」로 추가한 에디터 순으로 찾는다. 같은 버전이 두 곳에 있으면 앞의 것을 쓴다.
Android SDK는 `ANDROID_SDK_ROOT` → `local.settings.json`의 `sdkRoot` → `%USERPROFILE%\Android\Sdk`, AVD는 `ANDROID_AVD_HOME` → `avdHome` → `%USERPROFILE%\.android\avd` 순이다.
`ANDROID_HOME`은 일부러 무시한다(Android Studio가 `%LOCALAPPDATA%\Android\Sdk`로 두는 경우가 많고, 그 SDK의 emulator를 바꾸지 않으려고). 결과는 `artifacts\`(git 제외)에 쌓인다.
adb는 `EMU_ADB` → `local.settings.json`의 `adb` → SDK의 `platform-tools\adb.exe` 순이다. 같은 PC에서 Unity로 Android 빌드도 하면 Unity 내장 adb(`<에디터>\Editor\Data\PlaybackEngines\AndroidPlayer\SDK\platform-tools\adb.exe`)를 고른다. 버전이 다른 adb 둘이 섞이면 서버가 꺼졌다 다시 떠 logcat 수집이 끊긴다. 에뮬레이터는 adb 버전과 상관없이 붙는다.
PowerShell 스크립트는 ASCII만 쓴다(Windows PowerShell 5.1이 BOM 없는 파일을 CP949로 읽음).
adb 출력은 UTF-8로 읽는다(콘솔 코드 페이지 CP949로 읽으면 한글 알림 제목이 깨진다).
에뮬레이터·logcat 같은 오래 사는 자식 프로세스는 `cmd`를 거쳐 띄운다. `Start-Process -Redirect*`로 띄우면 호출자의 출력 파이프를 물려받아,
출력을 받는 호출자(CI, 에이전트, `| Tee-Object`)가 에뮬레이터가 꺼질 때까지 끝나지 않는다.
### 처음 한 번
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\doctor.ps1 -Target Android
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\setup-android-sdk.ps1 -AcceptLicenses
```
`-Target`은 쓰는 대상만 준다(`Android`, `WebGL`, 둘 다 `Both`). 프로젝트까지 보려면 `-ProjectPath <프로젝트>`, 샘플 확인을 건너뛰려면 `-NoSample`.
`-AcceptLicenses`는 Android SDK 라이선스 동의다. 받는 양: emulator 약 1.0GB, 시스템 이미지 약 3.5GB(압축 해제 기준).
### 매번
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run-all.ps1
```
결과 예(2026-11-04 실측): 첫 빌드 99초·증분 22~66초(IL2CPP ARM64, 22.4MB), 실행 0.9~4.9초, 20초 예약 알림 25~34초에 게시, 알림창 표시·탭 복귀 PASS.
출력을 캡처하는 호출(`$r = powershell -File scripts\run-all.ps1 -AskPermission`)로 빌드부터 권한 대화상자 자동 허용까지 118초에 끝났다.
다 쓰면 놓는다(Android):
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\release-emulator.ps1 -Uninstall
```
#### 임대 (한 번에 한 세션)
에뮬레이터는 PC에 하나라, 두 세션(사람·AI)이 동시에 설치·탭하면 서로의 테스트를 망친다. 그래서 unity-slot처럼 잡고 놓는다.
- `start-emulator.ps1`(`run-all.ps1`이 부름)이 `%USERPROFILE%\.emu-lab\leases\<AVD>.json`을 `CreateNew`로 만든다. 두 세션이 동시에 만들어도 하나만 이긴다. 위치는 `EMU_LAB_HOME`으로 옮길 수 있다.
- 주인: `-Owner` → `EMU_OWNER` → Claude Code 세션 `claude:<앞 8자>` → Codex 스레드 `codex:<끝 8자>` → `사용자@PC`(unity-slot과 같은 규칙). 기본 4시간(`-Hours`), 같은 주인이 다시 부르면 연장한다. 시간이 지난 임대는 다음 `start-emulator.ps1`이 넘겨받는다.
- 남의 유효한 임대가 있으면 `start-emulator`·`smoke-test`·`check-notification`·`time-travel`(앞당기기)이 기기를 건드리기 전에 `BUSY`로 멈춘다. 임대 없이 돌리면 `LEASE_NONE` 경고만 내고 진행한다(사람이 직접 돌릴 때).
- `smoke-test.ps1`은 설치한 패키지를 임대에 적어 두고, `release-emulator.ps1 -Uninstall`이 그 앱(과 데이터)을 지운다. 빼면 `KEPT apps ...`로 남긴 앱을 알린다.
- `release-emulator.ps1`은 임대를 잡을 때 이미 떠 있던 에뮬레이터는 끄지 않는다. 이 임대가 띄운 인스턴스(pid·시작 시각으로 확인)만 `emu kill`한다. `-KeepRunning`이면 그것도 둔다.
#### WebGL
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run-all.ps1 -Target WebGL
```
필요한 것: Unity의 WebGL Build Support 모듈, Chrome 또는 Edge. 추가 설치(Python·Node·Playwright)는 없다.
결과 예(2026-11-04 실측): 개발 빌드 43초(32.7MB), 준비 2.6초, 캔버스 클릭 PASS, 전체 54초.
릴리스 빌드 Brotli(4.7MB)·Gzip(6.1MB) 모두 http://localhost에서 그대로 떴다(Chrome 156).
- 준비 판정: 기본은 콘솔 로그 `-ReadyMarker`. 로그가 없는 프로젝트는 `-ReadyMode Loaded`(Unity 기본 템플릿의 로딩바가 사라지면 준비, 커스텀 템플릿이면 마커를 쓴다).
페이지가 상태를 노출하면 `-ReadyMode Expression -ReadyExpression "<JS>"`, 탭 결과는 `-TapExpression "<JS>" -TapTimeoutSec <초>`,
페이지 자체 오류 UI는 `-FailExpression "<오류일 때 문자열을 돌려주는 JS>"`, 기록할 값은 `-InfoExpression "<JS>"`(식 안에서는 작은따옴표).
- 실패 판정: 잡히지 않은 예외, 렌더러 크래시, 경고창(Unity 로더는 치명 오류를 `alert()`로 띄움, 자동으로 닫고 기록), Unity 오류 배너,
`/Build/` 파일 4xx·5xx, wasm 준비 실패, WebGL 컨텍스트 실패. 고장 낸 빌드(.wasm 삭제)로 4초 만에 FAIL 나는 것을 확인했다.
- 옵션: `-Headless`(창 없이), `-Width/-Height`(뷰포트), `-TapX/-TapY`(캔버스 비율), `-NoTap`, `-NoTapCheck`, `-Browser <exe>`,
`-ReadyTimeoutSec`, `-KeepProfile`(임시 브라우저 프로필을 지우지 않음, 기본은 실행 뒤 삭제). `run-all.ps1`도 같은 이름으로 넘겨준다(모르는 옵션은 오류).
- 서버는 Unity Build And Run 서버처럼 COOP/COEP/CORP 헤더를 보낸다. 멀티스레드 빌드가 SharedArrayBuffer를 쓸 수 있다.
커스텀 템플릿이 CORP/CORS 없는 외부 파일을 불러오면 `-NoIsolation`으로 끈다.
`.br`·`.gz` Content-Encoding은 Unity 빌드 파일(`*.data|js|wasm|symbols.json`)에만 붙인다. 동시 요청과 Range 요청(동영상)도 처리한다.
- 호출자가 강제 종료돼도 감시 프로세스(`watch-parent.ps1`)가 서버·브라우저·logcat을 정리한다. 결과 폴더는 `artifacts\<시각>-<종류>-<PID>\`.
- 샘플 빌드 옵션: `-Release`(개발 빌드 아님, WebGL은 이때만 압축), `-WebGLCompression brotli|gzip|disabled`(그 빌드에만 적용, ProjectSettings는 원래대로 되돌림).
- 다른 프로젝트: `run-all.ps1 -Target WebGL -SkipBuild -BuildDir <빌드 폴더> -ReadyMode Loaded -NoTapCheck`.
- 탭이 먹을 때까지 다시 탭: `-TapExpression "<탭이 먹혔을 때 참>" -TapRetrySec 5 -TapTimeoutSec 60`, 그 뒤 기다릴 상태는 `-AfterTapExpression`·`-AfterTapTimeoutSec`. 마지막 대기 `-SettleSec`(기본 2초) 뒤 `03-final.png`.
##### 예: 상태를 노출하는 커스텀 템플릿
WebGL 템플릿이 진행 상태를 `window.app.stage`(`loading` → `title` → `playing`)로 노출하고, 오류는 `#error` 요소에 보여 준다고 하자.
타이틀이 인트로 동안 입력을 무시해서 탭이 먹을 때까지 다시 탭하고, 탭 뒤 `playing`이 될 때까지 기다린다.
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\smoke-webgl.ps1 -BuildDir <out> -NoIsolation -SettleSec 10 -ReadyTimeoutSec 240 `
-ReadyMode Expression -ReadyExpression "window.app && window.app.stage === 'title'" `
-TapX 0.5 -TapY 0.6 -TapExpression "window.app && window.app.stage !== 'title'" -TapRetrySec 5 -TapTimeoutSec 60 `
-AfterTapExpression "window.app && window.app.stage === 'playing'" -AfterTapTimeoutSec 120 `
-FailExpression "document.querySelector('#error') && getComputedStyle(document.querySelector('#error')).display !== 'none' && document.querySelector('#error').innerText.slice(0, 300)"
```
- `-ReadyExpression`: 타이틀이 뜨면 준비로 본다.
- `-TapExpression` + `-TapRetrySec`: 상태가 `title`에서 벗어날 때까지 5초마다 다시 탭한다(최대 60초).
- `-AfterTapExpression`: 탭 뒤 게임 화면(`playing`)까지 기다린다.
- `-FailExpression`: 템플릿 오류 UI가 보이면 그 글을 실패 이유로 남긴다.
- `-NoIsolation`: 배포처(GitHub Pages 등)가 COOP/COEP를 보내지 않는 단일 스레드 빌드면 같은 조건으로 맞춘다.
- 빌드가 프로젝트 파일을 바꿔 놓으면 `scripts\project-guard.ps1`(Snapshot → Report → 동의 후 Revert)로 되돌린다(`AGENTS.md` 규칙 5).
몇 시간 뒤 알림(샘플처럼 앱이 예약 로그를 남길 때):
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\smoke-test.ps1 -Apk <apk> -NotifDelay 7200 -TimeTravelMinutes 185
```
### 다른 프로젝트에 붙이기 (Android)
빌드 전후는 `project-guard.ps1`로 감싼다(첫 빌드 전 `Snapshot`, 마지막 빌드 뒤 `Report`, 동의 후 `Revert`. `AGENTS.md` 규칙 5).
1. 빌드: 그 프로젝트가 에디터에 열려 있으면 batchmode가 막힌다(`Temp\UnityLockfile`. doctor·build-unity가 잡고 있는 프로세스를 알려 준다).
에디터를 닫고 `run-all.ps1 -ProjectPath <p> -Method <Class.Method>`(또는 `-BuildProfile <asset>`)로 빌드부터 하거나,
열린 에디터에서 빌드(Build Profiles 창 또는 unityMCP `manage_build`)한 APK를 `-SkipBuild -Apk`로 넘긴다.
출력 기본값은 이 저장소 `artifacts\builds\<폴더>-<해시8>\Android\app.apk`(프로젝트 밖)다. Mono·ARMv7 프로젝트는 템플릿 + `-EmuArm64`.
패키지 이름은 APK에서 읽는다(aapt2). `-Package`를 주면 APK와 맞는지 확인한다.
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run-all.ps1 -SkipBuild -Apk <apk> -ReadyMarker "<로그>" -NoTapCheck -NotifDelay 0
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run-all.ps1 -ProjectPath <p> -Method EmuProjectBuild.BuildApk -EmuArm64 -ReadyMarker "<로그>" -NoTapCheck -NotifDelay 0
```
2. 준비 신호: `-ReadyMarker "<첫 화면이 뜰 때 찍히는 로그>"`. 없으면 첫 화면에서 `Debug.Log` 한 줄을 추가한다.
3. 탭: `-TapX/-TapY`(회전 반영한 현재 화면 비율)로 위치를 정한다. 확인은 `-TapMarker "<탭 로그>"`(기본 `SMOKE_TAP count=1`은 샘플만 찍는다). 탭 로그가 없으면 `-NoTapCheck`, 탭 자체를 빼려면 `-NoTap`.
4. 알림: 앱이 예약 때 로그를 남기면 `-NotifScheduledRegex "<정규식, 1번 그룹 = 제목>"`(예: `"Scheduled notification: (.+)"`)으로 스모크가 자동 확인한다.
알림 탭 뒤 열림은 `-OpenedMarker "<로그>"`, 그런 로그가 없으면 `-NoOpenedMarker`(앞에 뜬 화면으로 판단). 이때만 `-TimeTravelMinutes`를 쓴다.
예약 로그가 없으면 `-NotifDelay 0`으로 스모크에서 빼고, 게임에서 알림을 예약한 뒤 `check-notification.ps1 -Package <id> -Title "<알림 제목 일부>" -Tap`으로 따로 확인한다.
- 제목은 와일드카드 없는 부분 문자열이다. 한글·대괄호(`[이벤트]`) 제목도 된다.
- 스크립트를 시작한 시각 이후에 게시된 알림만 인정한다(같은 제목의 옛 알림으로 통과하지 않게). 이미 게시된 알림을 보려면 `-SinceMs <기기 epoch ms>`를 준다.
- `-Tap`이면 앱이 앞에 떠 있을 때 먼저 홈으로 보낸 뒤 알림을 탭한다. 앱이 「알림으로 열림」 로그를 남기면 `-OpenedMarker "<로그>"`로 더 확실히 본다(logcat은 스크립트가 직접 받는다).
- 몇 시간 뒤 알림을 수동으로 볼 때: `time-travel.ps1 -Minutes <지연+60 이상>` → `check-notification.ps1` → 결과와 상관없이 `time-travel.ps1 -Reset`.
5. 권한 대화상자까지 보려면 `-AskPermission`(이전 실행의 알림 권한을 회수하고 대화상자가 다시 뜨게 함, 「Allow」는 자동 탭).
6. `summary.json`의 `app_exited=true`는 앱이 크래시 없이 스스로 끝난 것이다(안티치트·무결성·에뮬레이터 감지, 시작 때 로그인·네트워크 확인). 그 확인을 끈 테스트 빌드가 필요하다.
### 이번에 확인한 함정
- **x86_64 이미지 + ARM 전용 APK**: Unity 6.6 Android 플레이어에는 x86_64 라이브러리가 없다(arm64-v8a/armeabi-v7a만).
API 35 이미지는 `abilist=x86_64,arm64-v8a`, native bridge(Berberis)로 ARM64 IL2CPP 빌드를 그대로 돌린다. Vulkan은 호스트 GPU로 동작(검증 PC는 NVIDIA).
- **첫 실행 「Viewing full screen」 안내**: 전체화면 앱 첫 실행 때 시스템 대화상자가 포커스를 가져갔고,
이번 실측(6000.6.0f1, GameActivity)에서는 포커스가 돌아올 때까지 첫 씬의 `Start()`가 돌지 않았다(CPU 0%, 마커 없음).
Unity 문서에 적힌 동작은 아니다.
`start-emulator.ps1`이 `immersive_mode_confirmations=confirmed`로 미리 끄고, `smoke-test.ps1`은 「Got it」「Allow」「OK」를 찾아 눌러 `system-dialogs.txt`에 남긴다.
- **비정확 알람의 1시간 창**: Mobile Notifications 기본값은 `AlarmManager.set(RTC_WAKEUP)`(비정확).
Android 15에서 2시간 뒤 예약은 `window=+1h` → 실기기에서도 최대 1시간 늦을 수 있다. 정확한 시각이 필요하면 Mobile Notifications 설정의 Exact scheduling을 검토(구글 플레이 정책 제약 있음).
- **AI 앱 안에서 설치하면 AppData가 가상화된다**: Claude 데스크톱 앱처럼 패키지(MSIX)로 설치된 앱 안의 에이전트가 `%LOCALAPPDATA%`에 쓰면,
실제로는 `AppData\Local\Packages\<앱>\LocalCache\Local\...`로 들어간다. 에이전트 셸에서는 보이지만 일반 터미널에서는 없다
(`adb.exe ... 인식되지 않습니다`). 그래서 SDK 기본 위치를 `%USERPROFILE%\Android\Sdk`로 둔다.
- **cmdline-tools 23의 avdmanager는 Java 17 이상**: sdkmanager는 Android CLI(자체 JRE)로 넘어가 JAVA_HOME과 상관없다. 그러나 avdmanager.bat는 Java 17 미만이면
메시지만 찍고 종료 코드 0으로 끝난다(AVD 없음). Unity 2023.x 이하의 OpenJDK는 11이라 SDK 설치는 Unity 6 에디터의 JDK로 한다(스크립트가 고르고, 없으면 미리 멈춘다).
- **ARMv7 전용 APK는 못 돈다**: x86_64 이미지는 `x86_64`·`arm64-v8a`만 돌린다. Mono 백엔드나 ARMv7만 체크한 빌드는 IL2CPP + ARM64로 테스트 빌드를 따로 만든다
(템플릿 + `-EmuArm64` 스위치: Mono·ARMv7 설정에서 `arm64-v8a` APK를 만들고 설정을 원래대로 되돌리는 것을 확인했다).
스모크는 설치 전에 APK의 ABI를 보고 먼저 알린다.
- **다른 에뮬레이터**: 스크립트는 `adb emu avd name`으로 AVD `unity-test`만 고른다. 다른 AVD만 떠 있으면 설정·시계를 건드리지 않고 멈춘다.
- **`-File` 인자 끝의 `\`**: `-ProjectPath "C:\Game\"`처럼 쓰면 PowerShell 5.1이 `\"`를 따옴표 글자로 읽어 뒤 인자를 삼킨다. 경로는 `\`로 끝내지 않는다(스크립트는 따옴표가 섞인 경로를 거부한다).
- **한글 프로젝트 경로(Android)**: Unity가 Android 빌드를 바로 거부한다(「Project path ... contains non-ASCII characters ... Android Tools don't work properly」). 프로젝트는 ASCII 경로에 둔다. WebGL은 같은 경로에서 빌드됐다.
- **대괄호 프로젝트 경로(Android)**: `C:\Work\Game [v2]`처럼 `[ ]`가 든 경로는 GameActivity의 CMake가 패턴으로 읽어 「No SOURCES given to target: game」으로 실패한다(Unity·CMake 쪽 제한). 스크립트·WebGL 빌드는 대괄호 경로에서 동작한다.
- **대괄호 경로**: PowerShell은 `Test-Path`·`Resolve-Path`에서 `[v2]`를 와일드카드로 읽어, `My Game [v2]` 안의 파일을 「없음」으로 본다. 스크립트는 모두 `-LiteralPath`로 다룬다.
- **증분 빌드의 옛 시각**: Unity 증분 빌드는 안 바뀐 파일(WebGL `index.html` 등)의 시각을 그대로 둔다. `build-unity.ps1`은 폴더 안 가장 새 파일과 크기·개수로 「이번 빌드가 썼는지」를 본다.
- **sdkmanager 입력**: PowerShell 파이프로는 라이선스 `y`가 안 들어간다 → `cmd /c ... < yes.txt`. cmdline-tools 23은 stderr로 사용 중단 경고를 낸다.
- **mobile-mcp 기기 ID**: `emulator-5554`가 아니라 AVD 이름(`unity-test`). Unity 화면은 접근성 트리에 `unitySurfaceView` 하나라 게임 안은 스크린샷+좌표로 다룬다.
- **mobile-mcp와 스크립트를 동시에 쓰지 않는다**: mobile-mcp는 기기 안에 `com.mobilenext.mobilecli.DeviceServer`(유휴 30분 유지)를 띄워 UiAutomation을 잡는다.
그동안 `uiautomator dump`는 종료 코드 137로 죽는다. 스크립트는 덤프가 실패하면 이 서버를 끄고 다시 시도한다(mobile-mcp는 다음 호출 때 다시 띄운다).
- **실패한 덤프의 옛 파일**: `uiautomator dump`가 실패해도 기기에 이전 XML이 남는다. 그 파일을 읽으면 지난 실행의 알림·대화상자를 보고 판단하게 된다.
`Get-UiDump`가 덤프 전에 파일을 지우고 「dumped to」 응답을 확인한다.
### 한계
- Unity는 에뮬레이터를 공식 지원하지 않는다. 성능·발열·GPU 드라이버 차이는 실기기에서 따로 본다(여기 수치는 ARM 변환 위 수치).
- iOS는 범위 밖(Windows에서 불가).
- 자동 실행·예약 작업은 만들지 않았다. 필요할 때 사람이 스크립트를 실행한다.
TDQS
Scored across 9 tools
Most tools target a distinct resource+action: status/screenshot are read-only, start/renew/release manage the lease, clock manages time, job polls async work. The only blur is between emu_smoke (which includes a notification shade check) and emu_check_notification, but the descriptions explain when to use each (self-test pipeline vs. externally triggered notification after a clock forward).
All tools share a consistent emu_ prefix and snake_case formatting, which makes the set highly predictable. There is minor mixing between noun-style names (emu_status, emu_clock, emu_screenshot, emu_job) and verb-style names (emu_start, emu_renew, emu_release, emu_check_notification), but the pattern is still readable.
Nine tools is well-scoped for an emulator lab server: lease lifecycle (status/start/renew/release), test operations (smoke/notification/clock/screenshot), and async job polling. Each tool earns its place with no obvious filler.
The surface covers the full lease lifecycle plus testing, time control, screenshots, and job polling, so core automation workflows have no dead ends. Minor gaps exist: no standalone install-APK tool outside emu_smoke, and no reboot/wipe/reset-device operation, though these are workaroundable or out of scope.