> 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. 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 a partir de outras partes do seu código. ## Obter pelo 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, exatamente como aparece na visualização 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') // Garanta que ambas as doors existam na scene if (door1 && door2) { // } } ``` ![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-f7f9f97c23a28e3a6021d602807f72c5914d417d%2Fdoor-names.png?alt=media\&token=15e93230-2925-41ae-8fb1-c472fea44d6b) 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, o seu IDE apresentará uma dropdown 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-2768bcc690ab20fce96c5b3f4345e4012b4633ed%2FEntityNames.png?alt=media\&token=9bb9f75b-9d40-4db3-bec8-be9f8a721191) Você também pode usar a `engine.getEntityByName()` function, passando `` como um [generic TypeScript](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, esse método vai avisá-lo com um erro. Como o resultado dessa function 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.Door_1) // Não é necessário verificar null console.log(Transform.get(door1).position.x) } ``` {% hint style="warning" %} **📔 Observação**: Certifique-se de usar apenas `engine.getEntityOrNullByName()` e `engine.getEntityByName()` dentro da `main()` function, em funções que executam depois de `main()`, ou em um system. Se usado fora de um desses contextos, as entities criadas no Scene Editor talvez ainda não estejam instanciadas. {% endhint %} Depois de obter uma referência a uma entity com qualquer um dos métodos acima, você está 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. ```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 PointerEvents pointerEventsSystem.onPointerDown( { entity: door, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Abrir' }, }, 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 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 pela **Tags** seção no topo do Properties panel do item. Você pode escolher entre tags genéricas como **Tag Group 1** até **Tag Group 4**, ou crie as suas próprias 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-4a3c2b9800d4e65c22f83e5cabe22b51f8bdd9ec%2Ftags.png?alt=media\&token=e1d56d51-b512-4f1c-aa9d-03964cfcac1c) {% hint style="info" %} **💡 Dica**: Uma única entity pode ter várias tags atribuídas.  {% endhint %} Você pode então obter todas as entities que têm uma tag específica usando a `engine.getEntitiesByTag()` function. Isso é ideal para 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 para spawnar 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 Assim que você tiver uma referência a um item específico, você pode obter todos os itens agrupados como seus filhos na entity tree à esquerda da tela. O script a seguir obtém a parent entity e depois itera sobre cada um de seus filhos que tenham um Transform component. Você pode então aplicar qualquer lógica personalizada que quiser enquanto itera sobre cada um deles. ```ts import { engine, Entity, Transform, Name, getEntitiesWithParent } from '@dcl/sdk/ecs' import { EntityNames } from '../assets/scene/entity-names' function main() { // obter parent entity const parent = engine.getEntityByName(EntityNames.ParentEntity) // obter a lista completa de filhos const children = getEntitiesWithParent(engine, parent) for (const child of children) { // processar cada entity filha } } ``` ## Gatilhos de smart item Você pode detectar os **Trigger events**, 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 que pode tratar trigger events de um smart item específico, depois use a `.on()` function do objeto retornado para se inscrever em 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** evento genérico, você 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-8c5de89e8950aac8f10e9d799c7ab9a1410c8237%2Frestart-button.png?alt=media\&token=aca1d9bc-1e48-4ef3-a214-820484e75882) ```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() }) } } ``` Da mesma forma, você pode se inscrever em qualquer outro tipo de trigger events, como **ON\_PLAYER\_ENTERS\_AREA**, **ON\_SPAWN**, **ON\_TWEEN\_END**, etc. ## Ações de smart item Você pode detectar a ativação das actions de um smart item **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 tratar as actions de um smart item específico. Depois você pode usar a `.on()` function do objeto retornado para se inscrever em 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é mesmo por código personalizado seu. Por exemplo, se uma scene tiver 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. ![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-32fcce8d20d62bc71c830e43a35b18d0410a2910%2Fdoor-actions.png?alt=media\&token=460e7aa1-0e02-4799-a02b-81abdc869eec) ```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('Porta aberta!!') // código personalizado }) // detectar triggers const triggers = getTriggerEvents(door) triggers.on(TriggerType.ON_CLICK, () => { console.log('Porta clicada!!') // código personalizado }) } } ``` Você também pode emitir action events a partir do seu código, isso permite que você aproveite 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. ```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 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 [Tornar qualquer item smart](/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md). {% endhint %} ## Outros componentes de smart item Smart items podem incluir components especiais que fazem parte da library asset-packs, como `States` ou `Counter`. Esses components não fazem parte do Decentraland SDK, mas podem ser obtidos via a `function getComponents()` da library. Você pode então ler ou escrever values para esses 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ú são 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.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 baú ", 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=&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.