> 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/scene-editor/extender-con-codigo/reference-items.md). # Referenciar ítems en el código Referencia ítems en tu código por nombre o por etiqueta. Puedes hacer referencia a los items que se agregan mediante la interfaz de arrastrar y soltar de Creator Hub en tu código. Esto es útil para añadir comportamiento sofisticado a esos items, o para referenciarlos desde otras partes de tu código. ## Buscar por nombre Al usar Creator Hub y añadir entities arrastrándolas al canvas, cada entity tiene un nombre único. Usa la `engine.getEntityOrNullByName()` function para hacer referencia a una de estas entities desde tu código. Usa el `EntityNames` enum para acceder fácilmente a los nombres de las entities que añadiste mediante Creator Hub, o escribe el nombre como una cadena tal como aparece en la vista del entity tree de la escena en el Scene Editor. ```ts import { EntityNames } from '../assets/scene/entity-names' function main() { // Usa el enum EntityNames const door1 = engine.getEntityOrNullByName(EntityNames.Door_1) // Escribe el nombre como una cadena const door2 = engine.getEntityOrNullByName('Door 2') // Asegúrate de que ambas puertas existan en la escena if (door1 && door2) { // } } ``` ![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-f7f9f97c23a28e3a6021d602807f72c5914d417d%2Fdoor-names.png?alt=media\&token=15e93230-2925-41ae-8fb1-c472fea44d6b) El `EntityNames` enum contiene la lista completa de entities agregadas por Creator Hub y se actualiza inmediatamente en cuanto haces cualquier cambio. Si importas `EntityNames.` en tu código, tu IDE te mostrará un dropdown que incluirá todos los nombres de las entities disponibles. ![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-2768bcc690ab20fce96c5b3f4345e4012b4633ed%2FEntityNames.png?alt=media\&token=9bb9f75b-9d40-4db3-bec8-be9f8a721191) También puedes usar la `engine.getEntityByName()` function, passing `` as a [TypeScript generic](https://www.typescriptlang.org/docs/handbook/2/generics.html), para validar que realmente exista una entity con ese nombre en tu escena. Si la entity referenciada se renombra en Creator Hub, este método te avisará con un error. Como la salida de esta function no puede ser `null`, puedes evitar comprobar que la entity exista. ```ts import { EntityNames } from '../assets/scene/entity-names' function main() { const door1 = engine.getEntityByName(EntityNames.Door_1) // No hace falta comprobar si es null console.log(Transform.get(door1).position.x) } ``` {% hint style="warning" %} **📔 Nota**: Asegúrate de usar solo `engine.getEntityOrNullByName()` y `engine.getEntityByName()` 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 el Scene Editor aún no se hayan instanciado. {% endhint %} Una vez que hayas obtenido una referencia a una entity con cualquiera de los métodos anteriores, puedes realizar libremente cualquier acción con ella, como agregar o remover components, modificar valores de components existentes, o incluso remover la entity del engine. ```ts import { EntityNames } from '../assets/scene/entity-names' function main() { // obtener entity const door = engine.getEntityOrNullByName(EntityNames.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 agregadas mediante el Scene Editor tienen un `Nombre` component, también puedes iterar sobre todas ellas así: ```ts function main() { for (const [entity, name] of engine.getEntitiesWith(Name)) { console.log({ entity, name }) } } ``` ## Buscar por Tag También puedes obtener entities por sus tags. Los tags son una forma de agrupar entities, y son útiles para identificar entities que tienen el mismo propósito o comportamiento. Agrega Tags a una entity mediante la **Tags** section en la parte superior del panel de propiedades del item. Puedes elegir entre los tags genéricos como **Tag Group 1** hasta **Tag Group 4**, o crear los tuyos propios con un nombre más específico. ![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-4a3c2b9800d4e65c22f83e5cabe22b51f8bdd9ec%2Ftags.png?alt=media\&token=e1d56d51-b512-4f1c-aa9d-03964cfcac1c) {% hint style="info" %} **💡 Consejo**: Una sola entity puede tener asignados múltiples tags.  {% endhint %} Luego puedes obtener todas las entities que tengan un tag específico usando la `engine.getEntitiesByTag()` function. Esto es ideal cuando quieres iterar sobre un grupo de entities que tengan el mismo propósito o comportamiento. ```ts import { engine } from '@dcl/sdk/ecs' export function main() { const taggedEntities = engine.getEntitiesByTag('myTag') for (const entity of taggedEntities) { // Hacer algo con cada entity } } ``` También puedes agregar o remover tags de una entity desde tu código. Esto es útil si quieres cambiar tags según alguna lógica, o generar entities dinámicamente que tengan tags específicos. ```ts import { Tags } from '@dcl/sdk/ecs' Tags.remove(entity, tagName); Tags.add(entity, tagName); ``` ## Obtener todos los hijos de un item Una vez que tengas una referencia a un item en particular, puedes obtener todos los items que están agrupados como sus hijos en el entity tree a la izquierda de la pantalla. El siguiente script obtiene la entity padre y luego itera sobre cada uno de sus hijos que tienen un componente Transform. Luego puedes aplicar cualquier lógica personalizada que quieras mientras iteras sobre cada uno. ```ts import { engine, Entity, Transform, Name, getEntitiesWithParent } from '@dcl/sdk/ecs' import { EntityNames } from '../assets/scene/entity-names' function main() { // obtener entity padre const parent = engine.getEntityByName(EntityNames.ParentEntity) // obtener la lista completa de hijos const children = getEntitiesWithParent(engine, parent) for (const child of children) { // procesar cada entity hija } } ``` ## Activadores de smart items Puedes detectar los **eventos Trigger**, y responder a estos con código personalizado. Por ejemplo, podrías colocar un smart item de botón y activar código personalizado cuando se haga clic en el botón. Usa `getTriggerEvents` para obtener un objeto capaz de gestionar los eventos Trigger de un smart item concreto; luego usa la `.on()` function del objeto devuelto para suscribirte a una función callback. Esta función callback se ejecuta cada vez que ocurre el evento Trigger. Por ejemplo, si una escena tiene un botón con el siguiente **On Click** event genérico, puedes escribir el código de abajo para ejecutar código personalizado cada vez que se active el botón. ![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-8c5de89e8950aac8f10e9d799c7ab9a1410c8237%2Frestart-button.png?alt=media\&token=aca1d9bc-1e48-4ef3-a214-820484e75882) ```ts import { engine } from '@dcl/sdk/ecs' import { getTriggerEvents, getActionEvents } from '@dcl/asset-packs/dist/events' import { TriggerType } from '@dcl/asset-packs' import { EntityNames } from '../assets/scene/entity-names' function main() { const restart = engine.getEntityOrNullByName(EntityNames.Restart_Button) if (restart) { const restart_event = getTriggerEvents(restart) restart_event.on(TriggerType.ON_CLICK, () => { // restartGame() }) } } ``` De manera similar, puedes suscribirte a cualquier otro tipo de eventos Trigger, como **ON\_PLAYER\_ENTERS\_AREA**, **ON\_SPAWN**, **ON\_TWEEN\_END**, etc. ## Acciones de smart items Puedes detectar la activación de la **Actions**, y responder a esto con código personalizado. Por ejemplo, podrías colocar un smart item de puerta, y ejecutar código personalizado cada vez que la **Open** action gets called. Usa `getActionEvents` para obtener un objeto para gestionar las acciones de un smart item específico. Luego puedes usar la `.on()` function del objeto devuelto para suscribirte a una función callback. Esta función callback se ejecuta cada vez que sucede la acción, independientemente de si la acción fue activada por otro smart item o incluso por código personalizado tuyo. Por ejemplo, si una escena tiene una puerta con la siguiente **Open** acción predeterminada, puedes escribir el código de abajo para ejecutar código personalizado cada vez que se abra la puerta. ![](https://1216664193-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-32fcce8d20d62bc71c830e43a35b18d0410a2910%2Fdoor-actions.png?alt=media\&token=460e7aa1-0e02-4799-a02b-81abdc869eec) ```ts import { engine } from '@dcl/sdk/ecs' import { getTriggerEvents, getActionEvents } from '@dcl/asset-packs/dist/events' import { TriggerType } from '@dcl/asset-packs' import { EntityNames } from '../assets/scene/entity-names' function main() { const door = engine.getEntityOrNullByName(EntityNames.Wooden_Door) if (door) { // detectar acciones const actions = getActionEvents(door) actions.on('Open', () => { console.log('Door opened!!') // código personalizado }) // detectar triggers const triggers = getTriggerEvents(door) triggers.on(TriggerType.ON_CLICK, () => { console.log('Door clicked!!') // código personalizado }) } } ``` También puedes emitir eventos de acción desde tu código; esto te permite aprovechar acciones que ya están definidas dentro del component Action del smart item. El siguiente fragmento llama a la acción "Open" en un smart item de puerta cada vez que se activa un smart item de botón. ```ts import { engine } from '@dcl/sdk/ecs' import { getTriggerEvents, getActionEvents } from '@dcl/asset-packs/dist/events' import { TriggerType } from '@dcl/asset-packs' import { EntityNames } from '../assets/scene/entity-names' function main() { const button = engine.getEntityOrNullByName(EntityNames.Red_Button) const door = engine.getEntityOrNullByName(EntityNames.Wooden_Door) if (button && door) { // referencias a actions y triggers const buttonTriggers = getTriggerEvents(button) const doorActions = getActionEvents(door) // detectar triggers en el botón buttonTriggers.on(TriggerType.ON_INPUT_ACTION, () => { // abrir la puerta doorActions.emit('Open', {}) }) } } ``` {% hint style="info" %} **💡 Consejo**: Si no estás tratando de hacer algo muy complicado, en vez de escribir código también puedes crear un smart item personalizado para manejar las acciones que quieras realizar. Consulta [Hacer smart cualquier item](/creator/content-creator-es/scene-editor/interactividad/make-any-item-smart.md). {% endhint %} ## Otros components de smart item Los smart items pueden incluir components especiales que forman parte de la library asset-packs, como `States` o `Counter`. Estos components no forman parte del Decentraland SDK, pero se pueden obtener mediante la `getComponents()` function de la library. Luego puedes leer o escribir values en estos components desde el código de tu scene, para lograr una integración aún más estrecha entre el comportamiento del smart item y el código. El siguiente ejemplo lee y registra el value de un component State de un smart item de cofre, cada vez que se activan las actions del cofre. ```ts import { engine } from '@dcl/sdk/ecs' import { getComponents } from '@dcl/asset-packs' import { getTriggerEvents } from '@dcl/asset-packs/dist/events' import { TriggerType } from '@dcl/asset-packs' import { EntityNames } from '../assets/scene/entity-names' export function main() { const chest = engine.getEntityByName(EntityNames.chest) if (chest) { const chestTriggers = getTriggerEvents(chest) chestTriggers.on(TriggerType.ON_INPUT_ACTION, () => { const { States } = getComponents(engine) let state = States.getMutableOrNull(chest)?.currentValue console.log( "chest new state ", state) }) } } ``` --- # 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/scene-editor/extender-con-codigo/reference-items.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.