asciinevrdie/doc/progress-quest-flutter-plan.md

목표

• example/pq의 Progress Quest 6.4 싱글플레이 체험을 Flutter로 1:1 재현(게임플레이, 이름 생성, 레벨업/퀘스트/플롯 진행 로직까지 동일).
• 온라인/네트워크 기능(서버 선택, 계정/비밀번호, 길드/자랑 업로드, 웹 링크 열기, HTTP 요청)은 전부 제거하거나 더미로 대체한 완전 오프라인 버전 구현.
• 기존 데이터(종족, 직업, 스펠, 무기/방어구, 몬스터, 아이템 속성 등)는 원본과 같은 풀셋을 포함시켜 동일한 결과가 나오도록 유지.

참조 소스(원본 Delphi)

• 메인 루프/타이머/퀘스트/레벨업: example/pq/Main.pas
• 캐릭터 생성/주사위 굴림/이름 생성: example/pq/NewGuy.pas
• 데이터 세트(메모 내용): example/pq/Config.dfm (Spells, Weapons, Armors, Shields, Monsters, ItemAttrib/ItemOfs, Races, Klasses, Titles, ImpressiveTitles 등)
• 네트워크 관련 제거 대상: example/pq/Web.pas, HTTPGet.pas, SelServ.pas, Login.*, Info.*, Front.*(웹 링크 부분), Main.pas 내 Brag, Guildify, Navigate, AuthenticateUrl 호출부
• 자산: swords.gif, crossed_swords_sm.gif, screenshots.zip(참고용), pq.res(아이콘 참고)

범위와 비범위

• 포함: 캐릭 생성(3d6×6, Re-Roll/Unroll, 자동 이름 생성), 퀘스트/플롯 진행 큐, 몬스터/아이템/장비/스펠 획득, 인카운터 텍스트 큐, 저장/불러오기, 진행 바(Task/Quest/Plot/EXP/Encumbrance), 로그 힌트(툴팁 수준), 기본 UI 흐름(프런트 → 새 게임/불러오기 → 메인 화면).
• 제외: 모든 HTTP 통신, 서버/길드/자랑 업로드, 프록시/패스키, 외부 브라우저 열기, 시스템 트레이 연동, Windows 레지스트리/파일 연관.

구현 계획(Flutter)

1. 프로젝트 세팅

   • flutter create로 신규 앱 생성(안드로이드/웹/데스크톱 동시 지원), lints/analysis 옵션 활성화.
   • 의존성: path_provider(세이브 파일 위치), shared_preferences 또는 로컬 파일 I/O, 필요 시 intl(날짜 포맷). 상태 관리는 기본 ChangeNotifier/ValueNotifier 또는 간단한 provider로 최소화.

2. 데이터 포팅

   • Config.dfm의 TMemo 내용을 파싱해 정적 JSON/const 리스트로 변환(스펠/무기/방어구/몬스터/수식어 등). 파싱 스크립트 작성 후 lib/data/에 Dart 소스로 고정.
   • 종족/직업/칭호/몬스터 레벨 등 숫자 필드는 원본 문자열 포맷(name|level) 그대로 저장하여 로직 재현.

3. 게임 상태/엔진

   • GameState 모델: Traits(이름/종족/직업/레벨), Stats(STR/CON/DEX/INT/WIS/CHA/HP/MP), 장비/스펠/인벤토리, 진행 큐(fQueue), 현재 태스크/퀘스트/플롯 상태, encumbrance.
   • 주기적 타이머(Ticker/Timer.periodic)로 TaskBar 증분, Dequeue 동작, LevelUp, CompleteQuest, CompleteAct, WinEquip/WinSpell/WinItem/WinStat, MonsterTask 로직을 원본 알고리즘에 맞게 Dart로 포팅.
   • 난수 처리: Random seed를 저장/복원 가능하게 두어 재현성 확보(세이브/로드 포함).
   • 캐릭 생성: 3d6 롤, Total 색상 규칙, Race/Class 선택, 이름 생성(GenerateName), Re-Roll/Unroll 이력 지원.

4. UI 구성

   • 프런트 화면: 새 게임/불러오기(파일 선택)/종료 선택. 웹 링크 버튼은 제거하거나 “오프라인 버전” 안내로 대체.
   • 캐릭터 생성 화면: 원본과 동일한 정보 배치(종족/직업 라디오, 6개 스탯 패널, Total 표시, Reroll/Unroll, Name 입력/자동생성).
   • 메인 화면: ProgressQuest 레이아웃을 Flutter 위젯으로 재현(ListView/SelectableRows → ListView.builder + ListTile), 상단 Traits/Stats, Equipment/Spells/Inventory, Task/Quest/Plot/EXP/Encumbrance ProgressBar(LinearProgressIndicator 커스텀), 퀘스트/플롯 리스트, 상태바 텍스트 표시.
   • 툴팁/힌트: Long-press/Tooltip 위젯으로 EXP/Plot/Quest 남은 시간, Encumbrance 등 표시.
   • 치트 패널/숨김 키 조합은 개발자 메뉴로 옵션화(토글 버튼 또는 디버그 빌드 한정).

5. 저장/불러오기

   • 세이브 구조: 원본의 Zlib 압축/컴포넌트 덤프 대신 JSON + GZip(GZipCodec)으로 단일 파일(.pqf 등) 저장. 기존 .pq 파일과는 별도 호환 경고 표시.
   • 자동 저장 시점: 레벨업, 퀘스트/플롯 완료, 앱 백그라운드/종료 전 후킹(각 플랫폼 라이프사이클 대응).
   • 불러오기: 파일 피커(웹 제외 시 기본 리스트) + 버전 검증 후 상태 복원.

6. 네트워크 제거/대체

   • Brag, Guildify, Navigate, AuthenticateUrl 등 호출부는 무력화하거나 UI에서 노출하지 않음.
   • 서버 선택/로그인/패스키 필드 제거. 관련 설정 값은 로컬 상태로만 유지.
   • 웹 브라우저 링크 버튼은 “온라인 기능 미지원” 안내 다이얼로그로 교체.

7. 검증/테스트

   • 단위 테스트: LevelUpTime, GenerateName(seed 고정), MonsterTask(레벨/수식어 변형), CompleteQuest 보상 분배, 인카운트 큐(Dequeue) 진행 여부.
   • 위젯 테스트: 메인 화면 로딩, 진행 바 증가, 세이브/로드 왕복.
   • 회귀 체크: Delphi 원본과 동일한 RNG seed에서 주요 출력(예: 첫 번째 몬스터 이름/퀘스트 문구/장비 이름) 비교 스냅샷.

8. 작업 순서 제안

   1. 데이터 추출 스크립트 작성 → Dart 정적 데이터 생성
   2. GameState/엔진 포팅 및 단위 테스트 확보
   3. 캐릭터 생성 UI + 상태 연결
   4. 메인 화면 레이아웃 구현 → 진행 루프 연동
   5. 세이브/로드/자동저장 구현
   6. 네트워크 UI 제거/대체 처리 후 스타일 폴리싱
   7. 멀티플랫폼 빌드 검증(모바일/데스크톱/웹) 및 최종 회귀 테스트