277 lines
6.1 KiB
Markdown
277 lines
6.1 KiB
Markdown
# 虛擬寵物系統 - 使用說明
|
||
|
||
## 🚀 快速開始
|
||
|
||
### 方式一：瀏覽器 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）
|
||
- [ ] 實作多人互動
|
||
- [ ] 加入小遊戲系統
|
||
- [ ] 實作繁殖系統
|
||
- [ ] 加入成就系統
|
||
- [ ] 實作排行榜
|
||
|