10 KiB
10 KiB
| type | project | subject | version | date | status | author | related | 핵심원칙 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 설계문서 | 수상한잡화점 | 독립 시뮬레이터 아키텍처 (Unity MCP 실행 인프라) | v1 | 2026-04-17 | 초판 | 개발팀장 |
|
|
독립 시뮬레이터 아키텍처 v1
1. 배경 (왜 필요한가)
1-1. PD님 직접 지시 (2026-04-17)
"기존 수상한잡화점 프로젝트의 코드나 구조에 영향을 주지 않는 독립적인 시뮬레이터로 동작해야 함."
1-2. 요구사항 해석
- 기존 코드 불변 원칙:
Assets/Script/하위 파일을 일절 수정 불가. 시뮬 인프라는 관찰·참조만 허용, 수정·확장·상속을 통한 침투 불허 - 독립 어셈블리 격리: 기존
Assets/Script/*.asmdef와 별개 어셈블리로 운영하여 빌드 의존성·컴파일 영향 차단 - Editor-only 동작: 프로덕션 빌드 산출물에 시뮬 코드 포함 방지 (앱 크기·보안·의도치 않은 실행 차단)
- 메커닉 재현의 독립성: Actor·Effect 등의 로직을 재사용·복제가 아닌 동등 결과를 내는 별도 로직으로 독립 재구현
1-3. 설계 제약 (대안 고려)
- 대안 A (기각): 기존
Assets/Script/Actor/직접 호출하여 시뮬 실행 → 코드 수정 위험·PlayMode 의존·PD 제약 위반 - 대안 B (기각): 별도 레포 구축 → Unity MCP
execute_code가 현 프로젝트 내부만 접근 가능, 운영 분리 과도 - 대안 C (채택): 같은 Unity 프로젝트 내
Assets/Sim/신규 폴더 + 독립 asmdef + Editor-only define + 모델 독립 재구현
2. 폴더·어셈블리 구조
D:/BurningTimes/FilGoodBandits/DeckBuilding/Assets/Sim/ ← 신규 (이번에 생성)
├── BurningTimes.Sim.asmdef ← 독립 어셈블리 정의
├── Runtime/
│ ├── SimulationRunner.cs ← 진입점
│ ├── ScenarioLoader.cs ← 시나리오 JSON → ActorModel 로드
│ ├── ResultEmitter.cs ← 결과 JSON 출력
│ └── Models/
│ ├── ActorModel.cs ← Actor 동등 모델 (독립 재구현)
│ ├── DefenceModel.cs ← 터치 방어 30% + 지속형 재현
│ └── DamageCalc.cs ← 데미지 감소 pipeline 재현
2-1. 어셈블리 정의 (BurningTimes.Sim.asmdef)
name:BurningTimes.SimrootNamespace:BurningTimes.Simreferences: 비움 (기존 어셈블리 참조 안 함 — 독립성 확보)includePlatforms:["Editor"](Editor-only)excludePlatforms:[]autoReferenced:falsedefineConstraints:["UNITY_EDITOR"]noEngineReferences:false(UnityEngine은 사용, but 최소)
2-2. 의존성 격리 결과
- 빌드 시 본 어셈블리 자동 제외 (Editor 플랫폼만 타겟)
- 기존 게임 어셈블리와 컴파일 단위 분리 → 기존 코드 변경 감지 없음
- 기존
Assets/Script/전혀 참조하지 않으므로 기존 리팩토링·삭제에도 영향 없음
3. 실행 흐름
기획팀장 Unity MCP SimulationRunner
│ │ │
│ 04_MCP_호출_스니펫_v1.md 기반 │ │
│ execute_code 호출 │ │
│ {scenario_json_path: "..."} │ │
│ │ │
│ ─────────────────────────────► │ │
│ │ │
│ │ SimulationRunner.Run(path)
│ │ ─────────────────────────►
│ │ │
│ │ │ 1. ScenarioLoader.Load(path)
│ │ │ → ActorModel 생성
│ │ │ 2. 전투 tick 루프 실행
│ │ │ (DefenceModel·DamageCalc 호출)
│ │ │ 3. ResultEmitter.Emit(result)
│ │ │ → 결과 JSON 파일 또는 stdout
│ │ │
│ │ ◄─────────────────────────
│ │ {결과 JSON}
│ ◄───────────────────────────── │
│ │ │
│ 기획팀 분석·밸런스 튜닝 │ │
3-1. 실행 환경 2모드
- 모드 1 (단일 실행): Unity Editor 기동 상태 + MCP 연결 +
execute_code한 번 → 결과 1건 - 모드 2 (배치 실행):
execute_code로 스윕 파라미터 배열 전달 → 내부 루프로 N회 실행 + 결과 N건 집계
4. 독립 모델 설계 (Models/)
4-1. ActorModel
기존 Actor.cs(4545줄)를 재구현하지 않는다. 시뮬에 필요한 최소 상태만 추출:
public class ActorModel {
public string id;
public float maxHP, hp;
public float shield;
public float attackDmg;
public float attackCoolTime;
public float accumulatedAttackTime;
public bool isDefencing; // ActorStatus == Defecne 동등
public bool isDead => hp <= 0f;
// ... 시뮬 범위 내 최소 필드만
}
4-2. DefenceModel (실측 규칙 재현)
Q-P2 정밀 2차 응답서 §2 실측 기반 독립 구현:
PCDefence_Mul = 0.3f(30% 감소)PCDefence = 1(절대값 1 감소)- 터치 Down↔Up 지속 (
isDefencing플래그) - 방어 중 공격 불가 (
accumulatedAttackTime갱신 중단) - 방어 중 데미지:
dmg = (dmg - 1) * (1 - 0.3)(추가 감소 스택은 포함하지 않음 — 단순화)
4-3. DamageCalc (감소 pipeline 재현)
Actor.cs:762-809 실측 기반 간이 재구현. 시뮬 범위 외(카드·인장·각성)는 제외하고 순수 방어 메커닉 + 기본 스탯 차원만 재현. 복잡 메커닉 필요 시 scope 확장 v2에서 추가.
4-4. 재구현 원칙
- 동등 결과 우선, 구조 복사 금지 — 기존 코드를 복붙하지 않고 실측 스펙을 문서로 보고 재작성
- 최소 기능 원칙 — 밸런싱에 필요한 축(HP·Shield·Dmg·Defence·CoolTime)만 구현, 나머지는 생략
- 버전 고정 주석 — 각 파일 상단에
// 실측 기준: Dev 브랜치 43b6074c4 (2026-04-17)명시하여 원본 변경 시 재동기화 시점 명확화
5. 검증 방법
5-1. 기존 코드 불변 증명
- 본 작업 커밋 diff에
Assets/Script/하위 변경이 0건이어야 한다 git diff --stat Assets/Script/결과가 비어있는지 확인
5-2. 빌드 제외 증명
manage_buildMCP로 Player 빌드 시도 → 빌드 로그에BurningTimes.Sim미포함 확인BurningTimes.Sim.asmdef의includePlatforms: ["Editor"]준수
5-3. 메커닉 등가성 검증 (향후)
- 동일 시나리오에서 실제 게임 PlayMode vs 시뮬 실행 결과를 기획팀이 비교 → 오차 10% 이내 목표
- 오차 원인이 시뮬 모델 누락인지 실측 데이터 누락인지 구분하여 보완
5-4. MCP 연결 필요 환경
- 본 세션에서 Unity MCP 접근 가능 여부 미확인 (C23 정직:
mcp__unity-mcp__*호출을 실제로 수행하지 않음). 스켈레톤 코드는 작성 완료 상태이며, Unity Editor 구동 + MCP 연결 시점에 기획팀장·개발팀이 실행 검증
6. 확장 포인트 (v2 이후)
- 카드·인장·각성 효과 모델 추가 — 현재 스코프는 방어 메커닉 중심. 기획팀이 밸런싱 축 확장 요청 시 Models/에 파일 추가
- 몬스터 AI 모델 — 현재 단순 공격 tick만. 라인별 공격 조건·특수 효과(자폭·치명타 등) 재현 필요 시
MonsterAIModel.cs추가 - 앵커 전투 노드 시퀀스 통합 — 단일 전투가 아닌 스테이지 경로 전체 시뮬
7. 변경 이력
- v1 (2026-04-17): 초판. PD 지시 #37 독립 시뮬 제약에 따른 어셈블리 격리 아키텍처.
8. 기각안 (P24)
- 기각안 A:
AssemblyDefinitionReferences로 기존Assets/Script/어셈블리 참조 → 독립성 훼손, PD 제약 위반. 0 references 고수 - 기각안 B: Runtime 포함(Editor-only 제외) → 빌드 산출물 오염·보안. Editor-only 확정
- 기각안 C:
Assets/Editor/Sim/아래 배치 → Unity asmdef 자동 Editor 어셈블리와 충돌 위험.Assets/Sim/Runtime/+ 자체 asmdef의 Editor 플랫폼 제약이 깔끔 - 기각안 D: 별도 레포 서브모듈 → Unity MCP
execute_code경로 접근 제약·기획팀 셋업 복잡도 증가. 동일 레포 격리가 최선