kknongchang_2506/app/Module/Pet

宠物模块开发文档

宠物模块，宠物属性、技能、偷菜功能

1. 宠物系统功能

1.1 宠物属性系统

• 成长属性：
  • 等级：1-30级
  • 体力值：0-100（每分钟恢复5点）
  • 数值属性：随等级提升而增长
• 喂养机制：
  • 普通狗粮：提升基础经验
  • 优质狗粮：提供双倍经验

1.3 宠物状态系统

enum PetStatus: int {
    case NONE = 0;      // 未知
    case NORMAL = 1;    // 正常
    case DEAD = 3;      // 死亡
    case FEEDING = 4;   // 喂养中
    case TRAINING = 5;  // 训练中
    case RESTING = 6;   // 休息中
    case TRAVELING = 7; // 外出中
    case STEALING = 8;  // 偷菜中
}

1.4 技能系统

技能名称	消耗体力	冷却时间	开启条件	效果描述
自动收菜	50	2小时	等级≥5	自动收获成熟作物
自动播种	50	4小时	等级≥10	自动补种空闲土地
灾害防护	30	6小时	等级≥15	防止指定类型自然灾害

1.5 偷菜功能

• 功能定位：社交互动功能，无战斗逻辑
• 体力消耗：偷菜和防御操作独立配置体力消耗
• 成功判定：基于宠物等级比较，非战力比较
• 实现状态：当前处于规划阶段，详见偷菜.md文档

2. 数据库设计

2.1 数据表概览

表名	主要功能	关键字段
pet_users	用户宠物信息	id, user_id, name, level
pet_skills	技能配置	id, skill_name, stamina_cost, cool_down
pet_skill_logs	技能使用记录	id, pet_id, skill_id, used_at

| pet_configs | 宠物系统配置 | id, pet_type, feed_effect, display_attributes, numeric_attributes | | pet_level_configs | 等级配置 | id, level, exp_required, stamina_max, display_attributes, numeric_attributes |

2.2 数据表结构

2.2.1 基础表

-- 用户宠物表
CREATE TABLE `pet_users` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `name` VARCHAR(20) NOT NULL COMMENT '宠物名称',

  `level` TINYINT UNSIGNED DEFAULT 1,
  `experience` INT UNSIGNED DEFAULT 0,
  `stamina` SMALLINT UNSIGNED DEFAULT 100,
  `status` TINYINT UNSIGNED DEFAULT 1 COMMENT '宠物状态：0未知，1正常，3死亡，4喂养中，5训练中，6休息中，7外出中，8偷菜中',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  INDEX idx_user (user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 技能配置表
CREATE TABLE `pet_skills` (
  `id` INT UNSIGNED AUTO_INCREMENT,
  `skill_name` VARCHAR(50) NOT NULL COMMENT '技能名称',
  `stamina_cost` SMALLINT NOT NULL COMMENT '体力消耗',
  `cool_down` INT COMMENT '冷却时间(秒)',
  `effect_desc` TEXT COMMENT '效果描述',
  `min_level` TINYINT UNSIGNED DEFAULT 1 COMMENT '最低等级要求',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id)
) ENGINE=InnoDB;

-- 宠物配置表
CREATE TABLE `pet_configs` (
  `id` INT UNSIGNED AUTO_INCREMENT,
  `pet_type` VARCHAR(50) NOT NULL COMMENT '宠物类型',

  `feed_effect` JSON NOT NULL COMMENT '喂养效果配置',
  `max_level` TINYINT UNSIGNED NOT NULL COMMENT '最大等级',
  `stamina_recovery` SMALLINT UNSIGNED NOT NULL COMMENT '体力恢复值/分钟',
  `display_attributes` JSON DEFAULT NULL COMMENT '显示属性配置',
  `numeric_attributes` JSON DEFAULT NULL COMMENT '数值属性配置',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  UNIQUE KEY idx_pet_type (pet_type)
) ENGINE=InnoDB;

-- 宠物等级配置表
CREATE TABLE `pet_level_configs` (
  `id` INT UNSIGNED AUTO_INCREMENT,
  `level` TINYINT UNSIGNED NOT NULL COMMENT '等级',
  `exp_required` INT UNSIGNED NOT NULL COMMENT '升级所需经验值',
  `stamina_max` SMALLINT UNSIGNED NOT NULL DEFAULT 100 COMMENT '最大体力值',
  `stamina_recovery_rate` TINYINT UNSIGNED NOT NULL DEFAULT 5 COMMENT '每分钟恢复体力值',
  `unlock_skills` JSON DEFAULT NULL COMMENT '解锁的技能ID列表',
  `display_attributes` JSON DEFAULT NULL COMMENT '等级显示属性配置',
  `numeric_attributes` JSON DEFAULT NULL COMMENT '等级数值属性配置',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  UNIQUE KEY idx_level (level)
) ENGINE=InnoDB;

2.2.2 日志表

-- 技能使用日志表
CREATE TABLE `pet_skill_logs` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT,
  `pet_id` BIGINT UNSIGNED NOT NULL,
  `skill_id` INT UNSIGNED NOT NULL,
  `used_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  `effect_result` JSON COMMENT '技能使用结果',
  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  FOREIGN KEY (pet_id) REFERENCES pet_users(id),
  FOREIGN KEY (skill_id) REFERENCES pet_skills(id),
  INDEX idx_pet_skill (pet_id, skill_id)
) ENGINE=InnoDB;

2.3 索引设计

表名	索引字段	索引类型	说明
pet_users	id	主键	宠物ID主键索引
pet_users	user_id	普通索引	加速用户宠物查询
pet_users	status	普通索引	加速按状态查询宠物
pet_skills	id	主键	技能ID主键索引
pet_skill_logs	pet_id, skill_id	复合索引	加速查询宠物技能使用记录

| pet_level_configs | id | 主键 | 等级配置ID主键索引 | | pet_level_configs | level | 唯一索引 | 确保等级唯一性，加速等级查询 |

2.4 数据模型关联关系

以下是主要数据模型之间的关联关系：

1. 用户与宠物关系

   • 用户可以拥有多个宠物，通过 pet_users 表关联
   • 每个宠物只属于一个用户

2. 宠物与技能关系

   • 宠物可以使用多个技能，通过 pet_skill_logs 表记录使用历史
   • 技能配置在 pet_skills 表中定义

3. 宠物与偷菜关系

   • 宠物可以参与偷菜活动，基于等级比较进行成功判定
   • 偷菜功能为社交互动功能，无战斗逻辑

2.5 宠物等级系统

宠物等级配置表(pet_level_configs)用于定义每个等级的详细信息，包括：

• 升级所需经验：达到下一级所需的经验值
• 最大体力值：该等级的体力上限
• 体力恢复速率：每分钟恢复的体力点数
• 解锁技能：达到该等级时解锁的技能列表
• 显示属性：等级相关的UI显示属性，如等级图标、特效等
• 数值属性：等级相关的游戏数值属性，如攻击力、防御力等

2.5.1 显示属性

宠物配置表(pet_configs)中的显示属性用于定义宠物类型的UI展示相关配置，如：

{
  "icon": "pet_icon_001.png",
  "avatar": "pet_avatar_001.png",
  "animation": "pet_anim_001",
  "ui_color": "#FF5500",
  "description": "一只勤劳的宠物，擅长收集资源"
}

2.5.2 数值属性

宠物配置表和等级配置表中的数值属性用于定义宠物的游戏数值相关配置，如：

{
  "base_attack": 10,
  "base_defense": 5,
  "base_speed": 8,
  "harvest_efficiency": 1.2,
  "planting_speed": 1.0,
  "disaster_resistance": 0.8
}

通过这些配置表，可以灵活调整宠物成长曲线，平衡游戏难度，并提供丰富的视觉体验和游戏玩法。

3. 配置参数

// config/pet.php
return [
    // 宠物基础配置
    'max_level' => 30,                  // 最大等级
    'stamina_recovery' => 5,            // 每分钟恢复体力
    'stamina_max' => 100,               // 最大体力值

    // 技能冷却时间配置（秒）
    'skill_cooltime' => [
        'harvest' => 7200,              // 自动收菜：2小时
        'plant' => 14400,               // 自动播种：4小时
        'protect' => 21600              // 灾害防护：6小时
    ],





    // 偷菜功能体力消耗配置
    'steal_stamina_cost' => [
        'steal' => 10,                   // 偷菜操作消耗体力
        'defend' => 15                   // 防御操作消耗体力
    ]

];

4. 偷菜功能规划

偷菜功能目前处于规划阶段，详细设计文档请参考：app/Module/Pet/Docs/偷菜.md

4.1 规划要点

• 功能定位：社交互动功能，无战斗逻辑
• 体力消耗：偷菜和防御操作独立配置体力消耗
• 成功判定：基于宠物等级比较，非战力比较
• 实现状态：当前仅有基础框架，具体逻辑待实现

5. 关键改进

1. 数据完整性：完善外键约束和索引配置
2. 错误修复：修正枚举定义中的拼写错误
3. 文档规范：统一SQL和PHP代码格式
4. 功能完善：优化洗髓功能设计
5. 结构调整：移除狗粮库存表，使用物品系统管理狗粮
6. 表名规范：所有宠物模块相关表统一使用 pet_ 前缀
7. 状态管理：增加宠物状态系统，支持多种状态转换
8. 偷菜规划：设计无战斗的偷菜系统框架，纯社交互动功能（规划阶段）
9. 体力分离：偷菜和防御操作的体力消耗独立配置

6. 模块依赖关系

• 物品模块：宠物系统依赖物品模块管理狗粮和其他消耗品
• 用户模块：宠物系统需要关联用户信息
• 农场模块：宠物技能作用于农场系统
• 任务模块：宠物相关任务需要与任务系统集成
• Game模块：宠物模块依赖Game模块的暂存系统来存储和传输宠物变更数据

7. 宠物暂存系统

宠物暂存系统是由Game模块提供的一个用于跟踪和记录用户宠物变更的临时存储机制，主要用于优化前端UI更新和提高用户体验。

7.1 事件触发

宠物模块在以下情况下触发事件：

• PetCreatedEvent：当新宠物被创建时触发
• PetStatusChangedEvent：当宠物状态发生变化时触发

7.2 数据结构

Game模块使用DTO对象来存储和传输宠物数据：

• PetCreatedTempDto：宠物创建临时数据传输对象
• PetStatusTempDto：宠物状态变更临时数据传输对象

7.3 应用场景

• 宠物获取动画：当用户获取新宠物时，前端可以显示宠物获取动画
• 宠物状态变更提示：当宠物状态变化时，前端可以显示变更提示
• 喜养效果展示：当用户喜养宠物时，前端可以显示经验值和体力值增加的动画效果
• 升级提示：当宠物经验值达到升级条件时，前端可以显示升级提示

7.4 重要属性

宠物模型中的重要属性：

• experience（经验值）：宠物的经验值，用于衡量宠物的成长进度。当经验值达到一定阈值时，宠物可以升级。

• stamina（体力值）：宠物的体力值，表示宠物可以执行活动的能力。宠物进行某些活动（如战斗、工作等）会消耗体力值，通过喜养等方式可以恢复宠物的体力值。

8. 总结

宠物模块是游戏中重要的伙伴系统，为玩家提供了丰富的互动体验和游戏玩法。本文档详细描述了宠物系统的各个方面，包括：

1. 基础功能：宠物属性系统、状态系统和技能系统
2. 数据库设计：
   • 所有表名统一使用 pet_ 前缀
   • 数据表分为基础表和日志表
   • 完善的索引设计和外键约束
3. 等级系统：通过 pet_level_configs 表定义宠物成长曲线和等级特性
4. 配置参数：详细的系统配置参数，支持灵活调整游戏平衡性
5. 偷菜规划：设计无战斗的社交互动功能框架（规划阶段）
6. 暂存系统：与 Game 模块集成的宠物暂存系统，提供宠物变更的实时反馈

宠物系统的数据表结构清晰：

• 基础表：pet_users、pet_skills、pet_configs、pet_level_configs
• 日志表：pet_skill_logs、pet_remould_logs

宠物模块与其他模块的集成：

• 物品模块：使用物品模块管理狗粮和洗髓道具
• Game模块：使用Game模块的暂存系统存储宠物变更数据

通过宠物系统，玩家可以培养自己的宠物伙伴，参与各种游戏活动，增强游戏的趣味性和粘性。系统设计注重数据完整性、性能优化和扩展性，为后续功能迭代提供了良好的基础。