> 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 A maneira mais fácil de lidar com eventos de botão é registrar uma função de callback para uma entidade específica. Toda vez que essa entidade é interagida com um botão específico, a função de callback é chamada. Se você precisar adicionar o mesmo comportamento a várias entidades 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 entidade. A abordagem baseada em System pode resultar em maior eficiência à medida que você percorre uma lista de entidades semelhantes. A abordagem Register callback é especialmente útil se você quiser descrever um comportamento que afeta uma única entidade, pois é mais direta. {% hint style="warning" %} **📔 Nota**:\ Para que uma entidade seja interativa, ela **deve** precisa 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 %} ## Pressionamento do ponteiro Use `pointerEventsSystem.onPointerDown()` para detectar pressionamentos de um botão específico. Esta instrução requer dois parâmetros: * `data`: Um objeto que contém o seguinte: * `entity`: A entidade a tratar * `opts`: Um objeto com dados adicionais opcionais: * `button`: Qual botão ouvir. Veja [Botões do ponteiro](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) para as opções suportadas. Se nenhum botão for especificado, então todos os botões serão ouvidos, incluindo botões de movimento como avançar e pular. * `maxDistance`: A distância máxima entre a entidade e a **câmera**, em metros. * `maxPlayerDistance`: A distância máxima entre a entidade e a **avatar**, em metros. * `hoverText`: Qual string exibir na dica de feedback ao passar o cursor. "Interagir" por padrão. * `showFeedback`: Se false, oculta tanto a dica ao passar o cursor quanto o realce da borda para esta entidade. *true* por padrão. * `showHighlight`: Se true, os jogadores verão o realce da borda ao passar o cursor sobre a entidade. *true* por padrão. Este valor só é considerado se `showFeedback` for *true*. * `cb`: Uma função de callback a ser executada sempre que ocorrer um evento de button down enquanto estiver apontando para a entidade ```ts pointerEventsSystem.onPointerDown( { entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Clique' }, }, function () { console.log('entidade clicada') } ) ``` 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 a callback deve ser uma função síncrona; `async` funções não são suportadas aqui e resultam em erro. {% hint style="warning" %} **📔 Nota**:\ Apenas um `pointerEventsSystem.onPointerDown` pode ser registrado por entidade. Depois de adicionado, ele continuará ouvindo eventos até que o listener seja removido. Não execute isso repetidamente dentro de um System, pois isso continuaria reescrevendo o comportamento do evento de ponteiro. {% endhint %} ## Feedback de Hover É muito importante dar aos jogadores algum tipo de indicação de que é possível interagir com uma entidade. Ao registrar uma ação de input com o `EventsSystem`, por padrão os jogadores verão: * Um realce da borda na entidade * Uma dica perto do cursor com um ícone do botão que precisam pressionar e uma string que diz "Interagir". Esses elementos podem ser alternados e personalizados. O feedback ao passar o cursor na UI exibe um ícone diferente dependendo da entrada selecionada 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 esta 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: 'Abrir porta' }, }, function () { // abrir porta } ) ``` Para ocultar a dica ao passar o cursor, mas deixar o realce da borda, defina o valor de `hoverText` para "". ```ts pointerEventsSystem.onPointerDown( {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: ''}}, function () { console.log('clicou no item interativo surpresa') } ) ``` Para ocultar o realce da borda, mas deixar a dica ao passar o cursor, defina `showHighlight` para *false*. ```ts pointerEventsSystem.onPointerDown( { entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Abrir porta', showHighlight: false, }, }, function () { console.log('porta secreta aberta') } ) ``` Para ocultar tanto a dica ao passar o cursor quanto o realce da borda, defina `showFeedback` para *false*. Ao fazer isso, o cursor não mostra nenhum ícone, texto ou realce da borda. ```ts pointerEventsSystem.onPointerDown( {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, showFeedback: false}}, function () { console.log('porta secreta aberta') } ) ``` ### Alterar feedback existente Ao registrar uma ação de input com o `EventsSystem`, isso está criando um `PointerEvents` componente e adicionando-o à entidade interativa nos bastidores. Este componente lida com o comportamento da dica de hover da UI. Para alterar o comportamento do feedback ao passar o cursor, modifique este componente. 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 componente. ```ts const hoverFeedback = PointerEvents.getMutable(myEntity) if (hoverFeedback.pointerEvents[0]?.eventInfo) { hoverFeedback.pointerEvents[0].eventInfo.hoverText = 'Fechar porta' } ``` ## Limites de distância O `maxDistance` e `maxPlayerDistance` as opções definem a distância máxima entre a entidade e a câmera e o avatar do jogador, respectivamente. Se o jogador estiver muito longe, o efeito de realce da entidade será vermelho em vez de verde, e os eventos de ponteiro não funcionarão. ```ts pointerEventsSystem.onPointerDown( { entity: myEntity, opts: { maxDistance: 10, maxPlayerDistance: 5 } }, function () { console.log('entidade clicada') } ) ``` Se a cena estiver usando uma [Virtual Camera](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/camera.md#virtual-camera), as `maxDistance` é medida a partir da VirtualCamera que está atualmente ativa. * Se ambos `maxDistance` e `maxPlayerDistance` forem fornecidos, a interação é permitida se QUALQUER uma das verificações passar (lógica OR). Por exemplo, se `maxDistance` for 10 metros e `maxPlayerDistance` for 5 metros, a interação é permitida se o jogador estiver a até 10 metros da câmera OU a até 5 metros do avatar. * Se apenas um dos dois valores for fornecido, a interação é permitida se o jogador estiver dentro da distância fornecida, sem considerar o valor padrão da outra distância. * Se nenhum dos dois valores for fornecido, o padrão se comporta como se o `maxDistance` (câmera) fosse 10 metros. ## Soltura do ponteiro Use `pointerEventsSystem.onPointerUp` para registrar uma função de callback que é chamada quando o jogador indicado solta o botão enquanto aponta para a entidade. ```ts pointerEventsSystem.onPointerUp( { entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Botão solto' }, }, function () { console.log('botão solto') } ) ``` Esta instrução requer dois parâmetros: * `data`: Um objeto que contém o seguinte: * `entity`: A entidade a tratar * `opts`: Um objeto com dados adicionais opcionais: * `button`: Qual botão ouvir. Veja [Botões do ponteiro](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) para as opções suportadas. Se nenhum botão for especificado, então todos os botões serão ouvidos, incluindo botões de movimento como avançar e pular. * `hoverText`: Qual string exibir na dica de feedback ao passar o cursor. "Interagir" por padrão. * `showFeedback`: Se false, oculta a dica ao passar o cursor para esta entidade. *true* por padrão. * `maxDistance`: A que distância o jogador pode estar da entidade para conseguir interagir com esta entidade, em metros. Se o jogador estiver muito longe, não haverá feedback ao passar o cursor e os eventos de ponteiro não funcionarão. * `cb`: Uma função de callback a ser executada sempre que ocorrer um evento de button up enquanto aponta para a entidade. A mesma entidade pode ter dois callbacks diferentes registrados, um para `pointerEventsSystem.onPointerDown` e um para `pointerEventsSystem.onPointerUp`. A entidade só pode registrar um callback de cada, [Lidar com vários botões](#handle-multiple-buttons) para detectar botões diferentes em um único callback. {% hint style="warning" %} **📔 Nota**: O feedback ao passar o cursor para um evento de button up só é exibido quando o botão está atualmente pressionado. Se o jogador apontar para a entidade sem manter o botão pressionado, ele não verá nenhum feedback, ou verá o feedback do evento de button down, se houver. {% endhint %} ## Entrada e saída do hover Use `pointerEventsSystem.onPointerHoverEnter` para executar uma callback quando o cursor do jogador começa a apontar para uma entidade, e `pointerEventsSystem.onPointerHoverLeave` quando o cursor para de apontar para ela. ```ts pointerEventsSystem.onPointerHoverEnter( { entity: myEntity, opts: { button: InputAction.IA_POINTER }, }, function () { console.log('O cursor começou a passar sobre a entidade') } ) pointerEventsSystem.onPointerHoverLeave( { entity: myEntity, opts: { button: InputAction.IA_POINTER }, }, function () { console.log('O cursor parou de passar sobre a entidade') } ) ``` Esses callbacks são úteis para efeitos personalizados de hover, como tocar um som ou animar a entidade quando o jogador mirar 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) ``` Depois de removido, o feedback de hover na entidade não deve mais ser exibido, e a entidade não deve mais ser interativa. ## Interações de proximidade Para interações que são acionadas com base na proximidade do jogador em vez da 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. ### Dados da ação de input Obtenha dados de uma ação de input, como o botão que foi pressionado, a entidade atingida, a direção e o comprimento do raio, etc. Veja ([Veja a 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 com informações sobre o evento de input. ```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 entidade. O ideal é 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 quantas entradas 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){ // fazer X } else if (cmd.button === InputAction.IA_PRIMARY){ // fazer Y } } ) ``` Essa abordagem não é ideal, pois a dica ao passar o cursor mostra uma única string e não especifica qual ação ativar. Observe que isso fará a função de callback ser executada para cada ação de input, incluindo teclas de movimento, então você deve filtrar apenas as ações que lhe interessam. --- # 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/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 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.