更换本地玩家服装
您可以将本地玩家的服装更改为您拥有的服装。
必须安装 ZEPETO.Character.Controller 1.11.3 或更高版本。
使用 SetCostume API
方法
API | 描述 |
|---|---|
SetCostume($itemCode: string, $complete?: System.Action):void; | 将物品代码(物品 ID)作为参数值输入以更改本地玩家的服装。服装更改完成后接收回调。 |
本地玩家服装更改示例
您可以使用 SetCostume() 更改本地玩家的服装。
这是一个示例代码,当场景开始时创建一个本地玩家,并在本地玩家创建时使用特定的物品代码更改服装。
1) 添加 ZEPETO > Typescript 并命名脚本为 ChangeLocalPlayerCostume。
编写如下示例脚本。
import { SpawnInfo, ZepetoPlayers } from 'ZEPETO.Character.Controller';
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { WorldService } from 'ZEPETO.World';
export default class ChangeLocalPlayerCostume extends ZepetoScriptBehaviour {
public itemCode: string;
// 当场景开始时,使用提供的用户 ID 创建一个玩家并更改他们的服装。
Start() {
// 使用指定的用户 ID 创建一个新玩家。
ZepetoPlayers.instance.CreatePlayerWithUserId(WorldService.userId, new SpawnInfo(), true);
// 添加一个监听器到 OnAddedLocalPlayer 事件,当本地玩家被添加时触发。
ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
// 使用提供的物品代码调用 ChangeCostume 方法以更改服装。
this.ChangeCostume(this.itemCode);
});
}
// 使用提供的物品代码更改本地玩家的服装的方法。
ChangeCostume(itemCode: string) {
// 使用 LocalPlayer 属性访问本地玩家实例,并使用提供的物品代码设置他们的服装。
ZepetoPlayers.instance.LocalPlayer.SetCostume(itemCode, () => {
// 一旦服装更改完成,记录一条消息以指示成功更改。
console.log(`服装设置完成 : ${itemCode}`);
});
}
}脚本描述
- 此脚本根据给定的物品代码更改本地玩家的服装。
- 当场景开始时,创建一个具有指定用户 ID 的玩家,并使用 CreatePlayerWithUserId() 函数。
- 添加了一个 OnAddedLocalPlayer 事件监听器,以便在添加本地玩家时触发该事件,并调用 ChangeCostume() 方法来更改服装。
- 通过 LocalPlayer 属性访问本地玩家实例,并使用提供的物品代码更改服装。一旦服装更改完成,将记录一条 设置服装完成 的消息,表示更改成功。
📘 请参考模特指南以了解如何检查物品 ID。[ZEPETO 模型]
2) 如果你按下 [▶︎(播放)] 按钮运行它,你可以看到本地玩家被创建并根据输入的物品代码更改服装。

更换服装前(左),更换服装后(右)
- 如果物品是定期产品,将在检查是否过期后穿戴。对于已过期的物品,将调用一个错误日志,称为过期物品。
- 如果物品是 Zem 付费产品,将在检查是否被本地玩家拥有后穿戴。对于未拥有的物品,将调用一个错误日志,称为没有 ItemCode。
加载物品列表并更换服装的示例。
你可以通过利用 GetMyItemListAsync(), 来检索服装物品的列表,该方法提供有关用户拥有的物品的信息。
以下示例演示如何在屏幕上显示本地玩家拥有的服装,并使他们能够选择和更换服装。
步骤 1. 创建服装列表 UI
首先,创建一个 UI 列表资源,其中将显示服装列表的缩略图和名称。需要制作的资源包括:
步骤 1-1. 创建物品预制件
在加载本地玩家拥有的服装列表后,我们在 UI 中创建物品列表。物品预制件作为每个正在创建的物品列表的来源。
当物品预制件被创建时,缩略图和物品名称会显示在用户界面中。
物品预制件包含以下元素。
- Button_thumbnail 对象:这是一个注册了原始图像组件和按钮组件的对象,用于显示物品的缩略图。
- Text_name 对象:一个文本组件对象,其中将显示物品名称。

步骤 1-2. 设置画布
画布是创建物品预制件时显示的用户界面屏幕。建议在此画布内创建一个滚动视图,以便可以检索大量物品列表。
画布内的滚动视图对象设置如下。
- 滚动视图对象设置为仅允许垂直滚动。
- 内容对象设置以下组件:
- 网格布局组:
- 单元格大小:x: 150, Y: 150
- 约束:固定列数
- 约束数量:5

步骤 2. 脚本加载物品列表并更换服装
步骤 2-1. 编写脚本
- 添加 ZEPETO > Typescript 并将脚本重命名为 MyItemList。
- 编写如下示例脚本。
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { ShopService, ItemKeyword } from 'ZEPETO.Module.Shop';
import { ZepetoPropertyFlag } from 'Zepeto';
import { GameObject, Object, RectTransform, Texture2D, Transform, WaitUntil } from 'UnityEngine';
import { Button, LayoutRebuilder, RawImage, Text } from 'UnityEngine.UI';
import { SpawnInfo, ZepetoPlayers } from 'ZEPETO.Character.Controller';
import { WorldService } from 'ZEPETO.World';
import { Item } from 'ZEPETO.Module.Content';
export default class CheckMyItemList extends ZepetoScriptBehaviour {
public itemPrefab: GameObject;
public itemCanvas: Transform;
// 当场景开始时,使用提供的用户 ID 创建一个玩家,并开始获取和显示物品。
Start() {
// 使用指定的用户 ID 创建一个新玩家。
ZepetoPlayers.instance.CreatePlayerWithUserId(WorldService.userId, new SpawnInfo(), true);
// 添加一个监听器到 OnAddedLocalPlayer 事件,当本地玩家被添加时触发。
ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {
// 启动 CoGetMyItem 协程以获取和显示物品。
this.StartCoroutine(this.CoGetMyItem());
});
}
// 协程以获取和显示物品。
*CoGetMyItem() {
// 请求带有 "all" 关键字且没有过滤器的物品列表。
var requestItemList = ShopService.GetMyContentItemListAsync(ItemKeyword.all, null);
// 等待请求完成。
yield new WaitUntil(() => requestItemList.keepWaiting == false);
if (requestItemList.responseData.isSuccess) {
let contentItems: Item[] = requestItemList.responseData.items;
console.log(contentItems.length);
for (let i = 0; i < contentItems.length; ++i) {
const property: ZepetoPropertyFlag = contentItems[i].property;
// 请求物品的缩略图纹理。
var textureReq = contentItems[i].GetThumbnailAsync();
yield new WaitUntil(() => textureReq.keepWaiting == false);
let thumbnailTexture: Texture2D = textureReq.responseData.texture;
// 实例化一个物品预制件并设置其属性。
const item = Object.Instantiate(this.itemPrefab, this.itemCanvas) as GameObject;
item.GetComponentInChildren<RawImage>().texture = thumbnailTexture;
item.GetComponentInChildren<Text>().text = contentItems[i].id;
// 为物品按钮添加点击监听器,以便在点击时更改服装。
item.GetComponentInChildren<Button>().onClick.AddListener(() => {
this.SetItemButton(contentItems[i].id);
});
}
}
// 强制布局重建以确保 UI 元素的正确定位。
const rect = this.itemCanvas.gameObject.GetComponent<RectTransform>();
LayoutRebuilder.ForceRebuildLayoutImmediate(rect);
}
// 根据提供的物品代码更改本地玩家的服装的方法。
SetItemButton(itemCode: string) {
// 使用 ZepetoPlayers.instance.LocalPlayer 属性访问本地玩家实例并更改他们的服装。
ZepetoPlayers.instance.LocalPlayer.SetCostume(itemCode, () => {
// 一旦服装更改完成,记录一条消息以指示成功更改。
console.log(`设置服装完成 : ${itemCode}`);
});
}
}脚本描述
- 在 Start 方法中,使用 ZepetoPlayers.instance.CreatePlayerWithUserId() 创建一个新玩家,CoGetMyItem() 协程在本地玩家被添加时执行。
- 该 CoGetMyItem() 协程使用 ShopService.GetMyContentItemListAsync() 来检索玩家拥有的物品列表。
- 通过 ItemKeyword.all 请求所有类别中的所有物品列表。使用 yield new WaitUntil(() => requestItemList.keepWaiting == false) 等待请求完成。
- 如果请求成功,requestItemList.responseData.isSuccess,遍历 contentItems 的列表,并使用 GetThumbnailAsync() 获取每个物品的缩略图。
- 为每个物品创建一个 UI 元素,使用提供的 itemPrefab,并设置缩略图和 ID。为每个物品创建一个按钮,并设置为调用 SetItemButton(),将物品的 ID 作为参数传递。
- 当与物品关联的按钮被点击时,调用 SetItemButton() 方法。
- 使用 ZepetoPlayers.instance.LocalPlayer.SetCostume() 将所选物品应用为玩家的角色服装。
- 当服装成功更改时,显示一条日志消息,内容为 设置服装完成,并显示物品代码。
📘 提示
- 在搜索用户拥有的物品时,您可以使用 ItemKeyword 按类别搜索,并在 UI 上以列表形式显示它们。
❗️ 注意 通过 ShopService.GetMyContentItemListAsync() 获取的衣物列表包含过期的限时产品。因此 过期项目 错误日志可以被调用。
步骤 2-2. 设置 MyItemList 检查器
在应用 MyItemList 的组件中注册在步骤 1 中创建的 itemPrefab,并在 itemCanvas 中注册 Canvas。

步骤 3. 运行
如果您按下播放按钮运行它,画布用户界面将显示本地玩家拥有的物品列表,您可以看到当选择时物品会更改为相应的服装。

❗️ 注意
- 此服装穿戴 API 仅适用于本地玩家,目前不支持多人同步。
- 未来将提供服装多人同步功能。