pet_data/docs/USAGE.md

# 虛擬寵物系統 - 使用說明

## 🚀 快速開始

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

1. 啟動 Nuxt 開發伺服器：
```bash
npm run dev
```

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

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

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

```javascript
// 查看幫助
help()

// 顯示狀態
showStatus()

// 啟動遊戲循環
start()

// 餵食
feed(20)

// 玩耍
play(15)

// 祈福
pray()

// 抽籤
drawFortune()
```

### 方式二：Node.js 環境

```bash
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` 或使用時修改：

```javascript
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（寵物狀態）
```javascript
{
  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（事件配置）
```javascript
{
  id: 'lucky_find',
  type: 'good',
  weight: 0.3,
  condition: (state) => state.happiness > 50,
  effects: [
    { type: 'modifyStats', payload: { happiness: +10 } },
    { type: 'addBuff', payload: { ... } }
  ]
}
```

### Buff（Buff 效果）
```javascript
{
  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`：

```javascript
{
  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`：

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

### 添加新神明

編輯 `data/deities.js`：

```javascript
{
  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）
- [ ] 實作多人互動
- [ ] 加入小遊戲系統
- [ ] 實作繁殖系統
- [ ] 加入成就系統
- [ ] 實作排行榜