Skip to main content
Glama

unity-emu-lab

English · 변경 기록

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 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로 알린다).

설치와 등록

npm install -g unity-emu-lab
emu-lab status

emu-lab status는 아무것도 바꾸지 않고 임대·에뮬레이터·adb·SDK 경로와 그 출처를 보여 준다.

MCP 서버 명령은 emu-lab serve다(인자 없이 실행해도 표준 입력이 터미널이 아니면 서버로 뜬다). Windows에서는 .cmd를 바로 실행하지 못하는 클라이언트가 많아 cmd /c로 띄운다.

Claude Code

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)

[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)

{
  "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)

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는 실기기 인증이 아니다.

개발

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.

Related MCP server: orion-phone-mcp

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 설치 520분, 샘플 첫 실행 36분, 프로젝트 빌드 최대 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 -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 -NoProfile -ExecutionPolicy Bypass -File scripts\run-all.ps1

결과 예(2026-11-04 실측): 첫 빌드 99초·증분 2266초(IL2CPP ARM64, 22.4MB), 실행 0.94.9초, 20초 예약 알림 25~34초에 게시, 알림창 표시·탭 복귀 PASS. 출력을 캡처하는 호출($r = powershell -File scripts\run-all.ps1 -AskPermission)로 빌드부터 권한 대화상자 자동 허용까지 118초에 끝났다.

다 쓰면 놓는다(Android):

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 -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 -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 -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 -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에서 불가).

  • 자동 실행·예약 작업은 만들지 않았다. 필요할 때 사람이 스크립트를 실행한다.

Available Tools

9 tools
emu_check_notificationCheck a notificationA

Wait until a notification of the package whose title contains title is posted (dumpsys) and visible in the shade, optionally tap it and check the app opens (tap, opened_marker). Use it after the app scheduled a notification yourself (for example with emu_smoke notif_delay 0 and emu_clock forward). Needs this session's lease: NO_LEASE means emu_start first, BUSY means another session uses the emulator (wait or ask the person). Runs as a job: if the result is a job_id, call emu_job with it. Do not use mobile-mcp while it runs.

Inputs: title (required), package (required), avd, tap, +4 more.

emu_clockMove or reset the device clockA

action "forward" turns automatic time off and moves the device clock minutes ahead, so long-delay local notifications fire now (needs this session's lease: NO_LEASE means emu_start first). action "reset" puts the clock back to host time with automatic time on; it works without a lease and is refused only while another session holds the emulator (BUSY: wait or ask the person). After a forward always call reset, also when the check failed.

Inputs: action (required), avd, minutes.

emu_jobWait for a jobA
Read-onlyIdempotent

Wait for a job started by emu_start, emu_smoke, emu_check_notification or emu_release (job_id from their result) and return its result once it finished, or its status and latest report lines while it still runs (then call emu_job again). Without job_id it lists this server's jobs. JOB_UNKNOWN means the id is not known to this server (jobs do not survive a server restart): list the jobs or check emu_status.

Inputs: job_id, wait_sec.

emu_releaseGive the emulator backA
Destructive

Give back this session's lease when you are done: resets what test runs leave on the device (Firebase debug properties, a moved clock), uninstalls the apps installed under the lease when uninstall is true (or the listed packages), stops the emulator only if this lease started it (unless keep_running), then deletes the lease. Refused with NOT_OWNER for another session's lease: never try to release it, the person does that. No lease is not an error (released false). LEASE_CHANGED means another session took the lease over meanwhile: leave the emulator alone. Runs as a job: if the result is a job_id, call emu_job with it.

Inputs: avd, packages, uninstall, keep_running.

emu_renewRenew the leaseA
Idempotent

Extend this session's lease of the AVD (default 4 hours from now), also after it ran out. Refused with NO_LEASE when there is no lease (take it with emu_start) and NOT_OWNER when the lease is another session's (then the emulator is busy: wait or ask the person). Does not touch the device.

Inputs: avd, hours.

emu_screenshotScreenshotA
Read-only

Return a PNG screenshot of the AVD's screen (and its serial and size). Changes nothing and needs no lease; it works while another session holds the emulator, but then only look, do not act on it.

Inputs: avd.

emu_smokeSmoke-test an APKA

Install an APK on the leased emulator and self-test it from outside the app: ABI check, install, launch, wait for the ready marker in logcat (crash, ANR or self-exit fail the run), tap, background, local notification in the shade, tap it and check the app opens. Results (summary.json, logcat, screenshots) go to run_dir; check pass in the result. Needs this session's lease (emu_start first): NO_LEASE means take it, BUSY means another session uses the emulator (wait or ask the person). Defaults are the bundled sample app's log lines; for another app set ready_marker, no_tap or tap_marker, and notif_delay 0. Runs as a job: if the result is a job_id, call emu_job with it and do not start another smoke meanwhile. Do not use mobile-mcp while it runs.

Inputs: apk (required), avd, tap_x, tap_y, +14 more.

emu_startTake and boot the emulatorA
Idempotent

Lease the AVD to this session and boot it (or reuse it when it already runs), then make it predictable for automation (animations off, screen stays on, keyguard dismissed, clock reset). Call this before any other device-changing tool. On BUSY another session holds the emulator: do not retry in a loop and never release its lease; wait, or ask the person. Runs as a job: if the result is a job_id, call emu_job with it. Calling it again under your own lease only renews the lease. Always call emu_release when done.

Inputs: avd, hours, headless, wait_sec, +2 more.

emu_statusEmulator statusA
Read-onlyIdempotent

Show the lease of the AVD (owner, until, valid, mine), the running emulators, the AVD's serial and boot state, the adb version and the resolved paths (SDK root, AVD home, adb, lab home). Changes nothing and needs no lease. If the lease belongs to another owner and is valid, the emulator is BUSY: wait or ask the person, do not use it.

Inputs: avd.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 9 tools

    Disambiguation4/5

    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).

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents and humans to lease exclusive Android emulator sessions for bounded periods via MCP or HTTP, with a live web UI for watching or taking over active sessions.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables an AI agent to lease its own Android emulator phone and drive it over stdio: reading the screen, tapping, typing, and opening apps, with every action leaving an audit line and screenshot. Leases keep one agent per phone, and a locked phone stays inert until an operator unlocks it on its own screen.
      10
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to lease clean or signed-in Android emulator clones as adb-accessible devices, list and release them, and optionally open a scrcpy mirror, with short-lived leases that can be reclaimed after a client reconnects.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables an AI agent to boot and control an Android emulator — tapping, typing, scrolling, inspecting screens, reading logs and installing APKs — and to record those interactions as replayable, CI-ready test flows. Actions are captured by element text or id rather than coordinates, so the saved tests survive layout changes and rerun without the agent.
      18
      1
      MIT