普爾小鎮 - 文字冒險 RPG 遊戲

專案簡介

PureTown 是一個以 Python 與 PyQt5 開發的文字冒險 RPG 遊戲，旨在透過構建完整的遊戲引擎，探索互動式敘事設計與現代化 UI/UX 實作技巧。本專案從零開始設計遊戲架構，實作章節系統、劇情處理、指令解析、狀態管理、背景音樂等核心功能，為玩家打造沉浸式的純文字冒險體驗。專案的核心挑戰在於設計一個輕量級但功能完整的遊戲引擎，並透過 PyQt5 實現優雅的使用者介面。

核心理念

• 遊戲引擎設計：從零構建模組化的文字冒險遊戲引擎
• UI/UX 優化學習：探索 PyQt5 進階功能，提升使用者體驗
• 劇情驅動系統：章節式敘事架構，支援分支劇情與多結局
• 狀態機管理：完整的遊戲狀態追蹤與儲存機制

我的職責

作為本專案的唯一開發者，我負責所有系統設計與實作：

遊戲引擎架構設計

• 設計模組化遊戲引擎架構（game/資料夾）：
  • GameState：遊戲狀態管理（章節進度、物品、標記、位置）
  • StoryHandler：劇情處理器（章節載入、場景轉換）
  • CommandHandler：指令解析系統（玩家輸入處理）
  • GameProcesser：遊戲流程控制器（遊戲循環、事件觸發）
• 建立資源管理系統（resources/資料夾）：
  • 劇情文本（story.py）
  • 風味文字（flavortext.py）
  • 場景資料（scene.py）

核心系統實作

• 章節系統：多章節架構，支援 Chapter:Section:Part 三層結構
• 物品系統：背包管理（inventory）、物品獲取/使用邏輯
• 標記系統：事件標記（flags）追蹤玩家選擇與劇情分支
• 地點系統：地圖導航（location、depth_map）、場景轉換
• 目標系統：任務追蹤（goals）、進度提示
• 文字渲染：逐字顯示效果（typewriter effect）、HTML 格式化

UI/UX 設計與實作

• 主視窗設計（RPGMainWindow）：
  • 描述視窗（QTextEdit）：主要劇情顯示區
  • 狀態面板：玩家位置、狀態資訊
  • 指令輸入框：玩家互動介面
  • 控制按鈕：Skip、Continue、Inventory、Journal 等
• 子視窗系統：
  • 背包視窗（InventoryWindow）：物品列表與使用
  • 日誌視窗（JournalWindow）：章節大綱與進度追蹤
• 自訂 Widget：
  • 背景切換按鈕（create_background_switch_button_edit）
  • 按壓效果按鈕（create_pressed_button_edit）
  • 自訂文字編輯器（create_text_edit）

音效與多媒體

• 整合 Pygame 背景音樂系統（AudioControl）
• 實作音樂播放/暫停/切換功能
• 背景音樂循環播放機制

核心功能

1. 遊戲引擎核心系統

• 狀態管理：
  • 章節進度追蹤（chapter:section:part）
  • 玩家位置與深度地圖（location, depth_map）
  • 背包系統（inventory）
  • 事件標記（flags）
  • 目標列表（goals）
• 劇情處理：
  • 章節式敘事結構
  • 場景載入與轉換
  • Cutscene 與 Gameplay 模式切換
  • 分支劇情支援
• 文字渲染引擎：
  • 逐字顯示效果（typewriter）
  • HTML 格式支援（換行、粗體、顏色）
  • 靜態文字與動態文字分離
  • 文字索引與行索引管理

2. 指令處理系統

• 指令解析：
  • 自然語言指令辨識
  • 指令驗證與錯誤提示
  • 可用指令動態生成（usable_commands）
• 常用指令：
  • 移動指令（go, move, walk）
  • 互動指令（use, take, examine）
  • 系統指令（save, load, help）
  • 快捷指令（skip, continue）

3. UI/UX 互動設計

• 主視窗佈局：
  • 800x600 固定視窗大小
  • 多區塊資訊顯示（描述、狀態、移動、互動、目標）
  • 指令輸入與執行回饋
• 視覺化元素：
  • 自訂背景圖片（border-image）
  • 圓角邊框設計（border-radius）
  • 按鈕懸停效果
  • Icon 按鈕（Home、Journal、Save、Music）
• 使用者體驗優化：
  • 鍵盤快捷鍵支援
  • 文字不可選取設定（避免誤操作）
  • 按鈕提示文字（tooltip）
  • 音樂開關切換

4. 資源管理系統

• 劇情資源：
  • 章節標題（chapter_titles）
  • 章節名稱（chapter_names）
  • 章節段落數（chapter_sections）
  • 場景資料（story_scene）
• 風味文字：
  • 物品描述（items）
  • 隨機遊戲文本（game_texts）
• 多媒體資源：
  • 背景音樂（dark-piano-Sociopath.mp3）
  • UI 圖片（home, journal, save icons）

5. 存檔與進度管理

• 狀態儲存：
  • 章節進度儲存
  • 物品與標記儲存
  • 位置資訊儲存
• 進度追蹤：
  • 當前進度顯示（get_current_progress）
  • 進度設定（set_current_progress）
  • 章節大綱檢視（Journal 視窗）

使用技術

核心框架

• Python 3.10+：主要開發語言
• PyQt5 (5.15.11)：GUI 框架
• Pygame (2.6.1)：音效與多媒體處理

UI 開發

• QtCore：核心功能（事件、定時器、訊號/槽）
• QtGui：圖形元件（字型、圖片、Icon）
• QtWidgets：UI 組件（視窗、按鈕、文字框）
• QTimer：文字逐字顯示定時器

專案管理

• Visual Studio：IDE（.pyproj、.sln）
• pip：套件管理（requirements.txt）
• 虛擬環境：隔離專案依賴（env/）

專案狀態

當前版本：開發中（logic-v.4 分支）

• 核心引擎狀態：基礎架構已完成，持續優化遊戲邏輯
• 劇情內容：章節架構已建立，內容持續擴充

功能完成度

• ✅ 已完成：
  • 遊戲引擎核心架構（GameState、StoryHandler、CommandHandler）
  • 章節系統與進度管理
  • 物品、標記、地點系統
  • 文字逐字顯示引擎
  • 背景音樂系統
  • 主視窗 UI 設計
  • 背包與日誌子視窗
  • 自訂 Widget 與按鈕
• 🔄 進行中：
  • 劇情內容撰寫與擴充
  • 遊戲邏輯優化（logic-v.4）
  • 場景轉換流暢度提升
  • 更多互動指令實作
• 📋 計畫中：
  • 戰鬥系統
  • 角色屬性系統
  • 多結局分支
  • 存檔/讀檔功能完善
  • 音效效果（SFX）

開發挑戰與收穫

1. 遊戲引擎架構設計

挑戰：如何從零設計一個模組化、可擴展的文字冒險遊戲引擎？

解決方案：

• 採用 MVC 架構分離遊戲邏輯與 UI：
  • Model：GameState（遊戲狀態）、Resources（資源）
  • View：RPGMainWindow（主視窗）、子視窗
  • Controller：CommandHandler（指令處理）、GameProcesser（流程控制）
• 設計狀態機管理章節進度與場景轉換
• 實作事件驅動系統，透過標記（flags）觸發劇情分支
• 建立資源管理模組，集中管理劇情、文字、場景資料

收穫：

• 深入理解遊戲引擎設計模式
• 掌握狀態機在遊戲開發中的應用
• 學習模組化設計與程式碼組織
• 提升系統架構規劃能力

2. PyQt5 進階 UI/UX 實作

挑戰：如何使用 PyQt5 實現優雅的文字冒險遊戲介面，並優化使用者體驗？

解決方案：

• 使用 QSS（Qt Style Sheets）自訂視覺風格：
  • border-image 設定背景圖片
  • border-radius 實現圓角設計
  • 自訂字型與顏色配置
• 實作自訂 Widget 函式封裝常用組件
• 使用 QTextEdit 的 HTML 支援實現豐富文字格式
• 設計響應式按鈕（hover、pressed 狀態）
• 實作鍵盤事件處理（KeyDown、KeyUp）

收穫：

• 掌握 PyQt5 進階功能與 QSS 語法
• 學習 Qt 訊號/槽機制（Signal/Slot）
• 理解事件驅動 GUI 設計模式
• 提升 UI/UX 設計與實作能力
• 學習使用者體驗優化技巧

3. 文字逐字顯示引擎

挑戰：如何實現流暢的文字逐字顯示效果，並支援 HTML 格式與換行？

解決方案：

• 使用 QTimer 定時器控制文字顯示速度
• 實作字元索引與行索引雙重追蹤：
  • word_index：當前字元位置
  • line_index：當前行數
• 設計 get_next_character() 方法逐字返回字元
• 使用 HTML <br><br> 標籤處理換行
• 實作 Skip 與 Continue 按鈕控制顯示流程

收穫：

• 掌握定時器在動畫效果中的應用
• 學習文字處理與索引管理技巧
• 理解 HTML 在 GUI 文字渲染中的應用
• 提升演算法設計與邏輯思維能力

4. 音效系統整合

挑戰：如何整合 Pygame 音效系統到 PyQt5 應用中，並實現背景音樂循環播放？

解決方案：

• 使用 Pygame 的 mixer 模組處理音效：
  • pygame.mixer.init()：初始化音效系統
  • pygame.mixer.music.load()：載入音樂檔案
  • pygame.mixer.music.play(-1)：循環播放（-1 參數）
• 實作 AudioControl 類別封裝音效操作
• 設計音樂開關按鈕（背景切換按鈕）
• 處理音樂狀態追蹤（music_playing）

收穫：

• 學習 Pygame 與 PyQt5 混合使用技巧
• 掌握音效系統基本操作
• 理解多媒體資源管理
• 提升跨函式庫整合能力

5. 劇情分支與狀態管理

挑戰：如何設計彈性的劇情分支系統，支援玩家選擇影響後續劇情？

解決方案：

• 使用標記系統（flags）記錄玩家行為：
  • add_flag(flag_name)：新增標記
  • check_flag(flag_name)：檢查標記存在
• 設計條件判斷邏輯，根據標記載入不同場景
• 實作物品系統影響劇情（特定物品觸發特定事件）
• 建立章節:段落:部分三層結構，支援細緻的劇情控制

收穫：

• 掌握遊戲狀態管理技巧
• 學習分支劇情設計模式
• 理解事件驅動與條件判斷邏輯
• 提升互動式敘事設計能力
• 培養遊戲設計思維

專案架構

PureTownDemo/
├── Main.py              # 遊戲入口點
├── ui/                  # UI 層
│   ├── main_window.py   # 主視窗
│   ├── inventory_window.py  # 背包視窗
│   ├── journal_window.py    # 日誌視窗
│   └── widgets.py       # 自訂 Widget
├── game/                # 遊戲引擎層
│   ├── game_state.py    # 狀態管理
│   ├── story_handling.py    # 劇情處理
│   ├── command_handling.py  # 指令解析
│   ├── game_processer.py    # 流程控制
│   ├── outline_handling.py  # 大綱處理
│   └── audio_control.py     # 音效控制
├── resources/           # 資源層
│   ├── story.py         # 劇情文本
│   ├── flavortext.py    # 風味文字
│   ├── scene.py         # 場景資料
│   ├── images/          # 圖片資源
│   └── audio/           # 音效資源
└── utils/               # 工具層
    └── data.py          # 資料定義