Referenciar itens no código

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

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

Buscar por nome

Ao usar o Creator Hub e adicionar entities arrastando-as para o canvas, cada entity tem um nome único. Use a engine.getEntityOrNullByName() function para referenciar uma dessas entities a partir do seu código.

Use o EntityNames enum para acessar facilmente os nomes das entities que você adicionou via o Creator Hub, ou escreva o nome como uma string, como escrito na visualização da entity tree da scene no Scene Editor.

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

function main() {

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

	// Escreva o nome como uma string
	const door2 = engine.getEntityOrNullByName('Door 2')

	// Garanta que ambas as portas existam na scene
	(if door1 && door2){
		// 
	}

}

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

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

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

function main() {

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

	// Não é necessário verificar null
	console.log(Transform.get(door1).position.x)

}

📔 Nota: Certifique-se de usar engine.getEntityOrNullByName() e engine.getEntityByName() apenas dentro da main() function, em functions que executam depois de main(), ou em um system. Se usado fora de um desses contextos, as entities criadas no Scene Editor podem ainda não ter sido instanciadas.

Depois de obter uma referência para uma entity com qualquer um dos métodos acima, você fica livre para executar qualquer ação com ela, como adicionar ou remover components, modificar valores de components existentes ou até remover a entity do engine.

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

function main() {
	// buscar entity
	const door = engine.getEntityOrNullByName(EntityNames.Door_3)
	// verificar se a entity existe
	if (door) {
		// adicionar um callback de pointer events
		pointerEventsSystem.onPointerDown(
			{
				entity: door,
				opts: { button: InputAction.IA_PRIMARY, hoverText: 'Open' },
			},
			function () {
				// abrir porta
			}
		)
	}
}

Todas as entities adicionadas via o Scene Editor têm um Os seguintes campos estão disponíveis: component, 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 entities por suas tags. Tags são uma forma de agrupar entities, e são úteis para identificar entities que têm o mesmo propósito ou comportamento.

Adicione Tags a uma entity por meio da Tags section no topo do painel de properties do item. Você pode escolher entre as tags genéricas como Tag Group 1 até Tag Group 4, ou criar a sua própria com um nome mais específico.

💡 Dica: Uma única entity pode ter várias tags atribuídas a ela.

Depois você pode buscar todas as entities que têm uma tag específica usando a engine.getEntitiesByTag() function. Isso é ideal quando você quer iterar sobre um grupo de entities 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) {
      // Fazer algo com cada entity
    }
}

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

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

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

Buscar todos os children de um item

Depois de ter uma referência para um item específico, você pode buscar todos os itens que estão agrupados como seus children na entity tree à esquerda da tela. O script a seguir busca a parent entity e então itera sobre cada um de seus children que possuem um component Transform. Você pode então aplicar qualquer lógica personalizada que desejar enquanto itera sobre cada um.

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

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

	// buscar a lista completa de children
	const children = getEntitiesWithParent(engine, myEntity)
	for (const child of children) {
   		// processar cada child entity
	}
}

Smart item triggers

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

Use getTriggerEvents para obter um object que possa lidar com trigger events de um smart item específico, e então usar a .on() function do object retornado para assinar uma callback function. Essa callback function é executada toda vez que o trigger event acontece.

Por exemplo, se uma scene tiver um botão com o seguinte On Click event genérico, 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ê também pode assinar de forma semelhante qualquer outro tipo de trigger events, como ON_PLAYER_ENTERS_AREA, ON_SPAWN, ON_TWEEN_END, etc.

Smart item actions

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

Use getActionEvents para obter um object para lidar com as actions de um smart item específico. Então você pode usar a .on() function do object retornado para assinar uma callback function. Essa callback function é executada toda vez que a action acontece, independentemente de a action ter sido ativada por outro smart item ou até por código personalizado seu.

Por exemplo, se uma scene tiver uma porta com a seguinte Open action padrão, 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) {
		// detectar actions
		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
		})
	}
}

Você também pode emitir action events a partir do seu código; isso permite aproveitar actions que já estão definidas dentro do component Action do smart item. O trecho a seguir chama a action "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) {
		// referências para actions e triggers
		const buttonTriggers = getTriggerEvents(button)
		const doorActions = getActionEvents(door)

		// detectar triggers no botão
		buttonTriggers.on(TriggerType.ON_INPUT_ACTION, () => {
			// abrir porta
			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 actions que deseja executar. Veja Making any item smart.

Outros components de smart item

Smart items podem incluir components especiais que fazem parte da biblioteca asset-packs, como States ou Counter. Esses components não fazem parte do Decentraland SDK, mas podem ser obtidos via a getComponents() function da biblioteca. Então você pode ler ou escrever valores nesses components a partir do código da sua scene, 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 component State de um smart item de chest, sempre que as actions do chest 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( "novo estado do chest ", state)
        })
    }
}