# Referenciar itens no código

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

## Obter 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()` função para referenciar uma dessas entities a partir do seu código.

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

```ts
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')

	// Certifique-se de que ambas as portas existam na scene
	(if door1 && door2){
		// 
	}

}
```

![
](/files/9f5c4add3981d854584029fc15f7f4f7b32b1a62)

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

![
](/files/c1e5073fa6f57d02870fa8ca531b70fb8cb059e3)

Você também pode usar a `engine.getEntityByName<EntityNames>()` função, passando `<EntityNames>` como um [TypeScript generic](https://www.typescriptlang.org/docs/handbook/2/generics.html), 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 avisará você com um erro. Como a saída desta função não pode ser `null`, você pode evitar verificar se a entity existe.

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

function main() {

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

	// Não há necessidade de verificar null
	console.log(Transform.get(door1).position.x)

}
```

{% hint style="warning" %}
**📔 Nota**: Certifique-se de usar `engine.getEntityOrNullByName()` e `engine.getEntityByName()` apenas dentro da `main()` função, em funções que executam após `main()`, ou em um system. Se for usado fora de um desses contextos, as entities criadas no Scene Editor podem ainda não ter sido instanciadas.
{% endhint %}

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

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

function main() {
	// obter 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 `Nome` component, você também pode iterar sobre todas elas assim:

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

## Obter por Tag

Você também pode obter entities pelas 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 via a **Tags** seção no topo do painel de propriedades do item. Você pode escolher entre tags genéricas como **Tag Group 1** até **Tag Group 4**, ou criar a sua própria com um nome mais específico.

![
](/files/de893e44746ac2e12f0c263e63163979c5c93da6)

{% hint style="info" %}
**💡 Dica**: Uma única entity pode ter várias tags atribuídas a ela.

<img src="/files/73987b578a9db61a9c2c8c28e4c6c24f18b0a745" alt="
" data-size="original">
{% endhint %}

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

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

export function main() {
	const taggedEntities = engine.getEntitiesByTag('myTag')
  
	for (const entity of taggedEntities) {
      // Faça 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.

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

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

## Obter todos os filhos de um item

Depois de ter uma referência a um item específico, você pode obter todos os itens que estão agrupados como seus children na entity tree à esquerda da tela. O script a seguir obtém a entity pai e então itera sobre cada um de seus children que têm um component Transform. Você então pode aplicar qualquer lógica personalizada que quiser conforme itera sobre cada um.

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

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

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

## Triggers de smart item

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

Use `getTriggerEvents` para obter um objeto capaz de lidar com eventos de trigger de um smart item específico, depois 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 scene tiver um botão com o seguinte **On Click** evento genérico, você pode escrever o código abaixo para executar código personalizado sempre que o botão for ativado.

![
](/files/2ae0cbed77c357b60f133293c988bb4a41a69918)

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

Você também pode assinar de forma semelhante 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 de um **Actions**, e responder a isso com código personalizado. Por exemplo, você poderia colocar um smart item de porta e executar código personalizado sempre que a **Open** ação for chamada.

Use `getActionEvents` para obter um objeto para lidar com 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 toda vez que a ação acontece, independentemente de a ação ter sido ativada por outro smart item, ou até mesmo pelo seu próprio código personalizado.

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

![
](/files/3568b86fa27781be98009c4ae12db13218a7121f)

```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 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 eventos de action 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 é ativado.

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

{% hint style="info" %}
**💡 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 [Tornando qualquer item smart](/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md).
{% endhint %}

## 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()` função da biblioteca. Você então pode ler ou escrever valores nesses components a partir do código da sua scene, para ter uma integração ainda mais estreita 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 baú, sempre que as actions do baú forem disparadas.

```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>(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: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/reference-items.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.