CREATE YOUR WORLD
Economy
Product API 활용 예제
18min
다음은 Product 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}
- 사용자가 통화를 증가시키거나 감소시킬 때, 그들은 서버에 Room 메시지로 요청을 보냅니다. 어떤 통화를 얼마나 증가시키거나 감소시킬지를 포함한 데이터가 포함됩니다.
TypeScript
1this.multiplay.Room?.Send("CreditCurrency", data.GetObject());
2this.multiplay.Room?.Send("DebitCurrency", data.GetObject());
- 서버는 통화의 증가 또는 감소를 처리한 후, 최종 잔액 정보를 클라이언트에 보냅니다. 클라이언트는 이 정보를 수신하고 UI를 업데이트합니다.
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 Error: ${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 Error: 통화 부족");
60 }
61 } catch (e) {
62 console.error(`DebitCredit Error: ${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 Error: ${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 Error: ${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 Error: ${e}`);
108 }
109 }
110
111 onJoin(client: SandboxPlayer) {
112 // 입장 시 로직
113 }
114
115 onTick(deltaTime: number): void {
116 // 틱 로직
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 값에 조건을 걸어 해당 통화의 잔액만 가져올 수 있습니다.
- 최종 잔액 값을 클라이언트에게 방 메시지로 전달합니다.
업데이트됨 11 Oct 2024
이 페이지가 도움이 되었습니까?