# 시뮬레이터 이원화 해소 착수계획 (v1)

> 🔴 **2026-04-17 아카이브됨 — 대체 문서: [`프로젝트/수상한잡화점/시뮬레이터/01_시뮬레이터_아키텍처_v1.md`](../시뮬레이터/01_시뮬레이터_아키텍처_v1.md)**
>
> 본 07 원안("Headless C# CLI 추출")은 2026-04-17 PD님 직접 지시로 **Unity MCP EditMode + 독립 어셈블리(`Assets/Sim/` + `NerdNavis.Sim.asmdef`) 방향으로 전환**됨. 전환 사유·기각 근거: `프로젝트/수상한잡화점/시뮬레이터/01~04` + `공유/소통/완료/2026-04-17_Unity_MCP_시뮬레이션_기술검토_개발팀.md`.
>
> **본문은 기각안 근거·당시 설계 실증으로 보존**. 차기 프로젝트에서 Unity 외 환경 고려 시 참고 자료로 활용 가능 (헌법 제1원칙 목표 2 원칙 B).

> **작성일**: 2026-04-14
> **작성자**: 개발실장
> **우선순위**: 🔴 **최우선** — 기획실 Phase 3 HOLD 해제 조건 (당시)
> **근거**: 02번 분석 문서 §1 (시뮬레이터 이원화 🔴), PD님 지시 (2026-04-14)
> **관련 규칙**: 핵심 규칙 **C11 (개발 관점 원칙)**, **C5 (정보의 정직성)**, **C9 (AI 에이전트 조직 원칙 — 완성도 중심)**

---

## 1. 현황 분석 (재정리)

### 1.1 이원화 상태
| 측면 | 현황 |
|------|------|
| **기획실 시뮬** | Python 3종 — `battle_sim.py` (전투 단일), `full_stage_sim.py` (스테이지 전체), `stage_sim_v2.py` (개선판) |
| **Unity 구현** | C# — `Assets/Script/InGame/Actor/Actor.cs`, `PCActor.cs`, `MobActor.cs`, `Mgr/EffectMgr.cs` 등 |
| **데이터 SOT** | JSON — `D:/NerdNavis/FilGoodBandits/DeckBuilding/Assets/ResWork/Table/Export/*.json` (공통) |
| **로직 SOT** | 불명 — Python 시뮬이 독자 재구현했는지, Unity 코드를 참조했는지 **미확인** |
| **결과 일치 여부** | 검증된 바 없음 — **이원화 리스크 실재** |

### 1.2 핵심 리스크
1. **밸런싱 신뢰도 붕괴**: 기획실이 Python 시뮬로 도출한 수치가 실제 Unity 전투와 괴리될 경우, Phase 3 (성장 요소별 기여도 설정) 결과가 실제 게임에서 재현되지 않음
2. **유지비 2배**: 전투 공식 1건 변경 시 Python·C# 양쪽 동시 수정 필요 — 동기화 실패 시 조용히 축적되는 버그
3. **결정론 부재**: 양 구현 모두 재현 가능한 시드 기반 리플레이 보장 여부 미확인
4. **터치 방어·회피 SOT 불일치**: 02번 §4에 기록됨 — 기획문서·Python 시뮬·Unity 코드 3자 동작 상이 가능성

### 1.3 긴급도
- **기획실 Phase 3 HOLD** 상태 (PD님 지시, 2026-04-14)
- 본 작업 완료 전까지 기획실의 성장 밸런싱 작업 전면 정지

---

## 2. 해소 방향 — Unity C# 로직을 SOT로 하는 Headless 시뮬 추출

### 2.1 기본 방향
**"실제 게임에서 동작하는 C# 코드를 전투 시뮬의 SOT로 삼는다."**

- C11 원칙상 **두 구현을 동기화로 유지하는 것은 근본 해결이 아님** (C2 근원적 문제 해결)
- 따라서 **Unity 전투 로직을 Unity 엔진 의존성 없이 실행 가능한 Headless C# 라이브러리로 추출** → CLI에서 직접 실행
- Python 시뮬은 **검증·비교용 참조 구현으로만 유지**하다가, 결과 일치가 확증되면 **폐지 또는 아카이브**

### 2.2 선택 근거 (02번 §1 Option A·B 중 A 채택)
| 기준 | Option A (Headless C# 일원화) | Option B (Python 참조 유지 + 자동 동기화 테스트) |
|------|------------------------------|---------------------------------------------|
| **자원 효율성** | ✅ 유지비 1배 | 🔴 유지비 2배 |
| **코드 직관성** | ✅ 기획·개발 모두 동일 코드 참조 | 🔴 언어 이원화 유지 |
| **범용성** | ✅ 타 프로젝트 동일 패턴 적용 | 🔴 프로젝트마다 동기화 로직 재구현 |
| **기획실 친화성** | 🟡 C# CLI 실행 학습 필요 | ✅ Python 익숙 |
| **C9(완성도) 부합** | ✅ 근본 해결 | 🔴 현상 유지 |

→ **A 채택**. 기획실 친화성 문제는 CLI 래퍼·단순 JSON 입출력으로 해소 (§3.3 참조)

### 2.3 비-목표 (Out of Scope)
- Unity Editor 기반 통합 (별도 Play Mode 실행) — Headless CLI가 목적
- 실시간 시각화 — 결과 수치·로그만 산출
- 네트워크·IAP·ACTk 등 전투 외 시스템 — 05번 문서 영역

---

## ~~3·4·5. 작업 단계·담당 팀·재개 조건~~ (2026-04-18 삭제)

> 원 섹션(Phase A~E 실행 계획·담당 팀 매트릭스·Phase 3 재개 조건 5종)은 Unity MCP EditMode 전환으로 **완전히 대체**됨 (2026-04-17 PD님 직접 지시). 대체 경로: `프로젝트/수상한잡화점/시뮬레이터/01_시뮬레이터_아키텍처_v1.md` §3·§4 + `공유/소통/완료/2026-04-17_Unity_MCP_시뮬레이션_기술검토_개발팀.md`. Phase 3 재개 로드맵은 개발팀 #38 PD 지시 하 재정의 중. 삭제 근거: 2026-04-18 dev-auditor·개발팀장 공통 축약 권고 (실행 계획은 기각 근거로서의 자산 가치 없음, 설계 원리·Option 비교·검증 방법은 §2·§6에 보존).

---

## 6. 검증 방법

### 6.1 결정론 보장 검증
- 동일 시드·동일 입력 → 동일 출력 (100회 반복 시 편차 0)
- **검증 대상**: Unity 실제 플레이(녹화·시드 고정) vs CLI Headless 실행

### 6.2 Python ↔ C# 결과 일치 검증 (Phase D 핵심)
| 검증 항목 | 허용 오차 | 사유 |
|----------|----------|------|
| 스테이지 클리어 여부 | 완전 일치 (Pass/Fail) | 이진 결과 |
| 총 데미지량 | 0% (결정론이면 동일) | 정수 연산이면 동일해야 함 |
| 최종 HP | 0% | 정수 연산 |
| 클리어 시간(초) | ≤1% 오차 | 부동소수점 누적 오차 허용 |
| 이벤트 발생 순서 (치명타·처치 등) | 완전 일치 | 시드 동일 시 순서 불변 |

**불일치 발견 시 원칙**:
1. Unity C# 코드가 SOT → Unity 결과를 기준으로 간주
2. Python 시뮬이 다른 결과를 내면 **Python 로직 오류**로 규정 → Python 수정 또는 폐기
3. 기획실이 Python 결과를 근거로 밸런스를 설정했다면 **해당 밸런스 재검토 필요** (PD님 보고 사안)

### 6.3 연속적 회귀 방지
- 전투 코드 수정 시 CI에서 **기준 시나리오 시뮬** 자동 실행
- 결과가 기준선에서 이탈하면 **빌드 실패**

---

## ~~7. 완료 기준~~ (2026-04-18 삭제 — §3·4·5와 함께 실효. Unity MCP 전환 경로로 대체)

---

## 8. 열린 이슈 (당시 PD님 판단 필요 사항, 아카이브)

| ID | 이슈 | 의견 |
|----|------|------|
| **OI-A** | BattleCore 저장 위치 — Unity 프로젝트 내부 asmdef vs 별도 repo (06번 신규 코어와 통합 가능성) | 개발실장 의견: **별도 repo 권장** (타 프로젝트 재활용 가능성 대비) — PD님 판단 필요 |
| **OI-B** | Phase D 불일치 발견 시 기존 Python 시뮬 기반 밸런스 데이터의 신뢰성 재평가 범위 | 사안 발생 시 즉시 PD님 보고 대상 (C3 은폐 금지) |
| **OI-C** | 기획실이 CLI 학습 부담 없이 쓸 수 있도록 **웹 UI 래퍼** 추가 여부 | C9 원칙상 "완성도" 중심 — 필요성 판단 후 PD님 결정 |

---

## 9. 변경 이력

| 일자 | 작성·수정자 | 버전 | 사유 |
|------|-----------|------|------|
| 2026-04-14 | 개발실장 | v1 | PD님 지시(기획실 Phase 3 HOLD) 수령 후 착수계획 초안 작성 |
| 2026-04-17 | PM | v1-archived | Unity MCP EditMode 전환으로 원안 기각, 상단 아카이브 배너 추가, 02_개발자관점_점검 L19 주해 추가 |
| 2026-04-18 | PM | v1-slim | §3·§4·§5·§7(실행 계획·담당 팀·재개 조건·완료 기준 약 120줄) 삭제. §1·§2·§6·§8·§10(현황·Option 비교·검증 방법·OI·참고) 유지하여 기각 근거·차기 참고 가치 보존. 3축 감사(dev-auditor)·개발팀장 공통 권고 반영 |

---

## 10. 참고 문서

- `02_개발자관점_점검_v1.md` §1 (시뮬레이터 이원화 🔴), §4 (터치 방어·회피 SOT 불일치)
- `03_Unity프로젝트_구조_v1.md` (전투 시스템 코드 위치)
- `기획실/.cache/battle_sim.py`, `full_stage_sim.py`, `stage_sim_v2.py` (아카이브 대상)
- `06_신규코어_설계안_v1.md` §6 (신규 코어와의 연관)
- 공통 규칙 C2 (근원적 문제 해결), C5 (정보의 정직성), C9 (완성도 중심), C11 (개발 관점)
