> 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 items no código 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()` 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') // Garanta que ambas as doors existam na scene if (door1 && door2) { // } } ``` ![](/files/9f5c4add3981d854584029fc15f7f4f7b32b1a62) 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.` no seu código, seu IDE apresentará um dropdown com todos os nomes das entities disponíveis. ![](/files/c1e5073fa6f57d02870fa8ca531b70fb8cb059e3) Você também pode usar a `engine.getEntityByName()` função, passando `` como um [genérico de 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, este método mostrará 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.Door_1) // Não há necessidade de 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()` função, em funções que executam após `main()`, ou em um system. Se usado fora de um desses contextos, as entities criadas no Scene Editor talvez ainda não tenham sido instanciadas. {% endhint %} Depois de obter uma referência a 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é mesmo remover a entity do engine. ```ts 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 uma callback de pointer events pointerEventsSystem.onPointerDown( { entity: door, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Open' }, }, function () { // abrir a door } ) } } ``` 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 }) } } ``` ## Buscar por Tag Você também pode buscar entities pelas suas tags. Tags são uma forma de agrupar entities juntas 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 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.  {% endhint %} Você pode então buscar 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 mudar tags com base em alguma lógica, ou para spawn entities dinamicamente que tenham tags específicas. ```ts 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 a um item específico, você pode buscar todos os itens que estão agrupados como seus children na entity tree à esquerda da tela. O seguinte script busca a entity pai e então itera sobre cada um de seus children que têm um component Transform. Você pode então aplicar qualquer lógica personalizada que quiser à medida que iterar sobre cada um. ```ts import { engine, Entity, Transform, Name, getEntitiesWithParent } from '@dcl/sdk/ecs' import { EntityNames } from '../assets/scene/entity-names' function main() { // obter a entity pai const parent = engine.getEntityByName(EntityNames.ParentEntity) // buscar a lista completa de children const children = getEntitiesWithParent(engine, parent) for (const child of children) { // processar cada child entity } } ``` ## Triggers de smart item Você pode detectar os **Trigger events**, de um smart item, 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 buscar um objeto que possa lidar com trigger events de um smart item específico, depois use a `.on()` função do objeto 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** 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 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 da **Actions**, de um smart item's, e responder a ela com código personalizado. Por exemplo, você poderia colocar um smart item de door e executar código personalizado sempre que a **Open** action for chamada. Use `getActionEvents` para buscar um objeto para lidar com as actions de um smart item específico. Então você pode usar a `.on()` função do objeto 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é mesmo por código personalizado seu. Por exemplo, se uma scene tiver uma door com a seguinte **Open** action padrão, você pode escrever o código abaixo para executar código personalizado sempre que a door 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 action events a partir do seu código; isso permite tirar proveito de actions que já estão definidas dentro do component Action do smart item. O trecho abaixo chama a action "Open" em um smart item de door 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 para actions e triggers const buttonTriggers = getTriggerEvents(button) const doorActions = getActionEvents(door) // detectar triggers no botão buttonTriggers.on(TriggerType.ON_INPUT_ACTION, () => { // abrir a door 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 library asset-packs, como `States` ou `Counter`. Esses components não fazem parte do Decentraland SDK, mas podem ser buscados via a `getComponents()` função da library. Você então pode 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 chest, sempre que as actions do chest forem 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.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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.