> 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 oferece suporte a uma lista de components básicos que compartilham sua definição com scenes, fornecendo suporte integrado para posicionamento, animação, media e consultas de estado do world Existem cinco tipos de components: 1. [Components de objeto](#object) adicionam propriedades visuais e físicas às Entities. 2. [Components de jogo](#game) podem solicitar actions e receber informações do game engine. 3. [Components de media](#media) podem exibir images e reproduzir sounds. 4. [Components de área](#area) alteram o comportamento de Entities em zonas específicas. 5. [Components de UI](#ui) permitem que scenes renderizem interfaces flutuantes. Exceto por [`Transform`](#Transform), que é especificado em detalhe 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. ### Components de objeto Os components mais comuns são aqueles que anexam propriedades visuais e físicas a uma Entity. Eles podem ser usados para posicionar, redimensionar, pintar e adicionar collision a objetos in-game. *** **`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 ao longo do ciclo de vida de uma scene. Por isso, `Transform` não é serializado usando protocol buffers e, em vez disso, é empacotado em uma estrutura customizada. `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 um `Transform` reside pode ser copiada, compartilhada e apontada diretamente. As Coordinates 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/tree/main/contributor/runtime/entities/README.md#RootEntity) ID (`0`), qualquer `Transform` é relativa 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 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 collision 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 collision mesh personalizada, use [`GltfContainer`](#GltfContainer). *** **`Material`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/material.proto#L19) Define as propriedades de texture, lighting, cor e transparência de uma Entity que também tenha 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 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/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`** [**↗ 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 ficar de frente para a camera, ou opcionalmente para outra Entity referenciada via `target_entity`. Como o nome indica, é usado para exibir billboards in-game e frequentemente combinado com [`TextShape`](#TextShape). Ele afeta todas as direções por padrão, mas pode ser configurado para girar apenas em um eixo. Se a target Entity referenciada não existir, a reorientação é suspensa até que ela exista. *** **`Animator`** [**↗ source**](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. As scenes podem definir o estado do component para customizar, reproduzir e fazer transição entre animations, além de lê-lo para verificar quais animations estão disponíveis ou sendo reproduzidas no momento. *** **`AvatarAttach`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/avatar_attach.proto#L16) Indica que a position 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`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/text_shape.proto#L11) Renderiza texto na position de uma Entity, dada por sua `Transform`. É altamente configurável, com suporte a parâmetros como size, margin, padding, color, shadow e mais. *** **`Visibility`** [**↗ source**](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 exibem o comportamento de quaisquer outros components 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 seu body shape, colors, wearables e estado transitório. Este component é anexado a entities no [avatar scene](https://github.com/decentraland/docs/tree/main/contributor/runtime/execution/README.md#avatarScene). ### Components de jogo Alguns components básicos podem ser usados pela scene e pelo runtime para trocar informações. Eles aproveitam 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 para quaisquer alterações de state ou events. *** **`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á seguindo automaticamente o ponto de foco da camera (locked) ou se pode mover-se livremente na tela (unlocked). Está anexado à [`CameraEntity`](https://github.com/decentraland/docs/tree/main/contributor/runtime/entities/README.md#CameraEntity), e seu estado pode ser lido (mas não escrito) a partir da scene. *** **`PointerEvents`** [**↗ source**](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`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/pointer_events_result.proto#L13) Contém informações sobre entradas recentes do jogador, incluindo keys e pointer actions. Está anexado à `RootEntity`, e atualizado pelo runtime com quaisquer novos events 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 game engine. O `RaycastResult` component será anexado posteriormente à mesma entity. A origem, direção e comprimento máximo do ray 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 possuem um [`Raycast`](#Raycast) component com resultados pendentes. Contém informações sobre o ray original e identifica quaisquer Entities que foram atingidas. ### Components de media As scenes podem anexar components especiais para exibir images, mostrar video ou reproduzir sounds. *** **`AudioSource`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/audio_source.proto#L7) Reproduz um audio clip incluído com a scene, dado o [caminho do file no seu manifest](https://github.com/decentraland/docs/tree/main/contributor/content/entities/README.md#files). O sound se origina da position da entity associada. Seu pitch, volume e comportamento de looping podem ser definidos, e o estado do audio player 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`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/audio_stream.proto#L7) Semelhante a [AudioSource](#AudioSource), mas o audio é transmitido em tempo real a partir de uma URL externa. Apesar de estar anexado a uma entity específica, o sound não é afetado por sua position. Seu volume pode ser definido, e o estado do audio player 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 video. Renderiza um canvas 2D com uma moldura decorativa configurável. ### Components de área Estes components permitem que scenes modifiquem o comportamento padrão de 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 de avatars dentro de um espaço centrado em uma Entity. É definido com um vector de size 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. *** **`CameraModeArea`** [**↗ source**](https://github.com/decentraland/protocol/blob/ccb88d679f20c0e22840c324879d7b2535f6c9a6/proto/decentraland/sdk/components/camera_mode_area.proto#L11) Altera o camera mode (1st-person ou 3rd-person) dentro de um espaço centrado em uma Entity. É definido com um vector de size 3D e um camera mode desejado. ### Components de UI Os seguintes components são usados para criar interfaces gráficas que flutuam sobre o game world. Eles geralmente são anexados a conjuntos de Entities que possuem hierarchical [`UiTransform`](#UiTransform) components, relacionados uns aos outros 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, mais uma Entity com um child [`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 size, posicionamento, margin e padding de um UI component. É 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 texture para usar como background em uma UI Entity. *** **`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 serem exibidas 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 scene. *** **`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 margin para customizaçã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 scene. *** **`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 margin para customizaçã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 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/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 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.