Typical Use Case
这里我们以一个射击游戏来说明如何定义物品、授予物品、购买物品、消耗物品。
1. 配置您的游戏经济
如果这是您第一次使用 PGOS Economy，我们建议您按照以下配置流程进行操作：
- 配置虚拟货币
- 配置普通项目
- 配置捆绑包和容器
- 配置商店
1.1 配置虚拟货币
在PGOS Economy中，您可以根据游戏的需要配置一种或多种虚拟货币。在这个例子中，我们定义了两种虚拟货币：“Gold”和“Diamond”。
- 我们为金币设置了较大的初始存款，以允许玩家快速开始使用该货币。
- 钻石是通过战斗获胜获得的，所以我们将初始存款设置为0。
1.2 配置普通项
普通物品是游戏中使用的无法拆分的单个物品，例如单件盔甲或卷轴。下面提供了一些示例：
角色皮肤
一般来说，拥有单个皮肤项目的多个实例是没有意义的，因此皮肤项目的 is_unique 属性设置为“True”。
Normal items are individual items used in the game that cannot be split up, such as a single piece of armor or scroll. Some examples are provided below:
item_id: "item_skin_1111"
display_name: "Christmas style skin"
is_unique: true
is_stackable: false
is_consumable: false
tags: "class:skin"
default_custom_data: "-"
防弹背心
item_id: "item_armor_2222"
display_name: "Bulletproof vest"
is_unique: false
is_stackable: false
is_consumable: false
tags: "class:armor"
default_custom_data: "armor_value:15"冲锋枪
item_id: "item_weapon_3333"
display_name: "Submachine gun"
is_unique: false
is_stackable: false
is_consumable: false
tags: "class:weapon"
default_custom_data: "attack_value:10"经验奖励卷轴
item_id: "item_scroll_4444"
display_name: "Experience bonus scroll"
is_unique: false
is_stackable: true
is_consumable: true
tags: "class::scroll"
default_custom_data: "bonus_rate:1.5"
1.2.1 使用标签
在此示例中，我们使用 Tags 字段对每个项目进行分类。您可以自定义标签内容，以根据游戏的设计将项目标记为属于不同的类别。
1.2.2 使用默认自定义数据
在这个例子中，我们使用默认自定义数据字段来存储每个物品的游戏相关属性信息，例如盔甲提供的防御加值、武器提供的攻击加值以及卷轴提供的经验加值。
这样做的优点是可以将所有物品数据存储在 PGOS 经济系统中。如果您需要修改项目属性，则无需重新编译、部署和发布游戏客户端和服务器。
当然，你可能需要将客户端中的详细物品信息打包为本地资源。在这种情况下，您可以使用 item_id 字段作为将播放器库存中的项目与本地资源中的项目关联起来的标识符。
1.3 配置捆绑包项目
- 装备套装
type: "bundle item"
item_id: "item_suit_5555"
display_name: "Equipments"
content:
- item_armor_2222: 1
- item_weapon_3333: 1
初级宝箱
type: "container item"
item_id: "item_suit_5555"
display_name: "Equipments"
content:
- item_scroll_4444: 5
- DIAMOND: 25
1.4 配置商店
在 PGOS Economy 中，您可以配置一个或多个商店来销售游戏中的不同物品。我们提供一些示例如下：
装备店
这家商店中的所有物品都可以用金币或钻石购买。金币的价格比钻石高。这是因为，在实际的游戏设计中，获得金币比获得钻石更容易。
display_name: "Equipments store"
item_list:
- item_armor_2222:
prices:
GOLDCOIN: 250
DIAMONDCOID: 25
- item_weapon_3333:
prices:
GOLDCOIN: 250
DIAMONDCOID: 25
- item_scroll_4444:
prices:
GOLDCOIN: 25
DIAMONDCOID: 5皮肤商店
这家商店的物品只能用钻石购买。
display_name: "Skin store"
- item_skin_1111:
prices:
DIAMONDCOID: 250
2. 案例购买物品
玩家可以在商店购买游戏内物品。为了获取商店中的产品信息，您需要知道“store_id”。游戏客户端获取商店id的方式有很多种，以下是两种典型的方式：
- 将商店 ID 打包到游戏配置文件中。
- 在 PGOS 标题区域配置数据中存储存储 ID。
调用 UPgosEconomyAPI::GetStore 获取给定商店中的产品信息。
然后调用 UPgosEconomyAPI::CreateStoreOrder&UPgosEconomyAPI::CommitStoreOrder 购买商店商品。如item_armor_2222 x 1、item_suit_5555 x 1、item_scroll_4444* x 1。
购买操作的结果将通过UPgosEconomyAPI::CreateStoreOrder&UPgosEconomyAPI::CommitStoreOrder回调返回：
- 虚拟货币支出信息。
- 游戏内物品获得信息。
- 虚拟货币获取信息。
3. 箱子消耗物品
下面的例子说明了如何使用item消费机制。在进入战斗之前，使用 item_scroll_4444 x1 来获得经验提升。具体流程：
- 开始消费： 游戏客户端调用PGOS SDK中的UPgosEconomyAPI::ConsumeItemInstance接口发起物品实例消费请求。
- 等待消费完成： 经济服务实现与该项目关联的虚拟服务器功能，并等待实现完成。
- 处理消费结果：根据虚拟服务器功能返回的结果数据，游戏客户端可以通过UI提示告知玩家消费行为的结果和影响。
4. 角色皮肤
您可以创建代表游戏中角色皮肤的物品。此类物品的实例可以被视为角色皮肤的令牌。皮肤的获取与其他物品相同，这里不再赘述。您可能更关心如何在战斗中使用皮肤物品。有以下两个典型案例。
1.在战斗中选择皮肤。
- 游戏客户端连接到 DS。
- DS 调用 UPgosEconomyAPI::GetPlayerInventory 来获取玩家拥有的所有皮肤。
- 玩家选择皮肤。
2.战斗前选择皮肤。
- 游戏客户端调用UPgosEconomyAPI::GetInventory来获取玩家拥有的所有皮肤。
- 玩家选择皮肤。
- 游戏客户端通过皮肤数据连接到 DS。
- DS调用
UPgosEconomyAPI::GetPlayerInventory来检查玩家是否拥有该物品实例，以决定是否在战斗中为玩家角色应用皮肤。
5. 订单退款案例
1.发起退款： 如果玩家购买了超人套装但确实使用了它，则玩家可以发起退款。
2.收回物品并返还资金：玩家支付的 500 金币将返还至玩家的钱包。如果退款成功，则会在客户端 SDK 中触发 OnBalanceChanged 事件。同时，超人套装被回收，并在客户端 SDK 中触发 OnInventoryChanged 事件。
6. 向指定玩家授予物品的案例
在某些情况下，您可能必须向玩家授予游戏内物品或虚拟货币。这可以通过几种不同的方式来完成。
- 调用DS SDK API向玩家授予物品
Pgos::Server::UPgosEconomyAPI::GrantCurrencyToPlayer
Pgos::Server::UPgosEconomyAPI::BatchGetItemInstance
- 调用虚拟服务器API向玩家授予物品
GrantCurrencyToPlayer
GrantItemsToPlayer
- 使用门户向玩家授予物品
