kknongchang_2506/app/Module/GameItems/Docs/掉落组.md

掉落组文档

本文档描述了物品模块中的掉落组功能，包括定义、使用方式和最佳实践。

1. 概述

掉落组是一组相关物品的集合，用于定义物品的随机掉落规则。主要用途包括：

• 宝箱内容配置
• 任务奖励发放
• 随机事件奖励
• 其他需要随机掉落物品的场景

2. 数据库结构

2.1 物品组表 (item_groups)

字段	类型	说明
id	int	物品组ID，主键
name	string	物品组名称
code	string	物品组编码（唯一）
description	string	物品组描述
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

2.2 物品组内容表 (item_group_items)

字段	类型	说明
id	int	记录ID，主键
group_id	int	物品组ID，外键
item_id	int	物品ID，外键
weight	float	权重，决定选择概率
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

3. 核心类

3.1 ItemGroup 模型

/**
 * 物品组模型
 */
class ItemGroup extends ModelCore
{
    // 关联物品组内容
    public function groupItems(): HasMany
    {
        return $this->hasMany(ItemGroupItem::class, 'group_id','id');
    }

    // 关联宝箱内容配置
    public function chestContents(): HasMany
    {
        return $this->hasMany(ItemChestContent::class, 'group_id','id');
    }
}

3.2 ItemGroupItem 模型

/**
 * 物品组内容模型
 */
class ItemGroupItem extends ModelCore
{
    // 关联物品组
    public function group(): BelongsTo
    {
        return $this->belongsTo(ItemGroup::class, 'group_id');
    }

    // 关联物品
    public function item(): BelongsTo
    {
        return $this->belongsTo(Item::class, 'item_id');
    }
}

3.3 Group 逻辑类

/**
 * 物品组逻辑类
 */
class Group
{
    /**
     * 根据权重随机获取物品组中的一个物品
     */
    public function getRandomItem(ItemGroup $group): ?Item
    {
        // 实现逻辑...
    }
}

4. 使用示例

4.1 创建掉落组

// 创建掉落组
$group = ItemGroup::create([
    'name' => '初级宝箱掉落组',
    'code' => 'beginner_chest_drops',
    'description' => '初级宝箱可能掉落的物品'
]);

// 添加掉落组内容
ItemGroupItem::create([
    'group_id' => $group->id,
    'item_id' => 101, // 物品ID
    'weight' => 0.5   // 权重
]);

4.2 使用掉落组

// 获取随机物品
$group = ItemGroup::find(1);
$randomItem = app(Group::class)->getRandomItem($group);

// 在宝箱内容中使用掉落组
ItemChestContent::create([
    'chest_id' => 201, // 宝箱ID
    'group_id' => $group->id, // 使用掉落组
    'min_quantity' => 1,
    'max_quantity' => 3,
    'weight' => 1.0
]);

5. 最佳实践

1. 权重设计：

   • 总权重不需要等于1或100，系统会自动计算比例
   • 权重值应保持合理范围（如0.1-10.0），避免极端值

2. 性能优化：

   • 对于大型掉落组，考虑缓存计算结果
   • 使用预加载关联数据避免N+1查询

3. 测试验证：

   • 验证权重分布是否符合预期
   • 测试边界情况（空组、零权重等）

4. 文档维护：

   • 记录每个掉落组的用途和内容
   • 更新文档以反映配置变更

6. 扩展建议

1. 动态权重：可根据玩家等级、VIP等级等因素动态调整权重
2. 保底机制：实现类似宝箱保底的掉落组保底机制
3. 条件掉落：增加条件判断，如特定时间、活动期间的特殊掉落