简介
获取本游戏项目的所有金魔方商品组成的列表，您可以通过列表读取需要展示的金魔方商品的所有信息，是在客户端或服务器上调用、查看金魔方商品的前提。
获取商品列表的意义
- 可在游戏项目运行时实时获取金魔方商品信息。
- 由于每个金魔方商品在不同的服务器上都会有不同的 商品 ID（Product ID），您需要遍历金魔方商品列表，并根据金魔方商品既定的 别名（Aliases）找到该商品的 商品 ID（Product ID），进而控制在玩家面前显示该商品。
- 在服务器核验该交易时，服务器只能获取当前交易中附带服务器信息的 商品 ID（Product ID），您需要遍历金魔方商品列表，并根据该商品的 商品 ID（Product ID）找到金魔方商品既定的 别名（Aliases），确定玩家所购买的金魔方商品，至此您可根据交易结果在服务器上给该玩家分发奖励。
商品列表获取方法
获取商品列表时需要注意以下前提：
- SandMod 编辑器上无法获取金魔方商品列表，需要将游戏项目发布（发布测试或上线）才能读取。具体发布方法请参阅 游戏发布 章节。
- 游戏项目只有在支持 网络服务（Net Service），能连上 服务器场景（Server Scene）时才能获取到商品列表。具体连接方法请参阅 服务器 章节。
您可以在服务器或者客户端获取商品列表，两端获取的方法有所不一样。您也可以在服务器中获取金魔方商品列表后发送给各个客户端。
服务器获取商品列表
您可以在服务器场景中所引用的脚本使用 NetServer.on_get_goodslist 在服务器中获取金魔方商品列表。代码示例如下：
class GetGCPLOnServer extends Component {
/*
编辑运行时事件;
*/
OnStart(): void {
/*
在服务器中获取金魔方商品列表，列表将会由 JSON 格式转换为文本（String）后返回；
* 返回的函数中，参数 goodsjson 将会是 JSON 格式商品列表转换的文本；
*/
NetServer.on_get_goodslist = (goodsjson: string) => {
//您可以在此编辑针对文本格式的金魔方商品列表的逻辑,包括将其转回 JSON 格式；
}
}
OnUpdate(): void {
}
}客户端获取商品列表
您可以在客户端场景中所引用的脚本通过 SDKs.Invoke("BLOCKMAN::GOODS::GETGOODSLIST") 调动 SDK 获取金魔方商品列表，值得注意的是，即使在客户端就能获取金魔方商品列表，该游戏项目依然需要能连上服务器才能成功获取金魔方商品列表。
其中调动 "BLOCKMAN::GOODS::GETGOODSLIST" SDK 的代码格式如下：
SDKs.Invoke("BLOCKMAN::GOODS::GETGOODSLIST").then((res:SDKResult)=>{
if(res.success){
//参数 res.message 将会是 JSON 格式商品列表转换的文本；
};
});- "BLOCKMAN::GOODS::GETGOODSLIST" 是 SDK 中获取金魔方商品列表的指令。
- res 是通过 SDK 获取金魔方商品的回调，其包含 success 和 message 两个参数。
- res.success 是 布尔值（Boolean）类型，用于判断回调是否成功。
- res.message 是 文本（string）类型，在获取金魔方商品列表的过程中，该值为 JSON 格式商品列表转换的文本。
在客户端获取商品列表的代码示例如下：
class GetGCPLOnClient extends Component {
/*
编辑运行时事件;
*/
OnStart(): void {
//连接服务器;
NetClient.Connect();
/*
客户端连上服务器后的回调函数，确保访问 SDK 时该客户端已成功连网；
*/
NetClient.InjectOnConnectEvent((isConnected:boolean) => {
//判断是否成功连接成功；
if (isConnected) {
/*
通过 SDK 发送获取金魔方商品列表的请求；
*/
SDKs.Invoke(
"BLOCKMAN::GOODS::GETGOODSLIST"
).then((res:SDKResult)=>{
//判断是否成功访问 SDK 并获得回调；
if(res.success){
//参数 res.message 将会是 JSON 格式商品列表转换的文本；
//您可以在此编辑针对文本格式的金魔方商品列表的逻辑，包括将其转回 JSON 格式；
};
});
};
});
}
OnUpdate(): void {
}
}商品列表格式
SandMod 会以 JSON 的形式储存当前游戏项目的所有金魔方商品信息，并把金魔方商品的列表储存在命名为 "data" 的索引中。
假设该游戏项目包含以下金魔方商品，以及金魔方商品的信息如下：
【GCube_Product_List001.png】
则用于储存该游戏项目的金魔方商品 JSON 内容如下：
{
"code":1,
"message":"OK",
"data": [
{
"detail":{
"en-US":{
"desc":"It is item A",
"name":"Item A",
"icon_url":"https://staticgs.sandboxol.com/.../AE"
},
"zh-CN":{
"desc":"这是商品 A",
"name":"商品 A",
"icon_url":"https://staticgs.sandboxol.com/.../AC"
}
},
"status": 0,
"deleted":false,
"modified": 1713235692,
"goods_id": 1000000283,
"game_id":null,
"goods_price": 1,
"goods_mapping_id": "a"
},
{
"detail":{
"en-US":{
"desc":"It is item B",
"name":"Item B",
"icon_url":"https://staticgs.sandboxol.com/.../BE"
},
"zh-CN":{
"desc":"这是商品 B",
"name":"商品 B",
"icon_url":"https://staticgs.sandboxol.com/.../BC"
}
},
"status": 0,
"deleted":false,
"modified": 1712887322,
"goods_id": 1000000284,
"game_id":null,
"goods_price": 3,
"goods_mapping_id": "b"
}
],
"other":null
}储存金魔方商品列表的 JSON 中主要有以下常用索引：
- "code" 索引代表状态码，代表了后端响应给前端的业务状态。
- "message" 索引代表了响应信息，如果发生异常，或者系统错误，会将错误信息存储在此索引的值中。
- "data" 索引代表了金魔方商品的信息列表，可通过自然数索引获取每个金魔方商品的详细信息，第一个金魔方商品的索引为 0。其中每个金魔方商品包含以下信息：
3.1. "detail" 索引代表了当前金魔方商品的多语言信息，包含金魔方商品在各种语言环境下的描述、名称和图标地址。
3.1.1. "en-US" / "zh-CN" 等代表了当前语言的索引，命名符合语言缩写统一规范。值得注意的是，只有在 金魔方商品管理列表（Product Management）网页上设置了该金魔方商品对应语言的描述，金魔方商品列表中才会有该语言的索引。
3.1.1.1. "desc" 索引代表了对应语言环境下的商品描述，与创建商品时在 描述（Describe）属性中填写的内容一致。
3.1.1.2. "name" 索引代表了对应语言环境下的商品名称，与创建商品时在 名称（Name）属性中填写的内容一致。
3.1.1.3. "icon_url" 索引代表了对应语言环境下的商品图标地址。
3.2. "goods_id" 索引代表了该金魔方商品在当前游戏项目运行的服务器的唯一 商品 ID（Product ID），该商品 ID 由系统自动生成，且不同服务器运行该游戏项目此商品 ID 会有差异，因此商品 ID 仅用于调用该金魔方商品时的凭证，而不会直接作为查找金魔方商品的凭证。
3.3. "good_price" 索引代表了该金魔方商品的售价，以金魔方数为售价单位。
3.4 "goods_mapping_id" 代表了商品别名，与创建商品时在 别名（Aliases）属性中填写的内容一致，创建后可在 金魔方商品管理列表（Product Management）网页上点击对应的 别名（Aliases）旁边的 复制（
）按钮复制至剪贴板中。商品别名是用于查找金魔方商品的凭证，但是如果需要调用此金魔方商品，需要通过金魔方商品的别名找到该商品在当前服务器的唯一 商品 ID（Product ID，"goods_id" 索引的值）再调用。
4. "other" 索引用于储存数据传递过程中需要补充的内容，一般都为空。
商品列表读取方法
为了提升数据传递的效率，在客户端和服务器获取金魔方商品列表的时候一般只会获取到存储商品列表 JSON 转换的 文本（String），获取该文本以后需要使用 JSON.parse(res:string) 将其转换为 JSON 类型。
获取到 JSON 类型的金魔方商品列表后，只需要根据索引找到对应的信息，根据索引获取信息的方法类似 Map 对象或数组（Array）。
假设已知该游戏项目金魔方商品的 别名（Aliases）为 "A"，如果需要获取其在 英语环境（en-US）下的 商品名称（Name），并保存于命名为 AEnName 的公共代变量中，代码示例如下：
class GetAEnName extends Component {
//定义公共变量保存别名为 A 的金魔方商品的名称；
public AEnName:string;
/*
编辑运行时事件;
*/
OnStart(): void {
/*
在服务器中获取金魔方商品列表，列表将会由 JSON 格式转换为文本（String）后返回；
* 返回的函数中，参数 goodsjson 将会是 JSON 格式商品列表转换的文本；
*/
NetServer.on_get_goodslist = (goodsjson: string) => {
//将商品列表转换回 JSON 格式，并保存在命名为 GoodsListJson 的变量中；
let GoodsListJson:JSON = JSON.parse(goodsjson);
//在 JSON 中获取金魔方商品的信息列表，并保存在命名为 data 的变量中；
let data = GoodsListJson["data"];
//遍历商品列表;
for (let i = 0; i < data.length; i++) {
//找到别名为 A 的商品;
if (data[i]["goods_mapping_id"] == "A") {
//将该商品的名称保存在命名为 AEnName 的变量中；
this.AEnName = data[i]["detail"]["en-US"]["name"];
};
};
};
}
OnUpdate(): void {
}
}