# Basic Components

O World Explorer suporta uma lista de componentes básicos que compartilham sua definição com cenas, fornecendo suporte embutido para posicionamento, animação, mídia, consultas de estado do mundo

Existem cinco tipos de componentes:

1. [Componentes de objeto](#object) adicionam propriedades visuais e físicas às Entities.
2. [Componentes de jogo](#game) podem solicitar ações e receber informações do mecanismo de jogo.
3. [Componentes de mídia](#media) podem exibir imagens e reproduzir sons.
4. [Componentes de área](#area) alteram o comportamento das Entities em zonas específicas.
5. [Componentes UI](#ui) permitem que as cenas renderizem interfaces flutuantes.

Exceto por [`Transform`](#Transform), que é especificado em detalhe abaixo, o estado de todos os componentes é serializado usando protocol buffers. Você pode seguir o link em cada título para ver a definição completa.

### Componentes de Objeto <a href="#object" id="object"></a>

Os componentes mais comuns são aqueles que adicionam propriedades visuais e físicas a uma Entity. Eles podem ser usados para posicionar, redimensionar, pintar e adicionar colisão a objetos no jogo.

***

**`Transform`** [**↗ spec**](https://adr.decentraland.org/adr/ADR-153)

Adiciona posição, rotação e escala a uma entity.

Este componente é, de longe, o mais usado e frequentemente atualizado durante a vida útil de uma cena. Por causa disso, `Transform` não é serializado usando protocol buffers, sendo em vez disso empacotado em uma estrutura personalizada.

`Transform` tem um tamanho de `44` bytes, com esse layout exato:

```
.-----------------------.-------------------------------.-----------------------.-----------------.
|   x   |   y   |   z   |   x   |   y   |   z   |   w   |   x   |   y   |   z   | parent (uint32) |
'-----------------------'-------------------------------'-----------------------'-----------------'
╵  position (3x float)  ╵      rotation (4x float)      ╵   scale (3x float)    ╵

```

Essa abordagem permite que o runtime (especialmente em ambientes de código de baixo nível) evite etapas intermediárias de serialização e desserialização. A memória onde um `Transform` reside pode ser copiada, compartilhada e apontada diretamente.

As coordenadas podem ser fracionárias e, portanto, usam um número de ponto flutuante de 4 bytes.

O `parent` campo indica que esta Entity deve ser posicionada em relação a outra, identificada pelo seu ID.

Como o valor nulo para `parent` é também o [`RootEntity`](https://github.com/decentraland/docs/blob/main/contributor/runtime/entities/README.md#RootEntity) ID (`0`), qualquer `Transform` é relativo a ele por padrão.

Por protocolo, `Transform` deve ser serializado em ordem de bytes big-endian.

***

**`MeshRenderer`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/mesh_renderer.proto#L7)

Fornece comportamento básico de renderização para uma Entity.

Pode ser configurado para renderizar um plano, uma esfera, um cubo ou um cilindro. Para renderizar formas 3D arbitrárias, use [`GltfContainer`](#GltfContainer).

***

**`MeshCollider`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/mesh_collider.proto#L15)

Fornece comportamento básico de colisão e detecção do ponteiro do mouse para uma Entity.

Pode ser configurado para se comportar como um plano, uma esfera, um cubo ou um cilindro. Para ter uma malha de colisão personalizada, use [`GltfContainer`](#GltfContainer).

***

**`Material`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/material.proto#L19)

Define a textura, iluminação, cor e propriedades de transparência de uma Entity que também possui o componente [`MeshRenderer`](#MeshRenderer) .

É uma estrutura complexa projetada para cobrir todos os casos comuns, mas cada campo tem um valor padrão razoável e pode ficar não especificado.

Para personalizar completamente as propriedades visuais de uma Entity, use [`GltfContainer`](#GltfContainer).

***

**`GltfContainer`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/gltf_container.proto#L7)

Anexa um modelo 3D a esta Entity, dado o [caminho do arquivo](https://github.com/decentraland/docs/blob/main/contributor/content/entities/README.md#files) de um `.gltf` asset no manifesto da cena.

Como o modelo tem suas próprias malhas e materiais, este componente substitui qualquer comportamento de [`MeshRenderer`](#MeshRenderer), [`MeshCollider`](#MeshCollider) e [`Material`](#Material).

***

**`Billboard`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/billboard.proto#L17)

Faz com que uma Entity reoriente automaticamente seu `Transform` para enfrentar a câmera. Como o nome indica, é usado para exibir placas no jogo e frequentemente combinado com [`TextShape`](#TextShape).

Afeta todas as direções por padrão, mas pode ser configurado para girar apenas em um eixo.

***

**`Animator`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/animator.proto#L7)

Define uma ou mais animações que podem ser aplicadas simultaneamente a uma entity.

As cenas podem definir o estado do componente para personalizar, reproduzir e fazer transições entre animações, assim como lê-lo para verificar quais animações estão disponíveis ou estão sendo reproduzidas no momento.

***

**`AvatarAttach`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/avatar_attach.proto#L16)

Indica que a posição de uma Entity deve seguir um ponto de ancoragem particular no corpo de um avatar.

Pode afetar qualquer avatar, não apenas o do jogador, definindo um ID de usuário.

***

**`TextShape`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/text_shape.proto#L11)

Renderiza texto na posição de uma Entity, dada pelo seu `Transform`.

É altamente configurável, suportando parâmetros como tamanho, margem, padding, cor, sombra e mais.

***

**`Visibility`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/visibility_component.proto#L7)

Define se uma Entity é visível (o padrão) ou invisível.

Objetos invisíveis ainda existem e exibirão comportamento de quaisquer outros componentes anexados.

***

**`AvatarShape`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/avatar_shape.proto#L8)

Contém informações sobre o avatar do jogador, incluindo sua body shape, cores, wearables e estado transitório.

Este componente é anexado a entities na [avatar scene](https://github.com/decentraland/docs/blob/main/contributor/runtime/execution/README.md#avatarScene).

### Componentes de Jogo <a href="#game" id="game"></a>

Alguns componentes básicos podem ser usados pela cena e pelo runtime para trocar informações. Eles aproveitam o [mecanismo de sincronização ECS](https://github.com/decentraland/docs/blob/main/contributor/runtime/modules/engine_api/README.md#synchronization) para garantir consistência e ordenação para quaisquer mudanças de estado ou eventos.

***

**`CameraMode`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/camera_mode.proto#L8)

Pode ser usado para determinar se o jogador tem uma visão em primeira pessoa ou terceira pessoa.

***

**`PointerLock`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_lock.proto#L7)

Pode ser usado para determinar se o ponteiro do mouse está automaticamente seguindo o ponto de foco da câmera (locked), ou pode mover-se livremente na tela (unlocked).

Está anexado ao [`CameraEntity`](https://github.com/decentraland/docs/blob/main/contributor/runtime/entities/README.md#CameraEntity), e seu estado pode ser lido (mas não escrito) a partir da cena.

***

**`PointerEvents`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_events.proto#L17)

Mostra feedback visual quando o ponteiro clica ou passa o mouse sobre uma Entity.

***

**`PointerEventsResult`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_events_result.proto#L13)

Contém informações sobre entrada recente do jogador, incluindo teclas e ações do ponteiro.

Está anexado ao `RootEntity`, e atualizado pelo runtime com quaisquer novos eventos a cada frame.

***

**`Raycast`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/raycast.proto#L15)

Pode ser anexado a uma Entity para solicitar um raycast ao mecanismo de jogo. O componente `RaycastResult` será posteriormente anexado à mesma entity.

A origem, direção e comprimento máximo do raio podem ser configurados.

***

**`RaycastResult`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/raycast_result.proto#L9)

Anexado pelo runtime a Entities que têm um componente [`Raycast`](#Raycast) pendente de resultados.

Contém informações sobre o raio original e identifica quaisquer Entities que foram atingidas.

### Componentes de Mídia <a href="#media" id="media"></a>

As cenas podem anexar componentes especiais para exibir imagens, mostrar vídeo ou reproduzir sons.

***

**`AudioSource`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/audio_source.proto#L7)

Reproduz um clipe de áudio empacotado com a cena, dado o [caminho do arquivo no seu manifesto](https://github.com/decentraland/docs/blob/main/contributor/content/entities/README.md#files).

O som se origina da posição da entity associada. Seu pitch, volume e comportamento de repetição podem ser definidos, e o estado do reprodutor de áudio pode ser lido.

{% hint style="info" %}
Em preparação para upgrades futuros, o campo em `AudioSource` é chamado `audio_clip_url`, mas na versão atual do protocolo é na verdade o caminho definido no manifesto.
{% endhint %}

***

**`AudioStream`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/audio_stream.proto#L7)

Semelhante a [AudioSource](#AudioSource), mas o áudio é transmitido em tempo real a partir de uma URL externa.

Apesar de estar anexado a uma entity particular, o som não é afetado por sua posição. Seu volume pode ser definido, e o estado do reprodutor de áudio pode ser lido.

***

**`NftShape`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/nft_shape.proto#L36)

Exibe um NFT associado a um asset de imagem ou vídeo.

Renderiza uma tela 2D com uma moldura decorativa configurável.

### Componentes de Área

Esses componentes permitem que as cenas modifiquem o comportamento padrão das Entities dentro de limites especificados.

***

**`AvatarModifierArea`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/avatar_modifier_area.proto#L15)

Altera o comportamento dos avatares dentro de um espaço centrado em torno de uma Entity.

É definido com um vetor de tamanho 3D e pode afetar se avatares são visíveis ou clicáveis. Avatares específicos podem ser excluídos desse efeito dado o ID do seu usuário.

***

**`CameraModeArea`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/camera_mode_area.proto#L11)

Altera o modo de câmera (1st-person ou 3rd-person) dentro de um espaço centrado em torno de uma Entity.

É definido com um vetor de tamanho 3D e um modo de câmera desejado.

### Componentes de UI <a href="#ui" id="ui"></a>

Os seguintes componentes são usados para criar interfaces gráficas que flutuam sobre o mundo do jogo.

Eles geralmente são anexados a conjuntos de Entities que têm hierárquicos [`UiTransform`](#UiTransform) componentes, relacionados entre si via o `parent` atributo.

Por exemplo, uma janela de opções flutuante poderia ser uma Entity com um [`UiTransform`](#UiTransform) e um [`UiBackground`](#UiBackground) componente, além de uma Entity com um filho [`UiTransform`](#UiTransform) e um [`UiDropdown`](#UiDropdown).

***

**`UiTransform`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_transform.proto#L77)

Descreve o tamanho, posicionamento, margem e padding de um componente de UI.

É baseado no modelo flexbox e altamente personalizável.

***

**`UiBackground`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_background.proto#L11)

Descreve uma cor ou textura a ser usada como fundo em uma Entity de UI.

***

**`UiDropdown`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_dropdown.proto#L11)

Define uma lista de opções mutuamente exclusivas a ser exibida em um widget dropdown.

***

**`UiDropdownResult`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_dropdown_result.proto#L9)

Contém o valor selecionado de um [`UiDropdown`](#UiDropdown), definido pelo runtime e lido pela cena.

***

**`UiInput`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_input.proto#L11)

Define um widget de entrada de texto, com alguma margem para personalização.

***

**`UiInputResult`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_input_result.proto#L9)

Contém o valor de texto de um [`UiInput`](#UiInput), definido pelo runtime e lido pela cena.

***

**`UiText`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_text.proto#L11)

Define uma visualização de texto simples, com alguma margem para personalização.

***