> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/xiang-mu-lei-xing/smart-wearables.md).

# 智能可穿戴物

创建具有交互能力的可穿戴物

智能可穿戴设备是一种全局场景。类似 [便携体验](/creator/content-creator-zh/chang-jing-sdk7/xiang-mu-lei-xing/portable-experiences.md)一样，它们是玩家在穿行于元宇宙时随身携带的玩法。例如，在运行全局场景时，玩家可以从 Genesis Plaza 的地面捡起一个雪球，走到另一个场景，然后把雪球扔给另一位也在玩同一个游戏的玩家。

智能可穿戴设备是会在玩家穿上某件服装时激活的便携体验。智能可穿戴设备可以赋予玩家新的能力，比如让他们飞行的喷气背包，或者在整个 Genesis City 中随机放置可收集硬币，作为覆盖在世界其余部分之上的新内容层。

{% hint style="warning" %}
**📔 注**: 智能可穿戴设备只能使用 SDK 7 创建。

该 **创作者中心** 目前不支持创建智能可穿戴设备项目。
{% endhint %}

## 入门

### 使用 CLI

1. 在新文件夹中打开命令行并运行

`npx @dcl/sdk-commands init --project smart-wearable`

此命令会为新的智能可穿戴设备创建基础文件和结构。

## 模板中的文件

全新的智能可穿戴设备项目文件夹与 [Decentraland 场景](/creator/content-creator-zh/chang-jing-sdk7/xiang-mu-lei-xing/scene-files.md)的文件夹非常相似，但你会注意到以下差异：

* `wearable.json` 包含便携体验的全部元数据
* 有一个暗色眼镜的占位 3D 模型（glasses.glb）和缩略图（glasses.png）。你应该将它们替换为你正在创建的实际可穿戴设备
* `scene.json` 要短得多，它不包含与可穿戴设备无关的属性，例如地块或出生点

## 关于 wearable.json

默认的 `wearable.json` 文件看起来如下：

```json
{
	"data": {
		"replaces": [],
		"hides": [],
		"tags": ["特殊","新","眉毛"],
		"representations": [
			{
				"bodyShapes": [
					"urn:decentraland:off-chain:base-avatars:BaseMale",
					"urn:decentraland:off-chain:base-avatars:BaseFemale"
				],
				"mainFile": "glasses.glb",
				"contents": ["glasses.glb"],
				"overrideHides": [],
				"overrideReplaces": []
			}
		],
		"category": "眼镜"
	},
	"name": "智能可穿戴示例",
	"description": "戴上眼镜，看见一个新世界",
	"rarity": "神话级"
}
```

以下字段是必须包含的： `wearable.json`:

* `ID`: 智能可穿戴设备的唯一 ID。
* `名称`: 用户会在市场中看到的可穿戴设备名称
* `描述`: 用户会在市场中看到的可穿戴设备描述。请务必说明该智能可穿戴设备可以做什么，因为在购买之前，市场用户无法预览其功能。
* `稀有度`: 代币的稀有度供应量。可能的值有：
  * 独一无二（1 个副本）
  * 神话级（10 个副本）
  * 异域（50 个副本）
  * 传奇（100 个副本）
  * 史诗（1000 个副本）
  * 非凡（10,000 个副本）
  * 普通（100,000 个副本）

{% hint style="warning" %}
**📔 注**: 如果你是从现有项目分支出来的，并且其中包含一个 `ID`，请确保在发布你的可穿戴设备之前该值是唯一的。使用 [uuidgenerator.net](https://www.uuidgenerator.net/) 来生成一个新的随机 UUID
{% endhint %}

以下字段也可以选择性包含。在你上传智能可穿戴设备后，这些设置也可以在 Builder UI 中配置。

* `数据`: 包含以下
  * `替代`: 除了此类别的默认设置外，穿戴此可穿戴设备时还应卸下的其他可穿戴设备类别列表。例如：穿上上身披风时，也要隐藏脚部。
  * `隐藏`: 除了此类别的默认设置外，穿戴此可穿戴设备时还应隐藏（但不卸下）的其他可穿戴设备类别列表。
  * `标签`: 用于让该可穿戴设备在市场中可搜索的标签。
  * `表示形式`:
    * `体型`: 可使用此可穿戴设备的头像表示形式列表。所有智能可穿戴设备都必须同时适用于男性和女性体型。
    * `主文件`: 可穿戴设备 3D 模型的主文件。
    * `内容`: 用于渲染可穿戴设备 3D 模型的完整文件列表。例如，3D 模型可能会将纹理作为单独文件包含。
    * `覆盖隐藏`: 此可穿戴设备类别默认 *隐藏* 行为的任何例外情况。
    * `覆盖替换`: 此可穿戴设备类别默认 *替换* 行为的任何例外情况。
  * `类别`: 要使用的可穿戴设备类别。可能的值有：
    * '眉毛'
    * '眼睛'
    * '面部毛发'
    * '头发'
    * '嘴巴'
    * '上身'
    * '下身'
    * '脚部'
    * '耳环'
    * '眼镜'
    * '帽子'
    * '头盔'
    * '面具'
    * '皇冠'
    * '头顶'
    * '皮肤'
    * '手部穿戴'
* `菜单栏图标`: 在“experiences”菜单中用于代表此便携体验的图片。此图片应位于文件夹根目录。推荐图片尺寸为 256x256。
* `模型`: 可穿戴设备所使用的 3D 模型。此文件应位于文件夹根目录。
* `体型`: 此可穿戴设备兼容的头像体型。可能的值：
  * 男性
  * 女性
  * 两者
* `合集地址`: 已发布可穿戴设备合集的以太坊地址。该地址会在发布后分配，也可以留空。

## 缩略图

你必须在文件夹根目录中包含一个名为 `thumbnail.png` 的图片。该图片会同时显示在背包和市场中，用二维图像代表你的可穿戴设备。推荐所需图片尺寸为 256x256。

请选择一张能够设定玩家预期并正确代表你作品的图片。

## 预览

运行便携体验的预览就像运行场景预览一样：点击 **播放** 在 Creator Hub 中，或者运行 `npm run start` 在命令行中。如果该 `wearable.json` 文件配置正确，并且项目被识别为智能可穿戴设备，你会注意到你周围可见的一切都是默认的空地块。在此预览模式下，你不受任何指定地块的限制，可以在世界中的任何地方添加 3D 模型或声音。

要测试智能可穿戴设备在场景环境中的表现，你也可以在运行一个或多个场景预览的同时预览你的可穿戴设备，方法是使用一个 [工作区](/creator/content-creator-zh/chang-jing-sdk7/xiang-mu-lei-xing/workspaces.md)。例如，你可以将智能可穿戴设备与 [Genesis Plaza](https://github.com/decentraland-scenes/Genesis-Plaza) 场景一起运行，以测试它在繁忙场景中、在电梯上等情况下的表现。

## 提示

* 在定位实体时，请注意位置是全局的，参照 Genesis Plaza 的 0,0 坐标。
* 要对附近玩家做出反应：
  * 参见 [获取所有玩家](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/user-data.md#fetch-all-players) ，了解如何从周围的其他玩家那里获取数据。
  * 请注意，智能可穿戴设备、周围场景以及其他玩家的加载顺序可能会因情况而异。如果玩家在进入 Decentraland 时已经佩戴该智能可穿戴设备，那么你的可穿戴设备的全局场景很可能会比其他玩家先加载。另一方面，如果玩家先进入某个场景，然后再戴上该可穿戴设备，那么当可穿戴设备的场景开始运行时，其他玩家很可能已经加载完成。
  * 对于多人体验，请等到玩家已连接到其领域中的某个岛屿。获取领域数据并检查“room”字段。如果“room”字段为 null，则玩家尚未连接到岛屿，其他玩家也还不会加载。你可以每 1 秒周期性检查一次，直到“room”字段出现，然后再初始化你的逻辑。
* 要与周围场景交互：
  * 你无法直接向附近场景或其他便携体验发送任何指令， `messageBus` 目前对每个便携体验/场景都是沙箱隔离的。
  * 你可以使用中间服务器在便携体验和场景之间传递信息。
  * 如果你执行射线投射，可以检测与周围场景中实体碰撞体的命中。这可以告诉你精确的命中位置、法线方向，甚至 3D 模型的实体名称和网格名称。此功能仅在命中使用 SDK7 编写的场景中的实体时有效。
* 终止便携体验：运行 `kill()` 方法可使便携体验自行终止。

## 发布

要发布你的智能可穿戴设备：

1. 确保 `wearable.json` 中的信息准确无误。如果你使用了另一个项目作为起点，请确保 `ID` 是一个唯一标识符，没有被其他可穿戴设备使用。
2. 运行 `npm run pack` 在你的项目文件夹中。这会在你的项目文件夹中生成一个 `smart-wearable.zip` 文件。

{% hint style="warning" %}
**📔 注**: `npm run pack` 的输出将显示导出后未压缩项目的大小，必须小于 3MB。如果大于该值，Builder 将不接受。
{% endhint %}

3. 打开 Builder，打开 Collections 标签，点击 + 上传新的可穿戴设备。
4. 将压缩后的 `smart-wearable.zip` 文件拖入 Builder 中，确认所有信息准确无误。

> 注意：如果你的可穿戴设备包含不同的模型表示形式，你需要采用一种变通方法：
>
> 1. 在你的项目中，为每个表示形式创建一个新文件夹（`男性` 和 `女性`），并将每个表示形式的 3D 模型放入对应文件夹。
> 2. 更新你的 `wearable.json` 文件以包含新的表示形式。
> 3. ```lang-json
>    "representations": [{
>      "bodyShapes": ["urn:decentraland:off-chain:base-avatars:BaseMale"],
>      "mainFile": "male/glasses.glb",
>      "contents": ["male/glasses.glb"],
>      "overrideHides": [],
>      "overrideReplaces": []
>    },
>    {
>      "bodyShapes": ["urn:decentraland:off-chain:base-avatars:BaseFemale"],
>      "mainFile": "female/glasses.glb",
>      "contents": ["female/glasses.glb"],
>      "overrideHides": [],
>      "overrideReplaces": []
>    }],
>    ```
> 4. 运行 `npm run pack` 来生成新的 smart-wearable.zip 文件。
> 5. 将新的 smart-wearable.zip 文件拖入 Builder。

5. 打开可穿戴设备编辑器，确保“隐藏”和“移除”类别已正确设置，以便在穿戴此设备时禁用其他可穿戴设备类别。
6. 使用此设备以及可能的其他可穿戴设备创建一个新集合。
7. 点击“Mint Items”旁边的三点图标，选择“See in world”。这将打开一个带有 Sepolia 上浏览器的新标签页，你可以在 Decentraland 中试用你收藏中的所有可穿戴设备，并查看它们在更真实场景中的表现，例如在 Genesis Plaza 周围奔跑。
8. 到此，你的可穿戴设备已准备好发布。

## 受限操作

为防止滥用，某些功能默认不允许在便携体验中使用，需要添加权限标志。

参见 [所需权限](/creator/content-creator-zh/chang-jing-sdk7/xiang-mu-lei-xing/scene-metadata.md#required-permissions) 了解更多详情。

## 限制

> 重要：整个智能可穿戴设备必须控制在 3MB 以内。这包括 3D 模型、缩略图、代码、库、声音文件、额外的 3D 模型、UI 图像等。此限制针对未压缩文件夹。Builder 不会允许你上传更大的可穿戴设备。要检查便携体验的大小，请运行 `npm run pack`，项目大小会在命令的输出文本中标明。你也可以通过解压生成的 `smart-wearable.zip` 文件并检查文件夹大小来验证。

智能可穿戴设备只会为佩戴该设备的玩家运行便携体验。其他玩家看不到这些效果。例如，如果便携体验渲染了一个跟随玩家的宠物，周围其他玩家不会看到这只宠物。然而，其他玩家会看到头像执行作为可穿戴设备场景一部分运行的动画，即使 [自定义头像动画](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/tou-xiang/avatar-animations.md#custom-animations) 已作为智能可穿戴设备文件的一部分上传。

智能可穿戴设备只有在玩家佩戴时才生效。因此，玩家一次只能激活有限数量的智能可穿戴设备，而且根据它们占据的身体部位，有些会彼此不兼容。例如，你不能同时戴两顶帽子，也不能同时戴头盔和头发。

如果某件可穿戴设备被其他已穿戴的设备“隐藏”但未被“移除”，那么即使对应的可穿戴设备不可见，智能可穿戴设备仍然可以保持开启。

## 示例

[智能可穿戴示例](https://github.com/decentraland/smart-wearable-sample))


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/xiang-mu-lei-xing/smart-wearables.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.