# Registar callback A forma mais fácil de lidar com eventos de botão é registrar uma função de callback para uma entidade específica. Sempre que essa entidade for interagida usando 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 [Baseado 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 mais 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** deve ter uma [collider](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/colliders.md). Veja [obstacles](/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 pressionamentos de um botão específico. Esta instrução requer dois parâmetros: * `dados`: Um objeto que contém o seguinte: * `entity`: A entidade a ser tratada * `opts`: Um objeto com dados adicionais opcionais: * `button`: Qual botão ouvir. Veja [Pointer buttons](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) para opções suportadas. Se nenhum botão for especificado, então todos os botões serão ouvidos, incluindo botões de movimento como forward e jump. * `maxDistance`: A distância máxima entre a entidade e a **camera**do jogador, em metros. * `maxPlayerDistance`: A distância máxima entre a entidade e a **avatar**do jogador, em metros. * `hoverText`: Qual string exibir na dica de hover feedback. "Interact" por padrão. * `hideFeedback`: Se true, oculta tanto a dica de hover quanto o destaque de borda para esta entidade. *false* por padrão. * `showHighlight`: Se true, os jogadores verão o destaque de borda ao passar o cursor sobre a entidade. *true* por padrão. Este valor só é considerado se `hideFeedback` for *false*. * `cb`: Uma função de callback a ser executada cada vez que ocorrer um evento de button down enquanto se aponta para a entidade ```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 será chamada como um [funções assíncronas](/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/async-functions.md) cada vez que o evento de botão relacionado ocorrer. {% 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 recorrentemente dentro de um System, pois isso continuaria reescrevendo o comportamento do evento de pointer. {% endhint %} ## Feedback de Hover É muito importante dar aos jogadores algum tipo de indicação de que uma entidade pode ser interagida. Ao registrar uma ação de input com o `EventsSystem`, por padrão os jogadores verão: * Um destaque de borda na entidade * Uma dica de hover próxima ao cursor com um ícone para o botão que eles precisam pressionar e uma string que diz "Interact". Esses elementos podem ser alternados e personalizados. O hover feedback na UI exibe um ícone diferente dependendo do input selecionado no `button` field. 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 fique 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 destaque de borda, defina o valor de `hoverText` como "". ```ts pointerEventsSystem.onPointerDown( {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: ''}},, function () { console.log("clicked on surprise interactive item") } ) ``` Para ocultar o destaque de borda, mas manter a dica de hover, defina `showHighlight` // desenhar UI *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 destaque de borda, defina o `hideFeedback` como true. Ao fazer isso, o cursor não mostra nenhum ícone, texto ou destaque de borda. ```ts pointerEventsSystem.onPointerDown( {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hideFeedback: true}},, function () { console.log("opened secret door") } ) ``` ### Alterar feedback existente Ao registrar uma ação de input com o `EventsSystem`, isto está criando um `PointerEvents` component e adicionando-o à entidade interativa nos bastidores. Este component lida com o comportamento da dica de hover da UI. Para alterar o comportamento do hover feedback, modifique este component. Veja [Show 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) hoverFeedback.pointerEvents[0].eventInfo.hoverText = 'Close door' ``` ## Limites de distância O `maxDistance` e `maxPlayerDistance` as opções definem a distância máxima entre a entidade e a camera e o avatar do jogador, respectivamente. Se o jogador estiver longe demais, o efeito de hightlight da entidade será vermelho em vez de verde, e os eventos de pointer não funcionarão. ```ts pointerEventsSystem.onPointerDown( { entity: myEntity, opts: { maxDistance: 10, maxPlayerDistance: 5 } }, function () { console.log('clicked entity') } ) ``` Se a scene estiver usando um [Virtual Camera](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/camera.md#virtual-camera), os `maxDistance` é medido a partir da virtual camera 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 dentro de 10 metros da camera OU dentro de 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` (camera) fosse 10 metros. ## Pointer up 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: 'Button up' }, }, function () { console.log('button up') } ) ``` Esta instrução requer três parâmetros: * `dados`: Um objeto que contém o seguinte: * `entity`: A entidade a ser tratada * `opts`: Um objeto com dados adicionais opcionais: * `button`: Qual botão ouvir. Veja [Pointer buttons](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) para opções suportadas. Se nenhum botão for especificado, então todos os botões serão ouvidos, incluindo botões de movimento como forward e jump. * `hoverText`: Qual string exibir na dica de hover feedback. "Interact" por padrão. * `hideFeedback`: Se true, oculta a dica de hover para esta entidade. * `maxDistance`: Quão longe o jogador pode estar da entidade para conseguir interagir com esta entidade, em metros. Se o jogador estiver muito longe, não haverá hover feedback e os eventos de pointer não funcionarão. * `cb`: Uma função de callback a ser executada cada vez que ocorrer um evento de button up enquanto se aponta para a entidade. A mesma entidade pode ter dois callbacks diferentes registrados, um para `pointerEventsSystem.onPointerDown` e outro para `pointerEventsSystem.onPointerUp`. A entidade só pode registrar um callback de cada, [Lidar com múltiplos botões](#handle-multiple-buttons) para detectar botões diferentes em um mesmo callback. {% hint style="warning" %} **📔 Nota**: O hover feedback 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, não verá nenhum feedback, ou o feedback do evento de button down, se houver. {% endhint %} ## Hover enter e leave Use `pointerEventsSystem.onPointerHoverEnter` para executar um callback quando o cursor do jogador começa a apontar para uma entidade, e `pointerEventsSystem.onPointerHoverLeave` quando o cursor deixa 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 de hover personalizados, como tocar um som ou animar a entidade quando o jogador a mira. ## 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 hover feedback na entidade não deverá mais ser exibido, e a entidade não deverá mais ser interativa. ## Interações por 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 Busque dados de uma ação de input, como o botão que foi pressionado, a entidade que foi atingida, a direção e o comprimento do ray, etc. Veja ([Ver documentação](https://github.com/decentraland/docs/blob/main/README.md)) para uma descrição de todos os dados disponíveis. Para buscar 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 múltiplos botões Você não pode registrar mais de um `onPointerDown` em uma única entidade. Idealmente, você deve usar a abordagem [Baseado em System](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md) pois isso permite lidar com quantos inputs diferentes você quiser e exibir uma dica de hover feedback de 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){ // faça X } else if (cmd.button === InputAction.IA_PRIMARY){ // faça 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 ação de input, incluindo as teclas de movimento, então você deve filtrar apenas as ações que lhe interessam. --- # Agent Instructions: 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: ``` GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.