> 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/fundamentos-de-conteudo-3d/shape-components.md).

# Components de Forma

Saiba mais sobre os diferentes components que dão às entities sua forma 3D e colisão.

As cenas tridimensionais em Decentraland baseiam-se no [Entity-Component](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system) modelo, em que tudo numa cena é uma *entidade*, e cada entidade pode incluir *componentes* que definem as suas características e funcionalidades.

A forma apresentada de uma entidade é determinada pelo componente que utiliza.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-8bb43741efd4cdb7e001f4dca8acd7f21fbcb48e%2Fecs-simple-components-new.webp?alt=media)

## Use o Scene Editor no Creator Hub

A forma mais simples de dar uma forma a uma entidade é utilizar o Scene Editor. Pode adicionar um componente **Mesh Renderer** para fornecer uma forma primitiva, ou um componente **GLTF** para referenciar um modelo 3D a partir de um ficheiro. Consulte [Adicionar componentes](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/construir/components.md#add-components).

## Formas primitivas

É possível adicionar várias formas básicas, frequentemente chamadas *primitivas*, a uma entidade atribuindo-lhe um componente `MeshRenderer` .

Estão disponíveis as seguintes formas. Algumas incluem campos adicionais opcionais específicos dessa forma.

* **caixa**:

  Utilize `MeshRenderer.setBox()`, passando a entidade. Passe `uvs` como campo opcional adicional para definir o alinhamento da textura. Consulte [materiais](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/materials.md) para mais informações.
* **plano**:

  Utilize `MeshRenderer.setPlane()`, passando a entidade. Passe `uvs` como campo opcional adicional para definir o alinhamento da textura. Consulte [materiais](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/materials.md) para mais informações.
* **esfera**:

  Utilize `MeshRenderer.setSphere()`, passando a entidade.
* **cilindro**:

  Utilize `MeshRenderer.setCylinder()`, passando a entidade. Passe `radiusTop` e `radiusBottom` como campos opcionais adicionais para modificar o cilindro.

  DICA: Defina qualquer um dos seguintes `radiusTop` ou `radiusBottom` para 0 para criar um cone.

O exemplo seguinte cria um cubo:

```ts
const myCube = engine.addEntity()

Transform.create(myCube, {
	position: Vector3.create(8, 1, 8),
})

MeshRenderer.setBox(myCube)
```

O exemplo seguinte cria um cilindro com um `radiusTop` de 0, o que resulta num cone:

```ts
const myCone = engine.addEntity()

Transform.create(myCone, {
	position: Vector3.create(8, 1, 8),
})

MeshRenderer.setCylinder(myCone, 1, 0)
```

As formas primitivas não incluem materiais. Para lhes atribuir uma cor ou textura, tem de adicionar um [componente de material](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/materials.md) à mesma Entity.

Para tornar uma forma primitiva clicável ou impedir que os jogadores a atravessem, tem de adicionar à Entity um *Collider* através de um componente [MeshCollider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md) .

Para alterar a forma de uma Entity que já tenha um componente `MeshRenderer` execute `MeshRenderer.setBox()` ou qualquer uma das outras funções auxiliares, e a forma original será substituída. Não é necessário remover a forma original `MeshRenderer` nem utilizar a sintaxe avançada.

```ts
const myCube = engine.addEntity()

Transform.create(myCube, {
	position: Vector3.create(8, 1, 8),
})

MeshRenderer.setBox(myCube)

// substituir a forma
MeshRenderer.setSphere(myCube)
```

{% hint style="warning" %}
**📔 Nota**: o componente `MeshRenderer` tem de ser importado através de

> `import { MeshRenderer } from "@dcl/sdk/ecs"`

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

## Modelos 3D

Para criar formas mais complexas, pode criar um modelo 3D numa ferramenta externa, como o Blender, e depois importá-lo em formato *.glTF* ou *.glb* (formato binário *.glTF*). [glTF](https://www.khronos.org/gltf) (GL Transmission Format) é um projeto aberto da Khronos que disponibiliza um formato comum e extensível para recursos 3D, eficiente e altamente interoperável com as tecnologias Web modernas.

Para adicionar um modelo externo a uma Scene, adicione o componente `GltfContainer` a uma Entity e defina o seu `src` como o caminho para o ficheiro glTF que contém o modelo.

```ts
const houseEntity = engine.addEntity()

GltfContainer.create(houseEntity, {
	src: 'models/House.gltf',
})
```

O `src`  campo é obrigatório; tem de lhe atribuir um valor ao construir o componente. No exemplo acima, o modelo está localizado numa `models` pasta na raiz da pasta do projeto da cena.

{% hint style="info" %}
**💡 Sugestão**: recomendamos manter os seus modelos separados na pasta `assets/scene/models` dentro da sua cena.
{% endhint %}

Os modelos glTF podem incluir as suas próprias texturas, materiais, colliders e animações incorporados. Consulte [Modelos 3D](https://github.com/decentraland/docs/blob/main/creator/3d-modeling/3d-models.md) para obter mais informações. Para substituir os materiais de um modelo, use o componente [GltfNodeModifiers](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/materials.md#modify-gltf-materials) . Consulte [Modificar materiais glTF](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/materials.md#modify-gltf-materials) para obter mais detalhes.

Para impedir que os jogadores atravessem um modelo 3D ou para tornar um modelo clicável, é necessário ter um [collider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md), que pode estar incorporado no modelo ou ser fornecido através de um componente `MeshCollider` .

Tenha em atenção que todos os modelos, os respetivos shaders e texturas devem respeitar os [limites da cena](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/otimizacao/scene-limitations.md).

{% hint style="warning" %}
**📔 Nota**: o componente `GltfContainer` tem de ser importado através de

`import { GltfContainer } from "@dcl/sdk/ecs"`

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

### Pré-carregar um modelo 3D

Em alguns casos, é adicionado à cena um modelo 3D personalizado que não é utilizado imediatamente. Por exemplo, um modelo de cadeira personalizado pode só ser carregado quando o jogador interage com outro objeto. Neste cenário, a primeira interação pode demorar algum tempo até que o modelo termine de ser transferido e carregado.

Para evitar isto, use o método `AssetLoad.create` para garantir que o recurso é transferido antes de ser necessário.

```ts
import { AssetLoad } from "@dcl/sdk/ecs"

AssetLoad.create(engine.RootEntity, {
  assets: [
    "assets/scene/bundle1/explosion.glb",
  ],
})
```

Para obter mais informações, consulte a documentação [Pré-carregar recursos](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/otimizacao/pre-load-resources.md) .

### Bibliotecas gratuitas de modelos 3D

Em vez de criar os seus próprios modelos 3D, também pode transferi-los de várias bibliotecas gratuitas ou pagas.

Para começar, segue-se uma lista de bibliotecas com conteúdo gratuito ou relativamente barato:

* [IWB Catalog](https://dcl-iwb.co/)
* [Asset Ovi](https://assetovi.com/)
* [Recursos do Builder](https://github.com/decentraland/builder-assets/tree/master/assets)
* [SketchFab](https://sketchfab.com/)
* [Clara.io](https://clara.io/)
* [Archive3D](https://archive3d.net/)
* [Armazém 3D do SketchUp](https://3dwarehouse.sketchup.com/)
* [Thingiverse](https://www.thingiverse.com/) (modelos 3D criados principalmente para impressão 3D, mas adaptáveis a mundos virtuais)
* [ShareCG](https://www.sharecg.com/)
* [CGTrader](https://www.cgtrader.com/)

{% hint style="warning" %}
**📔 Nota**: tenha em atenção as restrições da licença do conteúdo que transfere.
{% endhint %}

Tenha em atenção que, em vários destes sites, pode escolher o formato em que pretende transferir o modelo. Escolha sempre o formato *.glTF* se estiver disponível. Caso contrário, terá de os converter para *glTF* antes de os poder usar numa cena. Para isso, recomendamos que os importe para o Blender e os exporte como *.glTF* a partir daí.

### Otimizar modelos 3D

Para garantir que os modelos 3D na sua cena carregam mais rapidamente e ocupam menos memória, siga estas práticas recomendadas:

* Guarde os seus modelos no formato *.glb*  , que é uma versão mais leve do formato *.gltf*.
* Se tiver vários modelos que partilham as mesmas texturas, exporte os modelos com as texturas num ficheiro separado. Assim, vários modelos podem referenciar um único ficheiro de textura, que só precisa de ser carregado uma vez.
* Se a sua Scene tiver Entities que aparecem e desaparecem, pode ser boa ideia agrupá-las e mantê-las debaixo do solo ou com uma escala de 0. Assim, aparecerão mais rapidamente. Em contrapartida, ocuparão memória quando não estiverem a ser utilizadas.

## Alongar uma forma

As formas primitivas e os modelos 3D têm dimensões predefinidas que pode alterar modificando a escala no componente `Transform` . da Entity.

```ts
const primitiveEntity = engine.addEntity()

MeshRenderer.setBox(primitiveEntity)

Transform.create(primitiveEntity, {
	position: { x: 8, y: 1, z: 8 },
	scale: { x: 4, y: 0.5, z: 4 },
})
```

## Tornar invisível

Pode tornar uma Entity invisível atribuindo-lhe um `VisibilityComponent`, com a propriedade `visible` definida como *false*.

```ts
const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 0, 4),
})
MeshRenderer.setBox(myEntity)

VisibilityComponent.create(myEntity, { visible: false })
```

O `VisibilityComponent` funciona da mesma forma com Entities que têm formas primitivas e com os componentes `GLTFContainer` .

Se uma Entity for invisível, o seu Collider pode bloquear o caminho de um jogador e/ou impedir que sejam clicadas Entities que estejam atrás dela, dependendo das camadas de colisão atribuídas ao Collider.

### Propagar a visibilidade

Pode usar o campo `propagateToChildren` do `VisibilityComponent` para aplicar uma configuração a todos os elementos subordinados na árvore de elementos subordinados da Entity. Se `propagateToChildren`  estiver definido como *true*, estas definições afetam todos os elementos subordinados em todos os níveis descendentes. Isto pode poupar-lhe muito trabalho repetitivo, evitando ter de marcar cada Entity subordinada como invisível ou visível.

```ts
// Entity principal (explicitamente invisível)
const parentEntity = engine.addEntity()
Transform.create(parentEntity, {
	position: Vector3.create(4, 0, 4),
})
MeshRenderer.setBox(parentEntity)
VisibilityComponent.create(parentEntity, { visible: false, propagateToChildren: true })

// Entity subordinada (implicitamente invisível devido à Entity principal)
const child = engine.addEntity()
Transform.create(child, {
	position: Vector3.create(0, 1, 0),
	parent: parentEntity
})
MeshRenderer.setBox(child)
```

{% hint style="warning" %}
**📔 Nota**: Se uma Entity tiver o seu próprio `VisibilityComponent`, este substitui qualquer configuração herdada das Entities principais.

Se uma Entity não tiver o seu próprio `VisibilityComponent`, a visibilidade é determinada pelo seu ancestral mais próximo com `VisibilityComponent` e `propagateToChildren` definido como *true*.
{% endhint %}

## Estado de carregamento

Se um modelo 3D for bastante grande, pode demorar algum tempo a ser renderizado. Esse tempo pode variar consoante o hardware do jogador e muitos outros fatores. Por vezes, é necessário garantir que o carregamento de um modelo terminou antes de realizar outra ação. Por exemplo, se quiseres teletransportar o jogador para uma plataforma no céu, primeiro tens de garantir que a plataforma foi totalmente renderizada antes de mover o jogador para lá; caso contrário, o jogador pode atravessar a plataforma e cair.

Para verificar se a renderização de um modelo 3D terminou, consulta o componente `GltfContainerLoadingState` . Este componente é apenas de leitura e existe em qualquer entidade que também tenha um componente `GltfContainer`.

Este componente tem uma única propriedade chamada `currentState`, que contém um valor do enum `LoadingState` .

O exemplo seguinte usa um sistema para verificar periodicamente o estado de carregamento do modelo 3D de uma entidade. Se o estado for `LoadingState.FINISHED`, podes executar aqui uma lógica personalizada e terminar a execução do sistema.

```ts
export function main() {
	const meshEntity = engine.addEntity()
	GltfContainer.create(meshEntity, { src: 'models/Monster.glb' })
	engine.addSystem((deltaTime) => {
		const loadingState = GltfContainerLoadingState.getOrNull(meshEntity)
		if (!loadingState) return
		switch (loadingState.currentState) {
			case LoadingState.LOADING:
				console.log('mesh is LOADING')
				break
			case LoadingState.FINISHED:
				console.log('mesh is FINISHED')
				// Perform custom logic
				break
			case LoadingState.FINISHED_WITH_ERROR:
				console.log('mesh is FINISHED BUT MAY HAVE PROBLEMS')
				break
			case LoadingState.UNKNOWN:
				console.log('mesh is in an UNKNOWN STATE')
				break
		}
	})
}
```

## Sintaxe avançada

A sintaxe completa para criar um componente `MeshRenderer` , sem quaisquer auxiliares para a simplificar, é a seguinte:

```ts
MeshRenderer.create(myBox, {
	mesh: {
		$case: 'box',
		box: { uvs: [] },
	},
})

MeshRenderer.create(myPlane, {
	mesh: {
		$case: 'plane',
		plane: { uvs: [] },
	},
})

MeshRenderer.create(myShpere, {
	mesh: {
		$case: 'sphere',
		sphere: {},
	},
})

MeshRenderer.create(myCylinder, {
	mesh: {
		$case: 'cylinder',
		cylinder: {},
	},
})
```

É assim que o protocolo base interpreta os componentes MeshRenderer. As funções auxiliares abstraem esta sintaxe e disponibilizam uma forma mais simples de a escrever, mas, nos bastidores, geram esta sintaxe.

O `$case` o campo permite especificar um dos tipos permitidos. Cada tipo suporta um conjunto diferente de parâmetros. No exemplo acima, o `box` tipo suporta um campo `uvs` .

Os valores suportados para `$case` são os seguintes:

* `box`
* `plane`
* `sphere`
* `cylinder`

Consoante o valor de `$case`, é válido definir o objeto para a forma correspondente, passando quaisquer propriedades relevantes.

Para adicionar um componente `MeshRenderer` a uma Entity que potencialmente já tenha uma instância deste componente, use `MeshRenderer.createOrReplace()`. As funções auxiliares, como `MeshRenderer.setBox()` tratam da substituição de instâncias existentes do componente, mas executar `MeshRenderer.create()` numa Entity que já tenha este componente devolve um erro.


---

# 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/fundamentos-de-conteudo-3d/shape-components.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.
