创造你的世界
经济
产品 API 使用示例
18min
以下是使用产品API管理世界货币和世界产品的示例。
此示例使您能够基本了解产品API，并实现服务器与客户端之间的消息发送和接收，以便您可以轻松测试授予和扣除世界货币和产品。
此示例包括世界货币和世界产品客户端脚本的描述，随后是处理所有服务器端处理的集成服务器脚本，并包括以下功能：
- 授予世界货币
- 扣除世界货币
- 在不扣除货币的情况下授予世界产品
- 扣除世界产品
以下是管理世界货币授予和扣除的完整客户端代码，以及如何实现它。
CurrencyManagerSample
1import { Button, Text } from 'UnityEngine.UI';
2import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
3import { LocalPlayer, ZepetoPlayers } from 'ZEPETO.Character.Controller';
4import { Room, RoomData } from 'ZEPETO.Multiplay';
5import { ZepetoWorldMultiplay } from 'ZEPETO.World';
6
7export default class CurrencyManagerSample extends ZepetoScriptBehaviour {
8
9 public currencyId: string;
10 public increaseQuantity: number;
11 public decreaseQuantity: number;
12 public increaseCurrencyBtn: Button;
13 public decreaseCurrencyBtn: Button;
14 public balanceText: Text;
15 public multiplay: ZepetoWorldMultiplay;
16
17 private _localPlayer: LocalPlayer;
18
19 Start() {
20
21 ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
22 this._localPlayer = ZepetoPlayers.instance.LocalPlayer;
23 this.loadCurrencyBalance(this.currencyId);
24 });
25
26 // 处理房间加入事件以更新货币 UI
27 this.multiplay.RoomJoined += (room: Room) => {
28 room.AddMessageHandler("SyncCurrencyInfo", (message: CurrencyMessage) => {
29 const currentCurrencyId = message.currencyId;
30 const currentQuantity = message.quantity;
31 this.balanceUIUpdate(currentCurrencyId, currentQuantity);
32 });
33 };
34
35 // 增加货币的按钮事件监听器：请求信用
36 this.increaseCurrencyBtn.onClick.AddListener(() => {
37 const data = new RoomData();
38 data.Add("currencyId", this.currencyId);
39 data.Add("quantity", this.increaseQuantity);
40 this.multiplay.Room?.Send("CreditCurrency", data.GetObject());
41 })
42
43 // 减少货币的按钮事件监听器：请求借记
44 this.decreaseCurrencyBtn.onClick.AddListener(() => {
45 const data = new RoomData();
46 data.Add("currencyId", this.currencyId);
47 data.Add("quantity", this.decreaseQuantity);
48 this.multiplay.Room?.Send("DebitCurrency", data.GetObject());
49 })
50
51 }
52
53 // 请求指定货币的当前数量
54 private loadCurrencyBalance(currentCurrencyId: string) {
55 this.multiplay.Room?.Send("LoadBalance", currentCurrencyId);
56 }
57
58 // 更新 UI 以反映当前货币的数量
59 private balanceUIUpdate(currentCurrencyId: string, currentQuantity: number) {
60 this.balanceText.text = currentQuantity.toString();
61 }
62
63}
64
65// 货币同步消息的接口
66interface CurrencyMessage {
67 currencyId: string,
68 quantity: number,
69}
- 当角色加载时，会向服务器发送房间消息以加载现有的货币余额。然后根据从服务器接收到的余额信息更新 UI。
TypeScript
1this.multiplay.Room?.Send("LoadBalance", currentCurrencyId);
- 为了促进消息交换，CurrencyMessage 接口被定义。
TypeScript
1interface CurrencyMessage {
2 currencyId: string,
3 quantity: number,
4}
- 当用户增加或减少他们的货币时，他们会作为房间消息向服务器发送请求。 它包括有关要增加或减少哪种货币以及增加或减少多少的数据。
TypeScript
1this.multiplay.Room?.Send("CreditCurrency", data.GetObject());
2this.multiplay.Room?.Send("DebitCurrency", data.GetObject());
- 服务器然后处理货币的增加或减少，并将最终余额信息发送给客户端。客户端接收此信息并更新用户界面。
TypeScript
1this.multiplay.RoomJoined += (room: Room) => {
2 room.AddMessageHandler("SyncCurrencyInfo", (message: CurrencyMessage) => {
3 const currentCurrencyId = message.currencyId;
4 const currentQuantity = message.quantity;
5 this.updateBalanceUI(currentCurrencyId, currentQuantity);
6 });
7};
以下是管理世界产品授予和扣除的完整客户端代码，以及如何实现它。
ProductManagerSample
1import { Button, Text } from 'UnityEngine.UI';
2import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
3import { LocalPlayer, ZepetoPlayers } from 'ZEPETO.Character.Controller';
4import { Room, RoomData } from 'ZEPETO.Multiplay';
5import { ZepetoWorldMultiplay } from 'ZEPETO.World';
6import { InventoryRecord, InventoryService } from 'ZEPETO.Inventory';
7import { WaitUntil } from 'UnityEngine';
8
9export default class ProductManagerSample extends ZepetoScriptBehaviour {
10
11 public productId: string;
12 public productAddQuantity: number;
13 public acquireItemBtn: Button;
14 public useItemBtn: Button;
15 public itemCountText: Text;
16 public multiplay: ZepetoWorldMultiplay;
17
18 private _localPlayer: LocalPlayer;
19
20 Start() {
21
22 ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
23 this._localPlayer = ZepetoPlayers.instance.LocalPlayer;
24 this.StartCoroutine(this.refreshProductUI());
25 });
26
27 // 处理房间加入事件以更新产品 UI
28 this.multiplay.RoomJoined += (room: Room) => {
29 room.AddMessageHandler("SyncProductInfo", (message: ProductMessage) => {
30 this.StartCoroutine(this.refreshProductUI());
31 });
32 };
33
34 // 获取物品的按钮事件监听器：添加产品
35 this.acquireItemBtn.onClick.AddListener(() => {
36 const data = new RoomData();
37 data.Add("productId", this.productId);
38 data.Add("quantity", this.productAddQuantity);
39 this.multiplay.Room?.Send("AddProduct", data.GetObject());
40 })
41
42 // 使用物品的按钮事件监听器：使用产品
43 this.useItemBtn.onClick.AddListener(() => {
44 const data = new RoomData();
45 data.Add("productId", this.productId);
46 data.Add("quantity", 1);
47 this.multiplay.Room?.Send("UseProduct", data.GetObject());
48 })
49
50 }
51
52 private * refreshProductUI() {
53 const request = InventoryService.GetAsync(this.productId);
54 yield new WaitUntil(() => request.keepWaiting == false);
55 // 如果请求成功，更新产品 UI
56 if (request.responseData.isSuccess) {
57 this.updateItemCountText(request.responseData.product);
58 }
59 else {
60 console.log("加载产品物品失败。");
61 }
62 }
63
64 private updateItemCountText(item: InventoryRecord) {
65 if (item != null) {
66 this.itemCountText.text = item.quantity.toString();
67 }
68 else {
69 this.itemCountText.text = "0";
70 }
71 }
72
73}
74
75// 产品消息的接口。
76interface ProductMessage {
77 productId: string,
78 productAction: ProductAction,
79}
80
81// 定义产品操作类型的枚举。
82export enum ProductAction {
83 Use,
84 Add,
85}
TypeScript
1private * refreshProductUI() {
2 const request = InventoryService.GetAsync(this.productId);
3 yield new WaitUntil(() => request.keepWaiting == false);
4 if (request.responseData.isSuccess) {
5 this.updateItemCountText(request.responseData.product);
6 }
7 else {
8 console.log("加载产品项失败。");
9 }
10 }
- 要发送和接收消息，定义 ProductMessage 接口。定义一个 ProductAction 枚举以供示例实现。
TypeScript
1interface ProductMessage {
2 productId: string,
3 productAction: ProductAction,
4}
5
6export enum ProductAction {
7 使用,
8 添加,
9}
- 当您增加或减少产品时，您将该数据作为房间消息发送到服务器。 它包括有关要增加或减少哪个产品以及增加或减少多少的数据。
TypeScript
1this.multiplay.Room?.Send("AddProduct", data.GetObject());
2this.multiplay.Room?.Send("UseProduct", data.GetObject());
- 处理产品变更后，服务器将最终库存信息发送给客户端，客户端相应地更新UI。
TypeScript
1this.multiplay.RoomJoined += (room: Room) => {
2 room.AddMessageHandler("SyncProductInfo", (message: ProductMessage) => {
3 this.StartCoroutine(this.refreshProductUI());
4 });
5};
- 通常，世界产品需要花费货币进行购买。
以下是管理世界货币和产品的完整服务器代码，以及如何实现它。
TypeScript
1import { Sandbox, SandboxOptions, SandboxPlayer } from "ZEPETO.Multiplay";
2import { loadCurrency } from "ZEPETO.Multiplay.Currency";
3import { loadInventory } from "ZEPETO.Multiplay.Inventory";
4
5export default class extends Sandbox {
6
7 async onCreate(options: SandboxOptions) {
8
9 // 货币
10 //请求加载货币
11 this.onMessage("LoadBalance", (client, message: string) => {
12 this.loadBalance(client, message);
13 });
14 //请求添加信用
15 this.onMessage("CreditCurrency", (client, message: CurrencyMessage ) => {
16 const currencyId = message.currencyId;
17 const quantity = message.quantity;
18 this.addCredit(client, currencyId, quantity);
19 });
20 //请求扣除信用
21 this.onMessage("DebitCurrency", (client, message: CurrencyMessage ) => {
22 const currencyId = message.currencyId;
23 const quantity = message.quantity;
24 this.onDebit(client, currencyId, quantity);
25 });
26
27 // 产品
28 //请求添加物品
29 this.onMessage("AddProduct", (client, message: any) => {
30 const productId = message.productId;
31 const quantity = message.quantity;
32 this.addProduct(client, productId, quantity);
33 });
34 //请求使用物品
35 this.onMessage("UseProduct", (client, message: any) => {
36 const productId = message.productId;
37 const quantity = message.quantity;
38 this.useProduct(client, productId, quantity);
39 });
40
41 }
42
43 async addCredit(client: SandboxPlayer, currencyId: string, quantity: number) {
44 try {
45 const currency = await loadCurrency(client.userId);
46 await currency.credit(currencyId, quantity);
47 this.loadBalance(client, currencyId);
48 } catch (e) {
49 console.error(`AddCredit 错误: ${e}`);
50 }
51 }
52
53 async onDebit(client: SandboxPlayer, currencyId: string, quantity: number) {
54 try {
55 const currency = await loadCurrency(client.userId);
56 if (await currency.debit(currencyId, quantity) === true) {
57 this.loadBalance(client, currencyId);
58 } else {
59 console.error("DebitCredit 错误: 货币不足");
60 }
61 } catch (e) {
62 console.error(`DebitCredit 错误: ${e}`);
63 }
64 }
65
66 async loadBalance(client: SandboxPlayer, currencyId: string) {
67 try {
68 const currency = await loadCurrency(client.userId);
69 let balancesObject = await currency.getBalances();
70 let balancesMap: Map<string, number> = new Map(Object.entries(balancesObject));
71 const specificCurrencyID = currencyId;
72 const specificBalance = balancesMap.get(specificCurrencyID) ?? 0;
73 const currencySync: CurrencyMessage = {
74 currencyId: specificCurrencyID,
75 quantity: specificBalance
76 }
77 client.send("SyncCurrencyInfo", currencySync);
78 } catch (e) {
79 console.error(`loadBalance 错误: ${e}`);
80 }
81 }
82
83 async addProduct(client: SandboxPlayer, productId: string, quantity: number) {
84 try {
85 const inventory = await loadInventory(client.userId);
86 await inventory.add(productId, quantity);
87 const productMessage: ProductMessage = {
88 productId: productId,
89 productAction: ProductAction.Add
90 }
91 client.send("SyncProductInfo", productMessage);
92 } catch (e) {
93 console.error(`addProduct 错误: ${e}`);
94 }
95 }
96
97 async useProduct(client: SandboxPlayer, productId: string, quantity: number) {
98 try {
99 const inventory = await loadInventory(client.userId);
100 await inventory.use(productId, quantity);
101 const productMessage: ProductMessage = {
102 productId: productId,
103 productAction: ProductAction.Use
104 }
105 client.send("SyncProductInfo", productMessage);
106 } catch (e) {
107 console.error(`useProduct 错误: ${e}`);
108 }
109 }
110
111 onJoin(client: SandboxPlayer) {
112 // 加入逻辑在这里
113 }
114
115 onTick(deltaTime: number): void {
116 // Tick 逻辑在这里
117 }
118
119 onLeave(client: SandboxPlayer, consented?: boolean) {
120 // 处理离开逻辑在这里
121 }
122
123}
124
125// 货币消息接口
126interface CurrencyMessage {
127 currencyId: string,
128 quantity: number,
129}
130
131// 产品消息接口。
132interface ProductMessage {
133 productId: string,
134 productAction: ProductAction,
135}
136
137// 定义产品操作类型的枚举。
138export enum ProductAction {
139 Use,
140 Add,
141}
- 使用 currency.credit() 和 currency.debit() 来增加或减少所需货币的余额。之后，调用 currency.getBalances() 来获取每种货币的当前余额。
TypeScript
1currency.credit(currencyId, quantity);
2currency.debit(currencyId, quantity);
3currency.getBalances();
- 使用 inventory.add() 和 inventory.use() 来增加或减少所需货币的余额。
TypeScript
1inventory.add(productId, quantity);
2inventory.use(productId, quantity);
- 处理来自客户的增加或减少货币和产品的请求。
- 使用loadBalance()来获取在ZEPETO Studio中注册的货币信息。
- 如果有多种货币，您可以根据特定的货币ID值进行条件筛选，以仅获取该货币的余额。
- 将最终余额值作为房间消息传递给客户端。
