> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/reference-items.md).

# Referenciar itens no código

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

Pode referenciar no seu código os itens adicionados através da interface de arrastar e largar do Creator Hub. Isto é útil para adicionar comportamentos sofisticados a esses itens ou para os referenciar noutras partes do seu código.

## Obter por nome

Ao usar o Creator Hub e adicionar Entities ao arrastá-las para o canvas, cada Entity tem um nome único. Use a `engine.getEntityOrNullByName()` função para referenciar uma destas Entities no seu código.

Use o `EntityNames` enum para aceder facilmente aos nomes das Entities que adicionou através do Creator Hub, ou escreva o nome como aparece na árvore de Entities da cena 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 existem na cena
	if (door1 && door2) {
		// 
	}

}
```

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-c11dd8e7b3d561d90af07abfbb1b15f06e66debc%2Fdoor-names.webp?alt=media)

O `EntityNames` enum contém a lista completa de Entities adicionadas pelo Creator Hub e é atualizado imediatamente sempre que faz alguma alteração. Se importar `EntityNames.` para o seu código, o seu IDE apresentará um menu pendente com todos os nomes das Entities disponíveis.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-d77034ebcb7c9b2f7981331c30ef174ca625cf28%2FEntityNames.webp?alt=media)

Também pode usar a `engine.getEntityByName<EntityNames>()` função, passando `<EntityNames>` como um [genérico TypeScript](https://www.typescriptlang.org/docs/handbook/2/generics.html), para validar que existe na sua cena uma Entity com esse nome. Se a Entity referenciada for renomeada no Creator Hub, este método apresenta um aviso de erro. Como o resultado desta função não pode ser `null`, 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 é necessário verificar se é null
	console.log(Transform.get(door1).position.x)

}
```

{% hint style="warning" %}
**📔 Nota**: Certifique-se de que usa `engine.getEntityOrNullByName()` e `engine.getEntityByName()` apenas dentro da função `main()` , em funções executadas depois de `main()`ou num system. Se forem usadas fora destes contextos, as Entities criadas no Scene Editor poderão ainda não ter sido instanciadas.
{% endhint %}

Depois de obter uma referência a uma Entity com qualquer um dos métodos acima, pode realizar qualquer ação com ela, como adicionar ou remover Components, modificar os valores dos Components existentes ou até remover a Entity do engine.

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

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

Todas as entidades adicionadas através do Scene Editor têm um componente `Name` , também pode iterar sobre todas elas desta forma:

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

## Obter por Tag

Também pode obter entidades pelas respetivas tags. As tags permitem agrupar entidades e são úteis para identificar entidades com a mesma finalidade ou comportamento.

Adicione tags a uma entidade através da secção **Tags** na parte superior do painel de propriedades do item. Pode escolher tags genéricas, como **Tag Group 1** até **Tag Group 4**, ou criar as suas próprias tags com um nome mais específico.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-67f6a44918b44cb9c486d54fb90dd4d4b1f0a2b5%2Ftags.webp?alt=media)

{% hint style="info" %}
**💡 Sugestão**: pode atribuir várias tags a uma única entidade.

<img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e111901f37132a7070e8d9729984fa2fa8c43fc3%2Ftags-multiple.webp?alt=media" alt="" data-size="original">
{% endhint %}

Depois, pode obter todas as entidades que têm uma tag específica utilizando a função `engine.getEntitiesByTag()` . É ideal quando pretende iterar sobre um grupo de entidades com a mesma finalidade ou comportamento.

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

export function main() {
	const taggedEntities = engine.getEntitiesByTag('myTag')
  
	for (const entity of taggedEntities) {
      // Fazer algo com cada entidade
    }
}
```

Também pode adicionar ou remover tags de uma entidade através do seu código. Isto é útil se quiser alterar tags com base em alguma lógica ou criar entidades dinamicamente com 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 obter uma referência a um item específico, pode obter todos os itens agrupados como seus filhos na árvore de entidades à esquerda do ecrã. O script seguinte obtém a entidade principal e, em seguida, itera sobre cada um dos seus filhos que têm um componente Transform. Pode aplicar a lógica personalizada que quiser durante a iteração.

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

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

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

## Acionadores de smart items

Pode detetar os eventos de **acionamento**de um smart item e responder-lhes com código personalizado. Por exemplo, pode colocar um smart item de botão e ativar código personalizado quando se clica no botão.

Utilize `getTriggerEvents` para obter um objeto que pode gerir eventos de acionamento de um smart item específico e, em seguida, utilize a função `.on()` do objeto devolvido para subscrever uma função de callback. Esta função de callback é executada sempre que ocorre o evento de acionamento.

Por exemplo, se uma cena tiver um botão com o seguinte **On Click** evento, pode escrever o código abaixo para executar código personalizado sempre que o botão for ativado.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-354d0c85d770f5e44c32fcd98ce46783df55ff21%2Frestart-button.webp?alt=media)

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

Pode subscrever-se de forma semelhante a qualquer outro tipo de eventos de trigger, como **ON\_PLAYER\_ENTERS\_AREA**, **ON\_SPAWN**, **ON\_TWEEN\_END**, etc.

## Ações de Smart items

Pode detetar a ativação das **Actions**, de um Smart item e responder-lhes com código personalizado. Por exemplo, pode colocar um Smart item de porta e executar código personalizado sempre que a ação **Open** for chamada.

Utilize `getActionEvents` para obter um objeto que permite gerir as ações de um Smart item específico. Depois, pode utilizar a função `.on()` do objeto devolvido para subscrever uma função de callback. Esta função de callback é executada sempre que a ação ocorre, independentemente de ter sido ativada por outro Smart item ou até pelo seu próprio código personalizado.

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

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-24c0cf117e2d98d79b272a087da4c815d4ff1a5d%2Fdoor-actions.webp?alt=media)

```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) {
		// detetar ações
		const actions = getActionEvents(door)
		actions.on('Open', () => {
			console.log('Door opened!!')
			// código personalizado
		})

		// detetar triggers
		const triggers = getTriggerEvents(door)
		triggers.on(TriggerType.ON_CLICK, () => {
			console.log('Door clicked!!')
			// código personalizado
		})
	}
}
```

Também pode emitir eventos de ação a partir do seu código. Isto permite-lhe tirar partido das ações já definidas no componente Action do Smart item. O seguinte excerto chama a ação "Open" de um Smart item de porta sempre que um Smart item de botão é acionado.

```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 a ações e triggers
		const buttonTriggers = getTriggerEvents(button)
		const doorActions = getActionEvents(door)

		// detetar triggers no botão
		buttonTriggers.on(TriggerType.ON_INPUT_ACTION, () => {
			// abrir a porta
			doorActions.emit('Open', {})
		})
	}
}
```

{% hint style="info" %}
**💡 Sugestão**: Se não estiver a tentar fazer algo muito complicado, em vez de escrever código, também pode criar um Smart item personalizado para tratar das ações que pretende realizar. Consulte [Tornar qualquer item inteligente](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md).
{% endhint %}

## Outros componentes de Smart items

Os Smart items podem incluir Components especiais que fazem parte da biblioteca asset-packs, como `States` ou `Counter`. Estes Components não fazem parte do SDK da Decentraland, mas podem ser obtidos através da `getComponents()` função da biblioteca. Em seguida, pode ler ou escrever valores nestes Components a partir do código da sua Scene, para uma integração ainda mais estreita entre o comportamento dos Smart items e o código.

O exemplo abaixo lê e regista o valor de um Component State de um Smart item baú sempre que as ações do baú são acionadas.

```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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
