# 文字冒险游戏 - 内容开发指南

本项目是一个基于 UniApp + Vue 3 的文字冒险游戏，采用配置驱动的架构。所有游戏内容（物品、NPC、技能、配方、事件等）都通过配置文件定义，无需修改核心代码即可扩展游戏内容。

## 目录结构

```
config/
├── constants.js    # 游戏常量（品质等级、时间等）
├── items.js        # 物品配置
├── skills.js       # 技能配置
├── npcs.js         # NPC配置
├── recipes.js      # 制造配方配置
├── enemies.js      # 敌人配置
├── events.js       # 事件/剧情配置
├── locations.js    # 地点配置
└── shop.js         # 商店配置
```

---

## 1. 创建物品

物品定义在 `config/items.js` 中的 `ITEM_CONFIG` 对象。

### 基本结构

```javascript
your_item_id: {
  id: 'your_item_id',           // 唯一ID（建议使用下划线命名）
  name: '物品名称',              // 显示名称
  type: 'weapon',               // 类型：weapon/armor/shield/accessory/consumable/book/material
  subtype: 'one_handed',        // 子类型（可选）
  icon: '🗡️',                   // 图标（emoji）
  baseValue: 100,               // 基础价值（铜币）
  description: '物品描述',       // 描述文本
  stackable: true,              // 是否可堆叠（消耗品/素材）
  maxStack: 99                  // 最大堆叠数
}
```

### 武器

```javascript
sword: {
  id: 'sword',
  name: '铁剑',
  type: 'weapon',
  subtype: 'sword',             // one_handed/two_handed/sword/axe/blunt/ranged
  icon: '⚔️',
  baseValue: 500,
  baseDamage: 25,               // 基础攻击力
  attackSpeed: 1.2,             // 攻击速度倍率
  quality: 100,                 // 基础品质（影响属性计算）
  unlockSkill: 'sword_mastery', // 装备解锁的技能
  stats: {                      // 额外属性加成
    critRate: 5                 // 暴击率+5%
  },
  description: '一把精工打造的铁剑。'
}
```

### 防具

```javascript
armor: {
  id: 'leather_armor',
  name: '皮甲',
  type: 'armor',
  subtype: 'light',             // light/heavy
  icon: '🦺',
  baseValue: 150,
  baseDefense: 8,               // 基础防御力
  quality: 100,
  stats: {
    evasion: 5                  // 闪避+5%
  },
  description: '用兽皮制成的轻甲。'
}
```

### 消耗品

```javascript
potion: {
  id: 'health_potion',
  name: '治疗药水',
  type: 'consumable',
  subtype: 'medicine',          // food/drink/medicine
  icon: '🧪',
  baseValue: 150,
  effect: {                     // 使用效果
    health: 100,                // 恢复生命值
    stamina: 20,                // 恢复耐力
    sanity: 10                  // 恢复精神
  },
  description: '快速恢复生命值。',
  stackable: true,
  maxStack: 20
}
```

### 书籍

```javascript
book: {
  id: 'skill_book',
  name: '战斗指南',
  type: 'book',
  icon: '📖',
  baseValue: 200,
  readingTime: 60,              // 阅读时间（秒）
  expReward: {                  // 阅读获得的技能经验
    combat: 100,                // 主经验
    sword_mastery: 50           // 特定技能经验
  },
  completionBonus: {            // 完成奖励（可选）
    exp: 200                    // 额外主经验
  },
  description: '记载着战斗技巧的书籍。'
}
```

---

## 2. 创建技能

技能定义在 `config/skills.js` 中的 `SKILL_CONFIG` 对象。

### 基本结构

```javascript
your_skill: {
  id: 'your_skill',
  name: '技能名称',
  type: 'combat',               // 类型：combat/life/passive
  category: 'weapon',           // 分类：weapon/crafting/reading等
  icon: '⚔️',
  maxLevel: 20,                 // 最大等级
  expPerLevel: (level) => level * 100,  // 每级所需经验公式
  milestones: {                 // 里程碑（等级解锁效果）
    5: {
      desc: '攻击力+10%',
      effect: { attackBonus: 10 }
    },
    10: {
      desc: '解锁新技能',
      effect: { unlockSkill: 'advanced_skill' }
    }
  },
  unlockCondition: {            // 解锁条件（可选）
    type: 'item',
    itemId: 'starter_sword'
  }
}
```

### 战斗技能

```javascript
sword_mastery: {
  id: 'sword_mastery',
  name: '剑术精通',
  type: 'combat',
  category: 'weapon',
  icon: '⚔️',
  maxLevel: 20,
  expPerLevel: (level) => level * 100,
  milestones: {
    5: { desc: '暴击率+5%', effect: { critRate: 5 } },
    10: { desc: '攻击力+15%', effect: { attackBonus: 15 } },
    15: { desc: '暴击伤害+0.5', effect: { critMult: 0.5 } },
    20: { desc: '剑术大师', effect: { mastery: true } }
  },
  unlockCondition: null         // 初始解锁/通过装备武器解锁
}
```

### 生活技能

```javascript
crafting: {
  id: 'crafting',
  name: '制造',
  type: 'life',
  category: 'crafting',
  icon: '🔨',
  maxLevel: 20,
  expPerLevel: (level) => level * 80,
  milestones: {
    1: { desc: '解锁基础制造', effect: {} },
    5: { desc: '制造成功率+5%', effect: { craftingSuccessRate: 5 } },
    10: { desc: '制造时间-25%', effect: { craftingSpeed: 0.25 } }
  },
  unlockCondition: null
}
```

### 被动技能

```javascript
night_vision: {
  id: 'night_vision',
  name: '夜视',
  type: 'passive',
  category: 'environment',
  icon: '👁️',
  maxLevel: 10,
  expPerLevel: (level) => level * 30,
  milestones: {
    5: { desc: '黑暗惩罚-10%', effect: { darkPenaltyReduce: 10 } },
    10: { desc: '黑暗惩罚-25%', effect: { darkPenaltyReduce: 25 } }
  },
  unlockCondition: {
    location: 'basement'       // 进入该地点自动解锁
  }
}
```

---

## 3. 创建NPC

NPC定义在 `config/npcs.js` 中的 `NPC_CONFIG` 对象。

### 基本结构

```javascript
your_npc: {
  id: 'your_npc',
  name: 'NPC名称',
  location: 'camp',             // 所在位置（location ID）
  dialogue: {
    first: {                    // 首次对话
      text: '对话文本...',
      choices: [
        { text: '选项1', next: 'node1' },
        { text: '选项2', next: null, action: 'action_name' }
      ]
    },
    node1: {                    // 后续对话节点
      text: '更多对话...',
      choices: [
        { text: '再见', next: null }
      ]
    }
  }
}
```

### 带动作的NPC

```javascript
merchant: {
  id: 'merchant',
  name: '商人',
  location: 'market',
  dialogue: {
    first: {
      text: '欢迎光临！',
      choices: [
        { text: '查看商品', next: null, action: 'open_shop' },
        { text: '这是哪里？', next: 'explain' }
      ]
    },
    explain: {
      text: '这里是市场...',
      choices: [
        { text: '查看商品', next: null, action: 'open_shop' },
        { text: '离开', next: null }
      ]
    }
  }
}
```

### 可用动作

| 动作 | 说明 |
|------|------|
| `open_shop` | 打开商店 |
| `give_item` | 给予物品（需指定 actionData） |
| `heal` | 恢复生命值 |
| `unlock_skill` | 解锁技能 |
| `teleport` | 传送到指定位置 |

---

## 4. 创建配方

配方定义在 `config/recipes.js` 中的 `RECIPE_CONFIG` 对象。

### 基本结构

```javascript
your_recipe: {
  id: 'your_recipe',
  type: RECIPE_TYPES.WEAPON,    // 类型：WEAPON/ARMOR/SHIELD/CONSUMABLE/SPECIAL
  resultItem: 'result_item_id', // 产物物品ID
  resultCount: 1,               // 产物数量
  materials: [                  // 材料需求
    { itemId: 'material_1', count: 5 },
    { itemId: 'material_2', count: 2 }
  ],
  requiredSkill: 'crafting',    // 所需技能
  requiredSkillLevel: 3,        // 所需技能等级
  baseTime: 60,                 // 基础制造时间（秒）
  baseSuccessRate: 0.85,        // 基础成功率（0-1）
  unlockCondition: {            // 解锁条件（可选）
    type: 'skill',              // skill/quest/item
    skillId: 'crafting',
    level: 5
  }
}
```

### 配方示例

```javascript
iron_sword: {
  id: 'iron_sword',
  type: RECIPE_TYPES.WEAPON,
  resultItem: 'iron_sword',
  resultCount: 1,
  materials: [
    { itemId: 'iron_ore', count: 5 },
    { itemId: 'leather', count: 2 }
  ],
  requiredSkill: 'sword_mastery',
  requiredSkillLevel: 5,
  baseTime: 180,
  baseSuccessRate: 0.75,
  unlockCondition: {
    type: 'skill',
    skillId: 'crafting',
    level: 3
  }
}
```

---

## 5. 创建敌人

敌人定义在 `config/enemies.js` 中的 `ENEMY_CONFIG` 对象。

### 基本结构

```javascript
your_enemy: {
  id: 'your_enemy',
  name: '敌人名称',
  icon: '👾',
  level: 5,                     // 等级
  hp: 100,                      // 生命值
  attack: 15,                   // 攻击力
  defense: 5,                   // 防御力
  speed: 10,                    // 速度（影响行动顺序）
  expReward: 50,                // 经验奖励
  // 可选属性
  critRate: 5,                  // 暴击率
  fleeRate: 20,                 // 逃跑成功率
  skills: ['skill_id'],         // 拥有的技能
  drops: [                      // 掉落列表
    { itemId: 'drop_item', chance: 0.3, count: { min: 1, max: 2 } }
  ]
}
```

---

## 6. 创建事件/剧情

事件定义在 `config/events.js` 中的 `EVENT_CONFIG` 对象。

### 基本结构

```javascript
your_event: {
  id: 'your_event',
  type: 'story',                // 类型：story/tips/unlock/dialogue/reward/combat
  title: '事件标题',
  text: '事件内容...',
  textTemplate: '支持{variable}变量替换',  // 或使用模板
  choices: [
    { text: '选项', next: 'next_event_id' },
    { text: '带动作的选项', next: null, action: 'action_name', actionData: {} }
  ]
}
```

### 事件类型

| 类型 | 说明 |
|------|------|
| `story` | 剧情事件 |
| `tips` | 提示信息 |
| `unlock` | 解锁内容提示 |
| `dialogue` | NPC对话 |
| `reward` | 奖励提示 |
| `combat` | 战斗事件 |

### 触发条件

在 `EVENT_TRIGGERS` 中配置触发条件：

```javascript
export const EVENT_TRIGGERS = {
  once: {
    your_trigger: {
      condition: (playerStore) => {
        // 返回 true 时触发事件
        return playerStore.level >= 5 && !playerStore.flags.yourEventSeen
      },
      eventId: 'your_event',
      setFlag: 'yourEventSeen'  // 触发后设置的标记
    }
  },
  environment: {
    your_env_trigger: {
      condition: (playerStore, locationId) => {
        return locationId === 'dark_cave' && !playerStore.flags.darkCaveFirstEnter
      },
      eventId: 'dark_warning'
    }
  }
}
```

---

## 7. 解锁条件

解锁条件可用于技能、配方、地点等。

### 类型

```javascript
// 基于等级
unlockCondition: {
  type: 'level',
  level: 5
}

// 基于技能
unlockCondition: {
  type: 'skill',
  skillId: 'crafting',
  level: 3
}

// 基于物品
unlockCondition: {
  type: 'item',
  itemId: 'key_item'
}

// 基于位置
unlockCondition: {
  type: 'location',
  locationId: 'secret_area'
}

// 基于任务标记
unlockCondition: {
  type: 'quest',
  flag: 'completed_quest_x'
}
```

---

## 8. 品质系统

物品品质定义在 `config/constants.js` 中的 `QUALITY_LEVELS`。

```javascript
QUALITY_LEVELS: {
  1: { level: 1, name: '垃圾', color: '#6b7280', range: [0, 49], multiplier: 0.5 },
  2: { level: 2, name: '普通', color: '#ffffff', range: [50, 89], multiplier: 1.0 },
  3: { level: 3, name: '优秀', color: '#22c55e', range: [90, 129], multiplier: 1.2 },
  4: { level: 4, name: '稀有', color: '#3b82f6', range: [130, 159], multiplier: 1.5 },
  5: { level: 5, name: '史诗', color: '#a855f7', range: [160, 199], multiplier: 2.0 },
  6: { level: 6, name: '传说', color: '#f59e0b', range: [200, 250], multiplier: 3.0 }
}
```

---

## 9. 快速开始示例

### 添加新武器

```javascript
// 在 config/items.js 中添加
flame_sword: {
  id: 'flame_sword',
  name: '烈焰之剑',
  type: 'weapon',
  subtype: 'sword',
  icon: '🔥⚔️',
  baseValue: 2000,
  baseDamage: 50,
  attackSpeed: 1.3,
  quality: 150,
  unlockSkill: 'sword_mastery',
  stats: {
    critRate: 10,
    fireDamage: 15
  },
  description: '燃烧着永恒烈焰的魔剑。'
}
```

### 添加新技能

```javascript
// 在 config/skills.js 中添加
fire_mastery: {
  id: 'fire_mastery',
  name: '火焰精通',
  type: 'combat',
  category: 'element',
  icon: '🔥',
  maxLevel: 15,
  expPerLevel: (level) => level * 150,
  milestones: {
    3: { desc: '火焰伤害+20%', effect: { fireDamageBonus: 20 } },
    7: { desc: '攻击附带燃烧', effect: { burnEffect: true } },
    15: { desc: '火焰免疫', effect: { fireImmunity: true } }
  },
  unlockCondition: {
    type: 'item',
    itemId: 'flame_essence'
  }
}
```

---

## 10. 注意事项

1. **ID命名**：统一使用下划线命名（snake_case），保持唯一性
2. **引用**：添加新物品后，记得在配方、商店、敌人掉落等处引用
3. **平衡性**：注意数值平衡，参考现有物品的属性比例
4. **测试**：添加内容后建议在游戏中测试效果
5. **保存**：游戏进度保存在 localStorage，修改配置后可能需要清除缓存测试