> 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/arquitetura/entities-components.md). # Entities e Components Aprenda o essencial sobre entities e components em uma scene do Decentraland As scenes do Decentraland são construídas em torno de [*entities*, *components* e *systems*](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system). Este é um padrão comum usado na arquitetura de vários game engines, que permite fácil composabilidade e escalabilidade. ![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-de62a18d51b28bebd55c86e8ef5a8a783467ae62%2Fecs-big-picture.png?alt=media\&token=0d7a02a2-955a-44ed-ae77-5df99c49e530) ## Vista geral *Entities* são a unidade básica para construir tudo nas scenes do Decentraland. Todos os objetos 3D visíveis e invisíveis e players de áudio na sua scene serão cada um uma entity. Uma entity nada mais é do que um id, que pode ser referenciado por components. A entity em si não tem propriedades nem métodos próprios; ela serve simplesmente para agrupar vários components juntos. *Componentes* definem os atributos de uma entity. Por exemplo, um `Transform` component armazena as coordenadas, rotação e escala da entity. Um `MeshRenderer` component dá à entity uma forma visível (como um cubo ou uma esfera) quando renderizada na scene, um `Material` component dá à entity uma cor ou textura. Você também pode criar custom components para atender aos dados necessários da sua scene, por exemplo um custom `health` poderia armazenar o valor de health restante de uma entity e adicioná-lo a entities que representam inimigos não jogadores em um jogo. Se você está familiarizado com web development, pense em entities como o equivalente a *Elements* num *DOM* tree, e de components como *attributes* daqueles Elements. No [Scene Editor no Creator Hub](/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md), você pode visualizar os components que pertencem a uma entity selecionando-a. ![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-2ffe3126d7a92824658497ed2664fcfcc28ce16a%2Fcomponents-example.png?alt=media\&token=543af76c-1c78-4a46-8238-d22a92fe16cc) {% hint style="warning" %} **📔 Observação**: Nas versões anteriores do SDK, Entities eram *objects* que eram instanciados e podiam ser estendidos para adicionar functions. A partir da versão 7.0 do SDK, entities são apenas um ID. Essa estrutura se encaixa melhor nos princípios de [programação orientada a dados](/creator/content-creator-pt/scenes-sdk7/arquitetura/data-oriented-programming.md) e pode ajudar no desempenho da scene. {% endhint %} ![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-ee29a02358e859a30079072e8da958b899aea659%2Fecs-components-new.png?alt=media\&token=c9ecdd6f-77bf-4b98-80aa-2b806c3e8949) Components como `Transform`, `Material` ou qualquer um dos *shape* components estão intimamente ligados ao rendering da scene. Se os valores nesses components mudarem, isso por si só é suficiente para o engine mudar como a scene é renderizada no próximo frame. O engine é a parte da scene que fica no meio e gerencia todas as outras partes. Ele determina quais entities são renderizadas e como os players interagem com elas. Ele também coordena quais functions de [systems](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) são executadas e quando. Components servem para armazenar dados sobre sua referenced entity. Eles só podem armazenar esses dados, não podem modificá-los por conta própria. Todas as mudanças nos valores dos components são realizadas por [Systems](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md). *systems* Systems são completamente desacoplados dos components e das entities em si. Entities e components são agnósticos em relação a quais ## estão atuando sobre eles. O exemplo abaixo mostra algumas operações básicas para declarar e configurar entities e components básicos. ```ts export function main() { // Criar uma entity const door = engine.addEntity() // Dar à entity uma posição por meio de um Transform component Transform.create(door, { position: Vector3.create(5, 1, 5), }) // Dar à entity uma forma visível por meio de um GltfContainer component GltfContainer.create(door, { src: 'assets/models/door.glb', }) } ``` {% hint style="warning" %} **📔 Observação**: Nas versões anteriores do SDK, era necessário adicionar manualmente uma entity ao engine para começar a renderizá-la. A partir da versão 7 do SDK, entities são implicitamente adicionadas ao engine assim que recebem um component. {% endhint %} Quando um component é criado, ele sempre é atribuído a uma parent entity. Os valores do component então afetam a entity. {% hint style="info" %} **💡 Dica**: Em vez de criar entities uma por uma, você pode spawn uma tree inteira de entities e components de uma vez a partir de um [composite](/creator/content-creator-pt/scenes-sdk7/arquitetura/composites.md) arquivo. {% endhint %} ## Remover entities Para remover uma entity do engine, use `engine.removeEntity()`. Esta function retorna um `boolean`: `true` se a entity foi removida, `false` se a remoção foi recusada. ```ts export function main() { // Criar uma entity const door = engine.addEntity() // Dar à entity uma forma visível por meio de um GltfContainer component GltfContainer.create(door, { src: 'assets/models/door.glb', }) // Remover entity const removed = engine.removeEntity(door) console.log('Entity removida:', removed) // true } ``` Se uma entity removida tiver any child entities, elas voltam a ter como parent o padrão `engine.RootEntity` entity, que é posicionada na base position da scene, com uma scale de *1*. ### Entities reservadas pelo renderer Alguns entity ids são reservados pelo renderer para avatars de jogadores remotos. Você não pode remover essas entities. Se você chamar `engine.removeEntity()` em uma entity reservada pelo renderer, ele retorna `false` e deixa todos os components intocados. O [entities reservadas nomeadas](#reserved-entities) (`engine.RootEntity`, `engine.PlayerEntity`, `engine.CameraEntity`) são um caso especial: `engine.removeEntity()` ainda retorna `false` para estas (seus ids nunca são liberados), mas seus components **são** são purged. Isso significa que você pode limpar seus próprios components delas (por exemplo, removendo um `InputModifier` de `engine.PlayerEntity`), mesmo que o entity id em si nunca seja liberado. ```ts // Tentando remover uma entity reservada const result = engine.removeEntity(engine.PlayerEntity) console.log(result) // false — o entity id não é liberado // Mas os próprios components da scene em PlayerEntity são purged ``` Você pode verificar o valor de retorno ao remover entities para lidar com edge cases: ```ts if (!engine.removeEntity(someEntity)) { console.log('Entity não pôde ser removida (reservada)') } ``` ### Remover uma entity com seus children Para remover uma entity e também todos os seus children (e quaisquer children dos seus children, recursivamente), use o `removeEntityWithChildren()` helper. ```ts export function main() { // Criar entity pai const door = engine.addEntity() // Criar entity filha const doorKnob = engine.addEntity() // Dar às entities uma forma visível GltfContainer.create(door, { src: 'models/door.glb', }) GltfContainer.create(doorKnob, { src: 'models/doorKnob.glb', }) // Parent Transform.create(doorKnob, { parent: door, }) // Remover tanto o parent quanto os children removeEntityWithChildren(engine, door) } ``` {% hint style="warning" %} **Observação:** Se uma entity reservada pelo renderer estiver em qualquer lugar na tree, `removeEntityWithChildren` remove todos os outros descendants, mas deixa a entity reservada no lugar. O `Transform.parent` apontará para uma entity removida. Isso só acontece se a sua scene definir uma entity reservada como child de uma scene entity, o que é incomum. {% endhint %} {% hint style="info" %} **💡 Dica**: Em vez de remover uma entity do engine, em alguns casos pode ser melhor torná-la invisible, caso você queira poder carregá-la novamente sem qualquer delay. Veja [Tornar invisível](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/shape-components.md#make-invisible) {% endhint %} ### Removendo entities nos bastidores Uma entity é apenas um id referenciado por seus components. Então, ao remover uma entity, você está realmente removendo cada um dos components que referenciam essa entity. Se você remover manualmente todos os components de uma entity, para o player isso parecerá o mesmo que fazer `engine.removeEntity()`. No entanto, `engine.removeEntity()` também realiza algum bookkeeping interno extra, marcando o entity id como não mais em uso, então essa é sempre a forma recomendada de remover uma entity. ## Entities aninhadas Uma entity pode ter outras entities como children. Graças a isso, podemos organizar entities em trees, assim como o HTML de uma página da web. ![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-8b6c8cd679f648a41400eb6f29889cd09ede8947%2Fecs-nested-entities-new.png?alt=media\&token=847cb6ef-9cee-49ea-9894-b294e72341d2) Para definir uma entity como parent de outra, a child entity deve ter um `Transform` component. Você então pode definir o `parent` field com uma referência à parent entity. ```ts export function main() { // Criar entidades const parentEntity = engine.addEntity() const childEntity = engine.addEntity() // Definir parent Transform.create(childEntity, { parent: parentEntity, }) } ``` Uma vez que um parent é atribuído, ele pode ser lido na child entity a partir do `parent` field em seu `Transform` component. ```ts // Obter parent de uma entity const parent = Transform.get(childEntity).parent ``` Se uma parent entity tiver um `Transform` component que afeta sua position, scale ou rotation, suas children entities também são afetadas. Quaisquer valores de position ou rotation são somados; quaisquer valores de scale são multiplicados. Se a parent ou a child entity não tiver um `Transform` component, os seguintes default values são usados. * Para **position**o center do parent é *0, 0, 0* * Para **rotation** a rotation do parent é o quaternion *0, 0, 0, 1* (equivalente aos Euler angles *0, 0, 0*) * Para **scale**, considera-se que o parent tem um size de *1*. Qualquer redimensionamento do parent afeta scale e position proporcionalmente. Entities sem component de shape são invisíveis na scene. Elas podem ser usadas como wrappers para lidar com e posicionar várias entities como um grupo. Para separar uma child entity de seu parent, você pode atribuir o parent da entity a `engine.RootEntity`. ```ts const mutableChildTransform = Transform.getMutable(childEntity) mutableChildTransform.parent = engine.RootEntity ``` {% hint style="warning" %} **📔 Observação**: Ao lidar com entities aninhadas que estão sincronizadas com outros players, use a `parentEntity()` função em vez da `parent` entity no Transform. Veja [Entities parentadas](/creator/content-creator-pt/scenes-sdk7/rede/serverless-multiplayer.md#parented-entities) {% endhint %} No Scene Editor, você pode ver toda a hierarchy de entities aninhadas na sua scene no painel lateral esquerdo. ![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-60929069a225f48ce0d6c94d9dce285ff875af10%2Fentity-tree-example.png?alt=media\&token=b2baf1b6-e035-4ae5-92fc-509628408f8d) ## Obter uma entity por ID Cada entity na sua scene tem um número único *id*. Você pode recuperar um component que se refere a uma entity específica do engine com base nesse ID. ```typescript // buscar um Transform component Transform.get(1000 as Entity) ``` {% hint style="warning" %} **📔 Observação**: Os entity ids entre *0* e *511* são reservados pelo engine para entities fixas, como o avatar do player, a base scene, etc. {% endhint %} Por exemplo, se um click do player ou um [raycast](/creator/content-creator-pt/scenes-sdk7/interatividade/raycasting.md) atinge uma entity, isso retornará o id da entity atingida, e você pode usar o comando acima para buscar o Transform component da entity que corresponde a esse id. Você também pode buscar qualquer outro component dessa entity da mesma forma. ## Obter uma entity por name Ao adicionar entities via drag-and-drop no Scene Editor, cada entity tem um name único. Use a `engine.getEntityOrNullByName()` function para referenciar uma dessas entities no seu code. Passe o name da entity como uma string, exatamente como escrito na UI do Scene Editor, na tree view à esquerda. ```ts function main() { const door = engine.getEntityOrNullByName('door3') } ``` {% hint style="warning" %} **📔 Observação**: Certifique-se de usar apenas `engine.getEntityOrNullByName()` dentro da `main()` function, em funções que executam depois de `main()`, ou em um system. Se usado fora de um desses contextos, as entities criadas na UI do Scene Editor podem ainda não ter sido instanciadas. {% endhint %} Você pode realizar qualquer ação em uma entity recuperada por esse método, como adicionar ou remover components, modificar valores de components existentes ou remover a entity do engine. ```ts function main() { // obter entity const door = engine.getEntityOrNullByName('door-3') // verificar se a entity existe if (door) { // adicionar um callback de PointerEvents pointerEventsSystem.onPointerDown( { entity: door, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Abrir' }, }, function () { // abrir porta } ) } } ``` Todas as entities adicionadas pela UI do Scene Editor têm um `Nome` component, você pode iterar sobre todas elas assim: ```ts function main() { for (const [entity, name] of engine.getEntitiesWith(Name)) { console.log({ entity, name }) } } ``` ## Adicionar ou substituir um component Cada entity pode ter apenas um component de um determinado tipo. Por exemplo, se você tentar atribuir um Transform a uma entity que já tenha um, isso causará um error. Para evitar esse error, você pode usar `.createOrReplace` em vez da `.create`. Este comando sobrescreve quaisquer components existentes do mesmo tipo, se eles existirem; caso contrário, cria um novo component assim como `.create`. ```ts Transform.createOrReplace(door, { position: Vector3.create(5, 1, 5), }) ``` {% hint style="warning" %} **📔 Observação**: Como `.createOrReplace` executa uma verificação adicional antes de criar o component, é sempre mais performático usar `.create`. Se você tiver certeza de que a entity ainda não tem um component como o que está adicionando, use `.create`. {% endhint %} ## Acessar um component de uma entity Você pode acessar components de uma entity usando o `.get()` ou no `getMutable()` funções. ```ts export function main() { // Criar entity const box = engine.addEntity() // Criar e adicionar component a essa entity Transform.create(box) // Obter a versão read-only do component let transform = Transform.get(box) // Obter a versão mutable do component let transform = Transform.getMutable(box) } ``` O `get()` function obtém uma referência read-only ao component. Você não pode alterar nenhum valor a partir dessa referência do component. Se você quiser alterar os valores do component, use a `getMutable()` function em vez disso. Se você alterar os valores na versão mutable do component, estará afetando diretamente a entity à qual esse component pertence. Veja [dados mutáveis](/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/mutable-data.md) para mais detalhes. {% hint style="warning" %} **📔 Observação**: Use apenas `getMutable()` se você realmente for fazer alterações nos valores do component. Caso contrário, use sempre `get()`. Essa prática segue os princípios de [programação orientada a dados](/creator/content-creator-pt/scenes-sdk7/arquitetura/data-oriented-programming.md), e pode ajudar significativamente no desempenho da scene. {% endhint %} ```ts // Obter a versão mutable do component let transform = Transform.getMutable(box) // alterar um valor do component transform.scale.x = 5 ``` O exemplo acima modifica diretamente o valor da *x* scale no Transform component. Se você não tiver certeza absoluta de que a entity possui o component que está tentando recuperar, use `getOrNull()` ou `getMutableOrNull()`. {% hint style="warning" %} **📔 Observação**: Evite usar `getOrNull()` ou `getMutableOrNull()` quando possível, pois essas functions envolvem verificações adicionais e, portanto, são menos eficientes que `.get()` e `getMutable()`. {% endhint %} ```ts // getOrNull const transformOrNull = Transform.getOrNull(myEntity) // getMutableOrNull const mutableTransformOrNull = Transform.getMutableOrNull(myEntity) ``` Se o component que você está tentando recuperar não existir na entity: * `get()` e `getMutable()` retorna um erro. * `getOrNull()` e `getMutableOrNull()` retorna `Null`. ## Remover um component de uma entity Para remover um component de uma entity, use o `deleteFrom()` método do tipo de component. ```ts Transform.deleteFrom(myEntity) ``` Se você tentar remover um component que não existe na entity, essa ação não gerará erros. {% hint style="warning" %} **📔 Observação**: Para remover todos os components de uma entity de uma vez, veja [esta seção](#remove-entities) {% endhint %} ## Verificar a existência de um component Você pode verificar se uma entity possui uma instância de um determinado component usando a `has()` function. Essa function retorna *true* se o component estiver presente, e *false* se não estiver. Isso pode ser muito útil para usar em lógica condicional na sua scene. ```ts const hasTransform = Transform.has(myEntity) ``` {% hint style="info" %} **💡 Dica**: Você também pode [consultar components](/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md) para buscar uma lista completa de components que possuem um component específico, ou um conjunto específico de components. Não itere manualmente por todas as entities na scene para verificar cada uma com um `has()`, essa abordagem é muito menos eficiente. {% endhint %} ## Verificar alterações em um component Use o `onChange` function para executar uma callback function sempre que os valores do component mudarem para uma determinada entity. Isso funciona com qualquer component e é um ótimo atalho para ajudar a manter seu code legível. A callback function pode incluir um parâmetro de input que contém o novo state do component. ```ts Transform.onChange(cubeEntity, (newTransform) => { if (!newTransform) return console.log( 'Posição do Cube alterada: ', newTransform.position, newTransform.rotation ) }) VisibilityComponent.onChange(cubeEntity, (newVisibilityComponent) => { if (!newVisibilityComponent) return console.log('Visibilidade do Cube alterada: ', newVisibilityComponent.visible) }) ``` Se o component for removido da entity, então a function é chamada com um input de `undefined`. {% hint style="info" %} **💡 Dica**: A `.onChange()` function funciona tanto com native components do SDK quanto com [custom components](/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md) definidos pelo creator. {% endhint %} ## Obter child entities Para acessar todas as entities que são children diretas de uma parent entity, use `getEntitiesWithParent`. Ele recebe como argumentos o `engine` quanto a `parent` entity e retorna uma lista de todas as entities que têm essa entity específica como parent. Note que ele retorna apenas children diretas, não children de children. ```ts import { getEntitiesWithParent } from '@dcl/sdk/ecs' const children = getEntitiesWithParent(engine, myEntity) for (const child of children) { // processar cada entity filha } ``` Para acessar todos os descendants de uma entity, independentemente de quão aninhados estejam, use a function `getComponentEntityTree()`. Em vez de percorrer manualmente a hierarchy nível por nível, essa function retorna uma lista plana de todos os descendants, fácil de iterar. Ela também filtra apenas entities que possuem um component ou lista de components específicos. ```ts import { getComponentEntityTree } from '@dcl/sdk/ecs' export function main() { // Criar uma parent entity com children aninhadas const parentEntity = engine.addEntity() Transform.create(parentEntity, { position: Vector3.create(8, 0, 8), }) // ... assuma que o parent tem vários children e grandchildren // Iterar sobre todos os descendants da parent entity for (const descendantEntity of getComponentEntityTree( engine, parentEntity, Transform )) { // Acessar cada descendant entity const transform = Transform.get(descendantEntity) console.log('Posição do descendant:', transform.position) } } ``` O `getComponentEntityTree` função recebe três parâmetros: * `engine`: A instância do engine que executa as entities * `entity`: A root entity da qual iniciar * `component`: O component pelo qual filtrar (normalmente `Transform` para spatial hierarchies) A function retorna um generator que produz cada descendant entity na estrutura de tree. Somente entities que têm o component especificado serão incluídas nos resultados. Você pode combinar isso com outras verificações de components para encontrar entities específicas na sua hierarchy: ```ts // Encontrar todos os descendants com um name específico for (const descendantEntity of getComponentEntityTree( engine, parentEntity, Transform )) { const name = Name.getOrNull(descendantEntity) if (name && name.value === 'targetEntity') { console.log('Entity alvo encontrada:', descendantEntity) } } ``` ## Entidades reservadas Certos entity ids são reservados para entities especiais que existem em toda scene. Elas podem ser acessadas por meio dos seguintes aliases: * `engine.RootEntity` * `engine.PlayerEntity` * `engine.CameraEntity` {% hint style="warning" %} **📔 Observação**: Evite referir-se a essas entities antes que sejam inicializadas. Para evitar esse problema, referencie essas entities na `main()` function, ou em um system. {% endhint %} ## A root entity Todas as entities na scene são children da `engine.RootEntity`, direta ou indiretamente. Esta entity não possui um Transform component, mas é usada para lidar com vários components que representam configurações mais globais, como [controle de skybox](/creator/content-creator-pt/scenes-sdk7/interatividade/skybox-control.md), [posição do cursor](/creator/content-creator-pt/scenes-sdk7/interatividade/user-data.md#check-the-players-cursor-position), ou [dimensões da tela](/creator/content-creator-pt/scenes-sdk7/ui-2d/ui-positioning.md#responsive-ui-size). ## A player entity O `engine.PlayerEntity` entity representa o avatar do player. Busque o `Transform` component para obter a position e a rotation atuais do player, veja [dados do usuário](/creator/content-creator-pt/scenes-sdk7/interatividade/user-data.md). O Transform do player é read-only; para modificá-lo, use a `movePlayerTo()` function, [saiba mais](/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/move-player.md). Você também pode anexar objects ao player definindo-os como children dessa entity, embora a [Attach to Player](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md#attach-an-entity-to-an-avatar) seja frequentemente a melhor opção para isso. ## A camera entity O `engine.CameraEntity` entity representa a camera do player. Busque o `Transform` component para obter a position e a rotation da camera. O Transform dessa entity também é read-only. Para modificar o ângulo ou a position da camera, use uma [Virtual camera](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/camera.md#using-virtual-cameras). Você também pode buscar o `CameraMode` component para saber se o player está usando o modo de camera em 1ª ou 3ª pessoa, veja [modo de camera](/creator/content-creator-pt/scenes-sdk7/interatividade/user-data.md#check-the-players-camera-mode). --- # 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/arquitetura/entities-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.