Referenciar elementos en el código

Referencia elementos en tu código por nombre o por etiqueta.

Puedes referenciar elementos que se añaden mediante 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() función 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 añadiste 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 existen 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 realizas 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 el engine.getEntityByName<EntityNames>() función, pasando <EntityNames> como un TypeScript generic, para validar que realmente existe en tu escena una entidad con ese nombre. 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 si es 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 usa fuera de uno de esos contextos, las entidades creadas en el Scene Editor podrían no haber sido instanciadas aún.

Una vez que obtienes 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 mediante 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 etiqueta

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

Añade Tags a una entidad mediante la Tags sección en la parte superior del panel de propiedades del ítem. Puedes escoger entre tags genéricos como Tag Group 1 hasta Tag Group 4, o crear los tuyos propios con un nombre más específico.

💡 Consejo: Una única entidad puede tener múltiples tags asignados.

Luego puedes obtener todas las entidades que tienen una etiqueta específica usando la engine.getEntitiesByTag() función. Esto es ideal cuando quieres iterar sobre un grupo de entidades que comparten 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 de una entidad desde tu código. Esto es útil si quieres cambiar tags según cierta lógica, o para generar entidades dinámicamente que tengan tags específicos.

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

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

Obtener todos los hijos de un ítem

También puedes escribir un script que te permita manejar todos los ítems que están agrupados como hijos de cierto ítem en el árbol de entidades a la izquierda de la pantalla. El siguiente script itera sobre todas las entidades que tienen un Transform y un padre, y comprueba si el nombre del padre coincide con el nombre some-parent en este caso. Luego puedes aplicar cualquier lógica personalizada que quieras a esas entidades específicas.

import { engine, Entity, Transform, Name } from '@dcl/sdk/ecs'
import { EntityNames } from '../assets/scene/entity-names'

function main() {
	// obtener entidad padre
	const parent = engine.getEntityByName<EntityNames>(EntityNames.ParentEntity)
	
	// obtener todas las entidades hijas de ese padre
	const childEntities = getChildren(parent)
	
	// recorrer cada hijo
	for(const entity of childEntities){
		// manejar entidad
	}

}

// función reutilizable para obtener todas las entidades hijas de un padre
function getChildren(parent: Entity): Entity[] {
	const childEntities: Entity[] = []
	for (const [entity, transform] of engine.getEntitiesWith(Transform)) {
		if (transform.parent === parent) {
			childEntities.push(entity)
		}
	}
	return childEntities
}

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 hace clic en el botón.

Usa getTriggerEvents para obtener un objeto que pueda manejar eventos 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 sucede el evento trigger.

Por ejemplo, si una escena tiene un botón con el siguiente genérico On Click evento, puedes escribir el código abajo para ejecutar código personalizado cada vez que el botón se activa.

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 forma 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 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 la Open acción sea llamada.

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 la acción ocurre, ya sea que la acción haya sido activada por otro smart item o incluso por código personalizado propio.

Por ejemplo, si una escena tiene una puerta con la siguiente acción por defecto Open action, puedes escribir el código abajo para ejecutar código personalizado cada vez que la puerta se abre.

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 intentas hacer algo muy complicado, en lugar de escribir código también puedes crear un smart item personalizado para manejar las acciones que quieres realizar. Ver Making any item smart.

Otros componentes de smart items

Los smart items pueden incluir componentes especiales que forman parte de la biblioteca asset-packs, como States u Counter. Estos componentes no forman parte del SDK de Decentraland, pero pueden obtenerse mediante la getComponents() función desde la biblioteca. Luego puedes leer o escribir valores en estos componentes desde el código de tu escena, para lograr 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)
        })
    }
}