> 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/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md). # Registrar Callback Saiba como lidar com cliques de usuário na sua scene. A maneira mais fácil de lidar com eventos de botão é registrar uma função de callback para uma Entity específica. Toda vez que essa Entity é interagida usando um botão específico, a função de callback é chamada. Se você precisar adicionar o mesmo comportamento a várias entities semelhantes, considere usar a [baseada em System](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md) em vez de adicionar callbacks a cada Entity. A abordagem baseada em System pode resultar em maior eficiência à medida que você itera por uma lista de entities semelhantes. A abordagem Register callback é especialmente útil se você quiser descrever um comportamento que afeta uma única Entity, pois é mais direta. {% hint style="warning" %} **📔 Observação**:\ Para que uma Entity seja interativa, ela **devem** ter um [collider](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md). Veja [obstáculos](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#obstacles) para mais detalhes. {% endhint %} ## Pointer down Use `pointerEventsSystem.onPointerDown()` para detectar pressões de um botão específico. Esta instrução requer dois parâmetros: * `dados`: Um objeto que contém o seguinte: * `entity`: A Entity a ser tratada * `opts`: Um objeto com dados adicionais opcionais: * `button`: Qual botão escutar. Veja [Botões do Pointer](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) para opções compatíveis. Se nenhum button for especificado, então todos os botões são escutados, incluindo botões de movimento como forward e jump. * `maxDistance`: A distância máxima entre a Entity e o **avatar**, em metros. 10 por padrão. Veja [Limites de distância](#distance-limits). * `maxCameraDistance`: A distância máxima entre a Entity e a **câmera ativa**, em metros. Não definido por padrão. Veja [Limites de distância](#distance-limits). * `hoverText`: Qual string exibir na dica de feedback de hover. "Interact" por padrão. * `showFeedback`: Se false, oculta tanto a dica de hover quanto o realce da borda para esta Entity. *true* por padrão. * `showHighlight`: Se true, os players verão o realce da borda ao passar o cursor sobre a Entity. *true* por padrão. Esse valor só é considerado se `showFeedback` é *true*. * `cb`: Uma função de callback para executar sempre que ocorrer um evento de button down enquanto aponta para a Entity ```ts pointerEventsSystem.onPointerDown( { entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Click' }, }, function () { console.log('clicked entity') } ) ``` O comando acima deixa a função de callback registrada, e ela será chamada toda vez que o evento de botão relacionado ocorrer. Observe que o callback deve ser uma função síncrona; `async` funções não são compatíveis aqui e resultam em um erro. {% hint style="warning" %} **📔 Observação**:\ Apenas um `pointerEventsSystem.onPointerDown` pode ser registrado por Entity. Uma vez adicionado, ele continuará escutando eventos até que o listener seja removido. Não execute isso repetidamente dentro de um System, pois isso continuaria reescrevendo o comportamento do pointer event. {% endhint %} ## Feedback ao passar o mouse É muito importante dar aos players algum tipo de indicação de que uma Entity pode ser interagida. Ao registrar uma input action com o `EventsSystem`, por padrão, os players verão: * Um realce de borda na Entity * Uma dica de hover perto do cursor com um ícone para o botão que precisam pressionar e uma string que diz "Interact". Esses elementos podem ser ativados/desativados e personalizados. O feedback de hover na UI exibe um ícone diferente dependendo de qual input você selecionar no `button` campo. No PC, ele exibe um ícone com um `E` para `InputAction.IA_PRIMARY`, um `F` para `InputAction.IA_SECONDARY`, e um mouse para `InputAction.IA_POINTER`. Altere a string alterando o `hoverText` valor. Mantenha essa string curta, para que seja rápida de ler e não seja muito intrusiva na tela. ```ts pointerEventsSystem.onPointerDown( { entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Open door' }, }, function () { // abrir porta } ) ``` Para ocultar a dica de hover, mas manter o realce da borda, defina o valor do `hoverText` para "". ```ts pointerEventsSystem.onPointerDown( {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: ''}}, function () { console.log("clicked on surprise interactive item") } ) ``` Para ocultar o realce da borda, mas manter a dica de hover, defina `showHighlight` como *false*. ```ts pointerEventsSystem.onPointerDown( { entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Open door', showHighlight: false, }, }, function () { console.log('opened secret door') } ) ``` Para ocultar tanto a dica de hover quanto o realce da borda, defina `showFeedback` como *false*. Ao fazer isso, o cursor não mostra nenhum ícone, texto nem realce de borda. ```ts pointerEventsSystem.onPointerDown( {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, showFeedback: false}}, function () { console.log("opened secret door") } ) ``` ### Alterar feedback existente Ao registrar uma input action com o `EventsSystem`, isso está criando um `PointerEvents` Component e adicionando-o à Entity interativa nos bastidores. Esse Component lida com o comportamento da dica de hover da UI. Para alterar o comportamento do feedback de hover, modifique este Component. Veja [Mostrar feedback](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md#show-feedback) para saber mais sobre como lidar com este Component. ```ts const hoverFeedback = PointerEvents.getMutable(myEntity) if (hoverFeedback.pointerEvents[0]?.eventInfo) { hoverFeedback.pointerEvents[0].eventInfo.hoverText = 'Close door' } ``` ## Limites de distância Por padrão, um player só pode interagir com uma Entity quando o seu **avatar** está a até 10 metros dela. Se o player estiver longe demais, o efeito de realce da Entity fica vermelho em vez de verde, e os pointer events não são disparados. Use `maxDistance` para alterar esse alcance: ```ts // Só clicável quando o avatar do player estiver a até 5 metros pointerEventsSystem.onPointerDown( { entity: myEntity, opts: { maxDistance: 5 } }, function () { console.log('clicked entity') } ) ``` ### Limitar pela distância da câmera `maxCameraDistance` mede a partir da **câmera ativa atualmente** em vez do avatar. Isso é útil quando sua Scene usa uma [Virtual Camera](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/camera.md#using-virtual-cameras) colocada longe do player, e você quer que a Entity seja clicável com base no que a câmera consegue ver. ```ts // Só clicável quando a câmera ativa estiver a até 15 metros pointerEventsSystem.onPointerDown( { entity: myEntity, opts: { maxCameraDistance: 15 } }, function () { console.log('clicked entity') } ) ``` ### Como os dois limites se combinam As duas opções são verificações independentes. Quais delas são executadas depende do que você definir: | O que você define | O que o player precisa | | -------------------------- | -------------------------------------------------- | | Nenhum | Avatar a até 10 metros (o padrão) | | `maxDistance` apenas | Avatar a até `maxDistance` | | `maxCameraDistance` apenas | Câmera a até `maxCameraDistance` | | Ambos | **Qualquer um** passar na verificação é suficiente | Definir ambos é uma forma de dizer "perto o bastante para chegar até ele caminhando, **ou** perto o bastante para vê-lo claramente": ```ts // Clicável quando o avatar estiver a até 3 metros OU a câmera estiver a até 20 metros pointerEventsSystem.onPointerDown( { entity: myEntity, opts: { maxDistance: 3, maxCameraDistance: 20 } }, function () { console.log('clicked entity') } ) ``` {% hint style="warning" %} **📔 Observação**: `maxCameraDistance` requer `@dcl/sdk` versão 7.28.0 ou mais recente. O suporte para isso já está disponível no Explorer baseado em Bevy. Se sua Scene precisar se comportar de forma idêntica em cada client hoje, confie em `maxDistance` e trate `maxCameraDistance` como uma melhoria. {% endhint %} ### maxPlayerDistance está obsoleto `maxPlayerDistance` é um alias obsoleto de `maxDistance`: ambos medem a distância a partir do avatar. Use `maxDistance` em novas Scenes. Se uma Scene definir ambos, o **maior** dos dois é usado como limite de distância do avatar. ## Pointer up Use `pointerEventsSystem.onPointerUp` para registrar uma função de callback que é chamada quando o player indicado solta o botão enquanto aponta para a Entity. ```ts pointerEventsSystem.onPointerUp( { entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Button up' }, }, function () { console.log('button up') } ) ``` Esta instrução requer dois parâmetros: * `dados`: Um objeto que contém o seguinte: * `entity`: A Entity a ser tratada * `opts`: Um objeto com dados adicionais opcionais: * `button`: Qual botão escutar. Veja [Botões do Pointer](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) para opções compatíveis. Se nenhum button for especificado, então todos os botões são escutados, incluindo botões de movimento como forward e jump. * `hoverText`: Qual string exibir na dica de feedback de hover. "Interact" por padrão. * `showFeedback`: Se false, oculta a dica de hover para esta Entity. *true* por padrão. * `maxDistance`: Quão longe o avatar do player pode estar da Entity e ainda interagir com ela, em metros. 10 por padrão. Se o player estiver longe demais, não haverá feedback de hover e os pointer events não funcionarão. Veja [Limites de distância](#distance-limits). * `cb`: Uma função de callback para executar sempre que ocorrer um evento de button up enquanto aponta para a Entity. Uma mesma Entity pode ter dois callbacks diferentes registrados, um para `pointerEventsSystem.onPointerDown` e outro para `pointerEventsSystem.onPointerUp`. A Entity só pode registrar um callback de cada, [Lidar com vários botões](#handle-multiple-buttons) para detectar botões diferentes em um mesmo callback. {% hint style="warning" %} **📔 Observação**: O feedback de hover para um evento de button up só é exibido quando o botão está atualmente pressionado. Se o player apontar para a Entity sem manter o botão pressionado, ele não verá feedback nenhum, ou o feedback do evento de button down, se houver. {% endhint %} ## Entrada e saída do hover Use `pointerEventsSystem.onPointerHoverEnter` para executar uma função de callback quando o cursor do player começar a apontar para uma Entity, e `pointerEventsSystem.onPointerHoverLeave` quando o cursor parar de apontar para ela. ```ts pointerEventsSystem.onPointerHoverEnter( { entity: myEntity, opts: { button: InputAction.IA_POINTER }, }, function () { console.log('Cursor started hovering over entity') } ) pointerEventsSystem.onPointerHoverLeave( { entity: myEntity, opts: { button: InputAction.IA_POINTER }, }, function () { console.log('Cursor stopped hovering over entity') } ) ``` Esses callbacks são úteis para efeitos personalizados de hover, como tocar um som ou animar a Entity quando o player mira nela. ## Remover callbacks Para remover uma função de callback, use a função de remoção correspondente: ```ts pointerEventsSystem.removeOnPointerDown(myEntity) pointerEventsSystem.removeOnPointerUp(myEntity) pointerEventsSystem.removeOnPointerHoverEnter(myEntity) pointerEventsSystem.removeOnPointerHoverLeave(myEntity) ``` Uma vez removido, o feedback de hover na Entity não deve mais ser exibido, e a Entity não deve mais ser interativa. Cada função de remoção remove apenas a entrada que sua função de registro correspondente adicionou. Registrar e remover o mesmo callback repetidamente não deixa entradas obsoletas na Entity. ## Interações de proximidade Para interações que são acionadas com base na proximidade do player, e não na mira do cursor, veja [**Proximity Events**](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/proximity-events.md). O `pointerEventsSystem` inclui helpers equivalentes (`onProximityDown`, `onProximityUp`, `onProximityEnter`, e `onProximityLeave`) que seguem o mesmo padrão das funções descritas nesta página. Uma Entity pode ter tanto um handler de cursor quanto um handler de proximidade para o mesmo tipo de evento. Ambos os callbacks são executados, cada um quando sua própria condição é atendida. ### Dados da input action Obtenha dados de uma input action, como o botão que foi pressionado, a Entity que foi atingida, a direção e o comprimento do ray, etc. Veja ([Ver documentação](https://github.com/decentraland/docs/tree/main/README.md)) para uma descrição de todos os dados disponíveis. Para obter esses dados, passe um parâmetro para a função de callback. Esse parâmetro contém a estrutura completa de dados sobre o input event. ```ts pointerEventsSystem.onPointerDown( { entity: myEntity, opts: { button: InputAction.IA_PRIMARY } }, function (cmd) { console.log(cmd.hit?.entityId) } ) ``` ### Lidar com vários botões Você não pode registrar mais de um `onPointerDown` em uma única Entity. Idealmente, você deve usar a [baseada em System](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md) abordagem, pois isso permite lidar com quantos inputs diferentes você quiser e exibir uma dica de feedback de hover da UI para cada botão. Como alternativa, você pode usar a abordagem Register callback e definir o `button` campo como `InputAction.IA_ANY`. ```ts pointerEventsSystem.onPointerDown( {entity: myEntity, opts: { button: InputAction.IA_ANY}}, function (cmd) { if(cmd.button === InputAction.IA_POINTER){ // do X } else if (cmd.button === InputAction.IA_PRIMARY){ // do Y } } ) ``` Essa abordagem não é ideal, pois a dica de hover mostra uma única string e não especifica qual ação ativar. Observe que isso fará com que a função de callback seja executada para cada input action, incluindo teclas de movimento, então você deve filtrar apenas as ações com as quais se importa. --- # 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/scenes-sdk7/interatividade/eventos-de-botao/register-callback.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.