Referenciar itens no código

Referencie itens no seu código por nome ou por tag.

Você pode referenciar itens adicionados via a interface de arrastar-e-soltar do Creator Hub no seu código. Isso é útil para adicionar comportamentos sofisticados a esses itens ou para referenciá-los de outras partes do seu código.

Buscar por nome

Ao usar o Creator Hub e adicionar entidades arrastando-as para a tela, cada entidade possui um nome único. Use o engine.getEntityOrNullByName() para referenciar uma dessas entidades a partir do seu código.

Use o EntityNames enum para acessar facilmente os nomes das entidades que você adicionou via Creator Hub, ou escreva o nome como uma string conforme está na visualização da árvore de entidades da cena no Scene Editor.

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

function main() {

	// Use the EntityNames enum
	const door1 = engine.getEntityOrNullByName(EntityNames.Door_1)

	// Write the name as a string
	const door2 = engine.getEntityOrNullByName('Door 2')

	// Ensure both doors exsist in the scene
	(if door1 && door2){
		// 
	}

}

O EntityNames enum contém a lista completa de entidades adicionadas pelo Creator Hub e é atualizado imediatamente assim que você faz qualquer alteração. Se você importar EntityNames. no seu código, seu IDE apresentará um dropdown incluindo todos os nomes das entidades disponíveis.

Você também pode usar o engine.getEntityByName<EntityNames>() função, passando <EntityNames> como um genérico TypeScript, para validar que uma entidade com esse nome realmente existe na sua cena. Se a entidade referenciada for renomeada no Creator Hub, esse método irá avisá-lo com um erro. Como a saída dessa função não pode ser null, você pode evitar verificar se a entidade existe.

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

function main() {

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

	// Ne need to check for null
	console.log(Transform.get(door1).position.x)

}

📔 Nota: Certifique-se de usar apenas engine.getEntityOrNullByName() e engine.getEntityByName() dentro da main() função, em funções que rodem após main(), ou em um sistema. Se usado fora de um desses contextos, as entidades criadas no Scene Editor podem ainda não ter sido instanciadas.

Uma vez que você obtém uma referência para uma entidade com qualquer um dos métodos acima, você está livre para executar qualquer ação com ela, como adicionar ou remover componentes, modificar valores de componentes existentes, ou até remover a entidade do engine.

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

function main() {
	// fetch entity
	const door = engine.getEntityOrNullByName(EntityNames.Door_3)
	// verify that the entity exists
	if (door) {
		// add a pointer events callback
		pointerEventsSystem.onPointerDown(
			{
				entity: door,
				opts: { button: InputAction.IA_PRIMARY, hoverText: 'Open' },
			},
			function () {
				// open door
			}
		)
	}
}

Todas as entidades adicionadas via Scene Editor possuem um componente Name , você também pode iterar sobre todas elas assim:

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

Buscar por Tag

Você também pode buscar entidades por suas tags. Tags são uma forma de agrupar entidades e são úteis para identificar entidades que têm o mesmo propósito ou comportamento.

Adicione Tags a uma entidade via a Tags seção no topo do painel de propriedades do item. Você pode escolher entre as tags genéricas como Tag Group 1 até Tag Group 4, ou criar as suas próprias com um nome mais específico.

💡 Dica: Uma única entidade pode ter múltiplas tags atribuídas a ela.

Você pode então buscar todas as entidades que têm uma tag específica usando a função engine.getEntitiesByTag() . Isso é ideal quando você quer iterar sobre um grupo de entidades que têm o mesmo propósito ou comportamento.

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

export function main() {
	const taggedEntities = engine.getEntitiesByTag('myTag')
  
	for (const entity of taggedEntities) {
      // Do something with each entity
    }
}

Você também pode adicionar ou remover tags de uma entidade a partir do seu código. Isso é útil se você quiser alterar tags com base em alguma lógica, ou para spawnar entidades dinamicamente que tenham tags específicas.

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

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

Buscar todos os filhos de um item

Uma vez que você tem uma referência para um item em particular, você pode buscar todos os itens que estão agrupados como seus filhos na árvore de entidades à esquerda da tela. O script a seguir busca a entidade pai e então itera por cada um dos seus filhos que possuem um componente Transform. Você então pode aplicar qualquer lógica personalizada enquanto itera por cada um.

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

function main() {
	// get parent entity
	const parent = engine.getEntityByName<EntityNames>(EntityNames.ParentEntity)

	// fetch full list of children
	const children = getEntitiesWithParent(engine, myEntity)
	for (const child of children) {
   		// process each child entity
	}
}

Gatilhos de smart item

Você pode detectar os Trigger eventsde um smart item e responder a eles com código personalizado. Por exemplo, você pode colocar um botão smart item e ativar código personalizado quando o botão for clicado.

Use getTriggerEvents para buscar um objeto que pode manipular eventos de trigger de um smart item específico, então use a .on() função do objeto retornado para assinar uma função de callback. Essa função de callback é executada toda vez que o evento de trigger acontece.

Por exemplo, se uma cena tem um botão com o seguinte genérico On Click event, você pode escrever o código abaixo para executar código personalizado sempre que o botão for ativado.

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

Você pode de forma semelhante assinar qualquer outro tipo de eventos de trigger, como ON_PLAYER_ENTERS_AREA, ON_SPAWN, ON_TWEEN_END, etc.

Ações de smart item

Você pode detectar a ativação das Actionsde um smart item e responder a elas com código personalizado. Por exemplo, você pode colocar um smart item de porta e executar código personalizado sempre que a ação Open for chamada.

Use getActionEvents para buscar um objeto para manipular as ações de um smart item específico. Então você pode usar a .on() função do objeto retornado para assinar uma função de callback. Essa função de callback é executada sempre que a ação acontece, independentemente se a ação foi ativada por outro smart item ou mesmo por código personalizado seu.

Por exemplo, se uma cena tem uma porta com a seguinte ação padrão Open , você pode escrever o código abaixo para executar código personalizado sempre que a porta for aberta.

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) {
		// detect actions
		const actions = getActionEvents(door)
		actions.on('Open', () => {
			console.log('Door opened!!')
			// custom code
		})

		// detect triggers
		const triggers = getTriggerEvents(door)
		triggers.on(TriggerType.ON_CLICK, () => {
			console.log('Door clicked!!')
			// custom code
		})
	}
}

Você também pode emitir eventos de ação a partir do seu código, isso permite tirar proveito de ações que já estão definidas dentro do componente Action do smart item. O snippet a seguir chama a ação "Open" em um smart item de porta sempre que um smart item de botão é acionado.

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) {
		// references to actions and triggers
		const buttonTriggers = getTriggerEvents(button)
		const doorActions = getActionEvents(door)

		// detect triggers on button
		buttonTriggers.on(TriggerType.ON_INPUT_ACTION, () => {
			// open door
			doorActions.emit('Open', {})
		})
	}
}

💡 Dica: Se você não estiver tentando fazer algo muito complicado, em vez de escrever código você também pode criar um smart item personalizado para lidar com as ações que deseja executar. Veja Making any item smart.

Outros componentes de smart item

Smart items podem incluir componentes especiais que fazem parte da biblioteca asset-packs, como States ou Counter. Esses componentes não fazem parte do SDK do Decentraland, mas podem ser obtidos via a função getComponents() da biblioteca. Você então pode ler ou escrever valores nesses componentes a partir do código da sua cena, para ter uma integração ainda mais próxima entre o comportamento do smart item e o código.

O exemplo abaixo lê e registra o valor de um componente State de um smart item de baú, sempre que as ações do baú são acionadas.

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