> 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/contributor/contributor-pt/runtime-da-scene/basic-components.md). # Basic Components O World Explorer suporta uma lista de basic components que compartilham sua definição com scenes, oferecendo suporte integrado para posicionamento, animação, media e consultas ao estado do mundo Existem cinco tipos de components: 1. [Object components](#object) adicionam propriedades visuais e físicas a Entities. 2. [Game components](#game) podem solicitar ações e receber informações do game engine. 3. [Media components](#media) podem exibir imagens e reproduzir sons. 4. [Area components](#area) alteram o comportamento de Entities em zonas específicas. 5. [Componentes de UI](#ui) permitem que scenes renderizem interfaces flutuantes. Exceto por [`Transform`](#Transform), que é especificado em detalhes abaixo, o estado de todos os components é serializado usando protocol buffers. Você pode seguir o link em cada título para ver a definição completa. ### Object Components Os components mais comuns são aqueles que anexaram propriedades visuais e físicas a uma Entity. Eles podem ser usados para posicionar, redimensionar, pintar e adicionar colisão a objetos do jogo. *** **`Transform`** [**↗ spec**](https://adr.decentraland.org/adr/ADR-153) Adiciona posição, rotação e escala a uma entity. Este component é, de longe, o mais usado e frequentemente atualizado durante a vida útil de uma scene. Por causa disso, `Transform` não é serializado usando protocol buffers e, em vez disso, é empacotado em uma estrutura personalizada. `Transform` tem um tamanho de `44` bytes, com este 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 uma `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` field 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/tree/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`** [**↗ fonte**](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 cilindro. Para renderizar formas 3D arbitrárias, use [`GltfContainer`](#GltfContainer). *** **`MeshCollider`** [**↗ fonte**](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 cilindro. Para ter uma malha de colisão personalizada, use [`GltfContainer`](#GltfContainer). *** **`Material`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/material.proto#L19) Define as propriedades de textura, iluminação, cor e transparência de uma Entity que também tem o [`MeshRenderer`](#MeshRenderer) component. É uma estrutura complexa projetada para cobrir todos os casos comuns, mas cada campo tem um valor padrão razoável e pode ser deixado sem especificação. Para personalizar completamente as propriedades visuais de uma Entity, use [`GltfContainer`](#GltfContainer). *** **`GltfContainer`** [**↗ fonte**](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/tree/main/contributor/content/entities/README.md#files) de um `.gltf` asset no manifest da scene. Como o modelo tem seus próprios Meshes e Materials, este component substitui qualquer comportamento de [`MeshRenderer`](#MeshRenderer), [`MeshCollider`](#MeshCollider) e [`Material`](#Material). *** **`Billboard`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/billboard.proto#L17) Faz uma Entity reorientar automaticamente seu `Transform` para ficar voltado para a câmera, ou opcionalmente para outra Entity referenciada via `target_entity`. Como o nome indica, é usado para exibir billboards 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. Se a Entity alvo referenciada não existir, a reorientação fica suspensa até que ela exista. *** **`Animator`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/animator.proto#L7) Define uma ou mais animations que podem ser aplicadas simultaneamente a uma entity. Scenes podem definir o estado do component para personalizar, reproduzir e fazer transições entre animations, além de lê-lo para verificar quais animations estão disponíveis ou sendo reproduzidas no momento. *** **`AvatarAttach`** [**↗ fonte**](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 específico no corpo de um Avatar. Pode afetar qualquer avatar, não apenas o do jogador, definindo um user ID. *** **`TextShape`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/text_shape.proto#L11) Renderiza texto na posição de uma Entity, dada por seu `Transform`. É altamente configurável, com suporte a parâmetros como tamanho, margem, preenchimento, cor, sombra e mais. *** **`Visibility`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/visibility_component.proto#L7) Define se uma Entity está visível (o padrão) ou invisível. Objetos invisíveis ainda existem e exibirão comportamento de quaisquer outros components anexados. *** **`AvatarShape`** [**↗ fonte**](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 component está anexado a entities no [avatar scene](https://github.com/decentraland/docs/tree/main/contributor/runtime/execution/README.md#avatarScene). ### Game Components Alguns basic components podem ser usados pela Scene e pelo runtime para trocar informações. Eles utilizam o [mecanismo de sincronização ECS](https://github.com/decentraland/docs/tree/main/contributor/runtime/modules/engine_api/README.md#synchronization) para garantir consistência e ordenação em quaisquer state changes ou events. *** **`CameraMode`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/camera_mode.proto#L8) Pode ser usado para determinar se o jogador está em visão em primeira pessoa ou terceira pessoa. *** **`PointerLock`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_lock.proto#L7) Pode ser usado para determinar se o mouse pointer está seguindo automaticamente o ponto de foco da câmera (locked) ou pode se mover livremente na tela (unlocked). Está anexado ao [`CameraEntity`](https://github.com/decentraland/docs/tree/main/contributor/runtime/entities/README.md#CameraEntity), e seu state pode ser lido (mas não escrito) a partir da Scene. *** **`PointerEvents`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_events.proto#L17) Mostra feedback visual quando o pointer clica ou passa sobre uma Entity. *** **`PointerEventsResult`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_events_result.proto#L13) Contém informações sobre a entrada recente do jogador, incluindo teclas e ações do ponteiro. Está anexado ao `RootEntity`, e atualizado pelo runtime com quaisquer novos events a cada frame. *** **`Raycast`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/raycast.proto#L15) Pode ser anexado a uma Entity para solicitar um raycast do game engine. O `RaycastResult` component será posteriormente anexado à mesma entity. A origem, a direção e o comprimento máximo do ray podem ser configurados. *** **`RaycastResult`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/raycast_result.proto#L9) Anexado pelo runtime a Entities que têm um [`Raycast`](#Raycast) component com resultados pendentes. Contém informações sobre o ray original e identifica quaisquer Entities atingidas. ### Media Components Scenes podem anexar components especiais para exibir imagens, mostrar video ou reproduzir sons. *** **`AudioSource`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/audio_source.proto#L7) Reproduz um clipe de áudio incluído com a Scene, dado o [caminho do arquivo em seu manifest](https://github.com/decentraland/docs/tree/main/contributor/content/entities/README.md#files). O som se origina da posição da entity associada. Seu pitch, volume e comportamento de looping podem ser configurados, e o estado do reprodutor de áudio pode ser lido. {% hint style="info" %} Em preparação para futuras atualizações, o campo em `AudioSource` é chamado `audio_clip_url`, mas na versão atual do protocolo, na verdade é o caminho definido no manifest. {% endhint %} *** **`AudioStream`** [**↗ fonte**](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 específica, o som não é afetado pela sua posição. Seu volume pode ser configurado, e o state do reprodutor de áudio pode ser lido. *** **`NftShape`** [**↗ fonte**](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 video. Renderiza um Canvas 2D com uma moldura decorativa configurável. ### Area Components Esses components permitem que scenes modifiquem o comportamento padrão de Entities dentro de limites especificados. *** **`AvatarModifierArea`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/avatar_modifier_area.proto#L15) Altera o comportamento de avatars dentro de um espaço centrado em uma Entity. É definido com um vetor de tamanho 3D e pode afetar se avatars estão visíveis ou clicáveis. Avatars específicos podem ser excluídos desse efeito com base no user ID do usuário. *** **`CameraModeArea`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/camera_mode_area.proto#L11) Altera o CameraMode (1st-person ou 3rd-person) dentro de um espaço centrado em uma Entity. É definido com um vetor de tamanho 3D e um CameraMode desejado. ### UI Components Os seguintes components são usados para criar interfaces gráficas que flutuam sobre o mundo do jogo. Geralmente, são anexados a conjuntos de Entities que têm components hierárquicos [`UiTransform`](#UiTransform) components, relacionados entre si por meio do `parent` atributo. Por exemplo, uma janela flutuante de opções poderia ser uma Entity com um [`UiTransform`](#UiTransform) e um [`UiBackground`](#UiBackground) component, além de uma Entity com um filho [`UiTransform`](#UiTransform) e um [`UiDropdown`](#UiDropdown). *** **`UiTransform`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_transform.proto#L77) Descreve o tamanho, posicionamento, margem e preenchimento de um UI component. Baseia-se no modelo flexbox e é altamente personalizável. *** **`UiBackground`** [**↗ fonte**](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 UI Entity. *** **`UiDropdown`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_dropdown.proto#L11) Define uma lista de opções mutuamente exclusivas a serem exibidas em um dropdown widget. *** **`UiDropdownResult`** [**↗ fonte**](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 Scene. *** **`UiInput`** [**↗ fonte**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/ui_input.proto#L11) Define um text input widget, com alguma margem para personalização. *** **`UiInputResult`** [**↗ fonte**](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 Scene. *** **`UiText`** [**↗ fonte**](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. *** --- # 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/contributor/contributor-pt/runtime-da-scene/basic-components.md?ask=&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.