---
type: 기술검토
from: 개발팀장
to: 총괄PM
date: 2026-04-17
related: PD지시 #28, #3, 07/08/09/10 산출물
status: 작성완료
---

# Unity MCP 기반 시뮬레이션 전환 — 기술 검토서

## 0. 요약 (한 줄)
**Unity MCP `execute_code` + EditMode 실행 경로가 결정론·유지비·기획팀 접근성 3축 모두에서 07 Headless 추출안을 우위로 대체 가능하며, 07·08·09·10 산출물은 90% 이상 재활용 가능**하다. 방향 전환을 권장한다.

## 1. Unity 엔진 내 시뮬레이션 동작 기술 방안

### 1.1 Unity MCP 실행 경로 4종 비교

| 경로 | 메커니즘 | 결정론 | 속도 | 배치 | 기획팀 접근성 |
|------|---------|--------|------|------|--------------|
| **A. EditMode `execute_code`** | MCP로 C# 스니펫 직접 Eval (Editor 프로세스 내) | 높음 (엔진 루프 차단) | 매우 빠름 (씬 로드 불요) | 우수 (프로세스 상주) | 높음 (JSON in → JSON out) |
| B. EditMode Test Runner (`run_tests`) | `[Test]` 어트리뷰트 메서드를 MCP로 실행 | 높음 | 빠름 | 중간 (테스트 단위) | 중간 |
| C. Play Mode 자동화 | `manage_editor`로 PlayMode 진입 + 씬 실행 | 낮음 (MonoBehaviour 프레임 의존) | 느림 | 약함 | 낮음 |
| D. Batch Mode Headless | Unity CLI `-batchmode -executeMethod` | 높음 | 중간 (프로세스 기동 비용) | 우수 | 중간 |

### 1.2 권장 경로 — A (EditMode `execute_code`) 주력 + D 보조

**A 선택 근거**:
- Unity Editor가 이미 기동된 상태에서 MCP로 C# 코드를 직접 Eval → **Actor.cs 실제 클래스를 그대로 호출** 가능
- MonoBehaviour/Coroutine 의존은 **EditMode 헬퍼**(프레임 시뮬레이터·코루틴 드라이버)로 우회. 07 Phase A의 의존성 식별(7종) 결과를 그대로 활용하여 stub 주입
- UnityEngine.Random → `IRandomSource` DI (07 B-3 기획 그대로 유지)
- Addressable → JSON 직접 로드(기획팀 xlsm export JSON 사용, 09·10 구조 활용)
- **Python↔C# 이원화의 근본 해결** (두 구현 자체가 소멸, 한 구현만 유지)

**D 보조 근거**: CI/야간 대량 배치(1만 회 이상 통계) 시 Editor를 점유하지 않고 별도 프로세스 구동. 동일 C# 코드가 두 경로에서 동일 결과 보장 (EditMode·BatchMode 모두 UnityEngine 엔진 루프 밖에서 동작).

### 1.3 결정론 확보 설계
1. 시드 기반 `IRandomSource` 전 경로 주입 (UnityEngine.Random 전수 치환)
2. `Time.deltaTime`·프레임 의존 로직 → `IClock`·`ITickDriver` 주입
3. Animator/VFX 경로는 `IBattlePresenter` null-object로 차단 (07 B-2 설계 재활용)
4. 동일 시드 + 동일 시나리오 JSON → 비트 단위 동일 결과 검증

## 2. 기존 07 착수계획 대비 평가

### 2.1 Unity MCP 방향의 이점

| 관점 | 07 Headless 추출 | Unity MCP 방향 |
|------|-----------------|---------------|
| **SOT 일치** | BattleCore 추출 → Unity와 동일 어셈블리 공유 | **Unity 프로젝트 자체가 SOT** (추출 개념 자체 불요) |
| **Actor.cs 4,545줄 리팩터링** | 필수 (순수 도메인 분리) | **불요** (stub 7종 주입만) |
| **유지비** | Unity 측 변경 시 BattleCore 재빌드·동기화 | 변경 즉시 반영 (동일 코드) |
| **결정론** | netstandard2.1로 엔진 완전 분리 | EditMode 실행 시 엔진 루프 비활성 (동등) |
| **C11 개발 관점** | 범용성 ○ / 효율성 △ (대규모 리팩터링) | 효율성 ○ / 직관성 ○ / 범용성 △ (Unity 종속) |

### 2.2 단점·리스크

1. **Unity Editor 기동 의존** — 시뮬 실행 시 Unity Editor가 열려 있어야 함(경로 A). MCP 서버도 연동 필요
2. **기획팀 로컬 환경** — Unity 에디터 설치·프로젝트 열기 필요. 단, 현행 기획팀도 xlsm export → Unity 재로드 루프를 이미 수행 중이라 실질 추가 부담은 **MCP 호출 래퍼 스크립트** 수준
3. **차기 프로젝트 재활용성 제약** — 헌법 제1원칙 목표 2(차기 프로젝트부터 자산 활용)와의 정합성. Unity MCP 방식은 **Unity 전제 위에서만** 재활용 가능하며, 비-Unity 엔진 이관 시 다시 추출 필요. 현 너드나비스는 Unity 전제 조직이므로 수용 가능하나 **명시 필요**
4. **대량 배치 성능** — EditMode 경로 A는 프로세스 1개 점유. 1만 회 이상 배치는 경로 D(BatchMode 병렬 프로세스) 필요
5. **Live 디버깅 인프라 부재** — Python 시뮬의 print 기반 경량 검증 대신 Unity Console·MCP read_console 경유 필요

### 2.3 기존 산출물 재활용 가능성

| 문서 | 재활용률 | 비고 |
|------|---------|------|
| **07 시뮬레이터 이원화 해소 착수계획** | 60% | Phase A(의존성 식별 7종)·B-2(Presenter 인터페이스)·B-3(IRandomSource)·D(결과 교차 검증)는 그대로 유효. Phase B-1(도메인 추출)·Phase C(dotnet CLI)는 폐기, Unity MCP 실행 래퍼로 대체 |
| **08 전투시스템 SOT** | 100% | 전투 공식 명문화는 시뮬 방식과 무관 |
| **09 카드시스템 아키텍처** | 100% | 카드 효과 구조 분석 그대로 유효 |
| **10 데이터로딩 구조** | 100% | JSON 로딩 구조 그대로 유효 (Addressable stub만 추가) |

## 3. 권장 아키텍처

### 3.1 실행 구조
```
[기획팀 시나리오 JSON]
    │
    ▼ (PM 단일 세션에서 MCP 호출)
mcp__unity-mcp__execute_code
    │  → NerdNavis.Sim.Runner.Run(json)
    ▼
[Unity Editor 프로세스]
  ├─ IRandomSource(seed)
  ├─ IClock/ITickDriver (프레임 시뮬)
  ├─ IBattlePresenter = NullPresenter
  ├─ ITableLoader = JsonTableLoader (기획팀 xlsm export)
  └─ Actor/PCActor/MobActor/EffectMgr (실프로덕션 코드)
    │
    ▼
[결과 JSON] → 기획팀 작업 폴더 + CSV 집계
```

### 3.2 기획팀 반복 실행 인터페이스

- **입력**: `시나리오.json` (시드·덱·스테이지ID·반복 횟수)
- **실행**: `scripts/run_sim.ps1 시나리오.json` (PM 세션에 MCP 호출 위임) 또는 Unity Editor 메뉴 `NerdNavis > Sim > Run`
- **출력**: `결과_YYYYMMDD_HHMM.json` + `집계.csv` (HP 추이·클리어율·평균 턴 등)
- **재실행**: 동일 시드 → 동일 결과 (결정론 검증 자동 포함)

### 3.3 C11 개발 관점 충족도

| 기준 | 평가 |
|------|------|
| 자원 효율성 | ○ — 추출 어셈블리 유지 불요, 빌드 비용 0 |
| 코드 직관성 | ○ — 기획·개발 모두 Unity 실코드 1개 참조 |
| 범용성 | △ — Unity 전제 내에서만 재활용. **헌법 제1원칙 목표 2 명시 필요** |

## 4. 착수 계획

### 4.1 재작성·신설 필요 문서

| # | 문서 | 처리 |
|---|------|------|
| 07 | 시뮬레이터 이원화 해소 착수계획 v1 | **07_v2로 갱신** (Unity MCP 방향, Phase C/E 재구성) |
| 11 | `11_Unity_MCP_시뮬_실행_설계_v1.md` | **신설** — `execute_code` 스니펫 템플릿·stub 7종 구현·IRandomSource DI 상세 |
| 12 | `12_시뮬_시나리오_JSON_스키마_v1.md` | **신설** — 기획팀 입출력 계약 |
| 08/09/10 | SOT 3종 | **유지** (변경 없음) |

### 4.2 기획팀 조기 제공 가능 산출물 (단계 순서)

1. **선행**: 경로 A 기술 검증 (Unity MCP + EditMode에서 Actor.cs 1건 호출 성공)
2. **Stage 1 스모크**: 최소 시나리오(단일 전투) 실행 가능 시점 → 기획팀이 Python 시뮬 병행 검증 개시
3. **교차 검증 완료**: 대표 스테이지 5건 Python vs Unity MCP 결과 일치 확증 → Python 시뮬 아카이브 + 기획팀 Phase 3 HOLD 해제 요건 충족

### 4.3 차단 요인 (C3)

1. **Unity MCP 연결 상태 의존** — 현재 세션에서 Unity Editor가 열려 있고 MCP 서버가 Stdio(port 6400) 연결된 상태 전제. 연결 끊김 시 시뮬 실행 불가. DevOps 관점에서 재연결 자동화 스크립트 필요
2. **Actor.cs의 Unity 엔진 의존 7종** — stub 구현 난이도는 경로 A 기술 검증 단계에서만 확정 가능. ObscuredInt/Float(안티치트 라이브러리)는 Editor에서도 정상 동작하는지 실측 필요
3. **헌법 제1원칙 목표 2 정합성** — 차기 프로젝트가 Unity 전제인지 PD님 확정 필요. 비-Unity 엔진 고려 시 본 방향 재검토
4. **C30 준수** — `${UNITY_PROJECT_ROOT}`는 별도 git 레포이므로 시뮬 래퍼 스크립트가 Unity 프로젝트 파일을 수정하는 경우 작업 전 `git fetch && git status` 선행 필수

## 5. 결론 (권장 판단)

**Unity MCP 방향 전환을 권장**. 근거:
1. 07 Headless 추출의 근본 리스크(Actor.cs 4,545줄 대규모 리팩터링)를 회피하면서 동일한 "단일 SOT" 효과 달성
2. 유지비·결정론·기획팀 접근성 3축 모두 우위 또는 동등
3. 기존 08/09/10 산출물 100% 재활용, 07도 60% 재활용

**PD님 결정 필요 사항** (PM 경유 상신):
1. 헌법 제1원칙 목표 2 — 차기 프로젝트 Unity 전제 확정 여부
2. 07_v2 재작성 + 11·12 신설 착수 승인

**본 검토는 검토·제안까지이며 실제 구현 착수는 PD님 방향 확정 후 진행**. 기획팀장의 병행 검토(Unity MCP 환경에서 Phase 3 밸런스 작업 실행 가능성) 결과와 교차 확인 필요.

---

**작성**: 개발팀장 / **수신**: 총괄PM / **배포**: 본 경로 확정 시 기획팀장에게 교차 공유
