info.md

로컬 TRPG 메이커 프로젝트 구조

이제까지 작성된 코드를 기반으로 전체 프로젝트의 구조를 정리하겠습니다. 각 파일과 함수들의 관계와 역할을 체계적으로 설명하겠습니다.

프로젝트 폴더 구조

📂 src/
├── config/                       # 환경 설정
│   ├── constants.py              # 상수 정의
│   └── styles.py                 # UI 스타일 정의
├── modules/                      # 기능 모듈
│   ├── ai_service.py             # AI 서비스 연동
│   ├── character_creation.py     # 캐릭터 생성 기능
│   ├── character_utils.py        # 캐릭터 관련 유틸리티
│   ├── game_play.py              # 게임 플레이 기능
│   ├── item_manager.py           # 아이템 관리 기능
│   └── world_description.py      # 세계관 설명 기능
├── utils/                        # 유틸리티 함수
│   ├── dice_roller.py            # 주사위 굴림 기능
│   ├── location_manager.py       # 위치 관리 기능
│   ├── session_manager.py        # 세션 상태 관리
│   └── theme_manager.py          # 테마 관리 기능
└── main.py                       # 메인 애플리케이션

파일별 주요 기능

main.py

• 애플리케이션의 진입점
• 전체 UI 레이아웃 구성 및 단계 흐름 제어
• 세션 상태 초기화 및 관리
• 현재 단계(stage)에 따른 UI 표시 로직

config/constants.py

• 애플리케이션 전반에서 사용되는 상수 정의
• 통합된 상수 관리로 일관성 유지
• 주요 상수: 스텟 이름, 테마 유형, AI 서비스 설정 등

config/styles.py

• UI 스타일 관련 CSS 정의
• 일관된 디자인 시스템 유지
• 주요 스타일: 카드, 버튼, 패널, 알림 등의 스타일 정의

modules/ai_service.py

• AI 서비스 연동 기능
• 주요 함수:
  • setup_gemini(): AI 모델 초기화
  • generate_gemini_text(): AI 모델로 텍스트 생성
  • generate_world_description(): 세계관 생성
  • generate_character_options(): 캐릭터 배경 옵션 생성
  • generate_story_response(): 주사위 결과에 따른 스토리 생성
  • get_ability_suggestion(): 행동에 적합한 능력치 제안
  • master_answer_game_question(): 마스터 질문 응답 생성

modules/character_creation.py

• 캐릭터 생성 관련 기능
• 주요 함수:
  • initialize_character_creation_state(): 캐릭터 생성 상태 초기화
  • display_character_creation_page(): 캐릭터 생성 페이지 표시
  • display_race_selection(): 종족 선택 UI 표시
  • display_profession_selection(): 직업 선택 UI 표시
  • display_background_selection(): 배경 선택 UI 표시
  • display_abilities_selection(): 능력치 설정 UI 표시
  • ability_roll_section(): 주사위 굴림 기반 능력치 생성
  • base_abilities_section(): 기본 능력치 설정
  • display_character_review(): 캐릭터 최종 확인

modules/character_utils.py

• 캐릭터 관련 유틸리티 함수
• 주요 함수:
  • generate_races(): 테마별 종족 목록 생성
  • generate_professions(): 테마별 직업 목록 생성
  • extract_background_tags(): 배경 스토리에서 태그 추출
  • get_stat_info(): 능력치 정보 및 시각적 표현 제공
  • generate_special_trait(): 캐릭터 특별 특성 생성

modules/game_play.py

• 게임 플레이 핵심 기능
• 주요 함수:
  • initialize_game_state(): 게임 상태 초기화
  • display_game_play_page(): 게임 플레이 페이지 표시
  • display_character_panel(): 캐릭터 정보 패널 표시
  • display_story_and_actions(): 스토리 및 행동 UI 표시
  • handle_action_phase(): 행동 단계 관리
  • handle_movement(): 위치 이동 처리
  • handle_ability_check(): 능력치 판정 처리
  • handle_action_suggestions(): 행동 제안 관리
  • handle_story_progression(): 스토리 진행 처리
  • display_game_tools(): 게임 도구 패널 표시
  • display_master_question_ui(): 마스터 질문 UI 표시

modules/item_manager.py

• 아이템 관리 기능
• 주요 함수 및 클래스:
  • Item 클래스: 아이템 데이터 및 메서드 정의
  • initialize_inventory(): 테마별 기본 인벤토리 초기화
  • display_inventory(): 인벤토리 아이템 표시
  • display_inventory_for_review(): 캐릭터 검토용 인벤토리 표시
  • extract_items_from_story(): 스토리에서 아이템 추출
  • extract_used_items_from_story(): 사용된 아이템 추출
  • update_inventory(): 인벤토리 아이템 추가/제거/사용

modules/world_description.py

• 세계관 설명 관련 기능
• 주요 함수:
  • world_description_page(): 세계관 설명 페이지 표시
  • process_question(): 세계관 질문 처리
  • handle_world_expansion(): 세계관 확장 처리

utils/dice_roller.py

• 주사위 관련 유틸리티
• 주요 함수:
  • roll_dice(): 기본 주사위 굴림
  • calculate_dice_result(): 주사위 표현식 계산
  • display_dice_animation(): 주사위 굴림 애니메이션

utils/location_manager.py

• 위치 관련 유틸리티
• 주요 함수:
  • generate_locations(): 테마별 위치 생성
  • generate_movement_story(): 이동 스토리 생성
  • get_location_image(): 위치 이미지 생성

utils/session_manager.py

• 세션 상태 관리 유틸리티
• 주요 함수:
  • reset_game_session(): 게임 세션 초기화
  • initialize_session_state(): 세션 상태 초기화

utils/theme_manager.py

• 테마 관련 유틸리티
• 주요 함수:
  • create_theme_image(): 테마별 이미지 생성
  • get_theme_description(): 테마 설명 제공

주요 기능 흐름

1. 초기화 및 메인 UI: main.py에서 시작하여 각 모듈 초기화
2. 테마 선택: 사용자가 테마 선택 → theme_manager.py의 함수 활용
3. 세계관 생성: ai_service.py를 통해 세계관 생성
4. 세계관 탐색: world_description.py를 통해 세계관 확장 및 질문 처리
5. 캐릭터 생성: character_creation.py의 단계별 함수를 통해 캐릭터 생성
6. 게임 플레이: game_play.py를 통해 스토리 진행, 행동 처리, 능력치 판정 등

개선된 설계 특징

1. 모듈화: 기능별로 명확히 분리된 모듈로 유지보수성 향상
2. 단일 책임 원칙: 각 모듈과 함수가 명확한 하나의 책임을 가짐
3. 상태 관리: 세션 상태를 효율적으로 관리하여 일관된 사용자 경험 제공
4. UI/비즈니스 로직 분리: 표시 로직과 비즈니스 로직을 분리
5. 확장성: 새로운 기능, 테마, 아이템 등을 쉽게 추가할 수 있는 구조
6. 재사용성: 공통 유틸리티 함수를 통해 코드 중복 제거

이 구조는 기존의 단일 파일 애플리케이션(app.py)에 비해 훨씬 더 체계적이고 유지보수하기 쉬운 코드베이스를 제공합니다. 각 모듈은 독립적으로 테스트하고 개발할 수 있으며, 전체 시스템의 복잡성을 관리하기 쉽게 합니다.