> 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 scene de Decentraland Las escenas de Decentraland se construyen en torno a [*entities*, *components* y *systems*](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system). Este es un patrón común usado en la arquitectura de varios motores de juego, que permite una fácil componibilidad 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) ## Descripción general *Entities* son la unidad básica para construir todo en las escenas de Decentraland. Todos los objetos 3D visibles e invisibles y los reproductores de audio en tu escena 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 propiedades ni métodos propios; simplemente sirve para agrupar varios components juntos. *Components* definen las características de una entity. Por ejemplo, un `Transform` component almacena las coordenadas, rotación y escala de la entity. Un `MeshRenderer` component le da a la entity una forma visible (como un cubo o una esfera) cuando se renderiza en la escena, un `Material` component le da a la entity un color o textura. También puedes crear components personalizados para servir a los datos que requiere tu escena; por ejemplo, un custom `health` podría almacenar el valor de salud restante de una entity, y añadirlo a entities que representan enemigos que no son jugadores en un juego. Si estás familiarizado con el desarrollo web, piensa en las entities como el equivalente de *Elementos* en un *DOM* tree, y en los components como *atributos* de esos elements. En el [Scene Editor in Creator Hub](/creator/content-creator-es/scene-editor/comenzar/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) {% hint style="warning" %} **📔 Nota**: En versiones anteriores del SDK, las Entities eran *objects* instanciados y podían extenderse para añadir funciones. 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 escena. {% 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) Components como `Transform`, `Material` o cualquiera de los *shape* components están estrechamente ligados al renderizado de la escena. Si los valores de estos components cambian, eso por sí solo es suficiente para que el motor cambie cómo se renderiza la escena en el siguiente frame. El motor es la parte de la escena que se sitúa en el centro 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. Components están pensados para almacenar datos sobre su entity referenciada. Solo pueden almacenar estos datos; no pueden modificarlos por sí mismos. Todos los cambios en los valores de los components los llevan a cabo [Systems](/creator/content-creator-es/scenes-sdk7/arquitectura/systems.md). Los Systems están completamente desacoplados de los components y las entities en sí. Entities y components son agnósticos a qué *systems* actúan sobre ellos. ## Sintaxis para entities y components El ejemplo de abajo muestra algunas operaciones básicas para declarar y configurar entities y components básicos. ```ts export function main() { // Crear una entity const door = engine.addEntity() // Darle a la entity una posición mediante un transform component Transform.create(door, { position: Vector3.create(5, 1, 5), }) // Darle a la entity una forma visible mediante un GltfContainer component 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 motor para empezar a renderizarla. A partir de la versión 7 del SDK, las entities se añaden implícitamente al motor en cuanto se les asigna un component. {% endhint %} Cuando se crea un component, siempre se asigna a una parent entity. Los valores del component entonces afectan a la entity. {% hint style="info" %} **💡 Consejo**: En lugar de crear entities una por una, puedes generar de una vez un árbol completo de entities y components a partir de un [composite](/creator/content-creator-es/scenes-sdk7/arquitectura/composites.md) file. {% endhint %} ## Eliminar entities Para eliminar una entity del motor, usa `engine.removeEntity()`. Esta function devuelve un `boolean`: `true` si la entity fue eliminada, `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 GltfContainer component GltfContainer.create(door, { src: 'assets/models/door.glb', }) // Eliminar entity const removed = engine.removeEntity(door) console.log('Entidad eliminada:', removed) // true } ``` Si una entity eliminada tiene alguna child entity, estas cambian su parent de vuelta al default `engine.RootEntity` entity, que está posicionada en la posición base de la scene, con una scale de *1*. ### Entities reservadas por el renderer Algunos entity ids están reservados por el renderer para avatares de jugadores remotos. No puedes eliminar estas entities. Si llamas `engine.removeEntity()` en una renderer-reserved entity, devuelve `false` y deja todos los components intactos. El [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** purged. Esto significa que puedes limpiar tus propios components de ellas (por ejemplo, eliminando un `InputModifier` de `engine.PlayerEntity`), aunque el entity id en sí nunca se libera. ```ts // Intentando eliminar una entity reservada const result = engine.removeEntity(engine.PlayerEntity) console.log(result) // false — el entity id no se libera // Pero los components propios de la escena en PlayerEntity se purgan ``` Puedes comprobar el valor de retorno al eliminar entities para gestionar casos límite: ```ts if (!engine.removeEntity(someEntity)) { console.log('La entity no pudo ser eliminada (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 hija 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', }) // Padre Transform.create(doorKnob, { parent: door, }) // Eliminar tanto padre como children removeEntityWithChildren(engine, door) } ``` {% hint style="warning" %} **Nota:** Si una renderer-reserved entity se sitúa en cualquier parte del árbol, `removeEntityWithChildren` elimina a todos los demás descendientes pero deja la reserved entity en su lugar. El `Transform.parent` de la reserved entity apuntará a una entity eliminada. Esto solo ocurre si tu scene hace parent de una reserved entity bajo una scene entity, lo cual es poco común. {% endhint %} {% hint style="info" %} **💡 Consejo**: En lugar de eliminar una entity del motor, en algunos casos puede ser mejor volverla invisible, por si quieres poder cargarla de nuevo sin retraso. Consulta [Hacer invisible](/creator/content-creator-es/scenes-sdk7/conceptos-basicos-del-contenido-3d/shape-components.md#make-invisible) {% endhint %} ### Eliminar entities detrás de escena Una entity es solo un id referenciado por sus components. Así que al eliminar una entity en realidad estás eliminando cada uno de los components que referencian esta entity. Si eliminas manualmente todos los components de una entity, al jugador le parecerá lo mismo que hacer `engine.removeEntity()`. Sin embargo, `engine.removeEntity()` también realiza un trabajo interno adicional de contabilidad, marcando el entity id como 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 árboles, igual que el HTML de una página web. ![](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) Para establecer una entity como parent de otra, la child entity debe tener un `Transform` component. Entonces puedes establecer el campo `parent` 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, se puede leer en la child entity desde el campo `parent` de su `Transform` componente. ```ts // Obtener parent de una entity const parent = Transform.get(childEntity).parent ``` Si una parent entity tiene un `Transform` component que afecta a su posición, escala o rotación, sus child entities también se ven afectadas. Cualquier valor de posición o rotación se suma; cualquier valor de escala se multiplica. Si la parent entity o la child entity no tiene un `Transform` component, se usan los siguientes valores por defecto. * Para **position**, el centro de la parent es *0, 0, 0* * Para **rotation** la rotation de la parent es el quaternion *0, 0, 0, 1* (equivalente a los ángulos de Euler *0, 0, 0*) * Para **scale**, la parent se considera que tiene un size de *1*. Cualquier cambio de tamaño de la parent afecta proporcionalmente a la escala y la posición. Las entities sin component de shape son invisibles en la escena. Estas pueden usarse como envoltorios para manejar 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 sincronizadas con otros players, usa la `parentEntity()` function en lugar de la `parent` entity en el Transform. Consulta [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 escena 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) ## Obtener una entity por ID Cada entity de tu escena tiene un número único *id*. Puedes recuperar un component que haga referencia a una entity específica del motor basándote en este ID. ```typescript // obtener un componente Transform Transform.get(1000 as Entity) ``` {% hint style="warning" %} **📔 Nota**: Los entity ids entre *0* y *511* están reservados por el motor para entities fijas, como el avatar del player, la escena base, etc. {% endhint %} Por ejemplo, si el click de un player o un [raycast](/creator/content-creator-es/scenes-sdk7/interactividad/raycasting.md) impacta una entity, esto devolverá el id de la entity impactada, y puedes usar el comando anterior para obtener el component Transform de la entity que coincide 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 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 funciones que se ejecuten 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 se hayan instanciado. {% endhint %} Eres libre de realizar cualquier acción sobre una entity obtenida mediante este método, como añadir o eliminar components, modificar valores de components existentes o eliminar la entity del motor. ```ts function main() { // obtener entity const door = engine.getEntityOrNullByName('door-3') // verificar que la entity existe if (door) { // añadir una callback de pointer events pointerEventsSystem.onPointerDown( { entity: door, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Abrir' }, }, function () { // abrir puerta } ) } } ``` Todas las entities añadidas mediante la UI del Scene Editor tienen un `Name` 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 comando sobrescribe cualquier component existente del mismo tipo si existe; de lo contrario, crea un nuevo component igual que `.create`. ```ts Transform.createOrReplace(door, { position: Vector3.create(5, 1, 5), }) ``` {% hint style="warning" %} **📔 Nota**: Dado que `.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 las funciones `getMutable()` . ```ts export function main() { // Crear entity 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 valor de este component desde esta referencia. Si deseas cambiar los valores del component, usa la `getMutable()` función en su lugar. Si cambias los valores 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 cambios en los valores del component. De lo 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 al rendimiento de la escena. {% endhint %} ```ts // Obtener versión mutable del component let transform = Transform.getMutable(box) // cambiar un valor del component transform.scale.x = 5 ``` El ejemplo anterior modifica directamente el valor de *x* la escala en el component Transform. Si no estás completamente seguro de si la entity tiene el component que intentas recuperar, 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 recuperar 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 acción no generará ningún error. {% hint style="warning" %} **📔 Nota**: Para eliminar todos los components de una entity a la vez, consulta [esta sección](#remove-entities) {% endhint %} ## Comprobar si hay un component Puedes comprobar si una entity posee una instancia de un determinado component usando la función `has()` . Esta función 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 la `función onChange` función para ejecutar una función callback cada vez que cambien los valores del component para una entity determinada. Esto funciona con cualquier component y es un gran atajo para mantener tu código legible. La función callback puede incluir un parámetro de entrada que contenga el nuevo estado del component. ```ts Transform.onChange(cubeEntity, (newTransform) => { if (!newTransform) return console.log( 'La posición del cubo cambió: ', newTransform.position, newTransform.rotation ) }) VisibilityComponent.onChange(cubeEntity, (newVisibilityComponent) => { if (!newVisibilityComponent) return console.log('La visibilidad del cubo cambió: ', newVisibilityComponent.visible) }) ``` Si se elimina el component de la entity, entonces la function se llama con una entrada de `undefined`. {% hint style="info" %} **💡 Consejo**: El `.onChange()` function funciona tanto con components nativos del SDK como con [custom components](/creator/content-creator-es/scenes-sdk7/arquitectura/custom-components.md) definidos por el creador. {% endhint %} ## Obtener child entities Para acceder a todas las entities que son children directos de una parent entity, usa `getEntitiesWithParent`. Toma como argumentos el `engine` y la `parent` entity y devuelve una lista de todas las entities que tienen esa entity concreta como parent. Ten en cuenta que solo devuelve children directos, no children de children. ```ts import { getEntitiesWithParent } from '@dcl/sdk/ecs' const children = getEntitiesWithParent(engine, myEntity) for (const child of children) { // procesar cada child entity } ``` Para acceder en su lugar a todos los descendientes de una entity, sin importar lo profundamente anidados que estén, usa la función `getComponentEntityTree()`. En lugar de recorrer manualmente la jerarquía nivel por nivel, esta función devuelve una lista plana de todos los descendientes que es fácil de iterar. También filtra para dejar 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 parent entity con children anidados const parentEntity = engine.addEntity() Transform.create(parentEntity, { position: Vector3.create(8, 0, 8), }) // ... asume que la parent tiene varios children y grandchildren // Iterar sobre todos los descendientes de la parent entity for (const descendantEntity of getComponentEntityTree( engine, parentEntity, Transform )) { // Accede a cada Entity descendiente const transform = Transform.get(descendantEntity) console.log('Descendant position:', transform.position) } } ``` El `getComponentEntityTree` La función toma tres parámetros: * `engine`: La instancia de Engine que ejecuta las entities * `entity`: La Entity raíz desde la que comenzar * `componente`: El Component por el que filtrar (normalmente `Transform` para jerarquías espaciales) La función devuelve un generador que produce cada Entity descendiente en la estructura en árbol. 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 descendientes 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('Found target entity:', descendantEntity) } } ``` ## Entities reservadas Ciertos ids de Entity están reservados para Entities especiales que existen en cada Scene. Se puede acceder a ellas mediante los siguientes alias: * `engine.RootEntity` * `engine.PlayerEntity` * `engine.CameraEntity` {% hint style="warning" %} **📔 Nota**: Evita hacer referencia a estas entities antes de que se inicialicen. Para evitar este problema, haz referencia a estas entities en la `main()` función, o en un System. {% endhint %} ## La Entity raíz Todas las entities de la Scene son hijas de la `engine.RootEntity`, directa o indirectamente. Esta Entity no tiene un Component Transform, pero se usa para manejar varios Components que representan configuraciones 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/2d-ui/ui-positioning.md#responsive-ui-size). ## La Entity del jugador El `engine.PlayerEntity` Entity representa el avatar del jugador. Obtén el `Transform` Component para obtener la posición y rotación actuales del jugador, consulta [los datos de usuario](/creator/content-creator-es/scenes-sdk7/interactividad/user-data.md). El Transform del jugador es de solo lectura; para modificarlo usa la `movePlayerTo()` función, [saber más](/creator/content-creator-es/scenes-sdk7/interactividad/avatars/move-player.md). También puedes adjuntar objetos al jugador estableciéndolos como hijos de esta Entity, aunque la [Adjuntar al jugador](/creator/content-creator-es/scenes-sdk7/conceptos-basicos-del-contenido-3d/entity-positioning.md#attach-an-entity-to-an-avatar) suele ser la mejor opción para ello. ## La Entity de la cámara El `engine.CameraEntity` Entity representa la cámara del jugador. Obtén el `Transform` Component para obtener la posición y rotación de la cámara. El Transform de esta Entity también es de solo lectura. Para modificar el ángulo o la posición de la cámara, usa una [cámara virtual](/creator/content-creator-es/scenes-sdk7/conceptos-basicos-del-contenido-3d/camera.md#using-virtual-cameras). También puedes obtener el `CameraMode` Component para saber si el jugador está usando el modo de cámara en primera o tercera persona; consulta [modo de cámara](/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 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-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 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.