> 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 componibilidade 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) ## Visão 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, um entity. Um entity não é nada mais do que um id, que pode ser referenciado por components. O entity em si não tem propriedades nem métodos próprios; ele simplesmente serve para agrupar vários components juntos. *Components* definem as características 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 renderizado na scene, um `Material` component dá à entity uma cor ou texture. Você também pode criar custom components para servir 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 às entities que representam inimigos não jogadores em um jogo. Se você está familiarizado com desenvolvimento web, pense em entities como o equivalente de *Elementos* em um *DOM* tree, e de components como *atributos* desses elementos. No [Scene Editor em Creator Hub](/creator/content-creator-pt/scene-editor/comece/about-editor.md), você pode ver 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) {% hint style="warning" %} **📔 Nota**: Nas versões anteriores do SDK, Entities eram *objetos* que eram instanciados e podiam ser estendidos para adicionar funções. 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) Components como `Transform`, `Material` ou qualquer um dos *shape* components estão intimamente ligados à renderização da scene. Se os valores nesses components mudarem, isso por si só já é suficiente para que o engine mude 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 funções de [systems](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) são executadas e quando. Components destinam-se a armazenar dados sobre a entity referenciada. Elas só podem armazenar esses dados; não podem modificá-los por conta própria. Todas as alterações nos valores dos components são realizadas por [Systems](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md). Systems são completamente desacoplados dos components e das entities em si. Entities e components são indiferentes a quais *systems* estão agindo sobre eles. ## Sintaxe para entities e components 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 component Transform Transform.create(door, { position: Vector3.create(5, 1, 5), }) // Dar à entity uma forma visível por meio de um component GltfContainer GltfContainer.create(door, { src: 'assets/models/door.glb', }) } ``` {% hint style="warning" %} **📔 Nota**: 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 adicionadas implicitamente ao engine assim que recebem um component. {% endhint %} Quando um component é criado, ele sempre é atribuído a uma entity pai. Os valores do component então afetam a entity. {% hint style="info" %} **💡 Dica**: Em vez de criar entities uma a uma, você pode spawnar 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 função 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 component GltfContainer 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, estas mudam o pai de volta para o default `engine.RootEntity` entity, que é posicionada na posição base da scene, com uma escala de *1*. ### Entities reservadas pelo Renderer Alguns ids de entity são reservados pelo renderer para avatares de players remotos. Você não pode remover essas entities. Se você chamar `engine.removeEntity()` em uma renderer-reserved entity, 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** removidos. Isso significa que você pode limpar seus próprios components deles (por exemplo, removendo um `InputModifier` de `engine.PlayerEntity`), mesmo que o próprio id da entity nunca seja liberado. ```ts // Tentando remover uma entity reservada const result = engine.removeEntity(engine.PlayerEntity) console.log(result) // false — o id da entity não é liberado // Mas os components da própria scene em PlayerEntity são removidos ``` Você pode verificar o valor de retorno ao remover entities para lidar com casos especiais: ```ts if (!engine.removeEntity(someEntity)) { console.log('Entity não pôde ser removida (reservada)') } ``` ### Remover uma entity com suas entities filhas Para remover uma entity e também todas as suas entities filhas (e quaisquer entities filhas das suas filhas, 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', }) // Pai Transform.create(doorKnob, { parent: door, }) // Remover pai e filhas removeEntityWithChildren(engine, door) } ``` {% hint style="warning" %} **Nota:** Se uma entity reservada pelo renderer estiver em qualquer parte da tree, `removeEntityWithChildren` remove todos os outros descendants, mas deixa a entity reservada no lugar. O Transform.parent da entity reservada `Transform.parent` apontará para uma entity removida. Isso só acontece se a sua scene colocar uma entity reservada como filha de uma entity da scene, o que é incomum. {% endhint %} {% hint style="info" %} **💡 Dica**: Em vez de remover uma entity do engine, em alguns casos pode ser melhor torná-la invisível, caso você queira poder carregá-la novamente sem atraso. Veja [Tornar invisível](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/shape-components.md#make-invisible) {% endhint %} ### Removendo entities em segundo plano Uma entity é apenas um id referenciado por seus components. Então, ao remover uma entity, você está na verdade removendo cada um dos components que referenciam essa entity. Se você remover manualmente todos os components de uma entity, para o player parecerá o mesmo que fazer `engine.removeEntity()`. No entanto, `engine.removeEntity()` também realiza alguma contabilidade interna extra, marcando o id da entity como não estando mais em uso; portanto, esta é sempre a forma recomendada de remover uma entity. ## entities aninhadas Uma entity pode ter outras entities como filhas. Graças a isso, podemos organizar entities em trees, assim como o HTML de uma página 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) Para definir uma entity como pai de outra, a child entity deve ter um `Transform` component Transform. Você então pode definir o `parent` field com uma referência à entity pai. ```ts export function main() { // Criar entities const parentEntity = engine.addEntity() const childEntity = engine.addEntity() // Definir pai Transform.create(childEntity, { parent: parentEntity, }) } ``` Uma vez atribuído um pai, ele pode ser lido na child entity a partir do `parent` field no seu `Transform` componente. ```ts // Obter pai de uma entity const parent = Transform.get(childEntity).parent ``` Se uma parent entity tiver um `Transform` component que afeta sua posição, scale ou rotação, suas child entities também são afetadas. Quaisquer valores de posição ou rotação são somados; quaisquer valores de scale são multiplicados. Se a entity pai ou a child entity não tiver um `Transform` component, os seguintes valores padrão são usados. * Para **position**, o centro do pai é *0, 0, 0* * Para **rotation** a rotação do pai é o quaternion *0, 0, 0, 1* (equivalente aos ângulos de Euler *0, 0, 0*) * Para **scale**, o pai é considerado como tendo um tamanho de *1*. Qualquer redimensionamento do pai afeta scale e position na mesma proporção. Entities sem um shape component são invisíveis na scene. Elas podem ser usadas como wrappers para gerenciar e posicionar várias entities como um grupo. Para separar uma child entity de seu pai, você pode atribuir o parent da entity para `engine.RootEntity`. ```ts const mutableChildTransform = Transform.getMutable(childEntity) mutableChildTransform.parent = engine.RootEntity ``` {% hint style="warning" %} **📔 Nota**: 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 com parent](/creator/content-creator-pt/scenes-sdk7/networking/serverless-multiplayer.md#parented-entities) {% endhint %} No Scene Editor, você pode ver toda a hierarquia 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) ## Obter uma entity por ID Toda entity na sua scene tem um número único *id*. Você pode recuperar do engine um component que se refere a uma entity específica com base nesse ID. ```typescript // obter um component Transform Transform.get(1000 as Entity) ``` {% hint style="warning" %} **📔 Nota**: Os ids de entity entre *0* e *511* são reservados pelo engine para entities fixas, como o avatar do player, a scene base etc. {% endhint %} Por exemplo, se o clique de um 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 obter o component Transform da entity que corresponde a esse id. Você também pode obter qualquer outro component dessa entity da mesma forma. ## Obter uma entity por nome Ao adicionar entities via drag-and-drop no Scene Editor, cada entity tem um nome único. Use a `engine.getEntityOrNullByName()` função para referenciar uma dessas entities no seu código. Passe o nome da entity como uma string, conforme escrito na UI do Scene Editor, na tree view à esquerda. ```ts function main() { const door = engine.getEntityOrNullByName('door3') } ``` {% hint style="warning" %} **📔 Nota**: Certifique-se de usar apenas `engine.getEntityOrNullByName()` dentro da `main()` função, em functions que executam após `main()`, ou em um system. Se usado fora de um desses contextos, as entities criadas na UI do Scene Editor talvez ainda não tenham sido instanciadas. {% endhint %} Você está livre para realizar qualquer ação em uma entity obtida 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 uma callback de pointer events pointerEventsSystem.onPointerDown( { entity: door, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Abrir' }, }, function () { // abrir a door } ) } } ``` Todas as entities adicionadas pela UI do Scene Editor têm um `Name` 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 erro. Para evitar esse erro, você pode usar `.createOrReplace` em vez de `.create`. Este comando sobrescreve quaisquer components existentes do mesmo tipo se eles existirem; caso contrário, cria um novo component exatamente como `.create`. ```ts Transform.createOrReplace(door, { position: Vector3.create(5, 1, 5), }) ``` {% hint style="warning" %} **📔 Nota**: 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 a `.get()` ou `getMutable()` funções. ```ts export function main() { // Criar entity const box = engine.addEntity() // Criar e adicionar component a essa entity Transform.create(box) // Obter versão somente leitura do component let transform = Transform.get(box) // Obter versão mutável do component let transform = Transform.getMutable(box) } ``` O `get()` função obtém uma referência somente leitura ao component. Você não pode alterar nenhum valor a partir dessa referência do component. Se você desejar alterar os valores do component, use a `getMutable()` função em vez disso. Se você alterar os valores na versão mutável 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" %} **📔 Nota**: 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 versão mutável do component let transform = Transform.getMutable(box) // alterar um valor do component transform.scale.x = 5 ``` O exemplo acima modifica diretamente o valor do *x* scale no component Transform. Se você não tiver certeza absoluta de que a entity tem o component que está tentando obter, use `getOrNull()` ou `getMutableOrNull()`. {% hint style="warning" %} **📔 Nota**: Evite usar `getOrNull()` ou `getMutableOrNull()` quando possível, pois essas funções envolvem verificações adicionais e, portanto, são menos eficientes do 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 obter 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 do component. ```ts Transform.deleteFrom(myEntity) ``` Se você tentar remover um component que não exista na entity, essa ação não gerará nenhum erro. {% hint style="warning" %} **📔 Nota**: Para remover todos os components de uma entity de uma vez, veja [esta seção](#remove-entities) {% endhint %} ## Verificar se há um component Você pode verificar se uma entity possui uma instância de um determinado component usando a `has()` função. Esta função 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 obter 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 a `onChange` função para executar uma callback 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 código legível. A callback pode incluir um parâmetro de entrada que contenha o novo estado do component. ```ts Transform.onChange(cubeEntity, (newTransform) => { if (!newTransform) return console.log( 'Posição do cubo alterada: ', newTransform.position, newTransform.rotation ) }) VisibilityComponent.onChange(cubeEntity, (newVisibilityComponent) => { if (!newVisibilityComponent) return console.log('Visibilidade do cubo alterada: ', newVisibilityComponent.visible) }) ``` Se o component for removido da entity, então a função é chamada com uma entrada de `undefined`. {% hint style="info" %} **💡 Dica**: O `.onChange()` função funciona tanto com components nativos do SDK quanto com [custom components](/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md) definidos pelo criador. {% endhint %} ## Obter entities filhas Para acessar todas as entities que são filhas diretas de uma entity pai, use `getEntitiesWithParent`. Ele recebe como argumentos o `engine` e a `parent` entity e retorna uma lista de todas as entities que têm essa entity específica como pai. Observe que ele retorna apenas filhas diretas, não filhas de filhas. ```ts import { getEntitiesWithParent } from '@dcl/sdk/ecs' const children = getEntitiesWithParent(engine, myEntity) for (const child of children) { // processar cada child entity } ``` Para em vez disso acessar todos os descendants de uma entity, independentemente de quão profundamente aninhados estejam, use a função `getComponentEntityTree()`. Em vez de percorrer manualmente a hierarquia nível por nível, esta função retorna uma lista plana de todos os descendants, fácil de iterar. Ela também filtra apenas entities que tenham um determinado component ou uma lista de components. ```ts import { getComponentEntityTree } from '@dcl/sdk/ecs' export function main() { // Criar uma entity pai com entities filhas aninhadas const parentEntity = engine.addEntity() Transform.create(parentEntity, { position: Vector3.create(8, 0, 8), }) // ... suponha que o pai tenha várias filhas e netos // Iterar por todos os descendants da entity pai for (const descendantEntity of getComponentEntityTree( engine, parentEntity, Transform )) { // Aceder a cada entity descendente const transform = Transform.get(descendantEntity) console.log('Posição da entity descendente:', transform.position) } } ``` O `getComponentEntityTree` A função recebe três parâmetros: * `engine`: A instância do Engine que executa as entities * `entity`: A root entity a partir da qual começar * `component`: O component pelo qual filtrar (normalmente `Transform` para hierarquias espaciais) A função devolve um generator que produz cada entity descendente na estrutura em árvore. Apenas as entities que tiverem o component especificado serão incluídas nos resultados. Pode combinar isto com outras verificações de component para encontrar entities específicas na sua hierarquia: ```ts // Encontrar todos os descendentes com um nome 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) } } ``` ## Entities reservadas Certos IDs de entity são reservados para entities especiais que existem em cada Scene. Podem ser acessados através dos seguintes aliases: * `engine.RootEntity` * `engine.PlayerEntity` * `engine.CameraEntity` {% hint style="warning" %} **📔 Nota**: Evite referir-se a estas entities antes de serem inicializadas. Para evitar este problema, refira-se a estas entities na `main()` function, ou num system. {% endhint %} ## A root entity Todas as entities na Scene são children da `engine.RootEntity`, direta ou indiretamente. Esta entity não tem um componente Transform, mas é usada para lidar com vários components que representam definições mais globais, como [controlo do 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 do ecrã](/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 jogador. Recupere o `Transform` component do jogador para obter a posição e rotação atuais do jogador, veja [dados do utilizador](/creator/content-creator-pt/scenes-sdk7/interatividade/user-data.md). O Transform do jogador é só de leitura; para o modificar, use a `movePlayerTo()` função, [saiba mais](/creator/content-creator-pt/scenes-sdk7/interatividade/avatars/move-player.md). Também pode anexar objetos ao jogador definindo-os como children desta entity, embora o [Attach to Player](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md#attach-an-entity-to-an-avatar) seja muitas vezes a melhor opção para isso. ## A camera entity O `engine.CameraEntity` entity representa a câmara do jogador. Recupere o `Transform` component da câmara para obter a posição e rotação da câmara. O Transform desta entity também é só de leitura. Para modificar o ângulo ou a posição da câmara, use uma [câmara virtual](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/camera.md#using-virtual-cameras). Também pode recuperar o `CameraMode` component para saber se o jogador está a usar o modo de câmara em 1.ª ou 3.ª pessoa, veja [modo de câmara](/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 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/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 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.