Referenciar ítems en el código

Referencia ítems en tu código por nombre o por tag.

Puedes referenciar elementos que se agregan a través de la interfaz de arrastrar y soltar del Creator Hub en tu código. Esto es útil para añadir comportamientos sofisticados a esos elementos, o para referenciarlos desde otras partes de tu código.

Buscar por nombre

Al usar el Creator Hub y añadir entidades arrastrándolas al lienzo, cada entidad tiene un nombre único. Usa el engine.getEntityOrNullByName() para referenciar una de estas entidades desde tu código.

Usa el EntityNames enum para acceder fácilmente a los nombres de las entidades que agregaste vía el Creator Hub, o escribe el nombre como una cadena tal como aparece en la vista del árbol de entidades de la escena en el Scene Editor.

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){
		// 
	}

}

El EntityNames enum contiene la lista completa de entidades añadidas por el Creator Hub y se actualiza inmediatamente tan pronto como haces cualquier cambio. Si importas EntityNames. en tu código, tu IDE te mostrará un desplegable que incluye todos los nombres de las entidades disponibles.

También puedes usar la engine.getEntityByName<EntityNames>() función, pasando <EntityNames> como un genérico de TypeScript, para validar que una entidad con ese nombre realmente existe en tu escena. Si la entidad referenciada se renombra en el Creator Hub, este método te advertirá con un error. Como la salida de esta función no puede ser null, puedes evitar comprobar que la entidad exista.

import { EntityNames } from '../assets/scene/entity-names'

function main() {

	const door1 = engine.getEntityByName<EntityNames>(EntityNames.Door_1)

	// No es necesario comprobar null
	console.log(Transform.get(door1).position.x)

}

📔 Nota: Asegúrate de usar únicamente engine.getEntityOrNullByName() y engine.getEntityByName() dentro de la main() función, en funciones que se ejecuten después de main(), o en un sistema. Si se usan fuera de uno de esos contextos, las entidades creadas en el Scene Editor pueden no estar aún instanciadas.

Una vez que obtuviste una referencia a una entidad con cualquiera de los métodos anteriores, eres libre de realizar cualquier acción con ella, como añadir o eliminar componentes, modificar valores de componentes existentes, o incluso eliminar la entidad del engine.

import { EntityNames } from '../assets/scene/entity-names'

function main() {
	// obtener entidad
	const door = engine.getEntityOrNullByName(EntityNames.Door_3)
	// verificar que la entidad existe
	if (door) {
		// añadir un callback de pointer events
		pointerEventsSystem.onPointerDown(
			{
				entity: door,
				opts: { button: InputAction.IA_PRIMARY, hoverText: 'Open' },
			},
			function () {
				// abrir puerta
			}
		)
	}
}

Todas las entidades añadidas vía el Scene Editor tienen un componente Name , también puedes iterar sobre todas ellas así:

function main() {
	for (const [entity, name] of engine.getEntitiesWith(Name)) {
		console.log({ entity, name })
	}
}

Buscar por Tag

También puedes obtener entidades por sus tags. Las tags son una forma de agrupar entidades, y son útiles para identificar entidades que tienen el mismo propósito o comportamiento.

Agrega Tags a una entidad a través de la sección Tags en la parte superior del panel de propiedades del ítem. Puedes elegir entre las tags genéricas como Tag Group 1 hasta Tag Group 4, o crear las tuyas con un nombre más específico.

💡 Consejo: Una sola entidad puede tener múltiples tags asignadas.

Luego puedes obtener todas las entidades que tienen una tag específica usando la función engine.getEntitiesByTag() . Esto es ideal cuando quieres iterar sobre un grupo de entidades que tienen el mismo propósito o comportamiento.

import { engine } from '@dcl/sdk/ecs'

export function main() {
	const taggedEntities = engine.getEntitiesByTag('myTag')
  
	for (const entity of taggedEntities) {
      // Haz algo con cada entidad
    }
}

También puedes añadir o eliminar tags a una entidad desde tu código. Esto es útil si quieres cambiar tags según alguna lógica, o para generar entidades dinámicamente que tengan tags específicas.

import { Tags } from '@dcl/sdk/ecs'

Tags.remove(entity, tagName);
Tags.add(entity, tagName);

Obtener todos los hijos de un ítem

Una vez que tienes una referencia a un ítem en particular, puedes obtener todos los ítems que están agrupados como sus hijos en el árbol de entidades a la izquierda de la pantalla. El siguiente script obtiene la entidad padre y luego itera sobre cada uno de sus hijos que tienen un componente Transform. Entonces puedes aplicar cualquier lógica personalizada que desees mientras iteras sobre cada uno.

import { engine, Entity, Transform, Name, getEntitiesWithParent } from '@dcl/sdk/ecs'

function main() {
	// obtener entidad padre
	const parent = engine.getEntityByName<EntityNames>(EntityNames.ParentEntity)

	// obtener lista completa de hijos
	const children = getEntitiesWithParent(engine, myEntity)
	for (const child of children) {
   		// procesar cada entidad hija
	}
}

Disparadores de smart items

Puedes detectar los Trigger eventsde un smart item, y responder a ellos con código personalizado. Por ejemplo, podrías colocar un smart item botón y activar código personalizado cuando se haga clic en el botón.

Usa getTriggerEvents para obtener un objeto que pueda manejar eventos de trigger de un smart item en particular, luego usa la .on() función del objeto retornado para suscribir 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 evento genérico On Click , puedes escribir el código abajo para ejecutar código personalizado cada vez que el botón se active.

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 de trigger, como ON_PLAYER_ENTERS_AREA, ON_SPAWN, ON_TWEEN_END, etc.

Acciones de smart items

Puedes detectar la activación de las Actionsde un smart item, y responder a ellas con código personalizado. Por ejemplo, podrías colocar un smart item puerta y ejecutar código personalizado cada vez que se llame la acción Open .

Usa getActionEvents para obtener un objeto que maneje las acciones de un smart item específico. Luego puedes usar la .on() función del objeto retornado para suscribir una función callback. Esta función callback se ejecuta cada vez que ocurre 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 acción por defecto Open , puedes escribir el código abajo para ejecutar código personalizado cada vez que la puerta se abra.

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 componente Action del smart item. El siguiente fragmento llama a la acción "Open" en un smart item puerta cada vez que se activa un smart item botón.

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 acciones y triggers
		const buttonTriggers = getTriggerEvents(button)
		const doorActions = getActionEvents(door)

		// detectar triggers en el botón
		buttonTriggers.on(TriggerType.ON_INPUT_ACTION, () => {
			// abrir puerta
			doorActions.emit('Open', {})
		})
	}
}

💡 Consejo: Si no estás intentando hacer algo muy complicado, en lugar de escribir código también puedes crear un smart item personalizado para manejar las acciones que deseas realizar. Ver Making any item smart.

Otros componentes de smart items

Los smart items pueden incluir componentes especiales que forman parte de la librería asset-packs, como States u Counter. Estos componentes no son parte del SDK de Decentraland, pero pueden obtenerse vía la función getComponents() de la librería. Entonces puedes leer o escribir valores en estos componentes desde el código de tu escena, para tener una integración aún más estrecha entre el comportamiento del smart item y el código.

El ejemplo abajo lee y registra el valor de un componente State de un smart item cofre, cada vez que se activan las acciones del cofre.

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>(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)
        })
    }
}