> 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-pt/scenes-sdk7/tipos-de-projetos/smart-wearables.md).

# Smart Wearables

Crie wearables com capacidades interativas

Os wearables inteligentes são um tipo de cena global. Tal como [as experiências portáteis](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/portable-experiences.md), são experiências de jogo que os jogadores levam consigo enquanto se deslocam pelo metaverso. Por exemplo, enquanto joga uma cena global, um jogador pode apanhar uma bola de neve do chão na Genesis Plaza, deslocar-se para outra cena e atirá-la a outro jogador que também esteja a jogar o mesmo jogo.

Os wearables inteligentes são experiências portáteis que são ativadas quando o jogador veste uma determinada peça de roupa. Podem conceder novas capacidades aos jogadores, como um jetpack que lhes permite voar, ou adicionar uma nova camada de conteúdo ao resto do mundo, como moedas colocadas aleatoriamente para serem recolhidas por toda a Genesis City.

{% hint style="warning" %}
**📔 Nota**: os wearables inteligentes só podem ser criados com o SDK 7.

O **Creator Hub** não permite atualmente criar projetos de wearables inteligentes.
{% endhint %}

## Primeiros passos

### Utilizar a CLI

1. Abra uma linha de comandos numa nova pasta e execute

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

Este comando cria os ficheiros básicos e a estrutura para um novo wearable inteligente.

## Os ficheiros do modelo

A pasta de um projeto de wearable inteligente acabado de criar é muito semelhante à de uma [cena de Decentraland](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/scene-files.md), mas irá notar as seguintes diferenças:

* `wearable.json` inclui todos os metadados da experiência portátil
* Existe um modelo 3D provisório (glasses.glb) e uma miniatura (glasses.png) de um par de óculos escuros. Deve substituí-los pelo wearable que está a criar
* `scene.json` inclui `"isPortableExperience": true`. Os parcels não são relevantes para o wearable publicado, que funciona em qualquer lugar, mas pode defini-los para testes locais: a pré-visualização só é executada nos parcels indicados em `scene.json`

## Sobre wearable.json

O ficheiro `wearable.json` predefinido tem este aspeto:

```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": "Smart Wearable Example",
	"description": "Put the glasses to see a new world",
	"rarity": "mythic"
}
```

Estes são os campos mais comuns em `wearable.json`:

* `id`: identificador único do wearable inteligente.
* `name` (obrigatório): O nome do wearable que os utilizadores verão no Marketplace
* `description`: A descrição do wearable que os utilizadores verão no Marketplace. Certifique-se de que indica o que o wearable inteligente pode fazer, uma vez que os utilizadores do Marketplace não terão como pré-visualizar a sua funcionalidade antes de o comprar. Pode ter, no máximo, **64 caracteres** de comprimento. Pode escrever uma descrição mais longa no editor de itens do Builder após o carregamento.
* `rarity`: A oferta de tokens correspondente à raridade. Os valores possíveis são:
  * unique (1 cópia)
  * mythic (10 cópias)
  * exotic (50 cópias)
  * legendary (100 cópias)
  * epic (1000 cópias)
  * rare (5000 cópias)
  * uncommon (10.000 cópias)
  * common (100.000 cópias)

{% hint style="warning" %}
**📔 Nota**: Se criou uma bifurcação do seu projeto a partir de um projeto existente e este incluir um `id`, certifique-se de que o valor é único antes de publicar o wearable. Utilize [uuidgenerator.net](https://www.uuidgenerator.net/) para gerar um novo UUID aleatório
{% endhint %}

* `data` (obrigatório): Inclui o seguinte. `replaces`, `hides`, `tags`, `representations` e `category` têm de estar todos presentes. `replaces`, `hides` e `tags` podem ser listas vazias `[]`, mas `representations` tem de ter pelo menos uma entrada. Também pode ajustar estas definições na UI do Builder depois de carregar o wearable inteligente.
  * `replaces`: Lista de categorias de outros wearables que devem ser desequipados ao equipar este wearable, além da categoria predefinida. Por exemplo: ao vestir uma capa para a parte superior do corpo, oculte também os pés.
  * `hides`: Lista de categorias de outros wearables que devem ser ocultados (mas não desequipados) ao equipar este wearable, além da categoria predefinida.
  * `tags`: Etiquetas usadas para permitir a pesquisa do wearable no Marketplace.
  * `representations`:
    * `bodyShapes`: A lista de representações de Avatar que podem usar este wearable. Todos os wearables inteligentes têm de estar disponíveis para as formas corporais masculina e feminina.
    * `mainFile`: O ficheiro principal com o modelo 3D do wearable.
    * `contents`: A lista completa dos ficheiros usados para renderizar o modelo 3D do wearable. Por exemplo, o modelo 3D pode incluir texturas em ficheiros separados.
    * `overrideHides`: Quaisquer exceções ao comportamento predefinido de *ocultar* desta categoria de wearable.
    * `overrideReplaces`: Quaisquer exceções ao comportamento *de substituição* predefinido desta categoria de Wearable.
  * `category`: Categoria de Wearable a utilizar. Os valores possíveis são:
    * 'eyebrows'
    * 'eyes'
    * 'facial\_hair'
    * 'hair'
    * 'mouth'
    * 'upper\_body'
    * 'lower\_body'
    * 'feet'
    * 'earring'
    * 'eyewear'
    * 'hat'
    * 'helmet'
    * 'mask'
    * 'tiara'
    * 'top\_head'
    * 'skin'
    * 'hands\_wear'

{% hint style="warning" %}
**📔 Nota**: Além dos campos acima, o Builder também aceita um campo opcional de nível superior `mapping` e os campos opcionais `removesDefaultHiding` e `blockVrmExport` dentro de `data`. Os Wearables inteligentes normalmente não precisam deles. O Builder rejeita um ficheiro `wearable.json` que contenha qualquer outro campo de nível superior, apresentando o erro *"o ficheiro de configuração do wearable é inválido"*. As versões anteriores desta página listavam `menuBarIcon`, `model`, `bodyShape` e `collectionAddress`: remova-os se o seu projeto ainda os tiver. O mesmo erro aparece se `description` tiver mais de 64 caracteres.
{% endhint %}

## A miniatura

Tem de incluir uma imagem com o nome `thumbnail.png` na pasta raiz. Esta imagem será apresentada tanto na mochila como no Marketplace, para representar o seu Wearable em 2D. O tamanho recomendado para a imagem é 256x256.

Escolha uma imagem que corresponda às expectativas dos jogadores e represente devidamente a sua criação.

## A pré-visualização

Executar uma pré-visualização de um wearable inteligente é igual a executar a de uma cena: clique em **Reproduzir** no Creator Hub ou execute `npm run start` na linha de comandos. O Creator Hub não pode criar um projeto de wearable inteligente, mas pode abrir e pré-visualizar um.

A pré-visualização executa o código do wearable como uma cena normal nos parcels indicados em `scene.json`, e não como uma experiência portátil. Isto significa que alguns comportamentos são diferentes dos do wearable publicado:

* O código que só funciona na cena onde o jogador se encontra, como [forças físicas no jogador](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/player-physics.md), deixa de funcionar quando o jogador sai dos parcels da pré-visualização. Depois de publicado, o wearable inteligente continua a funcionar onde quer que o jogador vá.
* O modelo 3D do wearable pode não aparecer no seu avatar.

Para experimentar o wearable equipado e a funcionar em qualquer lugar, carregue-o para o Builder e use **Ver no Decentraland** (consulte [Publicar](#publish)). Não precisa de fazer mint nem de publicar a coleção para isso.

Para testar o comportamento do wearable inteligente no contexto de uma cena, também pode executar uma pré-visualização do wearable ao mesmo tempo que executa uma pré-visualização de uma ou várias cenas, utilizando um [Workspace](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/workspaces.md). Por exemplo, pode executar o wearable inteligente em conjunto com a cena [Genesis Plaza](https://github.com/decentraland-scenes/Genesis-Plaza) para testar o comportamento numa cena movimentada, num elevador, etc.

## Sugestões

* Ao posicionar uma entidade, tenha em atenção que as posições são globais, relativas às coordenadas 0,0 de Genesis Plaza.
* Para reagir aos jogadores nas proximidades:
  * Consulte [Obter todos os jogadores](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/user-data.md#fetch-all-players) para saber como obter dados dos outros jogadores nas proximidades.
  * Tenha em atenção que o carregamento do wearable inteligente, das cenas próximas e dos outros jogadores pode ocorrer em ordens diferentes, consoante a situação. Se o jogador entrar no Decentraland com o wearable inteligente já equipado, é provável que a cena global do wearable seja carregada antes dos outros jogadores. Por outro lado, se o jogador entrar primeiro numa cena e só depois equipar o wearable, é provável que os outros jogadores já estejam carregados quando a cena do wearable começar a ser executada.
  * Os outros jogadores só são carregados depois de o jogador se ligar a uma ilha dentro do seu realm. Obtenha os dados do realm e verifique o campo ‘room’. Se o campo ‘room’ for null, o jogador ainda não está ligado a uma ilha e os outros jogadores ainda não serão carregados. Pode verificar periodicamente, a cada 1 segundo, até o campo ‘room’ estar presente e só então inicializar a sua lógica. Isto permite-lhe apenas ver os outros jogadores; para partilhar dados entre utilizadores de wearables, consulte [Limitações](#limitations).
* Para interagir com as cenas próximas:
  * Não pode enviar instruções diretamente para cenas próximas ou outras experiências portáteis; o `messageBus` está atualmente isolado para cada experiência portátil/cena.
  * Pode utilizar um servidor intermédio para enviar informações entre a experiência portátil e uma cena.
  * Se fizer um raycast, pode detetar colisões com os colliders das entidades das cenas próximas. Isto permite obter a localização exata do impacto, a direção da normal e até o nome da entidade e o nome da mesh do modelo 3D. Isto só funciona ao atingir entidades em cenas criadas com SDK7.
* Terminar uma experiência portátil: execute o método `kill()` para terminar a experiência portátil.
* Empurrar o jogador: [Physics](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/player-physics.md) funções como `Physics.applyImpulseToPlayer()` funcionam em qualquer lugar para onde o utilizador do wearable vá, uma vez que a cena de um wearable inteligente é sempre considerada a cena onde o jogador se encontra. Não é necessária qualquer permissão. As cenas podem desativar os wearables inteligentes para os seus visitantes; consulte [Alternâncias de funcionalidades](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/scene-metadata.md#feature-toggles).
* Reproduzir um som que só o utilizador do wearable ouve: associe uma entidade ao jogador com [AvatarAttach](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md#attach-an-entity-to-an-avatar) e adicione-lhe um `AudioSource`. Os outros jogadores não o ouvem.
* Carregue os ficheiros antes de serem necessários: use o [AssetLoad](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/otimizacao/pre-load-resources.md) component para obter ficheiros de sons, modelos ou emotes quando o wearable é iniciado, para que a primeira utilização não tenha de esperar por uma transferência.

## Publicar

Para publicar o seu smart wearable:

1. Certifique-se de que as informações em `wearable.json` estão corretas. Se usou outro projeto como ponto de partida, certifique-se de que o `id` é um identificador único, não utilizado por outros wearables.
2. Execute `npm run pack` na pasta do seu projeto. Isto gera um ficheiro `smart-wearable.zip` na pasta do seu projeto.

{% hint style="warning" %}
**📔 Nota**: o conteúdo descomprimido de `smart-wearable.zip` tem de ter menos de 3 MB no total, caso contrário, o Builder rejeita o ficheiro por ser demasiado grande. `npm run pack` apresenta uma mensagem sobre o tamanho quando o projeto ultrapassa 2 MB, mas continua a criar o ficheiro zip. Verifique o tamanho dos ficheiros dentro do zip, não o tamanho do próprio zip. Consulte [Limitações](#limitations).
{% endhint %}

3. Abra o Builder, aceda ao separador Collections e clique em + para carregar um novo wearable.
4. Arraste o ficheiro comprimido `smart-wearable.zip` para o Builder e confirme que todas as informações estão corretas.

> Nota: se o seu wearable tiver um modelo 3D diferente para cada formato de corpo, liste uma representação por formato de corpo:
>
> 1. No seu projeto, crie uma nova pasta para cada representação (`male` e `female`) e coloque o modelo 3D de cada representação na pasta correspondente.
> 2. Atualize o ficheiro `wearable.json` para incluir as novas representações.
> 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. Execute `npm run pack` para gerar um novo ficheiro smart-wearable.zip.
> 5. Arraste o novo ficheiro smart-wearable.zip para o Builder.

5. Abra o editor de wearables e certifique-se de que as categorias “hide” e “remove” estão configuradas corretamente para desativar outras categorias de wearables quando este wearable estiver ativo.
6. Crie uma nova coleção com este e, se quiser, outros wearables.
7. Na coleção, clique em **Ver no Decentraland**. Isto abre o Decentraland na rede de testes Sepolia, onde pode equipar os wearables da sua coleção a partir da mochila e ver como se comportam num cenário mais realista, por exemplo, a correr pela Genesis Plaza. Consulte [Testes no Decentraland](https://docs.decentraland.org/creator/content-creator-pt/wearables-e-emotes/gerir-colecoes/uploading-smart-wearables.md#testing-in-decentraland).
8. Nesta fase, o teu wearable está pronto para publicação.

## Permissões

Os smart wearables são executados com permissões restritas. Para usar qualquer uma das seguintes funcionalidades, declara a permissão correspondente na lista `requiredPermissions` do teu `scene.json`, caso contrário, a chamada falha em runtime:

* `USE_FETCH`: requests HTTP com `fetch` ou `signedFetch`
* `USE_WEBSOCKET`: ligações WebSocket
* `USE_WEB3_API`: transações de Wallet ou assinatura de mensagens
* `OPEN_EXTERNAL_LINK`: pedir ao jogador que abra um link externo

```json
"requiredPermissions": [
    "USE_FETCH"
  ],
```

Quando um smart wearable declara alguma destas permissões, os jogadores veem um pedido de autorização ao equipá-lo e, se recusarem, o wearable não é executado. Declara apenas o que usas. Consulta [Permissões necessárias](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/scene-metadata.md#required-permissions) para mais detalhes.

## Limitações

> IMPORTANTE: O smart wearable completo tem de caber em 3 MB. Isto inclui o modelo 3D, a miniatura, o código, as libraries, os files de sound, os modelos 3D adicionais, as imagens de UI, etc. Este limite aplica-se à folder descomprimida. O Builder não permite carregar wearables maiores do que isso. Para verificar o tamanho, descomprime o file `smart-wearable.zip` gerado e verifica o tamanho da folder, ou executa `unzip -l smart-wearable.zip` e consulta o total.

Para excluir files do zip, indica-os no file `.dclignore` do projeto, da mesma forma que farias para uma scene.

{% hint style="warning" %}
**📔 Nota**: Se editares o teu projeto de smart wearable no Creator Hub, este pode guardar uma captura de ecrã da vista 3D em tamanho completo como `assets/Images/autogenerated-thumbnail.png` e fazer com que `scene.json` aponte para ela. Essa imagem pode ocupar vários MB por si só e fazer com que o wearable exceda o limite. Os smart wearables não a usam, por isso adiciona `assets/Images/autogenerated-thumbnail.png` a `.dclignore`.
{% endhint %}

Os smart wearables executam a experiência portátil apenas para o jogador que os usa. Os outros jogadores não veem os efeitos. Por exemplo, se a experiência portátil apresentar um animal de estimação que segue o jogador, os outros jogadores nas proximidades não o verão. No entanto, os outros jogadores verão os avatars executar animations que fazem parte da scene do wearable, incluindo [animations personalizadas de avatar](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-animations.md#custom-animations) carregadas como parte dos files do smart wearable.

Os smart wearables não têm multiplayer integrado. Cada jogador que usa o wearable executa a sua própria cópia independente do código, mesmo quando dois utilizadores estão lado a lado. O `MessageBus`, a sincronização de entities com `syncEntity()` e o [Multiplayer Server](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/rede/authoritative-servers.md) não funcionam num smart wearable. A única forma de partilhar dados entre utilizadores, como uma pontuação partilhada, é através de um server próprio com o qual o wearable comunica usando `fetch` ou um WebSocket, consulte [Ligações de rede](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/rede/network-connections.md).

Uma animação personalizada pode incluir acessórios, e os acessórios podem incluir efeitos de partículas feitos com bones animados (consulte [Acessórios e sons](https://docs.decentraland.org/creator/content-creator-pt/wearables-e-emotes/emotes/props-and-sounds.md) e [Partículas em Emotes](https://docs.decentraland.org/creator/content-creator-pt/wearables-e-emotes/emotes/particles-in-emotes.md)). Os outros jogadores também os veem. O som é diferente: as animações personalizadas reproduzidas com `triggerSceneEmote()` não reproduzem áudio, mesmo que o ficheiro do emote inclua um. Para reproduzir um som, use um `AudioSource`, que só é ouvido por quem o está a usar.

Os wearables inteligentes só funcionam quando os jogadores os estão a usar. Por este motivo, os jogadores só podem ter um número limitado de wearables inteligentes ativados e, consoante a parte do corpo que ocupam, alguns são incompatíveis entre si. Por exemplo, não é possível usar dois chapéus ao mesmo tempo, nem um capacete e cabelo ao mesmo tempo.

Se um wearable estiver «oculto», mas não «removido» por outros wearables usados, o wearable inteligente pode continuar ativo, mesmo que o wearable correspondente não esteja visível.

## Exemplos

[Exemplo de wearable inteligente](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-pt/scenes-sdk7/tipos-de-projetos/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.
