道具系统与平台付费商店

本系统为游戏平台提供统一的付费道具管理解决方案，支持单机游戏的道具购买、发放、统计等功能，实现道具购买、查询、增减及进程触发发放功能。

• 核心功能：道具购买、持有查询、增减操作、变更监听、游戏进程触发发放

1. 开发者后台管理功能

• 开发者可通过后台手动创建道具数据，支持上传表格(道具单元表)与道具图标。
• 付费的商城道具目前只支持手动创建。
• 支持创建最多 5000 条道具数据。
• 暂时只支持买断制和内购类型的游戏使用。
• 道具创建后需要经过审核，通过审核后，会默认进入启用状态。

道具管理功能：

‌道具ID‌：唯一标识，创建后不可修改
‌道具名称与图标‌：用于前端展示
‌道具图标‌：支持手动更换Icon图
‌道具创建规则：支持选择游戏道具、商城付费道具
道具限制：支持设置通过平台发放给玩家的限制，每日发放数量限制、总计数量限制或者不限制
‌道具库存‌：可选择输入数量或不限制
道具价值设置：
免费道具(Platform activities)：支持到平台活动投放。
付费购买(Paid purchase)：支持道具商城付费购买。
默认美元计价
道具单元定价支持精确到0.0001美元
商城付费道具最小价值输入1美元

建议

• 先录入道具单元后，再手动录入道具商城付费购买的道具，支持选择1个或者多个道具组成一个集合商品进行销售。
• 当道具设置为免费道具时，平台可能会根据运营计划选择投放给玩家，在玩家进入游戏后会发放到玩家的游戏角色。

2. 道具 SDK 接入

核心接口说明

接口名称	方法签名	功能描述
打开购买窗口	openBuyGameItemsDialog(level: number)	通过游戏内的功能 UI 唤起商城道具的购买弹窗
获取持有道具	getUserGameItems(): GameItem[]	进入游戏时查询玩家当前道具列表（含 ID 和数量）
增加道具	addGameItem(itemId: string, amount: number)	游戏进程中发放道具（支持购买、关卡奖励、任务完成等场景）
减少道具	subtractGameItem(itemId: string, amount: number)	消耗道具（游戏进程中使用、消耗等场景，扣除后数量非负）
订阅变更通知	subscribeGameItemChange(callback: (res: GameItemChange) => void)	商城付费道具支付完成回调方法

关键数据格式

• ​**GameItem（道具信息）**​：{ itemId: string, amount: number }
• ​**GameItemChange（变更信息）**​：{ itemId: string, amount: number, changeType: 'add'|'subtract', total: number }

2.1 获取持有道具列表

// 获取玩家持有道具列表（游戏初始化时调用）
const items = window.JOGOS_SDK.gameItem.getUserGameItems();
console.log('持有道具：', items);

2.2 打开道具购买窗口

// 打开道具购买窗口
window.JOGOS_SDK.gameItem.openBuyGameItemsDialog(10);

2.3 增加道具

// 增加道具（ID：3232addasdda3aa2，数量10）
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);

2.4 减少道具

// 减少道具（ID：3232addasdda3aa2，数量5）
window.JOGOS_SDK.gameItem.subtractGameItem('3232addasdda3aa2', 5);

2.5 订阅道具变更通知

// 订阅道具变更通知
window.JOGOS_SDK.gameItem.subscribeGameItemChange((res) => {
  console.log('道具变更：', res);
});

2.6 付费道具购买全流程

// 1. 发起付费道具购买（商品ID：item_gold_100，对应100金币道具）
async function buyGoldItem() {
  try {
    const orderNo = await window.JOGOS_SDK.payment.buyGoods('item_gold_100');
    console.log('订单创建成功，订单号：', orderNo);
  } catch (err) {
    console.error('订单创建失败：', err);
    alert('购买发起失败，请稍后重试');
  }
}

// 2. 订阅支付成功通知（游戏初始化时调用）
window.JOGOS_SDK.payment.subscribeOrderPaid(async (order) => {
  console.log('支付成功，订单详情：', order);
  if (order.status === 'success') {
    // 3. 发放对应道具（商品ID：item_gold_100 对应道具ID：3232addasdda3aa2）
    window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
    // 4. 通知平台发货（必须调用，否则订单状态异常）
    await window.JOGOS_SDK.payment.deliverGoods(order.orderNo);
    alert('100金币购买成功，已发放到背包！');
  }
});

// 3. 异常场景：查询订单详情（如支付后未收到道具）
async function checkOrder(orderNo) {
  try {
    const order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo);
    console.log('订单详情查询：', order);
    if (order.status === 'success') {
      // 补发放道具
      window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
      await window.JOGOS_SDK.payment.deliverGoods(orderNo);
    }
  } catch (err) {
    console.error('订单查询失败：', err);
  }
}

2.7 游戏进程触发道具发放（示例：关卡通关奖励）

// 关卡10通关触发道具发放（含去重逻辑，避免重复领取）
function onLevel10Clear() {
  // 单机游戏：用本地存储记录发放状态
  const hasIssued = localStorage.getItem('level10_award_issued');
  if (hasIssued) {
    alert('该关卡奖励已领取，不可重复领取');
    return;
  }

  // 发放道具（ID：3232addasdda3aa2，数量10）
  window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);
  // 记录发放状态
  localStorage.setItem('level10_award_issued', 'true');
  alert('关卡10通关成功！获得10个道具奖励');
}