asciinevrdie/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

프로젝트 개요

Askii Never Die는 Progress Quest 6.4의 핵심 메커니즘을 기반으로, 독자적 세계관("디지털 판타지")과 확장된 시스템으로 재구성한 오프라인 싱글플레이어 방치형 RPG입니다. 네트워크 기능은 제외됩니다.

빌드 및 실행

# 의존성 설치
flutter pub get

# 실행 (플랫폼 지정 가능: -d macos, -d chrome 등)
flutter run

# 핸드오프 전 필수 검증
dart format --set-exit-if-changed .
flutter analyze
flutter test

아키텍처

디렉토리 구조

lib/
├── main.dart                          # 앱 진입점
├── data/                              # 정적 데이터 (Config.dfm 추출 + 확장)
│   ├── pq_config_data.dart            # PQ 원본 정적 데이터
│   ├── class_data.dart                # 직업 데이터
│   ├── race_data.dart                 # 종족 데이터
│   ├── skill_data.dart                # 스킬 데이터
│   ├── potion_data.dart               # 포션 데이터
│   ├── story_data.dart                # 스토리 데이터
│   └── game_text_l10n.dart            # 게임 텍스트 번역
├── l10n/                              # 앱 UI 다국어 리소스 (arb)
└── src/
    ├── app.dart                       # MaterialApp 설정
    ├── core/
    │   ├── engine/                    # 게임 루프 및 진행 로직
    │   │   ├── progress_loop.dart         # 타이머 기반 메인 루프
    │   │   ├── progress_service.dart      # 틱 처리, 경험치/레벨업 로직
    │   │   ├── game_mutations.dart        # 상태 변경 함수
    │   │   ├── reward_service.dart        # 보상 처리
    │   │   ├── combat_calculator.dart     # 전투 계산
    │   │   ├── combat_tick_service.dart   # 전투 틱 처리
    │   │   ├── arena_service.dart         # 아레나 시스템
    │   │   ├── skill_service.dart         # 스킬 시스템
    │   │   ├── item_service.dart          # 아이템 처리
    │   │   ├── potion_service.dart        # 포션 시스템
    │   │   ├── shop_service.dart          # 상점 시스템
    │   │   ├── story_service.dart         # 스토리 진행
    │   │   └── ...                        # 기타 서비스
    │   ├── model/                     # 게임 상태 및 데이터 모델
    │   ├── animation/                 # ASCII 애니메이션 데이터/렌더링
    │   ├── audio/                     # 오디오 서비스
    │   ├── storage/                   # 세이브/설정 저장소
    │   ├── notification/              # 알림 서비스
    │   ├── constants/                 # 상수 정의
    │   ├── l10n/                      # 게임 데이터 번역 유틸
    │   └── util/                      # 유틸리티 (RNG, 로직 헬퍼 등)
    ├── features/
    │   ├── front/                     # 타이틀/세이브 선택 화면
    │   ├── new_character/             # 캐릭터 생성 화면
    │   ├── game/                      # 게임 진행 화면 (메인)
    │   │   ├── controllers/           # 전투 로그, 오디오 컨트롤러
    │   │   ├── managers/              # 통계, 부활, 속도 부스트 등
    │   │   ├── pages/                 # 탭별 페이지 (장비, 인벤토리, 퀘스트 등)
    │   │   └── widgets/              # UI 위젯
    │   ├── arena/                     # 아레나 전투 화면
    │   ├── hall_of_fame/              # 명예의 전당
    │   └── settings/                  # 설정 화면
    └── shared/                        # 공통 테마/위젯

example/pq/     # Delphi 원본 소스 (참조용, 빌드 대상 아님)
test/           # 단위/위젯 테스트

레이어 구조 (Clean Architecture)

• Presentation (features/) → Domain (core/model/, core/engine/) → Data (data/, core/storage/)
• 역방향 의존 금지: Domain은 Flutter/UI import 불가

핵심 데이터 흐름

1. ProgressLoop가 타이머로 tickOnce() 호출
2. ProgressService.tick()이 GameState 업데이트
3. GameState 스트림으로 UI 갱신
4. 레벨업/퀘스트 완료 시 SaveManager 자동 저장

핵심 규칙

원본 참조 정책

• example/pq/는 참조용으로 유지
• 원본 알고리즘은 참고하되 독자적 확장/수정 허용

데이터 관리

• 정적 데이터(몬스터, 아이템, 주문 등)는 Config.dfm에서 추출하여 JSON/Dart const로 관리
• 영문 원문 기준 작성, UI 텍스트는 i18n 구조로 분리
• 이미지 파일 미사용

코딩 표준

• 2-space 인덴트, dart format 준수
• 타입 명시적 선언, any/dynamic 지양
• 파일명: snake_case, 클래스: PascalCase, 변수/함수: camelCase
• 파일당 200 LOC 이하, 함수 20 라인 이하 권장
• SRP(Single Responsibility Principle) 준수

화면 구성

• 주요 화면: 프론트, 캐릭터 생성, 게임 진행, 아레나, 명예의 전당, 설정
• 화면 내 요소는 위젯 단위로 분리

원본 소스 참조 (example/pq/)

참고용으로만 사용. 원본 로직을 그대로 따를 의무는 없음.

파일	핵심 함수/라인	역할
Main.pas:523-1040	MonsterTask	전투/전리품/레벨업
Main.pas:267-424	StartTimer	메인 게임 루프
Main.pas:456-521	InterplotCinematic, NamedMonster	시네마틱/명명
NewGuy.pas:55-68	RerollClick	캐릭터 생성 (3d6)
Config.dfm	TMemo 데이터	주문, 몬스터, 아이템, 종족, 직업 등

승인 필요 사항

• pubspec.yaml 의존성 변경
• 플랫폼 빌드 설정 (Android/iOS/desktop)
• 네트워크 접근 도입
• 대규모 파일 삭제 또는 구조 변경

커밋 규칙

type(scope): 한국어 설명

- 변경 상세 내용

Types: feat, fix, refactor, test, docs, style, chore, perf