Shop 模块说明文档

概述

Shop 模块是一个完整的游戏商店系统，支持商品浏览、装备管理、拖拽操作等功能。基于 LayaAir 3.x 引擎开发。

使用说明

将shop.layapkg导入LayaAir3.3中，将UI系统改成经典UI，分辨率1920*1080。
打开ShopScene运行。

演示示例

目录结构

assets/shop/
├── config/
│   └── ShopConfig.ts          # 商店配置管理器
├── Runtime/
│   ├── ShopSceneRuntime.ts           # 商店场景主逻辑
│   ├── ShopListRuntime.ts            # 商店列表逻辑
│   ├── ShopListItemRuntime.ts        # 列表项渲染
│   ├── ShopListItemDragHandler.ts    # 列表项拖拽处理
│   ├── EquipPanelRuntime.ts          # 装备面板逻辑
│   ├── ItemDescPanelRuntime.ts       # 物品描述面板
│   ├── DragManager.ts                # 拖拽管理器
│   └── *.generated.ts                # 自动生成的基类
├── prefab/
│   ├── ShopScene.ls                  # 商店场景
│   ├── ShopList.lh                   # 商店列表预制体
│   ├── ShopListItem.lh               # 列表项预制体
│   ├── EquipPanel.lh                 # 装备面板预制体
│   └── ItemDescPanel.lh              # 描述面板预制体
└── ShopScene.ls               # 场景入口文件

核心模块

1. ShopConfig - 配置管理器

文件: config/ShopConfig.ts

职责: 统一管理商店系统的配置数据，单例模式。

主要配置项:

配置项	类型	默认值	说明
qualityColors	string[]	6种颜色	品质颜色（普通/优秀/精良/史诗/传说/神话）
qualityNames	string[]	6个名称	品质名称
shopItemCount	number	30	商店商品数量
defaultIcon	string	“atlas/comp/image.png”	默认图标
dragThreshold	number	10	拖拽触发阈值（像素）
equipmentSlotCount	number	12	装备栏槽数量

主要方法:

// 获取单例
ShopConfig.getInstance(): ShopConfig

// 加载配置（从 resources/json/ShopConfig.json）
load(): Promise<void>

// 获取品质颜色
getQualityColor(quality: number): string

// 获取品质名称
getQualityName(quality: number): string

快捷函数:

getShopConfig(): ShopConfig
getQualityColor(quality: number): string
getQualityName(quality: number): string

2. ShopSceneRuntime - 场景管理器

文件: Runtime/ShopSceneRuntime.ts

职责: 商店场景的主控制器，协调各子模块。

组件引用:

• ShopList - 商店列表组件
• EquipPanel - 装备面板组件
• ItemDescPanel - 物品描述面板组件

主要回调:

// 装备物品时触发
onItemEquip: (slotIndex: number, item: ShopItemData) => void

// 物品交换时触发
onItemSwapped: (fromIndex: number, toIndex: number, item: ShopItemData) => void

// 槽位点击时触发
onSlotClick: (slotIndex: number, item: ShopItemData) => void

// 从商店移除物品时触发
onItemRemovedFromShop: (itemId: number) => void

3. ShopListRuntime - 商店列表

文件: Runtime/ShopListRuntime.ts

职责: 管理商店商品列表的显示和交互。

主要方法:

// 移除物品
removeItem(itemId: number): void

// 获取商店数据
getShopData(): ShopItemData[]

// 清除选中状态
clearSelection(): void

// 获取选中项
getSelectedItem(): ShopItemData | null

// 设置滚动启用状态
setScrollEnabled(enabled: boolean): void

4. ShopListItemRuntime - 列表项

文件: Runtime/ShopListItemRuntime.ts

职责: 渲染单个商品项。

UI 元素:

• icon - 商品图标
• nameLabel - 商品名称
• priceLabel - 商品价格
• qualityBorder - 品质边框
• SelectBg - 选中背景

主要方法:

setData(data: ShopItemData): void    // 设置商品数据
setSelected(selected: boolean): void // 设置选中状态
refresh(): void                       // 刷新显示

5. EquipPanelRuntime - 装备面板

文件: Runtime/EquipPanelRuntime.ts

职责: 管理装备栏（12个槽位），支持拖拽装备和槽位间物品交换。

主要方法:

// 装备到空槽位
equipToEmptySlot(slotIndex: number, item: ShopItemData): boolean

// 获取已装备物品
getEquippedItems(): (ShopItemData | null)[]

// 清空所有装备
clearAllEquip(): void

// 检查槽位是否为空
isSlotEmpty(slotIndex: number): boolean

// 获取槽位物品
getSlotItem(slotIndex: number): ShopItemData | null

// 高亮槽位
highlightSlotAt(x: number, y: number): void

// 清除高亮
clearHighlights(): void

事件回调:

onItemEquip: (slotIndex: number, item: ShopItemData) => void
onItemSwapped: (fromIndex: number, toIndex: number, item: ShopItemData) => void
onSlotClick: (slotIndex: number, item: ShopItemData) => void
onItemRemovedFromShop: (itemId: number) => void

6. ItemDescPanelRuntime - 物品描述面板

文件: Runtime/ItemDescPanelRuntime.ts

职责: 显示选中物品的详细信息。

UI 元素:

• Icon - 物品图标
• NameLabel - 物品名称
• QualityLabel - 品质标签
• PriceLabel - 价格标签
• DescLabel - 描述文本

主要方法:

showItem(data: ShopItemData): void  // 显示物品信息
clear(): void                        // 清空显示

7. DragManager - 拖拽管理器

文件: Runtime/DragManager.ts

职责: 统一管理所有拖拽操作，单例模式。

拖拽数据接口:

interface DragData {
    item: ShopItemData;              // 拖拽的物品
    source: "shop" | "equip";        // 来源类型
    sourceSlotIndex?: number;        // 来源槽位索引
    sourceItemIndex?: number;        // 来源商品索引
}

主要方法:

// 获取单例
getInstance(): DragManager

// 准备拖拽（鼠标按下时调用）
prepareDrag(startHandler: () => void): void

// 开始拖拽
startDrag(data: DragData): boolean

// 结束拖拽
endDrag(): void

// 注册拖放区域
registerDropZone(config: {
    test: (x: number, y: number) => boolean;
    onDrop: (data: DragData, x: number, y: number) => void;
    onHover?: (x: number, y: number) => void;
    onLeave?: () => void;
}): void

// 设置拖拽开始回调
setOnDragStart(callback: (data: DragData) => void): void

// 设置拖拽结束回调
setOnDragEnd(callback: (data: DragData, x: number, y: number) => void): void

8. ShopListItemDragHandler - 拖拽处理器

文件: Runtime/ShopListItemDragHandler.ts

职责: 处理商店列表项的拖拽操作，继承自 Laya.Script。

主要方法:

setItemData(data: ShopItemData, index: number): void  // 设置物品数据
setDragEnabled(enabled: boolean): void                 // 启用/禁用拖拽

数据结构

ShopItemData - 商店物品数据

interface ShopItemData {
    id: number;           // 物品ID
    name: string;         // 物品名称
    price: number;        // 价格
    icon: string;         // 图标路径
    quality: number;      // 品质等级 (0-5)
    desc?: string;        // 描述
    equipped?: boolean;   // 是否已装备
}

ShopConfigData - 配置数据结构

interface ShopConfigData {
    quality: {
        colors: string[];  // 品质颜色
        names: string[];   // 品质名称
    };
    shop: {
        itemCount: number;          // 商品数量
        defaultIcon: string;        // 默认图标
        dragThreshold: number;      // 拖拽阈值
    };
    equipment: {
        slotCount: number;          // 槽位数量
        emptyIcon: string | null;   // 空槽位图标
    };
}

交互流程

购买/装备流程

1. 用户在商店列表中点击商品
   ↓
2. ItemDescPanel 显示商品详情
   ↓
3. 用户拖拽商品到装备栏
   ↓
4. DragManager 处理拖拽操作
   ↓
5. EquipPanel 检测放置位置
   ↓
6. 如果槽位为空 → 装备物品
   如果槽位已有物品 → 交换物品
   ↓
7. 从商店列表移除物品
   ↓
8. 更新 UI 显示

槽位间交换流程

1. 用户在装备栏拖拽已装备物品
   ↓
2. DragManager 开始拖拽
   ↓
3. 用户释放到另一个槽位
   ↓
4. EquipPanel 处理交换逻辑
   ↓
5. 更新两个槽位的显示

品质系统

等级	名称	颜色	价格倍率
0	普通	#CCCCCC	x1
1	优秀	#00FF00	x2
2	精良	#00BFFF	x3
3	史诗	#FF00FF	x4
4	传说	#FFD700	x5
5	神话	#FF4500	x6

使用示例

获取配置

import { getShopConfig, getQualityColor, getQualityName } from "./config/ShopConfig";

// 获取配置实例
const config = getShopConfig();

// 获取品质颜色
const color = getQualityColor(3); // 史诗紫色

// 获取品质名称
const name = getQualityName(3); // "史诗"

使用拖拽管理器

import { DragManager } from "./Runtime/DragManager";

const dragManager = DragManager.getInstance();

// 设置拖拽回调
dragManager.setOnDragStart((data) => {
    console.log("开始拖拽:", data.item.name);
});

dragManager.setOnDragEnd((data, x, y) => {
    console.log("结束拖拽:", data.item.name, "at", x, y);
});

外部配置

配置文件路径: resources/json/ShopConfig.json

{
    "quality": {
        "colors": ["#CCCCCC", "#00FF00", "#00BFFF", "#FF00FF", "#FFD700", "#FF4500"],
        "names": ["普通", "优秀", "精良", "史诗", "传说", "神话"]
    },
    "shop": {
        "itemCount": 30,
        "defaultIcon": "atlas/comp/image.png",
        "dragThreshold": 10
    },
    "equipment": {
        "slotCount": 12,
        "emptyIcon": null
    }
}

注意事项

1. 拖拽冲突: 所有拖拽操作必须通过 DragManager 统一管理，避免事件冲突
2. 槽位索引: 装备栏槽位索引为 0-11，共12个槽位
3. 品质范围: 品质值为 0-5，超出范围将使用默认值
4. 配置加载: 配置文件加载失败时会使用默认配置，不会中断程序