跳转至

铸造

Mint是一个将游戏物品作为NFT发行的功能。它根据用户发行选项卡中的[i]配置内容[/i]在Hive控制台的区块链 > XPLA > NFT菜单中发行NFT。

铸造函数的实现流程

以下是Mint功能的实现过程。要实现Mint功能,请按照下面的流程图和指导内容在游戏客户端(Hive SDK,游戏客户端)和游戏服务器区域中实现代码。下面图像中标有蓝色星号的部分是开发人员需要工作的区域。有关主要任务的更多详细信息,请参阅下面的指南。

Note

完成准备后,您需要实现Mint功能。

Note

要实现Mint功能,您必须使用Hive SDK

在 hive SDK 中实现登录

在游戏客户端中实现代码,以允许用户使用 IdP 登录 和 Hive SDK 认证功能登录。 Web 登录 也支持作为登录方式。

NFT铸造按钮实现

在游戏客户端中实现一个用户界面,允许用户打开NFT发行页面。例如,当用户在访问游戏后从角色库存中选择一个物品时,应该出现一个将物品转换为NFT按钮。当按下此按钮时,应根据以下内容打开NFT发行页面。

请求将物品转换为 NFT

实现从游戏客户端向游戏服务器请求将用户游戏物品作为NFT发行的代码。这是为了实现用户选择NFT发行按钮时的操作。当游戏服务器收到来自游戏客户端的请求时,它会检查要作为NFT发行的游戏物品,然后调用NFT发行页面链接创建API将物品作为NFT发行。

NFT发行页面是一个允许用户将他们拥有的物品转换为NFT的网页。该网页由Hive区块链服务器提供。游戏服务器调用链接生成API以检索此网页的URL(webLinkUrl)。当用户访问此网页时,他们可以在区块链上铸造游戏内物品为NFT。

注意事项

开发人员在进行 API 调用时应采取的预防措施。

游戏服务器网址

gameServerUrl 用作 Hive 区块链服务器调用游戏服务器的 请求 URL 的 API (物品验证 API结果检查 API)。

游戏服务器网址和令牌

当 Hive 区块链服务器调用 物品验证 API结果确认 API 时,游戏服务器可以选择性地使用 身份验证令牌(头部参数) 进行 API 调用,这由开发者自行决定。如果要在 API 调用中使用身份验证令牌,游戏服务器必须在调用 NFT 发行页面链接生成 API 时,将此身份验证令牌预先附加为 token(查询参数)到 gameServerUrl 并发送给 Hive 区块链服务器。下面是一个示例。

"gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."

属性

attributes 在 Hive 区块链服务器调用 物品验证 API结果确认 API 到游戏服务器时用作请求体。

当您在attributes中使用项目唯一代码调用API时,唯一代码也可以包含在结果检查API的请求体attributes中。在这种情况下,您可以使用相应的唯一代码更新项目状态。

NFT发行页面链接有效期

一次创建的页面链接仅在10分钟内有效,基于第一次访问的会话。

请求 URL

项目
直播网址 https://bc-platform-api.withhive.com/web3/v1/web-link
沙盒网址 https://sandbox-bc-platform-api.withhive.com/web3/v1/web-link
HTTP 方法 POST
内容类型 application/json

头部参数

字段名称 描述 类型 必需
Authorization API 调用的身份验证令牌 字符串 Y

请求体

字段名称 描述 类型 必需
type MINT 字符串
playerId 玩家ID 数字
characterId 角色ID 字符串
gameServerUrl 接收物品验证和功能执行后成功/失败结果的地址。通过token查询参数发送身份验证令牌以进行物品验证/结果确认API头 字符串
data 根据类型的请求参数信息 json

数据对象

字段名称 描述 类型 是否必需
itemId 用户 NFT 模板标识符(控制台注册) 字符串
attributes 每个代币应用的附加元数据属性(例如,唯一物品代码、力量、敏捷等属性,包含在 NFT 中) json 数组
attributes.traitType 组成属性的物品名称 字符串
attributes.value 特征值 字符串

请求示例

curl -X 'POST' \
  'https://sandbox-bc-platform-api.withhive.com/web3/v1/web-link' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6NiwiaWQiOiIvVWpXN....' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "MINT",
  "playerId": 1276814678,
  "characterId": "zeratu",
  "gameServerUrl": "https://api.com2us.com/hive" // When sending authentication token: "gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."
  "data": {
    "itemId": "HIVE",
    "attributes": [
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ]
  },
}'

响应

字段名称 描述 类型
code API 调用结果代码,0: 成功 number
message 结果消息 string
data API 响应数据 json
data.webLinkId 网页链接 ID (UUID) string
data.webLinkUrl 生成的一次性网页链接 (URL) string
data.expiration 网页链接过期日期 (ISO 8601) string

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "webLinkid": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
    "webLinkUrl": "https://sandbox-xpla-platform.withhive.com/api/v1/web-link/redirect?token=b256c85c-aee8-4837-b54d-9a03fe8a7435.f94140b71c9ebf058956547753131adde9968a0266f208d7e3059bbb6dd0c7bc",
    "expiration": "2024-08-05T08:33:15.448Z"
  }
}

使用 hive SDK 实现 NFT 发行页面

NFT 发行页面链接创建 API 公开了作为响应接收到的网页 URL,以便在游戏内浏览器中使用 Hive SDK 打开。


以下是NFT发行页面的示例。

作为NFT发行的项目资料


当您打开NFT发行页面时,将出现X-PLANET钱包XLPA Vault的登录窗口。用户必须选择一个特定的钱包地址,以便在登录到X-PLANET钱包或XLPA Vault后执行铸造或销毁。

X-PLANET XPLA Vault XPLA Games

NFT 铸造 (执行铸造)

在NFT发行页面,用户选择一个项目,然后执行铸造。

在NFT发行前检查费用

项目验证 API 调用 (蜂巢区块链服务器 → 游戏服务器)

Note

该 API 不是游戏服务器调用 Hive 区块链服务器的 API,而是 Hive 区块链服务器调用游戏服务器的 API。因此,游戏服务器必须以 Hive 区块链服务器要求的形式配置并提供 API 端点。

在将游戏物品转换为NFT之前,Hive 区块链服务器会向游戏服务器请求物品验证。在确认游戏服务器提供的响应中的物品信息后,Hive 区块链服务器会在区块链上发行NFT。如果item verification fails,Hive 区块链服务器将不会发行NFT。

Note

在游戏服务器中,直到通过result confirmation API接收到NFT发行结果之前,您必须限制在游戏中已验证的物品的使用。

注意事项

以下是开发人员在配置 API 端点时的一些注意事项。

游戏服务器网址

此 API 从游戏服务器请求验证,使用从 NFT 发行页面链接创建 API 请求的 gameServerUrl

授权头

如果在从NFT发行页面链接创建API请求的gameServerUrl中存在token查询参数,请以Bearer形式使用此token值。

属性

在生成NFT发行页面链接的API请求体中包含attributes

请求 URL

这是需要在游戏服务器上准备的API端点信息。

项目
URL {gameServerUrl}/items/validate
HTTP 方法 POST
端口 80, 443
内容类型 application/json

头部参数

字段名称 描述 类型 必需
Authorization 作为 token 查询参数发送到 NFT 发行页面 API 的 gameServerUrl 的身份验证令牌。格式为 Bearer ${token}。 Bearer N
User-Agent HiveBlockchain/1.0 字符串 Y

请求体

字段名称 描述 类型 必需
type MINT 字符串
itemId NFT 项目识别代码 字符串
playerId 玩家 ID 数字
characterId 角色 ID 字符串
webLinkId 网页链接 ID (UUID) 字符串
tokenId NFT ID 字符串
attributes 每个代币应用的附加元数据属性(例如,唯一项目代码、力量、敏捷等包含在 NFT 中的属性) json 数组
attributes.traitType 组成属性的项目名称 字符串
attributes.value 特征值 字符串

请求示例

curl -X 'POST' \
  'https://api.com2us.com/hive/items/validate' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \ // When using authentication token
  -H 'User-Agent: HiveBlockchain/1.0' \
  -d '{
    "type": "MINT",
    "itemId": "HIVE",
    "playerId": 2319123897,
    "characterId": "zeratu",
    "webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
    "attributes": [ // Attributes when generating NFT issuance page link
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ]
  }'

响应

HTTP状态码如下。

  • 成功
    • 200
  • 失败
    • 4xx: 错误状态码,表示错误请求
    • 5xx: 错误状态码,表示服务器错误

结果检查 API 调用 (hive 区块链 → 游戏服务器)

Note

这个API不是游戏服务器调用Hive区块链服务器的API,而是Hive区块链服务器调用游戏服务器的API。因此,游戏服务器必须以Hive区块链服务器所需的形式配置API端点。

当Hive区块链服务器将NFT发行结果传递给游戏服务器时,游戏服务器处理该结果,使得这些物品无法在游戏中使用,然后通过API将结果发送回Hive区块链服务器。


游戏服务器将根据发行结果执行的操作如下。

  • NFT 发行成功
    • 处理以防止在游戏中使用物品(例如,从游戏用户的库存中删除物品)
  • NFT 发行失败
    • 处理以允许在游戏中使用物品(例如,解除使用限制以允许物品在游戏用户的库存中重新使用)
    • 如果用户取消 NFT 发行或超出时间限制,则发送 NFT 发行失败结果
Warning

您必须在游戏服务器上限制相应物品在游戏中的使用,直到您收到NFT发行结果。


以下是游戏服务器成功响应NFT发行时的NFT发行页面屏幕示例。

注意事项

以下是开发人员在配置 API 端点时需要考虑的事项。

属性

通过在attributes中包含唯一物品代码,您可以调用NFT发行页面链接创建API,并在请求体attributes中包含唯一代码。在这种情况下,您可以使用相应的唯一代码更新物品状态。

授权头

如果在从NFT发行页面链接创建API请求的gameServerUrl中存在token查询参数,请以Bearer形式使用此token值。

请求 URL

项目
URL {gameServerUrl}/items/callback
HTTP 方法 POST
端口 80, 443
内容类型 application/json

头部参数

字段名称 描述 类型 是否必需
Authorization 作为 token 查询参数发送的身份验证令牌,在NFT发行页面链接创建API的 gameServerUrl 中使用。以 Bearer ${token} 的形式调用。 Bearer N
User-Agent HiveBlockchain/1.0 string Y

请求体

字段名称 描述 类型 必需
type MINT 字符串
itemId NFT 项目识别代码 字符串
playerId 玩家 ID 数字
characterId 角色 ID 字符串
webLinkId 网页链接 ID (UUID) 字符串
tokenId NFT ID (成功时包含) 字符串
status 交易结果 (成功,失败) 字符串
attributes 每个代币应用的附加元数据属性 (例如,唯一代码、力量、敏捷等属性包含在 NFT 中) json 数组
attributes.traitType 构成属性的项目名称 字符串
attributes.value 特征值 字符串

请求示例

curl -X 'POST' \
  'https://api.com2us.com/hive/items/callback' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \  // When using authentication token
  -H 'User-Agent: HiveBlockchain/1.0' \
  -d '{
    "type": "MINT",
    "itemId": "HIVE",
    "playerId": 2319123897,
    "characterId": "zeratu",
    "webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
    "tokenId": "HIVE#348",
    "status": "success",
    "attributes": [ // Attributes when generating NFT issuance page link
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ]
  }'

响应

HTTP 状态码如下。

  • 成功
    • 200
  • 失败
    • 4xx: 错误状态码,表示错误请求
    • 5xx: 错误状态码,表示服务器错误