> 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": ["special", "new", "eyebrows"],
		"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": "eyewear"
	},
	"name": "智能穿戴物示例",
	"description": "戴上眼镜，看见一个新世界",
	"rarity": "mythic"
}
```

以下字段是必需的： `wearable.json`:

* `id`：智能穿戴物的唯一 ID。
* `名称`：用户会在市场中看到的穿戴物名称
* `描述`：用户会在市场中看到的穿戴物描述。请务必说明该智能穿戴物能做什么，因为市场用户在购买前无法预览其功能。
* `稀有度`：代币的稀有度供应量。可能的值有：
  * unique（1 份）
  * mythic（10 份）
  * exotic（50 份）
  * legendary（100 份）
  * epic（1000 份）
  * uncommon（10,000 份）
  * common（100,000 份）

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

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

* `数据`：包含以下
  * `替换`：当佩戴此穿戴物时，除了该类别的默认设置外，还应卸下的其他穿戴物类别列表。例如：穿上披风类上身穿戴物时，也会隐藏脚部。
  * `隐藏`：当佩戴此穿戴物时，除了该类别的默认设置外，还应隐藏（但不卸下）的其他穿戴物类别列表。
  * `标签`：用于让该穿戴物在市场中可被搜索的标签。
  * `表现形式`:
    * `体型`：可使用此穿戴物的头像表现形式列表。所有智能穿戴物都必须同时适用于男性和女性体型。
    * `主文件`：用于该穿戴物的 3D 模型主文件。
    * `内容`：用于渲染该穿戴物 3D 模型的完整文件列表。例如，3D 模型可能包含作为单独文件的纹理。
    * `覆盖隐藏`：该穿戴物类别默认 *hide* 行为的任何例外。
    * `覆盖替换`：该穿戴物类别默认 *替换* 行为的任何例外。
  * `类别`：要使用的穿戴物类别。可能的值有：
    * “eyebrows”
    * “eyes”
    * “facial\_hair”
    * “hair”
    * “mouth”
    * “upper\_body”
    * “lower\_body”
    * “feet”
    * “earring”
    * “eyewear”
    * “hat”
    * “helmet”
    * “mask”
    * “tiara”
    * “top\_head”
    * “skin”
    * “hands\_wear”
* `菜单栏图标`：用于“体验”菜单中的图片，用来代表这个可携式体验。该图片应位于你文件夹的根目录。建议的图片尺寸为 256x256。
* `模型`：用于穿戴物的 3D 模型。该文件应位于你文件夹的根目录。
* `bodyShape`：此穿戴物兼容的头像身体类型。可能的值：
  * male
  * female
  * both
* `collectionAddress`：已发布穿戴物合集的以太坊地址。该地址会在发布时分配，也可以留空。

## 缩略图

你必须包含一个名为 `thumbnail.png` 的图片，放在你文件夹的根目录。该图片会同时显示在背包和市场中，用于以 2D 形式代表你的穿戴物。建议的必需图片尺寸为 256x256。

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

## 预览

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

要测试智能穿戴物在场景中的表现，你也可以在运行一个或多个场景预览的同时运行你的穿戴物预览，只需使用一个 [Workspace](/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”字段为空，则玩家尚未连接到岛屿，其他玩家也还不会加载。你可以每 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. 在你的项目中，为每种表现形式创建一个新文件夹（`male` 和 `female`），并将每种表现形式的 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. 打开穿戴物编辑器，并确保“hide”和“remove”类别设置正确，以便在佩戴此穿戴物时禁用其他穿戴物类别。
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/player-avatar.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.