跳到主要内容

In-game Items

1. 什么是游戏内物品 ？​

通过游戏内物品 ，游戏可以在游戏内经济中Build物品集合，这些物品可用于多种场景。 在门户网站中，您可以创建和维护物品定义。 所有类型的物品都可以在商店中出售，也可以通过专用服务器和云函数 API 在游戏机制下授予玩家。 某些类型的物品可以在玩家背包中实例化，从而让玩家拥有它们。 我们提供以下类型的游戏内物品 ：

  • 普通物品（Normal item）：普通物品是单独的游戏内物品 。 当玩家获得普通物品时，会在玩家背包中创建一个普通物品实例。 普通物品可以是头盔或盔甲。

  • 捆绑包（Bundle）：捆绑包是游戏内物品或虚拟货币的集合。 它们可以包含多种不同类型的物品或一堆虚拟货币。 当玩家获得捆绑包时，PGOS 会自动将捆绑包的内容授予玩家。 捆绑包本身不会在玩家背包中实例化。比如，你可以定义一个包含一顶头盔和一套盔甲的 Bundle。

  • 容器（Container）：容器是游戏内物品或虚拟货币的集合，可以包含多种不同类型的物品或一堆虚拟货币。当玩家获得一个容器时，会在玩家背包中创建一个容器实例，玩家可以打开容器，此时 PGOS 会自动将容器中的内容授予玩家，打开后，容器会从背包中移除。比如，你可以定义一个包含一顶头盔和一套盔甲的容器。

下图展示了三种游戏内物品的结构以及玩家获取它们的过程：

1624954614405

2. 属性参考​

本节介绍游戏内物品的属性，用于创建和管理游戏内物品 。

  • 物品ID（Item ID）：物品标识，在游戏区服内必须是唯一的，一旦提交则不可更改。
  • 显示名称（Display Name）：物品的显示名称。
  • 图标（Icon）：用于记录展示给玩家的物品图标的资源地址。
  • 说明（Description）：物品的描述。
  • 标签（Tags）：您可以使用此字段商店自定义KV对格式的物品分类信息。
  • 默认价格（Default Prices）：默认价格信息，您可以使用多种虚拟货币设置物品价格，当物品在商店出售时，此字段作为商店价格，除非您为商店中的物品设置了不同的价格。
  • 有效期（Valid Duration）：此字段指定普通物品实例化后，在玩家背包中保留的时间。默认值为 0，表示除非用户主动使用或删除，否则物品永不过期。当设置的时间到期时，物品实例的状态将变为已过期。请参阅 物品实例了解有关物品状态的更多信息。
  • 默认自定义数据（Default Custom Data）：你可以使用此字段为物品添加自定义属性信息，比如头盔提供的护甲加成。你可以在物品实例中访问此字段。在后续版本中，我们将提供SDK API来更新自定义数据。
  • 是否唯一（Is Unique）：False/True，一旦提交则无法更改。此字段表示普通物品实例在玩家背包中是否唯一。如果为True，则表示玩家背包只能包含此物品的一个有效实例。用户将无法获得此物品的更多重复项。我们建议你为玩家只能持有其中一种的物品启用此属性 ，比如角色皮肤。
  • 是否可堆叠（Is Stackable）：False/True，一旦提交则无法更改。此字段表示普通物品的实例是否可以在玩家背包中堆叠。共享实例ID的可堆叠物品。只有具有完全相同属性的物品实例才能堆叠。例如，单独授予的具有非零有效期的相同物品无法堆叠，因为它们的剩余有效期不同。请参阅 物品实例#2-item-instances)了解更多关于物品状态的信息。
  • 堆叠限制（Stack Limit）：可堆叠物品实例的堆叠数量限制。0 表示无限制。
  • 是否可消耗（Is Consumable）：False/True。该字段表示普通物品实例是否可以消耗。您可以调用客户端 SDK 中的 ConsumeInstance API 来消耗此可消耗物品的实例。此外，PGOS 允许您为可消耗物品绑定一个虚函数来设置消耗时的效果。该虚函数会在物品实例被消耗时同步实现。请参阅可消耗了解更多信息。
  • 内容（Content）： 游戏内物品 、虚拟货币及其数量的列表。只要您的配置是自洽的，内容中可以包含的物品类型没有直接限制。但是，对于收藏类物品，我们不允许嵌套超过五层。

并非每个游戏内物品都需要上述所有属性。具体要求见下表：

普通物品捆绑包容器
物品 IDYYY
显示名称YYY
图标YYY
说明YYY
标签YYY
默认价格YYY
有效期Y
默认自定义数据YYY
是否唯一Y
是否堆叠Y
是否可消耗Y
内容YY
支持示例化YY

3. 定义游戏内物品​

PGOS不提供游戏内物品的默认定义，因此您必须根据需求配置自定义游戏内物品。前往门户网站 -> 经济 -> 游戏内物品，点击添加物品/捆绑包/容器来创建所选类型的物品。

1624264082095

3.1 物品定义约束条件​

您可以通过嵌套和组合多种类型的物品来设计复杂的物品方案。我们没有设置太多限制。但是，您必须确保物品定义保持自洽。因此，我们在物品创建过程中设置了一些约束条件，以避免出现难以理解或相互矛盾的物品定义：

  • 约束条件 1. 唯一物品和可堆叠不能同时为真，因为这两个属性相互矛盾。
  • 约束条件 2. 具有相同物品 ID 的多个唯一物品不能直接或间接包含在礼包、容器或其他集合类型物品中。在这种情况下，玩家将无法获得该物品，因为玩家不能拥有多个具有相同 ID 的唯一物品。
  • 约束条件 3. 礼包、容器的物品嵌套层级不能超过五层。
  • 约束条件 4. 礼包、容器不能直接或间接包含自身。

3.2 创建普通物品​

前往开发者中心 -> 经济系统 -> 游戏内物品 -> 普通物品，点击添加物品。以下是普通物品的属性示例：

Type: Normal
ID: fish_jdbl81fr
Display Name: Fish
Icon: null
Default Prices: null
Valid Duration: 20 seconds
Description: A small fish, eat it to restore some life
Is Unique: False
Is Stackable: True
Is Consumable: True
Tags: { "category": "food" }
Default Custom Data: { "hp_restore_value": 5 }

3.3 创建捆绑物品​

前往"经济" -> "游戏内物品"页面，选择"礼包"选项卡，然后点击"添加捆绑包"。以下是捆绑包的属性示例：

Type: Bundle
ID: gift_jdbl81fr
Display Name: Rookie gift
Icon: null
Default Prices: null
Content: [
    < fish_jdbl81fr, 10 >,
    < GAMEGOLD, 200 >
]
Description: A gift for rookies that contains a few fish and some gold coins.
Tags: null
Default Custom Data: null

3.4 创建容器物品​

前往门户 -> 经济 -> 游戏内物品 -> 容器并点击添加容器。以下是容器的属性示例：

Type: Bundle
ID: box_jdbl81fr
Display Name: Box
Icon: null
Default Prices: null
Content: [
    < gift_jdbl81fr, 2 >
]
Description: A box you can open at any time.
Tags: null
Default Custom Data: null

3.5 删除​

您可以根据需要删除已创建的游戏内物品。当您尝试删除物品时，我们会检查该物品在经济系统中的使用情况。在以下情况下，物品无法被删除：

  • 该物品已在商店中可购买
  • 该物品作为礼包/容器的内容物

删除操作不可逆，请谨慎操作。

4.消耗品​

游戏客户端可以消费消耗品，例如提供经验奖励的卷轴或增加生命值的鱼。您可以使用虚拟服务器来自定义物品消耗的效果。

4.1 消耗流程​

  • 游戏客户端调用UPgosEconomyAPI::ConsumeInstance API发起物品实例的消费请求。
  • 经济服务消耗玩家库存中的物品实例。消耗的物品实例对玩家不可见，但可以在门户的玩家库存部分进行检查。
  • 然后 PGOS 调用绑定虚拟服务器的 /pgos_economy URL。
    • 虚拟服务器请求所需的数据模式可以在 doc 中找到。
    • PGOS 将在 UPgosEconomyAPI::ConsumeInstance 接口的回调中返回来自消费处理程序的完整响应数据，对其数据格式没有任何限制。
Game ClientEconomy ServiceInventory ServiceVirtual ServerConsumeInstanceConsume the item instanceItem instance consumedCall bound virtual serverVirtual server responseOnConsumeInstanceGame ClientEconomy ServiceInventory ServiceVirtual Server

4.2 云函数处理消耗流程​

4.2.1 关联云函数​

前往管理后台 -> 经济系统 -> 游戏内物品 -> 普通物品，选择目标物品，修改可消耗属性。

  • 否/是: 设置为"是"以启用更多配置。

  • 云函数: 选择一个云函数来实现物品消耗效果。

image-20240530141714087

4.2.2 云函数示例​

您可以按照以下步骤创建云函数。这是一个简单的 Node.js 代码片段，仅打印 ItemConsumptionReq. 实际上，您可以在云函数中添加任何特定游戏逻辑以实现不同效果。要创建云函数，请参考此文档。

// pgos_economy handles the specific requests from PGOS economy service, please config the binding for the economy service on the portal in advance
router.post("/pgos_economy", async (ctx) => {
  var invoker = ctx.request.headers["invoker"];
  if (invoker != "economy") {
    ctx.status = 401;
    return;
  }
  // write your own code to handle
  console.log("/pgos_economy: " + ctx.request.rawBody);
  ctx.body = "";
});

4.3 在门户网站上查看消耗情况​

您可以查看玩家背包中物品的消耗情况。

当物品被消耗后，该物品实例的状态将变更为"已消耗"。

image-20240527162935673

此外，背包日志中会生成一条操作类型为消耗的交易记录。

image-20240527162902403

如果对绑定的云函数的 /pgos_economy URL 进行 HTTP 调用时返回错误，消耗操作将被标记为失败。但无论结果如何，该物品实例的状态都会被标记为"已消耗"，并且无法再次消耗。

image-20240527164144358