GameItems 模块设计文档

模块概述

GameItems模块负责游戏内物品系统的管理，包括基础物品属性和特殊物品(如宝箱)的管理。

功能特性

物品基础管理
- 名称、TID、类型等基础属性管理
- 物品获取与消耗逻辑
- 库存管理及变更事件通知
宝箱类物品
- 多物品宝箱系统：支持一个宝箱同时掉落多个物品
- 可配置每个物品的数量范围和概率
- 宝箱开启记录
过期机制
- 全局过期时间设置
- 用户特定过期时间设置
属性系统
- 键值对存储物品属性
- 支持复杂物品效果实现

目录结构

GameItems/
├── Actions/                # 物品操作类
├── Enums/                  # 枚举类
├── Events/                 # 事件类
├── Handlers/               # 处理器
├── Models/                 # 模型
├── Repositories/           # 数据仓库
├── Services/               # 服务类
├── Validations/            # 验证类
├── README.md               # 模块说明
└── README.roo.md           # 设计文档

核心类设计

1. Item (基础物品)

属性:
- tid: 物品唯一标识
- name: 物品名称
- type: 物品类型
- display_attrs: 展示属性(JSON) - 名称、描述、图标等
- numeric_attrs: 数值属性(JSON) - 攻击力、耐久度等
- expire_at: 全局过期时间
方法:
- acquire(): 获取物品
- consume(): 消耗物品
- checkExpired(): 检查是否过期

4. ItemInstance (物品实例类)

属性:
- instance_id: 实例唯一ID
- item_tid: 物品模板ID
- display_attrs: 实例展示属性(JSON) - 自定义名称、皮肤等
- numeric_attrs: 实例数值属性(JSON) - 当前耐久度、附加属性等
- expire_at: 过期时间
方法:
- updateAttributes(): 更新实例属性
- checkExpired(): 检查是否过期
- serialize(): 序列化为数组

2. Chest (宝箱类)

继承自Item，增加宝箱特有功能:

属性:
- rewards: 奖励配置(JSON)
- open_limit: 开启限制
方法:
- open(): 开启宝箱
- getRewards(): 获取奖励配置
- recordOpen(): 记录开启

3. ItemService (物品服务)

方法:
- getItem(tid): 获取物品模板
- getItemInstance(instance_id): 获取物品实例
- createItemInstance(user_id, item_tid, attributes): 创建物品实例
- updateInventory(): 更新可堆叠物品库存
- updateItemInstance(instance_id, attributes): 更新物品实例属性
- dispatchEvent(): 分发物品事件

使用示例

获取物品

$item = ItemService::getItem('item_tid');
$item->acquire($user, $amount);

开启宝箱

$chest = ItemService::getItem('chest_tid');
$rewards = $chest->open($user);

数据库设计

1. 物品基础表 (game_items)

CREATE TABLE `game_items` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `tid` varchar(64) NOT NULL COMMENT '物品唯一标识',
  `name` varchar(128) NOT NULL COMMENT '物品名称',
  `type` varchar(32) NOT NULL COMMENT '物品类型',
  `display_attrs` json DEFAULT NULL COMMENT '展示属性(名称、描述、图标等)',
  `numeric_attrs` json DEFAULT NULL COMMENT '数值属性(攻击力、耐久度等)',
  `expire_at` timestamp NULL DEFAULT NULL COMMENT '全局过期时间',
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `game_items_tid_unique` (`tid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

7. 物品组表 (item_groups)

CREATE TABLE `item_groups` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `group_id` varchar(64) NOT NULL COMMENT '组ID',
  `name` varchar(128) NOT NULL COMMENT '组名称',
  `items` json NOT NULL COMMENT '组内物品配置',
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `item_groups_group_id_unique` (`group_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

2. 宝箱配置表 (game_chests)

CREATE TABLE `game_chests` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `item_tid` varchar(64) NOT NULL COMMENT '关联物品TID',
  `rewards` json NOT NULL COMMENT '奖励配置(可配置物品或物品组)',
  `open_limit` int DEFAULT NULL COMMENT '开启限制',
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `game_chests_item_tid_unique` (`item_tid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

物品组配置示例

{
  "group_id": "weapon_group_1",
  "name": "初级武器组",
  "items": [
    {
      "item_tid": "sword_1",
      "weight": 30
    },
    {
      "item_tid": "axe_1",
      "weight": 20
    }
  ]
}

宝箱奖励配置支持物品组

{
  "rewards": [
    {
      "type": "group",
      "group_id": "weapon_group_1",
      "count": 1
    }
  ]
}

奖励配置(rewards)JSON结构说明

{
  "rewards": [
    {
      "item_tid": "物品TID",
      "min": 1,
      "max": 3,
      "probability": 0.5,
      "conditions": {
        "level": 10,
        "vip_level": 3
      }
    }
  ],
  "guarantees": [
    {
      "item_tid": "保底物品TID",
      "count": 10,
      "amount": 1
    }
  ]
}

字段说明：

rewards: 常规奖励列表
- item_tid: 奖励物品TID
- min: 最小数量
- max: 最大数量
- probability: 掉落概率(0-1)
- conditions: 获取条件(可选)
guarantees: 保底奖励列表(可选)
- item_tid: 保底物品TID
- count: 开启次数达到后触发
- amount: 奖励数量

3. 用户物品库存表 (item_users)

CREATE TABLE `item_users` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `user_id` bigint unsigned NOT NULL COMMENT '用户ID',
  `item_tid` varchar(64) NOT NULL COMMENT '物品TID',
  `quantity` int NOT NULL DEFAULT '0' COMMENT '数量(仅用于可堆叠物品)',
  `expire_at` timestamp NULL DEFAULT NULL COMMENT '用户特定过期时间',
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `user_items_user_id_item_tid_unique` (`user_id`,`item_tid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

6. 物品实例表 (item_instances)

CREATE TABLE `item_instances` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `user_id` bigint unsigned NOT NULL COMMENT '用户ID',
  `item_tid` varchar(64) NOT NULL COMMENT '物品TID',
  `instance_id` varchar(64) NOT NULL COMMENT '实例唯一ID',
  `display_attrs` json NOT NULL COMMENT '展示属性(名称、图标、皮肤等)',
  `numeric_attrs` json NOT NULL COMMENT '数值属性(攻击力、耐久度等)',
  `expire_at` timestamp NULL DEFAULT NULL COMMENT '过期时间',
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `item_instances_instance_id_unique` (`instance_id`),
  KEY `item_instances_user_id_index` (`user_id`),
  KEY `item_instances_item_tid_index` (`item_tid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

物品实例化设计说明

可堆叠物品：使用user_items表记录数量
不可堆叠物品：使用item_instances表记录每个实例
- 每把"刀"作为一个独立实例存储
- 每个实例有唯一的instance_id
- 实例属性存储在attributes字段(JSON)
混合模式：某些物品可同时支持两种存储方式

4. 宝箱开启记录表 (chest_open_logs)

CREATE TABLE `chest_open_logs` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `user_id` bigint unsigned NOT NULL COMMENT '用户ID',
  `chest_tid` varchar(64) NOT NULL COMMENT '宝箱TID',
  `rewards` json NOT NULL COMMENT '获得的奖励',
  `opened_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '开启时间',
  PRIMARY KEY (`id`),
  KEY `chest_open_logs_user_id_index` (`user_id`),
  KEY `chest_open_logs_chest_tid_index` (`chest_tid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

5. 用户宝箱开启计数表 (user_chest_counts)

CREATE TABLE `user_chest_counts` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `user_id` bigint unsigned NOT NULL COMMENT '用户ID',
  `chest_tid` varchar(64) NOT NULL COMMENT '宝箱TID',
  `open_count` int NOT NULL DEFAULT 0 COMMENT '开启次数',
  `last_opened_at` timestamp NULL DEFAULT NULL COMMENT '最后开启时间',
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `user_chest_counts_user_chest_unique` (`user_id`, `chest_tid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

保底奖励实现逻辑

用户每次开启宝箱时，更新user_chest_counts表中的open_count
当open_count达到保底配置中的count值时：
- 发放保底奖励
- 重置该宝箱的open_count为0
保底奖励与常规奖励可同时获得

开发规范

所有物品操作必须通过Validation验证
物品属性使用JSON存储，避免频繁修改表结构
库存变更必须触发相应事件
宝箱奖励配置使用概率表，便于调整
过期时间支持Carbon对象处理
数据库变更需人工执行上述SQL语句

README.roo.md 9.4 KB Historia Raaka

GameItems 模块设计文档

模块概述

功能特性

目录结构

核心类设计

1. Item (基础物品)

4. ItemInstance (物品实例类)

2. Chest (宝箱类)

3. ItemService (物品服务)

使用示例

获取物品

开启宝箱

数据库设计

1. 物品基础表 (game_items)

7. 物品组表 (item_groups)

2. 宝箱配置表 (game_chests)

物品组配置示例

宝箱奖励配置支持物品组

奖励配置(rewards)JSON结构说明

3. 用户物品库存表 (item_users)

6. 物品实例表 (item_instances)

物品实例化设计说明

4. 宝箱开启记录表 (chest_open_logs)

5. 用户宝箱开启计数表 (user_chest_counts)

保底奖励实现逻辑

开发规范

README.roo.md 9.4 KB

Historia Raaka