NerdNavis_AiDev
/
BurningTimesAi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
BurningTimesAi/프로젝트/EerieVillage/개발/02_스크립트_분석.md

12 KiB
Raw Permalink Blame History

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 핵심)

// 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)

// 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)

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)

// 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 (사망 시 상태 보존 매트릭스)