> 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-es/scenes-sdk7/arquitectura/entities-components.md). # Entities y Components Aprende lo esencial sobre entities y components en una escena de Decentraland Las scenes de Decentraland se construyen alrededor de [*entities*, *components* y *systems*](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system). Este es un patrón común utilizado en la arquitectura de varios game engines, que permite una fácil composabilidad y escalabilidad. ![](https://1216664193-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) ## Resumen *Entidades* son la unidad básica para construir todo en las scenes de Decentraland. Todos los objetos 3D visibles e invisibles y los reproductores de audio en tu scene serán cada uno una entity. Una entity no es más que un id, que puede ser referenciado por components. La entity en sí no tiene properties ni methods propias; simplemente sirve para agrupar varios components juntos. *Components* definen los traits de una entity. Por ejemplo, un `Transform` component almacena las coordinates, rotation y scale de la entity. Un `MeshRenderer` component le da a la entity una forma visible (como un cube o una sphere) cuando se renderiza en la scene, un `Material` component le da a la entity un color o texture. También puedes create custom components para servir los datos requeridos por tu scene, por ejemplo un custom `health` podría almacenar el valor de salud restante de una entity, y añadirlo a entities que representen enemigos que no sean jugadores en un juego. Si estás familiarizado con el desarrollo web, piensa en las entities como el equivalente de *Elements* en un *DOM* tree, y en los components como *attributes* de esos elements. En el [Scene Editor en Creator Hub](/creator/content-creator-es/scene-editor/primeros-pasos/about-editor.md), puedes ver los components que pertenecen a una entity seleccionándola. ![](https://1216664193-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" %} **📔 Nota**: En versiones anteriores del SDK, Entities eran *objects* que se instanciaban, y podían extenderse para añadir functions. A partir de la versión 7.0 del SDK, las entities son solo un ID. Esta estructura se ajusta mejor a los principios de [programación orientada a datos](/creator/content-creator-es/scenes-sdk7/arquitectura/data-oriented-programming.md) y puede ayudar en el rendimiento de la scene. {% endhint %} ![](https://1216664193-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` o cualquiera de los *shape* components están estrechamente vinculados con el rendering de la scene. Si los values de estos components cambian, eso por sí solo basta para que el engine cambie cómo se renderiza la scene en el siguiente frame. El engine es la parte de la scene que se sitúa en el medio y gestiona todas las demás partes. Determina qué entities se renderizan y cómo interactúan los players con ellas. También coordina qué functions de [systems](/creator/content-creator-es/scenes-sdk7/arquitectura/systems.md) se ejecutan y cuándo. Los components están pensados para almacenar data sobre su referenced entity. Solo pueden almacenar estos data, no pueden modificar estos data por sí mismos. Todos los changes en los values de los components son realizados por [Systems](/creator/content-creator-es/scenes-sdk7/arquitectura/systems.md). Los systems están completamente desacoplados de los components y de las entities en sí. Entities y components son agnósticos respecto a qué *systems* están actuando sobre ellas. ## Sintaxis para entities y components El siguiente ejemplo muestra algunas operaciones básicas para declarar y configurar entities y components básicas. ```ts export function main() { // Crear una entity const door = engine.addEntity() // Darle una posición a la entity mediante un component Transform Transform.create(door, { position: Vector3.create(5, 1, 5), }) // Darle a la entity una forma visible mediante un component GltfContainer GltfContainer.create(door, { src: 'assets/models/door.glb', }) } ``` {% hint style="warning" %} **📔 Nota**: En versiones anteriores del SDK, era necesario añadir manualmente una entity al engine para empezar a renderizarla. A partir de la versión 7 del SDK, las entities se añaden implícitamente al engine en cuanto se les asigna un component. {% endhint %} Cuando se crea un component, siempre se asigna a una parent entity. Los values del component entonces afectan a la entity. {% hint style="info" %} **💡 Consejo**: En lugar de crear entities una por una, puedes spawn a whole tree of entities y components de una vez desde un [composite](/creator/content-creator-es/scenes-sdk7/arquitectura/composites.md) thumbnail.png. {% endhint %} ## Eliminar entities Para eliminar una entity del engine, usa `engine.removeEntity()`. Esta function devuelve un `boolean`: `true` si la entity se eliminó, `false` si la eliminación fue rechazada. ```ts export function main() { // Crear una entity const door = engine.addEntity() // Darle a la entity una forma visible mediante un component GltfContainer GltfContainer.create(door, { src: 'assets/models/door.glb', }) // Eliminar entity const removed = engine.removeEntity(door) console.log('Entity removed:', removed) // true } ``` Si una entity eliminada tiene child entities, estas vuelven a cambiar su parent al `engine.RootEntity` entity por defecto, que está posicionada en la base de la scene, con una scale de *1*. ### Entities reservadas para el Renderer Algunos ids de entity están reservados por el Renderer para avatares de players remotos. No puedes eliminar estas entities. Si llamas a `engine.removeEntity()` sobre una entity reservada por el Renderer, devuelve `false` y deja todos los components intactos. El [las entities reservadas con nombre](#reserved-entities) (`engine.RootEntity`, `engine.PlayerEntity`, `engine.CameraEntity`) son un caso especial: `engine.removeEntity()` sigue devolviendo `false` para estas (sus ids nunca se liberan), pero sus components **son** se purgan. Esto significa que puedes borrar tus propios components de ellas (por ejemplo, eliminando un `InputModifier` de `engine.PlayerEntity`), aunque el id de la entity en sí nunca se libera. ```ts // Intentando eliminar una entity reservada const result = engine.removeEntity(engine.PlayerEntity) console.log(result) // false — el id de la entity no se libera // Pero los components propios de la scene sobre PlayerEntity se purgan ``` Puedes comprobar el valor de retorno al eliminar entities para manejar casos límite: ```ts if (!engine.removeEntity(someEntity)) { console.log('No se pudo eliminar la entity (reservada)') } ``` ### Eliminar una entity con sus children Para eliminar una entity y también todos sus children (y cualquier child de sus children, recursivamente), usa el `removeEntityWithChildren()` helper. ```ts export function main() { // Crear Entity padre const door = engine.addEntity() // Crear Entity hijo const doorKnob = engine.addEntity() // Dar a las entities una forma visible GltfContainer.create(door, { src: 'models/door.glb', }) GltfContainer.create(doorKnob, { src: 'models/doorKnob.glb', }) // Parent Transform.create(doorKnob, { parent: door, }) // Eliminar tanto parent como children removeEntityWithChildren(engine, door) } ``` {% hint style="warning" %} **Nota:** Si una entity reservada por el Renderer se encuentra en cualquier punto del tree, `removeEntityWithChildren` elimina a todos los demás descendants pero deja la reserved entity en su lugar. El `Transform.parent` apuntará a una entity eliminada. Esto solo ocurre si tu scene pone una reserved entity como child de una scene entity, lo cual es poco común. {% endhint %} {% hint style="info" %} **💡 Consejo**: En lugar de eliminar una entity del engine, en algunos casos podría ser mejor hacerla invisible, por si quieres poder cargarla de nuevo sin ningún retraso. Ver [Hacer invisible](/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/shape-components.md#make-invisible) {% endhint %} ### Eliminar entities por detrás de escena Una entity es solo un id al que hacen referencia sus components. Así que al eliminar una entity en realidad estás eliminando cada uno de los components que hacen referencia a esa entity. Si eliminas manualmente todos los components de una entity, le parecerá igual al player que hacer `engine.removeEntity()`. Sin embargo, `engine.removeEntity()` también realiza algo de bookkeeping interno adicional, marcando el id de la entity como ya no usado, así que siempre es la forma recomendada de eliminar una entity. ## Entities anidadas Una entity puede tener otras entities como children. Gracias a esto, podemos organizar entities en trees, igual que el HTML de una webpage. ![](https://1216664193-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 establecer una entity como parent de otra, la entity child debe tener un `Transform` component. Entonces puedes establecer el `parent` field con una referencia a la parent entity. ```ts export function main() { // Crear entities const parentEntity = engine.addEntity() const childEntity = engine.addEntity() // Establecer parent Transform.create(childEntity, { parent: parentEntity, }) } ``` Una vez asignado un parent, puede leerse en la entity child desde el `parent` field de su `Transform` componente. ```ts // Obtener parent desde una entity const parent = Transform.get(childEntity).parent ``` Si una parent entity tiene un `Transform` component que afecta a su position, scale o rotation, sus child entities también se ven afectadas. Cualquier value de position o rotation se suma, cualquier value de scale se multiplica. Si la parent o la child entity no tiene un `Transform` component, se usan los siguientes valores por defecto. * Para **posición**, el centro del parent es *0, 0, 0* * Para **rotación** la rotation del parent es el quaternion *0, 0, 0, 1* (equivalente a los Euler angles *0, 0, 0*) * Para **escala**, el parent se considera que tiene un size de *1*. Cualquier resizing del parent afecta a la scale y la position en proporción. Las entities sin component de shape son invisibles en la scene. Estas pueden usarse como wrappers para gestionar y posicionar varias entities como un grupo. Para separar una child entity de su parent, puedes asignar el parent de la entity a `engine.RootEntity`. ```ts const mutableChildTransform = Transform.getMutable(childEntity) mutableChildTransform.parent = engine.RootEntity ``` {% hint style="warning" %} **📔 Nota**: Al tratar con nested entities que están sincronizadas con otros players, usa la `función parentEntity()` en lugar de la `parent` entity en el Transform. Ver [Entities con parent](/creator/content-creator-es/scenes-sdk7/networking/serverless-multiplayer.md#parented-entities) {% endhint %} En el Scene Editor, puedes ver toda la jerarquía de nested entities de tu scene en el panel de la izquierda. ![](https://1216664193-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) ## Obtener una entity por ID Cada entity de tu scene tiene un número único *id*. Puedes recuperar desde el engine un component que haga referencia a una entity específica basándote en este ID. ```typescript // obtener un component Transform Transform.get(1000 as Entity) ``` {% hint style="warning" %} **📔 Nota**: Los ids de entity entre *0* y *511* están reservados por el engine para entities fijas, como el avatar del player, la scene base, etc. {% endhint %} Por ejemplo, si el click de un player o un [raycast](/creator/content-creator-es/scenes-sdk7/interactividad/raycasting.md) golpea una entity, esto devolverá el id de la entity golpeada, y puedes usar el comando anterior para obtener el component Transform de la entity que coincida con ese id. También puedes obtener cualquier otro component de esa entity de la misma manera. ## Obtener una entity por nombre Al añadir entities mediante drag-and-drop en el Scene Editor, cada entity tiene un nombre único. Usa la `engine.getEntityOrNullByName()` function para referenciar una de estas entities desde tu código. Pasa el nombre de la entity como una string, tal como aparece escrito en la UI del Scene Editor, en la vista de árbol de la izquierda. ```ts function main() { const door = engine.getEntityOrNullByName('door3') } ``` {% hint style="warning" %} **📔 Nota**: Asegúrate de usar solo `engine.getEntityOrNullByName()` dentro de la `main()` function, en functions que se ejecutan después de `main()`, o en un system. Si se usa fuera de uno de esos contextos, es posible que las entities creadas en la UI del Scene Editor aún no estén instanciadas. {% endhint %} Tienes libertad para realizar cualquier action sobre una entity obtenida mediante este method, como add o remove components, modificar values de components existentes o eliminar la entity del engine. ```ts function main() { // obtener entity const door = engine.getEntityOrNullByName('door-3') // verificar que la entity exista if (door) { // agregar un callback de Pointer Events pointerEventsSystem.onPointerDown( { entity: door, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Open' }, }, function () { // abrir la puerta } ) } } ``` Todas las entities añadidas mediante la UI del Scene Editor tienen un `Nombre` component, puedes iterar sobre todas ellas así: ```ts function main() { for (const [entity, name] of engine.getEntitiesWith(Name)) { console.log({ entity, name }) } } ``` ## Añadir o reemplazar un component Cada entity solo puede tener un component de un tipo dado. Por ejemplo, si intentas asignar un Transform a una entity que ya tiene uno, esto provocará un error. Para evitar este error, puedes usar `.createOrReplace` en lugar de `.create`. Este command sobrescribe cualquier component existente del mismo tipo si existen, en caso contrario crea un nuevo component igual que `.create`. ```ts Transform.createOrReplace(door, { position: Vector3.create(5, 1, 5), }) ``` {% hint style="warning" %} **📔 Nota**: Como `.createOrReplace` realiza una comprobación adicional antes de crear el component, siempre es más eficiente usar `.create`. Si estás seguro de que la entity aún no tiene un component como el que estás añadiendo, usa `.create`. {% endhint %} ## Acceder a un component desde una entity Puedes acceder a los components de una entity usando el `.get()` o `getMutable()` funciones. ```ts export function main() { // Crear entidad const box = engine.addEntity() // Crear y añadir component a esa entity Transform.create(box) // Obtener versión de solo lectura del component let transform = Transform.get(box) // Obtener versión mutable del component let transform = Transform.getMutable(box) } ``` El `get()` function obtiene una referencia de solo lectura al component. No puedes cambiar ningún value de esta reference del component. Si deseas cambiar los values del component, usa la `getMutable()` function en su lugar. Si cambias los values en la versión mutable del component, estás afectando directamente a la entity a la que pertenece ese component. Consulta [mutable data](/creator/content-creator-es/scenes-sdk7/patrones-de-programacion/mutable-data.md) para más detalles. {% hint style="warning" %} **📔 Nota**: Usa solo `getMutable()` si realmente vas a hacer changes a los values del component. En caso contrario, usa siempre `get()`. Esta práctica sigue los principios de [programación orientada a datos](/creator/content-creator-es/scenes-sdk7/arquitectura/data-oriented-programming.md), y puede ayudar significativamente en el rendimiento de la scene. {% endhint %} ```ts // Obtener versión mutable del component let transform = Transform.getMutable(box) // cambiar un value del component transform.scale.x = 5 ``` El ejemplo anterior modifica directamente el value de *x* scale en el component Transform. Si no estás totalmente seguro de si la entity sí tiene el component que intentas obtener, usa `getOrNull()` o `getMutableOrNull()`. {% hint style="warning" %} **📔 Nota**: Evita usar `getOrNull()` o `getMutableOrNull()` cuando sea posible, ya que estas functions implican comprobaciones adicionales y, por lo tanto, son menos eficientes que `.get()` y `getMutable()`. {% endhint %} ```ts // getOrNull const transformOrNull = Transform.getOrNull(myEntity) // getMutableOrNull const mutableTransformOrNull = Transform.getMutableOrNull(myEntity) ``` Si el component que intentas obtener no existe en la entity: * `get()` y `getMutable()` devuelve un error. * `getOrNull()` y `getMutableOrNull()` devuelve `Null`. ## Eliminar un component de una entity Para eliminar un component de una entity, usa el `deleteFrom()` método del tipo de component. ```ts Transform.deleteFrom(myEntity) ``` Si intentas eliminar un component que no existe en la entity, esta action no generará ningún error. {% hint style="warning" %} **📔 Nota**: Para eliminar todos los components de una entity de una vez, consulta [esta sección](#remove-entities) {% endhint %} ## Comprobar si hay un component Puedes comprobar si una entity posee una instancia de un cierto component usando la `has()` function. Esta function devuelve *true* si el component está presente, y *false* si no lo está. Esto puede ser muy útil para usarlo en lógica condicional en tu scene. ```ts const hasTransform = Transform.has(myEntity) ``` {% hint style="info" %} **💡 Consejo**: También puedes [consultar components](/creator/content-creator-es/scenes-sdk7/arquitectura/querying-components.md) para obtener una lista completa de components que contienen un component específico, o un conjunto específico de components. No iteres manualmente sobre todas las entities de la scene para comprobar cada una con un `has()`, ese enfoque es mucho menos eficiente. {% endhint %} ## Comprobar cambios en un component Usa el `onChange` usa la function para ejecutar una callback function cada vez que los values del component cambien para una entity dada. Esto funciona con cualquier component y es un gran atajo para ayudar a que tu código sea legible. La callback function puede incluir un parámetro de entrada que contenga el nuevo state del component. ```ts Transform.onChange(cubeEntity, (newTransform) => { if (!newTransform) return console.log( 'La posición del Cube cambió: ', newTransform.position, newTransform.rotation ) }) VisibilityComponent.onChange(cubeEntity, (newVisibilityComponent) => { if (!newVisibilityComponent) return console.log('La visibilidad del Cube cambió: ', newVisibilityComponent.visible) }) ``` Si el component se elimina de la entity, entonces la function se llama con una entrada de `undefined`. {% hint style="info" %} **💡 Consejo**: La `.onChange()` function funciona tanto con native components del SDK como con [custom components](/creator/content-creator-es/scenes-sdk7/arquitectura/custom-components.md) definidos por el creator. {% endhint %} ## Obtener child entities Para acceder a todas las entities que son child directos de una parent entity, usa `getEntitiesWithParent`. Toma como arguments el `engine` y la `parent` entity y devuelve una lista de todas las entities que tienen esa entity en particular como parent. Ten en cuenta que solo devuelve child directos, no children de children. ```ts import { getEntitiesWithParent } from '@dcl/sdk/ecs' const children = getEntitiesWithParent(engine, myEntity) for (const child of children) { // procesar cada entity hija } ``` Para acceder en su lugar a todos los descendants de una entity, sin importar lo profundamente anidados que estén, usa la function `getComponentEntityTree()`. En lugar de recorrer manualmente la jerarquía nivel por nivel, esta function devuelve una lista plana de todos los descendants que es fácil de iterar. También filtra solo las entities que tienen un component dado o una lista de components. ```ts import { getComponentEntityTree } from '@dcl/sdk/ecs' export function main() { // Crear una entity parent con children anidados const parentEntity = engine.addEntity() Transform.create(parentEntity, { position: Vector3.create(8, 0, 8), }) // ... asume que el parent tiene múltiples children y grandchildren // Iterar sobre todos los descendants de la entity parent for (const descendantEntity of getComponentEntityTree( engine, parentEntity, Transform )) { // Acceder a cada entity descendant const transform = Transform.get(descendantEntity) console.log('Posición del descendant:', transform.position) } } ``` El `getComponentEntityTree` function toma tres parámetros: * `engine`: La instancia de engine que ejecuta las entities * `entidad`: La root entity de la que partir * `component`: El component por el que filtrar (normalmente `Transform` para jerarquías espaciales) La function devuelve un generator que produce cada entity descendant en la estructura en tree. Solo se incluirán en los resultados las entities que tengan el component especificado. Puedes combinar esto con otras comprobaciones de component para encontrar entities específicas en tu jerarquía: ```ts // Encontrar todos los descendants con un nombre específico for (const descendantEntity of getComponentEntityTree( engine, parentEntity, Transform )) { const name = Name.getOrNull(descendantEntity) if (name && name.value === 'targetEntity') { console.log('Entity objetivo encontrada:', descendantEntity) } } ``` ## Entidades reservadas Ciertos ids de entity están reservados para entities especiales que existen en todas las scenes. Se puede acceder a ellas mediante los siguientes aliases: * `engine.RootEntity` * `engine.PlayerEntity` * `engine.CameraEntity` {% hint style="warning" %} **📔 Nota**: Evita referirte a estas entities antes de que se inicialicen. Para evitar este problema, refiérete a estas entities en la `main()` function, o en un system. {% endhint %} ## La root entity Todas las entities de la scene son children de la `engine.RootEntity`, directa o indirectamente. Esta entity carece de un component Transform, pero se usa para gestionar varios components que representan ajustes más globales, como [el control del skybox](/creator/content-creator-es/scenes-sdk7/interactividad/skybox-control.md), [la posición del cursor](/creator/content-creator-es/scenes-sdk7/interactividad/user-data.md#check-the-players-cursor-position), o [las dimensiones de la pantalla](/creator/content-creator-es/scenes-sdk7/ui-2d/ui-positioning.md#responsive-ui-size). ## La player entity El `engine.PlayerEntity` entity representa el avatar del player. Obtén el `Transform` component del player para obtener la posición y rotation actuales del player, ver [user data](/creator/content-creator-es/scenes-sdk7/interactividad/user-data.md). El Transform del player es de solo lectura; para modificarlo usa la `movePlayerTo()` function, [aprende más](/creator/content-creator-es/scenes-sdk7/interactividad/avatares/move-player.md). También puedes adjuntar objetos al player poniéndolos como children de esta entity, aunque la [Attach to Player](/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/entity-positioning.md#attach-an-entity-to-an-avatar) suele ser la mejor opción para eso. ## La camera entity El `engine.CameraEntity` entity representa la camera del player. Obtén el `Transform` component de la camera para obtener la posición y rotation de la camera. El Transform de esta entity también es de solo lectura. Para modificar el ángulo o la posición de la camera, usa una [Virtual camera](/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/camera.md#using-virtual-cameras). También puedes obtener el `CameraMode` component de la camera para saber si el player está usando el modo de cámara en primera o tercera persona, ver [CameraMode](/creator/content-creator-es/scenes-sdk7/interactividad/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-es/scenes-sdk7/arquitectura/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.