game/prompt/00_project_context_restore.md

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

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

1. 프로젝트 개요

• 프로젝트명: Colosseum's Choice
• 플랫폼: Flutter (Android/iOS/Web/Desktop)
• 장르: 텍스트 기반의 턴제 RPG + GUI (로그라이크 요소 포함)
• 상태: 프로토타입 단계 (전투 시각화, 데이터 주도 시스템, 반응형 UI 구현 완료)

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

A. 게임 흐름 (Game Flow)

1. 메인 메뉴 (MainMenuScreen): 게임 시작 버튼.
2. 캐릭터 선택 (CharacterSelectionScreen): 'Warrior' 직업 구현.
3. 메인 게임 (MainWrapper): 하단 탭 네비게이션 (Battle / Inventory).
4. 반응형 레이아웃 (Responsive UI):
   • ResponsiveContainer 위젯을 통해 최대 너비(600px) 및 높이(1000px) 제한.
   • 웹/태블릿 환경에서도 모바일 앱처럼 중앙 정렬된 화면 제공.
   • Battle UI Layout: 플레이어(좌측 하단) vs 적(우측 상단) 대각선 구도 배치 및 캐릭터 임시 아이콘 적용.
   • Widget Refactoring: BattleScreen의 주요 UI 컴포넌트(CharacterStatusCard, BattleLogOverlay 등)를 lib/widgets/battle/로 분리하여 모듈화.

B. 전투 시스템 (BattleProvider)

• 턴제 전투: 플레이어 턴 -> 적 턴.
• 행동 선택: 공격(Attack) / 방어(Defend).
• 리스크 시스템 (Risk System): Safe(100%/50%), Normal(80%/100%), Risky(40%/200%) 선택.
• 적 인공지능 (Enemy AI & Intent):
  • Intent UI: 적의 다음 행동(공격/방어, 리스크)을 미리 표시.
  • 선제 방어 (Pre-emptive Defense): 적이 방어를 선택하면 턴 시작 전에 즉시 방어도가 적용됨.
  • Defense Restriction: DefenseForbidden 상태 시 방어 행동 선택 불가.
  • Variance Removed: 적의 공격/방어 수치 계산 시 랜덤 분산(Variance) 제거 (고정 수치).
• 적 장비 시스템 (Enemy Equipment):
  • 적에게 아이템 장착 가능 (enemies.json의 equipment 필드).
  • 장착된 아이템의 스탯 및 특수 효과(상태이상 등)가 전투 시 적용됨.
• 시각 효과 (Visual Effects):
  • Floating Text: 데미지 발생 시 캐릭터 위에 데미지 수치가 떠오름 (일반: 빨강, 출혈: 보라, 취약: 주황).
  • Action Feedback: 공격 빗나감(MISS - 적 위치/회색) 및 방어 실패(FAILED - 내 위치/빨강) 텍스트 오버레이.
  • Effect Icons: 공격/방어 및 리스크 레벨에 따른 아이콘 애니메이션 출력.
• 상태이상: Stun, Bleed, Vulnerable, DefenseForbidden.
• 행운 시스템 (Luck System):
  • 아이템 옵션으로 luck 스탯 제공.
  • totalLuck 수치만큼 행동(공격/방어) 성공 확률 증가 (1 Luck = +1%).
  • 성공 확률은 최대 100%로 제한됨.
  • UI: 인벤토리에서 Luck 수치 확인 가능, 전투 시 Risk 선택 창에서 보정된 확률 표시.

C. 데이터 주도 설계 (Data-Driven Design)

• JSON 데이터: assets/data/items.json (ID 포함), assets/data/enemies.json (장비 포함).
• 데이터 로더: ItemTable (ID 조회 지원), EnemyTable (장비 장착 지원).

D. 아이템 및 경제 (Item, Inventory)

• 장비: 무기, 방어구, 방패, 장신구.
• 아이콘 및 색상 (ItemUtils):
  • 무기: 빨강 삼각형 (Icons.change_history)
  • 방패: 파랑 방패 (Icons.shield)
  • 갑옷: 파랑 옷 (Icons.checkroom)
  • 장신구: 보라 다이아몬드 (Icons.diamond)
• 가격: JSON 고정 가격 사용. 판매 시 60% (GameMath.floor) 획득.
• 인벤토리: 장착 슬롯 및 가방(Bag) 그리드 UI 구현.

E. 스테이지 시스템 (StageModel)

• 타입: Battle, Shop, Rest, Elite.
• 적 생성: 스테이지 레벨에 따른 스탯 스케일링 적용.
• 게임 구조 (Game Structure):
  • 총 3라운드 (3 Rounds): 각 라운드는 12개의 스테이지로 구성 (12/12/12).
  • 라운드 구성:
    1. 1라운드: 지하 불법 투기장 (Underground Illegal Arena)
    2. 2라운드: 콜로세움 (Colosseum)
    3. 3라운드: 왕의 투기장 (King's Arena) - 최종 보스(Final Boss) 등장.

3. 핵심 파일 및 아키텍처

• lib/providers/battle_provider.dart:
  • Core Logic: 상태 관리, 전투 루프.
  • Streams: damageStream, effectStream을 통해 UI(BattleScreen)에 비동기 이벤트 전달.
• lib/game/enums.dart: 프로젝트 전반의 Enum 통합 관리 (ActionType, RiskLevel, StageType 등).
• lib/utils/item_utils.dart: 아이템 타입별 아이콘 및 색상 로직 중앙화.
• lib/widgets/battle/: BattleScreen에서 분리된 재사용 가능한 위젯들 (CharacterStatusCard, BattleLogOverlay, FloatingBattleTexts, StageUI).
• lib/widgets/responsive_container.dart: 반응형 레이아웃 컨테이너.
• lib/game/model/:
  • damage_event.dart, effect_event.dart: 이벤트 모델.
  • entity.dart: Character (Player/Enemy).
  • item.dart: Item (ID 필드 포함).
• lib/screens/battle_screen.dart:
  • StreamSubscription을 통해 이펙트 이벤트 수신 및 Overlay 애니메이션 렌더링.
  • Stack 및 Positioned 기반의 정교한 레이아웃.

4. 작업 컨벤션 (Working Conventions)

• Prompt Driven Development: prompt/XX_description.md 유지.
• State Management: Provider + Stream (이벤트성 데이터).
• Data: JSON 기반.

5. 다음 단계 작업 (Next Steps)

1. 상점 구매 기능: Shop 스테이지 구매 UI 구현.
2. 이미지 리소스 적용: JSON 경로에 맞는 실제 이미지 파일 추가 및 UI 표시.
3. 밸런싱 및 콘텐츠 확장: 아이템/적 데이터 추가 및 밸런스 조정.

6. 장기 목표 (Future Roadmap / TODO)

• 출혈 상태 이상 조건 변경: 공격 시 상대방의 방어도에 의해 공격이 완전히 막힐 경우, 출혈 상태 이상이 적용되지 않도록 로직 변경.
• 장비 분해 시스템 (적 장비): 플레이어 장비의 옵션으로 상대방의 장비를 분해하여 '언암드' 상태로 만들 수 있는 시스템 구현.
• 플레이어 공격 데미지 분산(Variance) 적용 여부 검토: 현재 적에게만 적용된 +/- 20% 데미지 분산을 플레이어에게도 적용할지 결정.
• 애니메이션 및 타격감 고도화:
  • 캐릭터별 이미지 추가 및 하스스톤 스타일의 공격 모션(대상에게 돌진 후 타격) 구현.
  • Risky 공격: 하스스톤의 7데미지 이상 타격감(화면 흔들림, 강렬한 파티클 및 임팩트) 재현.
• 체력 조건부 특수 능력: 캐릭터의 체력이 30% 미만일 때 발동 가능한 특수 능력 시스템 구현.
• 영구 스탯 수정자 로직 적용 (필수):
  • 현재 Character 클래스에 permanentModifiers 필드만 선언되어 있음.
  • 추후 totalAtk, totalDefense, totalMaxHp 계산 시 이 수정자들을 반드시 반영해야 함.
• Google OAuth 로그인 및 계정 연동:
  • Firebase Auth 등을 활용한 구글 로그인 구현.
  • Firestore 또는 Realtime Database에 유저 계정 정보(진행 상황, 재화 등) 저장 및 불러오기 기능 추가.
  • Note: 이 기능은 게임의 핵심 로직이 안정화된 후, 완전 나중에 진행할 예정입니다.

---

이 프롬프트를 읽은 AI 에이전트는 위 내용을 바탕으로 즉시 개발을 이어가십시오.