pet_data/docs/USAGE.md

虛擬寵物系統 - 使用說明

🚀 快速開始

方式一：瀏覽器 Console（推薦）

1. 啟動 Nuxt 開發伺服器：

npm run dev

2. 打開瀏覽器，訪問：http://localhost:3000/console-demo.html

3. 打開開發者工具（F12 或 Cmd+Option+I），切換到 Console 標籤

4. 系統會自動初始化，然後你可以輸入命令：

// 查看幫助
help()

// 顯示狀態
showStatus()

// 啟動遊戲循環
start()

// 餵食
feed(20)

// 玩耍
play(15)

// 祈福
pray()

// 抽籤
drawFortune()

方式二：Node.js 環境

node console-demo.js

📁 專案結構

nuxt-app/
├── data/                  # 資料配置（資料驅動）
│   ├── pet-species.js    # 寵物種族配置
│   ├── deities.js        # 神明資料
│   ├── events.js         # 事件配置
│   ├── items.js          # 道具配置
│   └── fortune-lots.js   # 籤詩資料
├── core/                 # 核心系統
│   ├── api-service.js    # API 服務層（支援 mock/real）
│   ├── pet-system.js     # 寵物系統
│   ├── event-system.js   # 事件系統
│   └── temple-system.js  # 神明系統
├── console-demo.js       # Console 互動介面
├── public/
│   └── console-demo.html # 瀏覽器版本
└── docs/
    ├── API_STRUCTURE.md  # API 端點文檔
    └── USAGE.md          # 本文件

🎮 可用命令

遊戲控制

• init() - 初始化系統
• start() - 啟動遊戲循環（每 3 秒 tick，每 10 秒檢查事件）
• stop() - 停止遊戲循環
• showStatus() - 顯示當前寵物狀態

寵物互動

• feed(amount) - 餵食（預設 +20 飢餓）
• play(amount) - 玩耍（預設 +15 快樂，+0.5 敏捷）
• clean() - 清理便便（+10 快樂）
• heal(amount) - 治療（預設 +20 健康，可治癒疾病）
• sleep() - 睡覺/起床（睡覺時 +5 健康）

事件系統

• triggerEvent(eventId) - 手動觸發事件（測試用）
• listEvents() - 查看所有可用事件
• history() - 查看事件歷史記錄
• applyBuffs() - 手動應用 Buff（通常自動執行）

神明系統

• pray() - 祈福（每日上限 3 次，+5 好感度）
• drawFortune() - 抽籤（獲得 Buff）
• switchDeity(deityId) - 切換神明（'mazu', 'earthgod', 'yuelao', 'wenchang', 'guanyin'）
• listDeities() - 查看所有神明及其好感度

🔌 API 整合

切換到真實 API

在 console-demo.js 或使用時修改：

import { ApiService } from './core/api-service.js'

const apiService = new ApiService({
  useMock: false,  // 切換到真實 API
  baseUrl: 'https://your-api-domain.com/api',
  mockDelay: 0
})

API 端點結構

詳見 docs/API_STRUCTURE.md，包含：

• 寵物狀態相關端點
• 事件系統端點
• Buff 系統端點
• 神明系統端點
• 籤詩系統端點
• 道具系統端點

📊 資料結構

PetState（寵物狀態）

{
  speciesId: 'tinyTigerCat',
  stage: 'baby',
  hunger: 80,
  happiness: 60,
  health: 100,
  weight: 500,
  ageSeconds: 0,
  str: 0,
  int: 0,
  dex: 0,
  luck: 15,
  isSleeping: false,
  isSick: false,
  isDead: false,
  currentDeityId: 'mazu',
  deityFavors: { mazu: 20, ... },
  dailyPrayerCount: 0,
  buffs: [],
  inventory: []
}

GameEvent（事件配置）

{
  id: 'lucky_find',
  type: 'good',
  weight: 0.3,
  condition: (state) => state.happiness > 50,
  effects: [
    { type: 'modifyStats', payload: { happiness: +10 } },
    { type: 'addBuff', payload: { ... } }
  ]
}

Buff（Buff 效果）

{
  id: 'fortune',
  name: '福運加持',
  durationTicks: 5,
  flat: { hunger: -10 },      // 固定值加成
  percent: { luck: 0.2 }      // 百分比加成
}

🎯 核心機制

Tick 循環

• 每 3 秒執行一次
• 自動衰減：飢餓 -5%，快樂 -8%
• 便便機率：2%
• 生病機率：1%

事件觸發

• 每 10 秒檢查一次
• 10% 機率觸發
• 依權重隨機選擇事件
• 檢查條件函數
• 執行效果（修改屬性、添加 Buff 等）

Buff 系統

• 每 tick 自動應用
• 計算公式：(base + flat) * (1 + percent)
• 持續時間倒數（Infinity 為永久）
• 可堆疊（需設定 stacks: true）

神明系統

• 5 位神明：媽祖、土地公、月老、文昌、觀音
• 每日祈福上限 3 次
• 好感度 0-100，每 20 點一星
• 不同神明有不同 Buff 加成

🛠️ 擴展開發

添加新事件

編輯 data/events.js：

{
  id: 'new_event',
  type: 'good',
  weight: 0.2,
  condition: (state) => state.luck > 20,
  effects: [
    { type: 'modifyStats', payload: { luck: +5 } },
    { type: 'logMessage', payload: '新事件觸發！' }
  ]
}

添加新道具

編輯 data/items.js：

newItem: {
  id: 'new_item',
  name: '新道具',
  type: 'consumable',
  effects: { modifyStats: { health: +30 } },
  description: '恢復健康'
}

添加新神明

編輯 data/deities.js：

{
  id: 'new_deity',
  name: '新神明',
  personality: '個性描述',
  buffs: { gameSuccessRate: 0.15 },
  buffDescriptions: ['小遊戲 +15%'],
  dialogues: ['對話 1', '對話 2'],
  icon: 'deity-new'
}

🐛 除錯技巧

1. 查看狀態：showStatus()
2. 查看事件歷史：history()
3. 手動觸發事件：triggerEvent('lucky_find')
4. 檢查 Buff：eventSystem.getBuffManager().getActiveBuffs()
5. 檢查 API 模式：apiService.useMock

📝 注意事項

1. Mock 模式：資料儲存在 localStorage，刷新頁面會保留
2. API 同步：所有狀態更新都會嘗試同步到 API（失敗時降級到本地）
3. 事件條件：條件函數必須返回 boolean
4. Buff 計算：每 tick 自動應用，無需手動呼叫（除非測試）
5. 每日限制：祈福次數每日重置（需實作時間檢查）

🔮 未來擴展

• 實作真實 API 後端
• 加入認證系統（JWT）
• 實作多人互動
• 加入小遊戲系統
• 實作繁殖系統
• 加入成就系統
• 實作排行榜