---
type: 스크립트_분석
scope: C#_전수_분석
author: 개발팀장
date: 2026-04-23
version: v0.1
project: EerieVillage (기묘한 고을 : 조선퇴마뎐 / EerieVillage: Joseon Exorcist)
phase: BT5-Dev 3단계 (템플릿 선행 분석)
data_source: E:/EerieVillage/Assets/Scripts/ 36개 전수 식별 · 핵심 11개 본문 심층 분석 + 주변 6개 요지 스캔 (총 17종 이름 기반 재사용/교체/신규 분류)
status: 초기 분석 — 주요 클래스 의존·확장 지점 식별 + 재사용/교체/신규 3종 분류
---

# 02. 스크립트 분석

## 1. 스크립트 전수 목록 (36개)

### 1-1. Core/ (5개) — 이벤트 시뮬레이션 엔진

| 파일 | 역할 |
|---|---|
| `Simulation.cs` | static partial — 이벤트 큐·풀·Tick·Schedule·GetModel API |
| `Simulation.Event.cs` | `Event` 추상 클래스 + `Event<T>` 제네릭 (OnExecute 콜백) |
| `Simulation.InstanceRegister.cs` | 제네릭 모델 인스턴스 레지스트리 |
| `HeapQueue.cs` | Min-heap 우선순위 큐 (tick 기준) |
| `Fuzzy.cs` | 확률·보간 유틸 |

### 1-2. Gameplay/ (12개) — 이벤트 정의

| 파일 | 트리거 |
|---|---|
| `PlayerSpawn.cs` | 플레이어 (재)스폰 — Teleport + 애니메이터 dead=false + EnablePlayerInput 2초 후 |
| `PlayerDeath.cs` | 사망 처리 — health.Die() + controlEnabled=false + PlayerSpawn 2초 예약 (재시도 구조) |
| `PlayerEnemyCollision.cs` | 적 접촉 판정 — `player.Bounds.center.y >= enemy.Bounds.max.y`면 적 피해, 아니면 PlayerDeath |
| `PlayerJumped.cs`·`PlayerLanded.cs`·`PlayerStopJump.cs` | 점프 단계별 오디오·이펙트 |
| `PlayerTokenCollision.cs` | 토큰 수집 처리 |
| `PlayerEnteredDeathZone.cs` | 낙사 — PlayerDeath 체인 |
| `PlayerEnteredVictoryZone.cs` | 승리 — MetaGameController 메인메뉴 전환 |
| `EnemyDeath.cs` | 적 사망 — collider·controller disable + 오디오 |
| `HealthIsZero.cs` | Health.Decrement 시 HP=0 도달 — PlayerDeath 체인 |
| `EnablePlayerInput.cs` | controlEnabled=true 복귀 |

### 1-3. Mechanics/ (14개) — 물리·제어

| 파일 | 역할 |
|---|---|
| `KinematicObject.cs` | 물리 베이스 — Rigidbody2D Kinematic + body.Cast + groundNormal + shellRadius (플랫포머 정밀 제어 표준) |
| `PlayerController.cs` | 플레이어 입력·점프 상태머신 (Grounded→PrepareToJump→Jumping→InFlight→Landed) + SpriteRenderer flip + animator 파라미터 |
| `AnimationController.cs` | `KinematicObject` 서브 — 적용 간단 물리 애니 통합 (EnemyController가 RequireComponent) |
| `EnemyController.cs` | PatrolPath 순찰 + OnCollisionEnter2D → PlayerEnemyCollision 이벤트 |
| `GameController.cs` | Singleton + `Simulation.Tick()` 매 프레임 호출 + PlatformerModel 직렬화 참조 |
| `Health.cs` | maxHP=1 기본 + Increment/Decrement/Die + HealthIsZero 이벤트 발행 |
| `PatrolPath.cs`·`PatrolPath.Mover.cs` | 순찰 경로 정의 + 이동기 |
| `TokenController.cs`·`TokenInstance.cs` | 토큰 수집 시스템 |
| `VictoryZone.cs`·`DeathZone.cs`·`SpawnPoint.cs` | 트리거 존 3종 |
| `PlayAudioClip.cs` | 오디오 재생 유틸 |

### 1-4. Model/ (1개)

| 파일 | 역할 |
|---|---|
| `PlatformerModel.cs` | virtualCamera·player·spawnPoint·jumpModifier(1.5)·jumpDeceleration(0.5) — **[System.Serializable]** 로 Inspector 노출 |

### 1-5. UI/ (2개)

| 파일 | 역할 |
|---|---|
| `MainUIController.cs` | 패널 인덱스 기반 토글 (SetActivePanel) |
| `MetaGameController.cs` | 메인메뉴↔게임플레이 토글 + Time.timeScale 제어 + Menu 키 대응 |

### 1-6. View/ (2개)

| 파일 | 역할 |
|---|---|
| `AnimatedTile.cs` | 타일맵 애니메이션 |
| `ParallaxLayer.cs` | 배경 시차 |

## 2. 주요 아키텍처 패턴 분석 (Read 실측 기반)

### 2-1. Discrete Event Simulation (Simulation.cs 핵심)

```csharp
// Simulation.cs — 이벤트 예약
Schedule<PlayerDeath>()           // tick=현재+0, 즉시 실행
Schedule<PlayerSpawn>(2f)         // tick=현재+2s 후 실행

// Simulation.Tick() — GameController.Update에서 호출
while (eventQueue.Count > 0 && eventQueue.Peek().tick <= Time.time) {
    var ev = eventQueue.Pop();
    ev.ExecuteEvent();  // Precondition() → Execute() → OnExecute<T> invoke
    eventPools[ev.GetType()].Push(ev);  // 풀 반환
}
```

**강점**:
- 이벤트 타입별 풀링으로 GC 압박 최소화 (C11 자원 효율성 ✓)
- `Event<T>.OnExecute` 정적 Action으로 **외부 시스템 훅** 가능 → **EerieVillage 카드 효과가 이벤트에 부착되는 구조 가능**
- 시간 지연 이벤트 (`Schedule<T>(delay)`) 네이티브 지원

**EerieVillage 활용 예상**:
- `Schedule<PlayerAttack>` 이벤트 신규 → 카드 효과(관통·AoE·연사)가 `PlayerAttack.OnExecute` 훅
- `Schedule<LevelUp>` → 3픽 UI 띄우기
- `Schedule<ItemPickup>` → 파츠 교체 확인 다이얼로그

### 2-2. Kinematic 물리 (KinematicObject.PerformMovement)

```csharp
// FixedUpdate 흐름
velocity += Physics2D.gravity * dt;       // 중력 누적
var deltaPos = velocity * dt;
var moveAlongGround = new Vector2(groundNormal.y, -groundNormal.x);
PerformMovement(moveAlongGround * deltaPos.x, false);  // 수평
PerformMovement(Vector2.up * deltaPos.y, true);         // 수직

// PerformMovement — body.Cast로 예상 경로 스캔
var count = body.Cast(move, contactFilter, hitBuffer, distance + shellRadius);
// 법선 y > minGroundNormalY(0.65f) → IsGrounded=true
// projection < 0이면 벽·경사 밀어내기
// shellDistance로 "살짝 띄운" 이동으로 박힘 방지
```

**강점**: Unity 표준 Dynamic Rigidbody2D의 "tunneling·jitter" 이슈 회피. EerieVillage 빠른 횡스크롤에 필수

### 2-3. 밟기 판정 (PlayerEnemyCollision.willHurtEnemy)

```csharp
var willHurtEnemy = player.Bounds.center.y >= enemy.Bounds.max.y;
if (willHurtEnemy) { Schedule<EnemyDeath>(); player.Bounce(2); }
else { Schedule<PlayerDeath>(); }
```

- **마리오 식 "위에서 밟으면 적 피해"** 구조
- EerieVillage는 "**공격 키로 적 피해**" 구조이므로 **이 판정 교체 필요** (개발 03 §3-1 P0)

### 2-4. Model 직렬화 참조 (PlatformerModel)

```csharp
// GameController.cs
public PlatformerModel model = Simulation.GetModel<PlatformerModel>();
// Simulation.InstanceRegister<T>.instance는 static 단일
// Unity가 Inspector에서 이 shared reference를 덮어쓸 때 모든 참조자에게 반영됨
```

**강점**: Inspector로 튠 가능한 Model을 코드·Event가 공유 → **EerieVillage 카드 풀·아이템 DB·특성 테이블도 동일 패턴으로 확장 가능** (C11 범용성 ✓)

## 3. 재사용 / 교체 / 신규 3종 분류

### 3-1. 재사용 (Reuse) — 그대로 계승 10종

| 대상 | 근거 |
|---|---|
| `Simulation.cs` 일체 | discrete event 엔진 — 카드 효과 시스템 기반으로 확장 |
| `KinematicObject.cs` | 플랫포머 정밀 물리 — 기획 04 §4-1 "템플릿 계승" 일치 |
| `Health.cs` | maxHP=1 기본값이 라이프 1과 정합. **i-frame 필드·타이머 추가만 필요** |
| `HealthIsZero.cs`·`PlayerDeath.cs` 이벤트 | 사망 체인 — 마을 복귀 로직 추가로 확장 |
| `PlatformerModel.cs` 패턴 | 카드·아이템·특성 테이블 Model 3종 신설의 설계 템플릿 |
| `PatrolPath` 시스템 | 일반 적 순찰 — 조선 귀신 AI 기본 이동 |
| `CinemachineCamera` 연결 구조 | 보스룸 고정 카메라 전환은 virtualCamera 교체로 해결 |
| `MetaGameController.cs` | 메인메뉴↔게임 토글 구조 — 마을↔전투 씬 전환 확장 베이스 |
| `MainUIController.cs` | 패널 인덱스 토글 — 스테이지 선택·카드 3픽 UI 베이스 |
| `GameController.cs` | Singleton + Tick 호출 — 싱글톤 구조 유지, 게임 상태(마을·전투·메뉴) 머신 추가 |

### 3-2. 교체 (Replace) — 리팩터·변경 5종

| 대상 | 변경 이유·방향 |
|---|---|
| `PlayerEnemyCollision.cs` "위에서 밟기" 로직 | 기획 04 "공격 키 기반 피해"로 **로직 교체** (bounds.y 비교 → 공격 범위 AABB 체크) |
| `PlayerController.cs` 공격 입력 부재 | **마우스 좌클릭 / 터치 공격 버튼 `Player/Attack` 액션 추가** + `Schedule<PlayerAttack>` 이벤트 체인 |
| `Health.cs` | i-frame 필드 (float invulnerableUntil) + Decrement 시 Time.time < invulnerableUntil 스킵 로직 편입 |
| `PlayerDeath.cs` | 현재는 "2초 후 재스폰" — EerieVillage는 "사망 → 레벨·카드 전손 → 마을 씬 복귀" 체인으로 교체 |
| `PlatformerModel.cs` | virtualCamera·player·spawnPoint 유지 + cardDeck·equippedItems·traits 필드 확장 |

### 3-3. 신규 (New) — 전용 시스템 11종

| 대상 | 목적 | 관련 기획 |
|---|---|---|
| `VillageController.cs` | 마을 허브 씬 제어 (스테이지 선택 UI·특성 관리·상태 확인) | 기획 05 §2-1 |
| `StageManager.cs` | 3단 스테이지 구조(도입→전개→보스방) + 구간 전환·보스룸 후방 차단 | 기획 05 §3-1 |
| `RunState.cs` | 현재 런 상태 (레벨·경험치·카드덱) — 사망 시 리셋 대상 | 기획 02 §4 |
| `MetaState.cs` | 영속 상태 (아이템·특성) — JSON 저장 | 기획 02 §4 |
| `SaveSystem.cs` | JSON 직렬화 (PlayerPrefs 불가 — 구조 복잡) · 저장소는 `Application.persistentDataPath` | 개발 03 §3-2 |
| `CardSystem/CardPool.cs`·`CardPick.cs`·`CardEffect.cs` (3파일) | 카드 풀·3픽 선택 UI·효과 적용 (`Simulation.Event<T>.OnExecute` 훅 연동) | 기획 03 §3 |
| `ItemSystem/ItemSlot.cs`·`ItemPickupUI.cs` (2파일) | 파츠 1개 교체식 장착·교체 UI | 기획 03 §4 |
| `TraitSystem/TraitManager.cs` | 특성 영구 유지 + 런 시작 시 자동 적용 | 기획 03 §5 |
| `BossController.cs` | `EnemyController` 상속 — 페이즈·패턴·후방 차단 트리거 | 기획 05 §3-2 |
| `LevelUpFlow.cs` | 경험치 누적 → LevelUp 이벤트 → 카드 3픽 → 재개 | 기획 02 §2 |
| `DamageSystem/AttackHitbox.cs` | 근거리 AABB 판정 — 플레이어 공격 처리 | 기획 04 §5-1 |

## 4. 의존·확장 지점 요지

```
GameController (Singleton)
    └── Simulation.Tick()
            └── eventQueue (HeapQueue<Event>)
                    └── Event<T>.OnExecute  ← 카드·특성 훅 지점 (신규)
                            └── PlayerController
                                    └── KinematicObject (물리)
                                    └── Health (i-frame 추가)
                                    └── PlatformerModel (확장)
                                            └── CardDeck·Items·Traits (신규 필드)
```

- **카드 효과 훅**: `PlayerAttack.OnExecute += CardEffectProcessor.Apply` 패턴으로 무관섭 확장
- **사망 체인**: `PlayerDeath → ResetRunState → TeleportToVillage` 3단 이벤트 체인
- **씬 전환**: Additive Load로 마을·전투 씬 공존 또는 Single Load + 페이드 연출

## 5. C11 개발 관점 평가

| 기준 | 평가 | 근거 |
|---|---|---|
| **자원 효율성** | ✅ 양호 | 이벤트 풀링·Kinematic 물리·Cinemachine 등 모바일 친화 패턴 |
| **코드 직관성** | ✅ 양호 | 네임스페이스 분할 명확·이벤트 이름 명시적·Model 단일화 |
| **범용성** | ⚠️ 부분 | 플랫포머 한정. 로그라이크 메타 (런 상태·메타 상태) 구조 **신규 필요** (§3-3) |

## 6. 변경 이력

| 일시 | 변경 | 사유 | 기안 |
|---|---|---|---|
| 2026-04-23 | v0.1 스크립트 실측 분석 — 36개 전수 + 11개 본문 Read | BT5-Dev 3단계 | 개발팀장 |

## 7. 참조 문서

- `01_템플릿_구조_분석.md` — 디렉토리 구조·패키지 목록
- `03_게임_제작_준비.md` — 로드맵·P0/P1/P2 우선순위
- 기획 `03_진행_시스템_초안.md` §3·§4·§5 (카드·아이템·특성 설계)
- 기획 `04_전투_기본_스펙.md` §5 (공격 확장)
- 기획 `02_코어_루프.md` §4 (사망 시 상태 보존 매트릭스)