6.3 KiB

Raw Blame History

type	project	subject	version	date	status	author	target_users
설계문서	수상한잡화점	Unity MCP 호출 스니펫 — 기획팀장용 복붙 템플릿	v1	2026-04-17	초판	개발팀장	기획팀장, /balance, /level 에이전트

Unity MCP 호출 스니펫 v1

1. 사용 전제

Unity Editor 기동 중 (D:/NerdNavis/FilGoodBandits/DeckBuilding 프로젝트 열림)
Unity MCP 연결 상태 (mcp__unity-mcp__* 도구 사용 가능)
독립 시뮬 어셈블리 컴파일 완료 (Assets/Sim/NerdNavis.Sim.asmdef)
시나리오 JSON 파일 준비 (스키마: 02_시나리오_JSON_스키마_v1.md)

검증 방법:

mcp__unity-mcp__execute_code (code: "UnityEngine.Debug.Log(\"MCP OK\");")

2. 3종 템플릿

2-1. 단일 실행 스니펫

용도: 시나리오 1건 즉시 실행하여 결과 확인.

복붙용 프롬프트 (기획팀장이 Claude/PM에게 전달):

Unity MCP로 아래 시나리오 1건 실행해주세요:
- 시나리오 파일: {경로 예: D:/NerdNavis/FilGoodBandits/DeckBuilding/Assets/Sim/Scenarios/anchor_stage1.json}
- 출력 모드: stdout
- 결과 요지 요청: pc_survived, pc_remaining_hp_ratio, total_turns, defence_active_ratio

MCP 도구 호출 (실행자가 실제 수행):

mcp__unity-mcp__execute_code
  code: """
  using NerdNavis.Sim;
  var runner = new SimulationRunner();
  var result = runner.Run("Assets/Sim/Scenarios/anchor_stage1.json");
  UnityEngine.Debug.Log(UnityEngine.JsonUtility.ToJson(result, true));
  """

기대 결과: Unity Console에 결과 JSON 출력 (§03 포맷 v1 준수). read_console 로 회수 가능.

2-2. 파라미터 스윕 스니펫

용도: 한 축 또는 여러 축 값들을 그리드 형태로 N회 반복 실행, 통계 집계.

복붙용 프롬프트:

Unity MCP로 파라미터 스윕을 실행해주세요:
- 베이스 시나리오: {경로}
- 스윕 축:
  - PCDefence_Mul: [0.2, 0.3, 0.4, 0.5]
  - monsters[0].attack_dmg: [3, 5, 7]
- 모드: cartesian
- 셀당 반복: 10회
- 결과 집계 요지 요청: 각 셀의 pc_survived_ratio + pc_remaining_hp_mean

MCP 도구 호출:

mcp__unity-mcp__execute_code
  code: """
  using NerdNavis.Sim;
  var runner = new SimulationRunner();
  var sweep = runner.RunSweep("Assets/Sim/Scenarios/sweep_defence_mul.json");
  UnityEngine.Debug.Log(UnityEngine.JsonUtility.ToJson(sweep, true));
  """

결과 해석 예시:

cells[0] (Mul=0.2, dmg=3): survived=1.0, HP_mean=62.3
cells[1] (Mul=0.2, dmg=5): survived=1.0, HP_mean=34.8
cells[2] (Mul=0.2, dmg=7): survived=0.6, HP_mean=12.1
... (총 4 × 3 = 12 cells)

2-3. 배치 비교 스니펫

용도: 서로 다른 시나리오·전략 N개를 한 번에 실행하여 결과 비교.

복붙용 프롬프트:

Unity MCP로 전략 비교 배치 실행 해주세요:
- 배치 파일: {경로}
- 포함 시나리오: strategy_never, strategy_always, strategy_touch_hold
- 랭킹 기준: pc_remaining_hp_ratio
- 결과 요지 요청: 전략별 ranking + deltas

MCP 도구 호출:

mcp__unity-mcp__execute_code
  code: """
  using NerdNavis.Sim;
  var runner = new SimulationRunner();
  var batch = runner.RunBatch("Assets/Sim/Scenarios/strategies_compare.json");
  UnityEngine.Debug.Log(UnityEngine.JsonUtility.ToJson(batch, true));
  """

3. 파일 기반 결과 회수 (출력 모드 `file`)

시나리오 입력에 "output_mode": "file" 또는 호출 시 지정:

mcp__unity-mcp__execute_code
  code: """
  using NerdNavis.Sim;
  var runner = new SimulationRunner();
  var result = runner.Run("Assets/Sim/Scenarios/anchor_stage1.json");
  ResultEmitter.EmitFile(result, "Assets/Sim/Output/anchor_stage1_result.json");
  UnityEngine.Debug.Log("saved");
  """

이후 Read 도구로 파일 내용 조회:

Read: D:/NerdNavis/FilGoodBandits/DeckBuilding/Assets/Sim/Output/anchor_stage1_result.json

4. 프로젝트 외부 저장 (기획팀 `.cache/` 등)

시뮬 결과를 Unity 외부 기획 워크스페이스에 직접 저장:

mcp__unity-mcp__execute_code
  code: """
  using NerdNavis.Sim;
  var runner = new SimulationRunner();
  var result = runner.Run("Assets/Sim/Scenarios/anchor_stage1.json");
  ResultEmitter.EmitFile(result, @"D:/NerdNavis/NerdNavisAi/기획팀/.cache/sim_results/anchor_stage1.json");
  """

5. 에러 진단 체크리스트

5-1. MCP 연결 실패

Unity Editor 상태 확인 (manage_editor 호출)
MCP 서버 재시작 (Claude Code 재연결)
Transport 모드 stdio:6400 확인 (교훈: 2026-04-14 Transport HTTP Local 불일치)

5-2. 컴파일 에러

Assets/Sim/*.cs 변경 후 refresh_unity 호출하여 재컴파일
Editor Console 스캔: read_console

5-3. 시나리오 파싱 실패

스키마 버전 확인 (schema_version: "1.0")
JSON 유효성 검사 (외부 툴 또는 JsonUtility.FromJson try/catch 확인)
ScenarioValidationException 메시지 참조

5-4. 결과가 이상 (비현실적 값)

seed 고정 여부 (deterministic 모드인지 확인)
global_value 기본값 오버라이드 확인
상세 로그 활성화(record_detail: true)로 tick 추적

6. 실행 흐름 예시 (전체 파이프라인)

1. 기획팀장: 시나리오 JSON 작성
   ↓
2. PM 또는 기획팀장: Claude Code에서 본 문서 §2-1 프롬프트 전달
   ↓
3. Claude: mcp__unity-mcp__execute_code 호출
   ↓
4. Unity Editor: SimulationRunner.Run() 실행
   ↓
5. Claude: read_console 로 결과 JSON 회수
   ↓
6. 기획팀장: 결과 JSON 분석·밸런스 튜닝
   ↓
7. (반복) 시나리오·스윕 조정하여 다시 §2

7. 변경 이력

v1 (2026-04-17): 초판. MCP 연결 미확인 상태에서 작성 — 실제 실행 검증은 Unity Editor 기동 + MCP 연결 시점에 수행 (C23 정직).

8. 기각안

기각안 A: Unity Editor 외부에서 .NET 직접 실행 → Unity 테이블 의존성·Addressable 로드 등 환경 재현 비용 과도. Editor 내 실행이 최선
기각안 B: PlayMode 강제 전환 후 시뮬 → 시뮬 독립성 저해·프레임 락·기존 InGame 로직 간섭. EditMode + 독립 Runner가 깔끔
기각안 C: Headless 모드 배치 빌드 실행 → 빌드·CI 파이프라인 복잡. MCP execute_code 즉시 실행이 기획팀 피드백 루프 최적

6.3 KiB Raw Blame History Unescape Escape