horoli
/
game
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
game/prompt/00_project_context_restore.md

11 KiB
Raw Blame History

00. 프로젝트 컨텍스트 및 복구 (Project Context & Restore Point)

이 파일은 다른 개발 환경이나 새로운 AI 세션에서 프로젝트의 현재 상태를 빠르게 파악하고 작업을 이어가기 위해 작성되었습니다.

1. 프로젝트 개요

  • 프로젝트명: Colosseum's Choice
  • 플랫폼: Flutter (Android/iOS/Web/Desktop)
  • 장르: 텍스트 기반의 턴제 RPG + GUI (로그라이크 요소 포함)
  • 상태: 핵심 시스템 구현 완료 및 안정화 (i18n 구조 적용, 애니메이션 동기화 완료)

2. 현재 구현된 핵심 기능 (Feature Status)

A. 게임 흐름 (Game Flow)

  1. 메인 메뉴 (MainMenuScreen): 게임 시작, 이어하기(저장된 데이터 있을 시), 설정 버튼.
  2. 캐릭터 선택 (CharacterSelectionScreen): 'Warrior' 직업 구현 (스탯 확인 후 시작).
  3. 메인 게임 (MainWrapper): 하단 탭 네비게이션 (Battle / Inventory / Settings).
  4. 설정 (SettingsScreen):
    • 적 애니메이션 활성화/비활성화 토글 (SettingsProvider 연동).
    • 게임 재시작, 메인 메뉴로 돌아가기 기능.
  5. 반응형 레이아웃 (Responsive UI):
    • ResponsiveContainer를 통해 다양한 화면 크기 대응 (최대 너비/높이 제한).
    • Battle UI: 플레이어(좌하단) vs 적(우상단) 대각선 구도.

B. 전투 시스템 (BattleProvider)

  • 턴제 전투: 플레이어 턴 -> 적 턴.
  • 행동 선택: 공격(Attack) / 방어(Defend).
  • 리스크 시스템 (Risk System):
    • Safe: 성공률 100%+, 효율 50%.
    • Normal: 성공률 80%+, 효율 100%.
    • Risky: 성공률 40%+, 효율 200% (성공 시 강력한 이펙트).
    • Luck 보정: totalLuck 1당 성공률 +1%.
  • 회피 시스템 (Dodge System):
    • 캐릭터는 dodge 스탯을 가지며, 공격을 회피할 확률이 생김.
    • CombatCalculator에서 회피 성공 여부를 계산.
    • 공격이 회피되면 dodge 피드백과 함께 데미지가 0으로 처리됨.
  • 적 인공지능 (Enemy AI & Intent):
    • Intent UI: 적의 다음 행동(공격/방어, 데미지/방어도) 미리 표시.
    • 동기화된 애니메이션: 적 행동 결정(_generateEnemyIntent)은 이전 애니메이션이 완전히 끝난 후 이루어짐.
    • 선제 방어: 적이 방어 행동을 선택하면 턴 시작 시 데이터상으로 즉시 방어도가 적용되나, 시각적 애니메이션은 플레이어가 행동을 선택하는 시점에 발동됨.
  • 애니메이션 및 타격감 (Visuals & Impact):
    • UI 주도 Impact 처리: 애니메이션 타격 시점(onImpact)에 정확히 데미지가 적용되고 텍스트가 뜸 (완벽한 동기화).
    • 적 돌진: 적도 공격 시 플레이어 위치로 돌진함 (설정에서 끄기 가능).
    • 이펙트: 타격 아이콘, 데미지 텍스트(Floating Text, Risky 공격 시 크기 확대), 화면 흔들림(ShakeWidget), 폭발(ExplosionWidget). 적 방어 시 성공/실패 이펙트 추가.
  • 상태이상: Stun, Bleed, Vulnerable, DefenseForbidden, Disarmed.
  • UI 알림 (Toast): 하단 네비게이션을 가리지 않는 상단 Overlay 기반 알림 시스템.

C. 데이터 및 로직 (Architecture)

  • Data-Driven: items.json, enemies.json, players.json.
  • Logic 분리:
    • BattleProvider: UI 상태 관리 및 이벤트 스트림(damageStream, effectStream) 발송.
    • CombatCalculator: 데미지 공식, 확률 계산, 상태이상 로직을 순수 함수화하여 전투 로직의 재사용성과 테스트 용이성을 높임.
      • 공격/방어 액션 타입별 효율 분리: 각 행동(공격/방어) 및 리스크 레벨(Safe, Normal, Risky)에 따른 효율(efficiency)을 분리하여 적용.
      • 받는 피해 계산: 취약성(Vulnerable) 적용 및 현재 방어도를 통한 데미지 흡수 계산 (calculateDamageToHp, calculateRemainingArmor).
      • 주는 피해 계산: 공격자가 Disarmed 상태일 경우, 최종 데미지 값에 대한 감폭 적용 (Character.totalAtk 게터에서 처리).
      • 기타 계산: 회피 확률(calculateDodge), 턴 시작 효과(processStartTurnEffects), 아이템에 의한 상태이상 적용 확률(getAppliedEffects) 등을 담당.
    • BattleLogManager: 전투 로그 관리.
    • LootGenerator: 아이템 생성, 접두사(Prefix) 부여, 랜덤 스탯 로직.
    • SettingsProvider: 전역 설정(애니메이션 on/off 등) 관리 및 영구 저장.
    • PermanentStatModifier: 슬레이 더 스파이어의 승천(Ascension)과 유사한 전역 난이도 조절 또는 영구적 버프/디버프를 위한 데이터 모델(lib/game/model/stat_modifier.dart) 및 캐릭터 필드(Character.permanentModifiers)가 구현되어 있음. (현재 로직 미적용, 추후 확장 예정)
  • Soft i18n: UI 텍스트는 lib/game/config/app_strings.dart에서 통합 관리.
  • Config: GameConfig, BattleConfig, ItemConfig 등 설정 값 중앙화. BattleConfig의 공격/방어 효율 분리.

D. 아이템 및 경제

  • 장비: 무기, 방어구, 방패, 장신구.
  • 시스템:
    • Rarity: Common ~ Unique.
    • Tier: 라운드 진행도에 따라 상위 티어 아이템 등장.
    • Prefix: Rarity에 따라 접두사가 붙으며 스탯이 변형됨 (예: "Sharp Wooden Sword").
  • 상점 (ShopProvider): 아이템 구매/판매, 리롤(Reroll), 인벤토리 관리.

E. 저장 및 진행 (Persistence)

  • 자동 저장: 스테이지 클리어 시 SaveManager를 통해 자동 저장.
  • Permadeath: 패배 시 저장 데이터 삭제 (로그라이크 요소).

G. 스테이지 시스템 (Stage System)

  • Map Generation: 진행에 따라 랜덤하게 다음 스테이지 타입이 결정됨 (현재는 단순 랜덤).
  • Underground Colosseum System (Rounds/Tiers):
    • Round Progression: 스테이지 진행(stage count)에 따라 난이도(Tier)가 상승.
    • Tier:
      • Tier 1: Stage 1 ~ 12 (지하 불법 투기장)
      • Tier 2: Stage 13 ~ 24 (콜로세움)
      • Tier 3: Stage 25+ (왕의 투기장)
  • Stage Types:
    • Battle: 일반 몬스터 전투.
    • Elite: 강화된 몬스터 전투 (보상 증가, 12 스테이지마다 등장).
    • Shop: 아이템 구매/판매/리롤 (5 스테이지마다 등장).
    • Rest: 휴식 (8 스테이지마다 등장).

F. 코드 구조 (Code Structure - Barrel Pattern)

  • Barrel File Pattern: lib/ 내의 모든 주요 디렉토리는 해당 폴더의 파일들을 묶어주는 단일 진입점 파일(.dart)을 가집니다.
    • lib/game/models.dart, lib/game/config.dart, lib/game/data.dart, lib/game/logic.dart
    • lib/providers.dart, lib/utils.dart, lib/screens.dart, lib/widgets.dart
  • Imports: 개별 파일 import 대신 위 Barrel File을 사용하여 가독성과 유지보수성을 높였습니다.

3. 작업 컨벤션 (Working Conventions)

  • Prompt Driven Development: prompt/XX_description.md 유지. (유사 작업 통합 및 인덱스 정리 권장)
  • i18n Strategy (Soft i18n): UI에 표시되는 문자열은 하드코딩하지 않고 lib/game/config/app_strings.dart의 상수를 사용해야 합니다. (전투 로그 등 동적 문자열 제외)
  • Config Management: 하드코딩되는 값들은 config 폴더 내 파일들(lib/game/config/ 등)에서 통합 관리할 수 있도록 작성해야 합니다.
  • State Management: Provider (UI 상태) + Stream (이벤트성 데이터).
  • Data: JSON 기반 + Table 클래스로 로드.
  • Barrel File Pattern (Strict): lib/ 하위의 모든 주요 디렉토리는 Barrel File을 유지해야 하며, 외부에서 참조 시 반드시 이 Barrel File을 import 해야 합니다. 개별 파일에 대한 직접 import는 허용되지 않습니다.

4. 최근 주요 변경 사항 (Change Log)

  • [Feature] Dynamic Intent UI: 적의 상태(예: Disarmed) 변화 시, UI에 표시되는 인텐트(공격/방어 값)가 실시간으로 갱신되도록 로직을 개선하여 전투 정보의 정확성과 직관성 향상.
  • [Feature] Dodge Mechanic: 캐릭터의 dodge 스탯에 기반한 공격 회피 시스템 구현. 회피 시 전용 피드백과 함께 데미지 무효화.
  • [Refactor] BattleProvider: CombatCalculator, BattleLogManager, LootGenerator 분리로 코드 다이어트.
  • [Refactor] Animation Sync: Future.delayed 예측 방식을 버리고, UI 애니메이션 콜백(onImpact)을 통해 로직을 트리거하는 방식으로 변경하여 타격감 동기화 해결.
  • [Refactor] Settings: SettingsProvider 도입 및 적 애니메이션 토글 기능 추가.
  • [Fix] Bugs: 아이템 이름 생성 오류 수정, 리워드 팝업 깜빡임 및 중복 생성 수정, 앱 크래시(Null Safety) 수정.
  • [Feature] Interactive Enemy Defense Animation: 플레이어 행동(버튼 클릭) 시점에 적 방어 애니메이션 및 이펙트(Icon/FAILED 텍스트)가 발동되도록 구현. (데이터는 턴 시작 시 선적용)
  • [Improvement] Turn Responsiveness: 적 턴 종료 후 플레이어 턴 활성화까지의 불필요한 딜레이 제거 (_processMiddleTurn).
  • [Improvement] Visual Impact: Risky 공격 및 높은 데미지 시 Floating Damage Text의 크기 확대. Floating Effect/Feedback Text의 위치 조정.
  • [Refactor] Balancing System: BattleConfig에서 공격/방어 효율 상수를 분리하고 CombatCalculator 및 관련 로직에 적용하여 밸런싱의 유연성 확보.
  • [Fix] UI Stability: CharacterStatusCard의 Intent UI 텍스트 길이에 따른 레이아웃 흔들림 방지 (FittedBox). BattleScreen 내 Stack 위젯 구성 문법 오류 수정.
  • [Refactor] Barrel Pattern Adoption: 프로젝트 전체(lib/ 하위)에 Barrel File 패턴을 적용하여 Import 구문을 통합하고 디렉토리 의존성을 명확하게 정리.
  • [UI] Top-Aligned Toast: SnackBar를 상단 토스트 알림으로 교체하여 하단 네비게이션 가림 현상 해결 및 애니메이션 버그 수정.
  • [Fix] Asset 404 Error: 적 이미지 누락 문제 해결(Placeholder 적용) 및 pubspec.yaml 경로 업데이트.
  • [Refactor] ShopUI: 상점 UI의 문법 및 로직 오류 수정.
  • [Feature] Consumable Items: 체력/방어/공격버프 물약 구현. 전투 중 사용 가능하며, 사용 시 턴을 소모하지 않음(Free Action). 상점에서 판매.
  • [Feature] Enhanced Enemy Display: 적 이미지 동적 로딩 및 크기 확대, 스테이지 헤더에 Boss/Tier 정보 상세 표시.

5. 다음 단계 (Next Steps)

  1. 밸런싱: 현재 몬스터 및 아이템 스탯 미세 조정.
  2. 콘텐츠 확장: 더 많은 아이템, 적, 스킬 패턴 추가.
  3. 튜토리얼: 신규 유저를 위한 가이드 추가.