|
|
@@ -0,0 +1,206 @@
|
|
|
+# GameItems 模块文档
|
|
|
+
|
|
|
+## 模块概述
|
|
|
+
|
|
|
+GameItems 模块是游戏内物品系统的核心，负责管理所有与物品相关的逻辑和数据。它旨在提供一个灵活、可扩展且功能完善的物品管理解决方案。
|
|
|
+
|
|
|
+## 主要职责
|
|
|
+
|
|
|
+该模块涵盖了以下核心功能领域：
|
|
|
+
|
|
|
+- **物品基础属性管理**:
|
|
|
+ - 名称
|
|
|
+ - 分类
|
|
|
+ - 类型
|
|
|
+ - 展示属性（如图标、描述等）
|
|
|
+ - 数值属性（如攻击力、防御力、使用效果值等）
|
|
|
+ - 其他自定义基础属性
|
|
|
+- **物品获取与消耗**: 定义和处理物品如何被玩家获得以及如何被消耗或使用。
|
|
|
+- **物品库存管理**: 跟踪玩家拥有的物品及其数量。
|
|
|
+- **物品交易系统**: （如果适用）支持玩家之间的物品交易或与 NPC 的交易。
|
|
|
+- **宝箱类物品管理**:
|
|
|
+ - 定义宝箱内容物。
|
|
|
+ - 实现宝箱开启机制，包括随机掉落逻辑。
|
|
|
+- **物品过期时间管理**:
|
|
|
+ - **全局过期**: 设定所有同类物品的统一过期时间点。
|
|
|
+ - **物品有效期**: 物品从获得时刻起的一段有效时间。
|
|
|
+ - **用户特定过期**: 为特定用户的特定物品设置单独的过期时间。
|
|
|
+
|
|
|
+## 核心功能特点
|
|
|
+
|
|
|
+1. **多物品宝箱系统**:
|
|
|
+ - 允许一个宝箱（或类似容器）在开启时同时掉落多种不同的物品。
|
|
|
+ - 可以为宝箱中的每种物品配置：
|
|
|
+ - 掉落数量范围（例如，掉落 1 到 5 个）
|
|
|
+ - 掉落概率（例如，有 30% 的几率掉落）
|
|
|
+ - 提供了高度可配置的掉落逻辑，以满足复杂的游戏设计需求。
|
|
|
+ - **支持保底机制 (Pity System)**: 可配置在开启一定次数后必定获得指定的稀有物品，增加玩家的获得确定性。需要记录玩家针对特定宝箱或奖池的开启次数。
|
|
|
+
|
|
|
+2. **灵活的过期机制**:
|
|
|
+ - **全局过期**: 适用于活动物品或限时物品，到期后所有玩家的该物品将失效或移除。
|
|
|
+ - **物品有效期**: 物品在获得后的一段时间内有效，例如体验卡、临时增益道具。
|
|
|
+ - **用户特定过期**: 允许根据特定条件（如补偿、特殊奖励）为单个用户设置物品的过期时间。
|
|
|
+ - 系统能自动处理过期物品的逻辑（如移除、状态变更）。
|
|
|
+
|
|
|
+3. **完善的属性系统**:
|
|
|
+ - 使用灵活的键值对（Key-Value）结构来存储物品的各种属性。
|
|
|
+ - 支持数值型、字符型、布尔型等多种数据类型的属性。
|
|
|
+ - 易于扩展，可以方便地添加新的属性来支持复杂的物品效果和游戏机制（如装备词缀、宝石镶嵌、附魔效果等）。
|
|
|
+
|
|
|
+4. **单独物品属性系统**:
|
|
|
+ - 允许基于一个“基础物品”（模板）创建出多个具有独立属性的“单独物品”实例。
|
|
|
+ - 每个单独物品实例可以拥有自己独特的属性值（例如，两把相同的剑，但一把有 +10 攻击力，另一把有 +5 攻击力和 +5% 暴击率）。
|
|
|
+ - 适用于需要精细管理每个物品个体差异的场景，如装备、宠物等。
|
|
|
+ - 每个单独物品拥有唯一的实例 ID，便于追踪和管理。
|
|
|
+
|
|
|
+5. **物品组管理**:
|
|
|
+ - 允许创建物品的逻辑分组，一个物品组可以包含多个基础物品。
|
|
|
+ - 主要用于简化配置，例如在宝箱奖励配置中可以直接引用物品组，而不是列出组内所有物品。
|
|
|
+ - 可以为物品组内的物品配置额外的属性，如在组内的权重或特殊掉落规则。
|
|
|
+
|
|
|
+## 设计目标
|
|
|
+
|
|
|
+- **高内聚，低耦合**: 模块内部功能紧密相关，与其他模块的依赖尽可能减少。
|
|
|
+- **可扩展性**: 易于添加新的物品类型、属性和功能。
|
|
|
+- **性能**: 高效处理大量物品数据和相关操作。
|
|
|
+- **可配置性**: 游戏策划可以通过配置轻松调整物品属性、掉落、过期规则等。
|
|
|
+
|
|
|
+## 数据库设计
|
|
|
+
|
|
|
+为了支持上述功能，建议采用以下核心数据表结构：
|
|
|
+
|
|
|
+1. **`game_item_bases` (基础物品表)**: 存储物品的模板信息。
|
|
|
+ * `id`: 主键
|
|
|
+ * `name`: 物品名称
|
|
|
+ * `category_id`: 物品分类 ID (外键关联分类表)
|
|
|
+ * `type`: 物品类型 (例如：消耗品, 装备, 材料, 宝箱)
|
|
|
+ * `description`: 物品描述
|
|
|
+ * `icon`: 物品图标
|
|
|
+ * `stack_limit`: 堆叠上限 (1 表示不可堆叠)
|
|
|
+ * `base_attributes`: JSON/Text 存储基础属性 (如攻击力、防御力)
|
|
|
+ * `is_tradable`: 是否可交易
|
|
|
+ * `is_sellable`: 是否可出售
|
|
|
+ * `sell_price`: 出售价格
|
|
|
+ * `global_expire_at`: 全局过期时间 (NULL 表示永不过期)
|
|
|
+ * `created_at`, `updated_at`
|
|
|
+
|
|
|
+2. **`game_item_instances` (单独物品实例表)**: 存储具有独立属性的物品实例 (针对“单独物品属性系统”)。
|
|
|
+ * `id`: 主键 (唯一实例 ID)
|
|
|
+ * `base_item_id`: 基础物品 ID (外键关联 `game_item_bases`)
|
|
|
+ * `owner_user_id`: 所属用户 ID (外键关联用户表)
|
|
|
+ * `instance_attributes`: JSON/Text 存储实例特定属性 (如强化等级, 随机词缀)
|
|
|
+ * `created_at`, `updated_at`
|
|
|
+ * `expire_at`: 特定过期时间 (NULL 表示遵循基础物品或永不过期)
|
|
|
+ * `status`: 物品状态 (例如：在背包中, 已装备, 已锁定)
|
|
|
+
|
|
|
+3. **`user_inventories` (用户物品库存表)**: 存储用户拥有的可堆叠物品。
|
|
|
+ * `id`: 主键
|
|
|
+ * `user_id`: 用户 ID (外键关联用户表)
|
|
|
+ * `base_item_id`: 基础物品 ID (外键关联 `game_item_bases`)
|
|
|
+ * `quantity`: 拥有数量
|
|
|
+ * `created_at`, `updated_at`
|
|
|
+ * `expire_at`: 特定过期时间 (针对用户特定过期，优先级高于全局过期和有效期)
|
|
|
+
|
|
|
+4. **`game_item_categories` (物品分类表)**:
|
|
|
+ * `id`: 主键
|
|
|
+ * `name`: 分类名称 (例如：武器, 护甲, 药水)
|
|
|
+ * `parent_id`: 父分类 ID (支持层级分类)
|
|
|
+ * `created_at`, `updated_at`
|
|
|
+
|
|
|
+5. **`game_chest_rewards` (宝箱奖励配置表)**:
|
|
|
+ * `id`: 主键
|
|
|
+ * `chest_base_item_id`: 宝箱的基础物品 ID (外键关联 `game_item_bases`)
|
|
|
+ * `reward_base_item_id`: 奖励的基础物品 ID (外键关联 `game_item_bases`)
|
|
|
+ * `min_quantity`: 最小掉落数量
|
|
|
+ * `max_quantity`: 最大掉落数量
|
|
|
+ * `probability`: 掉落概率 (例如 0.3 表示 30%)
|
|
|
+ * `is_pity_reward`: 布尔值, 标记此项是否为可通过保底获得的奖励之一 (可选, 简化逻辑)
|
|
|
+ * `created_at`, `updated_at`
|
|
|
+
|
|
|
+6. **`game_chest_pity_configs` (宝箱保底配置表)**: 定义宝箱的保底规则。
|
|
|
+ * `id`: 主键
|
|
|
+ * `chest_base_item_id`: 宝箱的基础物品 ID (外键关联 `game_item_bases`)
|
|
|
+ * `pity_group_id`: 保底组 ID (可选, 用于多个宝箱共享保底计数)
|
|
|
+ * `pity_threshold`: 触发保底所需的尝试次数
|
|
|
+ * `guaranteed_reward_item_id`: 保底必定获得的物品 ID (外键关联 `game_item_bases`)
|
|
|
+ * `guaranteed_reward_quantity`: 保底物品数量
|
|
|
+ * `reset_on_trigger`: 触发保底后是否重置计数器 (通常为 true)
|
|
|
+ * `description`: 保底规则描述 (例如 "90抽小保底", "180抽大保底")
|
|
|
+ * `created_at`, `updated_at`
|
|
|
+
|
|
|
+7. **`user_chest_pity_progress` (用户宝箱保底进度表)**: 跟踪用户针对特定保底规则的进度。
|
|
|
+ * `id`: 主键
|
|
|
+ * `user_id`: 用户 ID (外键关联用户表)
|
|
|
+ * `pity_config_id`: 关联的保底配置 ID (外键关联 `game_chest_pity_configs`)
|
|
|
+ * `attempts_count`: 当前累计尝试次数
|
|
|
+ * `created_at`, `updated_at`
|
|
|
+
|
|
|
+**说明:**
|
|
|
+
|
|
|
+* 对于不可堆叠且具有独立属性的物品（如装备），主要使用 `game_item_instances` 表。`owner_user_id` 标识归属。
|
|
|
+* 对于可堆叠的物品（如消耗品、材料），主要使用 `user_inventories` 表。
|
|
|
+* 过期逻辑处理优先级：`user_inventories.expire_at` > `game_item_instances.expire_at` > `game_item_bases.global_expire_at` > 物品有效期（通常在获得时计算并存入 `user_inventories` 或 `game_item_instances` 的 `expire_at` 字段）。
|
|
|
+* 属性存储建议使用 JSON 类型，便于灵活扩展。
|
|
|
+* 宝箱开启时，根据 `game_chest_pity_configs` 中的配置，检查并更新 `user_chest_pity_progress` 表。当用户的 `attempts_count` 达到对应 `pity_config_id` 的 `pity_threshold` 时，强制发放 `guaranteed_reward_item_id` 指定的物品，并根据 `reset_on_trigger` 决定是否重置计数器。
|
|
|
+
|
|
|
+**数据表关系图 (Mermaid ER Diagram):**
|
|
|
+
|
|
|
+```mermaid
|
|
|
+erdiagram
|
|
|
+ users "用户" ||--o{ user_inventories "用户库存"
|
|
|
+ users "用户" ||--o{ game_item_instances "物品实例"
|
|
|
+ users "用户" ||--o{ user_chest_pity_progress "用户保底进度"
|
|
|
+
|
|
|
+ game_item_categories "物品分类" ||--o{ game_item_bases "基础物品"
|
|
|
+ game_item_categories "物品分类" ||--o{ game_item_categories "物品分类"
|
|
|
+
|
|
|
+ game_item_bases "基础物品" ||--o{ game_item_instances "物品实例"
|
|
|
+ game_item_bases "基础物品" ||--o{ user_inventories "用户库存"
|
|
|
+ game_item_bases "基础物品" ||--o{ game_chest_rewards "宝箱奖励配置"
|
|
|
+ game_item_bases "基础物品" ||--o{ game_chest_pity_configs "宝箱保底配置"
|
|
|
+
|
|
|
+ game_chest_pity_configs "宝箱保底配置" ||--o{ user_chest_pity_progress "用户保底进度"
|
|
|
+
|
|
|
+ game_item_bases "基础物品" {
|
|
|
+ int id pk
|
|
|
+ int category_id fk
|
|
|
+ }
|
|
|
+
|
|
|
+ game_item_instances "物品实例" {
|
|
|
+ bigint id pk
|
|
|
+ int base_item_id fk
|
|
|
+ bigint owner_user_id fk
|
|
|
+ }
|
|
|
+
|
|
|
+ user_inventories "用户库存" {
|
|
|
+ bigint id pk
|
|
|
+ bigint user_id fk
|
|
|
+ int base_item_id fk
|
|
|
+ }
|
|
|
+
|
|
|
+ game_item_categories "物品分类" {
|
|
|
+ int id pk
|
|
|
+ int parent_id fk
|
|
|
+ }
|
|
|
+
|
|
|
+ game_chest_rewards "宝箱奖励配置" {
|
|
|
+ bigint id pk
|
|
|
+ int chest_base_item_id fk
|
|
|
+ int reward_base_item_id fk
|
|
|
+ }
|
|
|
+
|
|
|
+ game_chest_pity_configs "宝箱保底配置" {
|
|
|
+ int id pk
|
|
|
+ int chest_base_item_id fk
|
|
|
+ int guaranteed_reward_item_id fk
|
|
|
+ }
|
|
|
+
|
|
|
+ user_chest_pity_progress "用户保底进度" {
|
|
|
+ bigint id pk
|
|
|
+ bigint user_id fk
|
|
|
+ int pity_config_id fk
|
|
|
+ }
|
|
|
+
|
|
|
+ users "用户" {
|
|
|
+ bigint id pk
|
|
|
+ }
|
Your Name