sce-game-sdk

v1.2.0

Published

4 months ago

Web browser mini game SDK with TypeScript

Downloads

0High
0Medium
0Low

meiqi2677

SCE SDK使用指南

简介

SCE SDK 是一个用于在 星火对战平台 中开发小游戏的 TypeScript 工具包。该 SDK 提供了登录验证、云数据存储和排行榜等功能，帮助开发者快速集成和开发小游戏。

安装

前提条件

Node.js >=16.0.0

通过 npm 安装 SCE 小游戏 SDK：

npm install sce-game-sdk

导入 SDK

import 'sce-game-sdk';

CDN直接引入

在 HTML 文件的 <head> 或 <body> 标签中添加以下 script 标签：

<script src="https://cdn.jsdelivr.net/npm/sce-game-sdk@latest/dist/sce.min.js"></script>
或
<script src="https://unpkg.com/sce-game-sdk@latest/dist/sce.min.js"></script>

引入 SDK 后，全局对象 SceSDK 将可用于访问所有功能。

调用方式

SDK支持两种调用方式：Promise风格和回调风格。您可以根据项目需求选择最适合的方式。

标记为 以 [Promise 风格]调用支持 的接口最后一个参数可传Callback参数表示用回调的方式接受返回，回调方式使用对象形式 {success, fail} 而不是单一函数

初始化与配置

在非星火运行环境使用 SDK 调试，需要进行初始化配置，正式环境可以不用初始化

SceSDK.init_for_dev(options)

初始化 SDK 并设置环境参数。sce_developer_token前往星火编辑器-创作者中心创建

注意： 以下参数仅供在非星火运行环境下调试使用，调试环境下设置云变量数据不会对线上产生影响
在正式环境中星火引擎会自动初始化SDK，不会用到开发者调试用的options

参数：

| 参数名 | 类型 | 必选 | 说明 | | --------------------------- | ------ | ---- | ------------------------------------------ | | options.sce_developer_token | string | 是 | 开发者后台获取的调试令牌 | | options.project_id | string | 否 | 调试的游戏项目ID，不传会给一个默认的随机值 |

返回值： 无

示例：

SceSDK.init_for_dev({
  sce_developer_token: 'YOUR_DEVELOPER_TOKEN',
  project_id: 'YOUR_PROJECT_ID'
});

主要功能

获取玩家信息

SceSDK.get_user_info()

以 [Promise 风格]调用：支持

获取当前登录用户的信息。

返回值： Object 对象，包含以下字段：

| 字段名 | 类型 | 说明 | | ------- | ------ | -------------- | | user_id | string | 用户SCEID | | name | string | 用户TapTap昵称 |

示例（Promise方式）：：

const res = await SceSDK.get_user_info();
if (res.result) {
  console.log(`用户ID: ${res.result.user_id}, 用户名: ${res.result.name}`);
} else {
  console.error(`get_user_info 失败: ${res.error}`);
}

示例（回调方式）：

SceSDK.get_user_info({
  success(userInfo) {
    console.log(`用户ID: ${userInfo.user_id}, 用户名: ${userInfo.name}`);
  },
  fail(error) {
    console.error(`get_user_info 失败: ${error}`);
  }
})

云数据存储

SceSDK.cloud.set_data(key, value)

以 [Promise 风格]调用：支持

存储对象类型的数据。

参数：

| 参数名 | 类型 | 必选 | 说明 | | ------ | ------ | ---- | ---------------------------------------------- | | key | string | 是 | 数据的键名，用于标识不同的数据 | | value | Object | 是 | 需要存储的数据，可以是对象、字符串或二进制数组 |

示例（Promise方式）：

let res = await SceSDK.cloud.set_data('test_data', { score: 100 });
if (res.result) {
  console.log(`set_data 成功`);
} else {
  console.error(`set_data 错误: ${res.error}`);
}

示例（回调方式）：

SceSDK.cloud.set_data('test_data', { score: 100 }, {
  success() {
    console.log('存储数据成功');
  },
  fail(error) {
    console.error('存储数据失败:', error);
  }
});

SceSDK.cloud.get_data(key)

以 [Promise 风格]调用：支持

获取已存储的对象类型数据。

result返回值： Object类型

参数：

| 参数名 | 类型 | 必选 | 说明 | | -------- | -------------------------------- | ---- | ---------------------- | | key | string | 是 | 要获取的数据的键名 |

示例（Promise方式）：

let res = await SceSDK.cloud.get_data('test_data');
if (res.result) {
  console.log('获取的数据:', res.result);
} else {
  console.error(`获取数据失败: ${res.error}`);
}

示例（回调方式）：

SceSDK.cloud.get_data('test_data', {
  success(result) {
    console.log('获取的数据:', result);
  },
  fail(error) {
    console.error('获取数据失败:', error);
  }
});

SceSDK.cloud.set_number(key, value)

以 [Promise 风格]调用：支持

存储数值类型的数据，专用于需要进行排名的数值。

参数：

| 参数名 | 类型 | 必选 | 说明 | | -------- | ------------------------------- | ---- | -------------------------------------- | | key | string | 是 | 数据的键名，用于标识不同的数值 | | value | number | 是 | 需要存储的数值，必须是数字类型 |

示例（Promise方式）：

let res = await SceSDK.cloud.set_number('player_score', 1000);
if (res.result) {
  console.log(`set_number 成功`);
} else {
  console.error(`set_number 错误: ${res.error}`);
}

示例（回调方式）：

SceSDK.cloud.set_number('player_score', 1000, {
  success(result) {
    console.log('存储分数成功');
  },
  fail(error) {
    console.error('存储分数失败:', error);
  }
});

SceSDK.cloud.get_number(key)

以 [Promise 风格]调用：支持

获取已存储的数值类型数据。

参数：

| 参数名 | 类型 | 必选 | 说明 | | -------- | -------------------------------- | ---- | ---------------------- | | key | string | 是 | 要获取的数值的键名 |

result返回值： number类型

示例（Promise方式）：

let res = await SceSDK.cloud.get_number('player_score');
if (res.result) {
  console.log('获取的分数:', res.result);
} else {
  console.error(`获取分数失败: ${res.error}`);
}

示例（回调方式）：

SceSDK.cloud.get_number('player_score', {
  success(result) {
    console.log('获取的分数:', result);
  },
  fail(error) {
    console.error('获取分数失败:', error);
  }
});

排行榜功能

SceSDK.cloud.get_top_rank(options)

以 [Promise 风格]调用：支持

获取排行榜数据。

参数：

| 参数名 | 类型 | 必选 | 说明 | | -------------------- | ------- | ---- | ---------------------------------------------------------- | | options | Object | 是 | 排行榜查询选项 | | options.key | string | 是 | 排行榜的键名，对应 set_number 设置的键 | | options.limit | number | 否 | 获取排行榜的数量限制，默认为 10 | | options.without_name | boolean | 否 | 是否不包含用户名信息，默认为 false (即包含用户名) | | options.order_by | string | 否 | 排序方式，可选值：'desc'(降序)、'asc'(升序)，默认为 'desc' |

result返回值： Object列表

| 列表项属性 | 类型 | 说明 | | ---------- | ------ | ------------ | | user_id | string | 用户ID | | name | string | 用户昵称 | | value | number | 排行榜中的值 |

示例（Promise方式）：

let res = await SceSDK.cloud.get_top_rank({
  key: 'player_score', 
  limit: 10, 
  without_name: false, 
  order_by: 'desc'
});
if (res.result) {
  console.log('排行榜数据:', res.result);
} else {
  console.error(`获取排行榜失败: ${res.error}`);
}

示例（回调方式）：

SceSDK.cloud.get_top_rank({
  key: 'player_score',
  limit: 10,
  without_name: false,
  order_by: 'desc'
}, {
  success(result) {
    console.log('排行榜数据:', result);
  },
  fail(error) {
    console.error('获取排行榜失败:', error);
  }
});

SceSDK.cloud.get_user_rank(options)

以 [Promise 风格]调用：支持

获取指定用户在排行榜中的排名。

参数：

| 参数名 | 类型 | 必选 | 说明 | | ---------------- | ------ | ---- | ---------------------------------------------------------- | | options | Object | 是 | 用户排名查询选项 | | options.key | string | 是 | 排行榜的键名，对应 set_number 设置的键 | | options.user_id | string | 否 | 要查询的用户ID，不传则查询当前登录用户 | | options.order_by | string | 否 | 排序方式，可选值：'desc'(降序)、'asc'(升序)，默认为 'desc' |

result返回值： Object类型

| 属性 | 类型 | 说明 | | ------- | ------ | ---------------------- | | user_id | string | 用户ID | | value | number | 排行榜中的值 | | rank | number | 排名，返回-1表示未上榜 |

示例（Promise方式）：

let res = await SceSDK.cloud.get_user_rank({key: 'player_score'});
if (res.result) {
  console.log('用户排名数据:', res.result);
} else {
  console.error(`获取用户排名失败: ${res.error}`);
}

示例（回调方式）：

SceSDK.cloud.get_user_rank({
  key: 'player_score'
}, {
  success(result) {
    console.log('用户排名数据:', result);
  },
  fail(error) {
    console.error('获取用户排名失败:', error);
  }
});

完整示例

Promise方式

const initGame = async () => {
  // 初始化 SDK
  SceSDK.init({
    sce_developer_token: 'YOUR_DEVELOPER_TOKEN'
  });
  
  try {
    // 获取用户信息
    const userInfo = SceSDK.get_user_info();
    console.log(`用户ID: ${userInfo.user_id}, 用户名: ${userInfo.name}`);
    
    // 保存游戏数据
    let setDataRes = await SceSDK.cloud.set_data('test', 'test1');
    if (setDataRes.result) {
      console.log(`set_data 成功`);
    } else {
      console.error(`set_data 错误: ${setDataRes.error}`);
    }
    
    // 获取游戏数据
    let getDataRes = await SceSDK.cloud.get_data('test');
    if (getDataRes.result) {
      console.log(`get_data 成功: ${getDataRes.result}`);
    } else {
      console.error(`get_data 错误: ${getDataRes.error}`);
    }
    
    // 保存得分
    const scoreKey = 'player_score';
    const score = 1000;
    
    let setScoreRes = await SceSDK.cloud.set_number(scoreKey, score);
    if (setScoreRes.result) {
      console.log(`set_number 成功`);
    } else {
      console.error(`set_number 错误: ${setScoreRes.error}`);
    }
    
    // 获取得分
    let getScoreRes = await SceSDK.cloud.get_number(scoreKey);
    if (getScoreRes.result) {
      console.log(`get_number 成功: ${getScoreRes.result}`);
    } else {
      console.error(`get_number 错误: ${getScoreRes.error}`);
    }
    
    // 获取排行榜
    let topRankRes = await SceSDK.cloud.get_top_rank({
      key: scoreKey,
      limit: 10,
      without_name: false,
      order_by: 'desc'
    });
    if (topRankRes.result) {
      console.log(`get_top_rank 成功: ${JSON.stringify(topRankRes.result)}`);
    } else {
      console.error(`get_top_rank 错误: ${topRankRes.error}`);
    }
    
    // 获取用户排名
    let userRankRes = await SceSDK.cloud.get_user_rank({key: scoreKey});
    if (userRankRes.result) {
      console.log(`get_user_rank 成功: ${JSON.stringify(userRankRes.result)}`);
    } else {
      console.error(`get_user_rank 错误: ${userRankRes.error}`);
    }
    
  } catch (e) {
    console.error('操作失败:', e);
  }
};

// 启动游戏
initGame();

回调方式

// 初始化 SDK
SceSDK.init({
  sce_developer_token: 'YOUR_DEVELOPER_TOKEN'
});

// 获取用户信息
SceSDK.get_user_info({
  success(userInfo) {
    console.log(`用户ID: ${userInfo.user_id}, 用户名: ${userInfo.name}`);
  },
  fail(error) {
    console.error(`get_user_info 失败: ${error}`);
  }
})

// 保存游戏数据
SceSDK.cloud.set_data('test', { value: 'test_value' }, {
  success(result) {
    console.log(`set_data 成功`);
    
    // 获取游戏数据
    SceSDK.cloud.get_data('test', {
      success(result) {
        console.log(`get_data 成功: ${JSON.stringify(result)}`);
      },
      fail(error) {
        console.error(`get_data 失败: ${error}`);
      }
    });
  },
  fail(error) {
    console.error(`set_data 错误: ${error}`);
  }
});

// 测试数值型数据操作
const scoreKey = 'player_score';
const score = 1000;

SceSDK.cloud.set_number(scoreKey, score, {
  success(result) {
    console.log(`set_number 成功`);
    
    // 获取数值
    SceSDK.cloud.get_number(scoreKey, {
      success(result) {
        console.log(`get_number 成功: ${result}`);
      },
      fail(error) {
        console.error(`get_number 错误: ${error}`);
      }
    });
  },
  fail(error) {
    console.error(`set_number 错误: ${error}`);
  }
});

// 获取排行榜前10名
SceSDK.cloud.get_top_rank({
  key: scoreKey, 
  limit: 10, 
  without_name: false, 
  order_by: 'desc'
}, {
  success(result) {
    console.log(`get_top_rank 成功: ${JSON.stringify(result)}`);
  },
  fail(error) {
    console.error(`get_top_rank 错误: ${error}`);
  }
});

// 获取当前用户排名
SceSDK.cloud.get_user_rank({key: scoreKey}, {
  success(result) {
    console.log(`get_user_rank 成功: ${JSON.stringify(result)}`);
  },
  fail(error) {
    console.error(`get_user_rank 错误: ${error}`);
  }
});

注意事项

SDK支持Promise和回调两种方式调用，可以根据项目需要选择合适的方式
回调方式使用对象形式 {success, fail} 而不是单一函数
错误处理可以通过检查 result 是否存在或 error 是否为null来进行

广告功能

sce.playVideoAd(callback)

播放激励视频广告。用户观看广告后可以获得游戏内奖励。

参数：

| 参数名 | 类型 | 必选 | 说明 | | -------- | -------- | ---- | ---------------------------------- | | callback | function | 是 | 广告播放结果的回调函数 |

回调函数参数： PlayVideoAdResult 对象，包含以下字段：

| 字段名 | 类型 | 说明 | | ---------- | ------- | --------------------------------------------- | | is_end | boolean | 是否播放结束（true: 播放完成, false: 中途退出） | | error_code | number | 错误代码（0表示成功） | | error_msg | string | 错误信息（成功时为空字符串） |

示例：

// 播放激励视频广告
sce.playVideoAd((result) => {
  console.log('广告播放结果:', result);
  
  if (result.error_code === 0) {
    if (result.is_end) {
      // 用户完整观看了广告，给予奖励
      console.log('广告播放完成，给予用户奖励');
      // 在此处添加奖励逻辑
      giveUserReward();
    } else {
      // 用户中途退出广告
      console.log('用户中途退出广告');
    }
  } else {
    // 广告播放失败
    console.error(`广告播放失败: ${result.error_msg}`);
  }
});

function giveUserReward() {
  // 示例：给用户增加金币
  console.log('用户获得 100 金币奖励！');
  // 可以在这里调用云数据存储接口保存用户的奖励
}

注意事项：

只有当 is_end 为 true 时才应该给予用户奖励
建议在给予奖励前检查 error_code 是否为 0
广告播放可能因为网络问题或其他原因失败，请做好错误处理
激励视频广告的可用性由星火平台控制，建议在调用前检查是否有可用广告

界面

sce.showLoading()

显示星火平台的加载页。需主动调用 sce.hideLoading 才能关闭加载页。你可以通过这个接口手动控制展示游戏画面的时机，在你的游戏完全准备好之后展示。

示例：

// 开始加载时显示加载页
sce.showLoading();

setTimeout(function () {
  sce.hideLoading()
}, 3000)

sce.hideLoading()

隐藏星火平台的加载页。

注意事项：

sce.showLoading() 和 sce.hideLoading() 必须成对使用
建议在 DOMContentLoaded 前调用 showLoading()，操作完成后调用 hideLoading()

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

SCE SDK使用指南

简介

安装

前提条件

导入 SDK

CDN直接引入

调用方式

初始化与配置

SceSDK.init_for_dev(options)

主要功能

获取玩家信息

SceSDK.get_user_info()

云数据存储

SceSDK.cloud.set_data(key, value)

SceSDK.cloud.get_data(key)

SceSDK.cloud.set_number(key, value)

SceSDK.cloud.get_number(key)

排行榜功能

SceSDK.cloud.get_top_rank(options)

SceSDK.cloud.get_user_rank(options)

完整示例

Promise方式

回调方式

注意事项

广告功能

sce.playVideoAd(callback)

界面

sce.showLoading()

sce.hideLoading()