🚀 Socket Launch Week Day 5:Introducing Repository Access Permissions and Custom Roles.Learn more →

sce-game-sdk

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

sce-game-sdk

Web browser mini game SDK with TypeScript

latest

npm

Version: 1.2.0

Version published: 11 months ago

Weekly downloads: 23

Maintainers: 1

Weekly downloads

Created: last year

Source

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()

FAQs

What is sce-game-sdk?

Is sce-game-sdk popular?

Is sce-game-sdk well maintained?

Package last updated on 06 Aug 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

sce-game-sdk

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()

Related posts

Socket MCP Adds Org Alerts, Threat Feed Review, and Package Inspection

Socket Firewall Now Blocks Malicious VS Code and Open VSX Extensions