For the complete documentation index, see llms.txt. This page is also available as Markdown.

Eventos Baseados em System

Saiba como lidar com cliques de usuário na sua scene.

Se a sua scene tiver várias Entities semelhantes, todas ativadas usando a mesma lógica, pode escrever um único System que percorra todas elas e descreva esse comportamento apenas uma vez. Esta é também a abordagem mais eficiente e mais orientada a dados .

Também pode usar um System para detetar eventos de input globais, para que a scene reaja sempre que uma tecla é premida, sem ter em conta para onde o cursor do jogador está apontado.

Se apenas pretende clicar ou premir um botão numa única Entity para a ativar, a forma mais fácil é usar a abordagem Registar um callback .

Para definir uma lógica personalizada mais específica, talvez queira lidar com os dados em bruto e usar a abordagem Avançada .

Para que uma Entity seja interativa, tem de ter um collider. Consulte obstáculos para obter mais detalhes. Isto também se aplica aos eventos de clique por proximidade.

Utilizar um System

Verifique se ocorreram eventos de botão executando uma das funções auxiliares no namespace de input inputSystem em cada tick dentro de um System.

Por exemplo, o System seguinte utiliza a função inputSystem.isTriggered() para verificar se houve um clique do ponteiro. Em cada tick, verifica se o botão foi premido. Se inputSystem.isTriggered() devolver true, o System executa uma lógica personalizada em resposta.

engine.addSystem(() => {
	if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN)) {
		// Logic in response to button press
	}
})

As seguintes funções auxiliares estão disponíveis no namespace inputSystem e podem ser chamadas de forma semelhante em cada tick:

  • inputSystem.isTriggered: Devolve true se tiver ocorrido uma ação de input desde o último tick.

  • inputSystem.isPressed: Devolve true se um input estiver a ser premido no momento. Devolverá true em cada tick até o botão ser novamente libertado.

  • inputSystem.getInputCommand: Devolve um objeto com dados sobre a ação de input.

Consulte as secções abaixo para obter mais detalhes sobre cada uma.

Ao processar eventos de botão numa Entity, forneça sempre feedback ao jogador, para que saiba que é possível interagir com a Entity. Se adicionar um componente PointerEvents a uma Entity, os jogadores verão uma indicação quando passarem o cursor sobre essa Entity. Consulte Mostrar feedback para saber como adicionar indicações ao passar o cursor sobre Entities interativas.

Eventos de input globais

Utilize inputSystem.isTriggered para detetar eventos de premir e libertar botões em qualquer um dos inputs monitorizados pelo SDK.

O exemplo acima verifica se o botão foi premido, independentemente da posição do apontador ou das Entities que possam estar no seu caminho.

inputSystem.isTriggered() devolve true apenas se o botão indicado tiver sido premido no tick atual do ciclo do jogo. Se o botão não tiver sido premido ou já estivesse premido no tick anterior, devolve false.

A função inputSystem.isTriggered recebe os seguintes argumentos obrigatórios:

  • InputAction: O input a detetar, como valor do InputAction enum. Consulte Botões do apontador para ver as opções suportadas.

  • PointerEventType: O tipo de evento a detetar, como valor do PointerEventType enum. Consulte Tipos de eventos do apontador para ver as opções suportadas.

Ativar uma Entity

Para detetar eventos de botões enquanto aponta para uma Entity específica, passe um terceiro argumento opcional para inputSystem.isTriggered para especificar a Entity a verificar.

O exemplo acima verifica em cada tick se uma Entity única, definida diretamente no código, foi premida com o botão do apontador (botão esquerdo do rato).

A função inputSystem.isTriggered recebe os seguintes argumentos:

  • InputAction: O input a detetar, como valor do InputAction enum. Consulte Botões do apontador para ver as opções suportadas.

  • PointerEventType: O tipo de evento a detetar, como valor do PointerEventType enum. Consulte Tipos de eventos do apontador para ver as opções suportadas.

  • Entity (opcional): A Entity na qual verificar estes eventos. Se não for fornecido nenhum valor, verifica os cliques globais no botão, independentemente da posição para onde o cursor do jogador apontava.

Note que, neste exemplo, também estamos a adicionar um componente PointerEvents à Entity com que queremos interagir. Este passo é necessário: sem este componente, a Entity não será detetável por nenhuma das funções de inputSystem. consulte Mostrar feedback para obter mais detalhes sobre o PointerEvents componente.

Se houver várias entities com as quais o jogador pode interagir da mesma maneira, considere usar inputSystem.getInputCommand. Esse comando retorna informações sobre um comando global de clique, incluindo o ID da entity. Você pode usar isso para executar uma única função que possa lidar com todas elas.

Consulte Dados da ação de entrada para obter mais informações. Esse método também fornece dados mais detalhados sobre o acerto do evento de pointer.

Soltar o botão de entrada

Você também pode verificar eventos de liberação do pointer de maneira semelhante, usando PointerEventType.PET_UP.

Verificar se os botões estão pressionados

Verifique se um botão está sendo pressionado usando inputSystem.isPressed() dentro de um system.

inputSystem.isPressed() retorna true se o botão estiver sendo mantido pressionado, independentemente de quando foi pressionado e de para onde o cursor do jogador estiver apontando. Caso contrário, retorna false.

A inputSystem.isPressed função aceita um único argumento:

  • InputAction: O input a detetar, como valor do InputAction enum. Consulte Botões do apontador para ver as opções suportadas.

Processar várias Entities

Se a sua Scene tiver várias Entities afetadas da mesma forma por Pointer Events, faz sentido escrever um System que percorra todas elas.

Este exemplo usa uma consulta de Component para percorrer todas as Entities com um Component PointerEvents . Em seguida, verifica cada uma dessas Entities com inputSystem.isTriggered, percorrendo-as uma a uma. Se for detetada uma ação de input em qualquer uma destas Entities, executa uma lógica personalizada.

Em vez de percorrer todas as Entities com um Component PointerEvents num único System, pode preferir escrever Systems diferentes para processar as Entities que devem comportar-se de formas distintas. A abordagem recomendada é identificar diferentes tipos de Entities com Components personalizadose percorrê-las em Systems separados.

Este exemplo tem um System que percorre todas as Entities com um Component personalizado chamado IsDoor e outro que percorre todas as Entities com um Component personalizado chamado isGem. Em ambos os Systems, verifica cada Entity correspondente para ver se foi ativada com o botão do ponteiro.

Esta forma de organizar o código da sua Scene é muito orientada a dados e deverá resultar numa utilização muito eficiente dos recursos de memória.

## Vários botões numa Entity

Ao utilizar helpers como pointerEventsSystem.onPointerDown, cada Entity está limitada a um único tipo de evento. Não é possível registar dois eventos de botão diferentes. Esta limitação não existe quando se utilizam eventos baseados em Systems. Por exemplo, eis uma Entity com a qual os jogadores podem interagir premindo E e F, sendo cada tecla responsável por funcionalidades diferentes.

Mostrar feedback

Para apresentar sugestões de UI ao apontar para uma Entity, utilize as propriedades do Component PointerEvents da Entity.

Sempre que o cursor do jogador apontar para os Colliders desta entidade, a UI apresentará uma dica ao passar o cursor, indicando que é possível interagir com a entidade. Consulte as secções abaixo para saber o que pode configurar.

O PointerEvents componente requer pelo menos uma definição de evento do ponteiro. Cada definição de evento do ponteiro pode ser configurada com o seguinte:

  • eventType: O tipo de evento a escutar, como um valor do enum PointerEventType . Consulte Tipos de eventos do ponteiro para ver as opções suportadas.

  • eventInfo: Um objeto que pode conter os seguintes campos:

    • button (obrigatório): A entrada a escutar, como um valor do enum InputAction . Consulte Botões do ponteiro para ver as opções suportadas.

    • hoverText (opcional): O texto a apresentar na dica de feedback ao passar o cursor. O valor predefinido é "Interact".

    • showFeedback (opcional): Se for false, oculta tanto a dica ao passar o cursor como o realce do contorno desta entidade. true por predefinição.

    • showHighlight (opcional): Se for true, os jogadores verão o realce do contorno quando passarem o cursor sobre a entidade. true por predefinição. Este valor só é tido em conta se showFeedback for true.

    • maxDistance (opcional): A distância máxima a que o avatar do jogador pode estar da entidade e ainda interagir com ela, em metros. O valor predefinido é 10 metros. Consulte Distância máxima.

    • maxCameraDistance (opcional): A que distância a câmara ativa pode estar da entidade e continuar a interagir com ela, em metros. Não está definido por predefinição. Consulte Distância máxima.

    • priority (opcional): Determina qual entidade prevalece quando várias se sobrepõem. Os valores mais altos têm precedência. 0 por predefinição.

Um único PointerEvents componente pode conter várias definições de eventos de ponteiro, que podem detetar eventos diferentes para botões diferentes. Cada entidade só pode ter um PointerEvents componente, mas este pode incluir vários objetos na sua pointerEvents matriz, um para cada evento a que responder.

Os jogadores verão várias etiquetas, uma para cada evento de ponteiro, apresentadas radialmente à volta do cursor.

O exemplo abaixo combina a utilização de PointerEvents para apresentar sugestões ao passar o cursor, com um sistema que processa efetivamente a ação do jogador através de lógica personalizada.

Feedback ao passar o cursor

Quando um jogador passa o cursor sobre um item com um componente PointerEvents , vê:

  • Um contorno realçado na entidade

  • Uma sugestão junto ao cursor, com um ícone do botão que deve premir e o texto «Interagir».

Estes elementos podem ser ativados ou desativados e personalizados.

O feedback apresentado na UI ao passar o cursor mostra um ícone diferente, consoante a entrada selecionada no campo button . No PC, é apresentado um ícone com um E para InputAction.IA_PRIMARY, um F para InputAction.IA_SECONDARYe um rato para InputAction.IA_POINTER.

Altere o texto modificando o valor de hoverText . Mantenha este texto curto para que seja rápido de ler e não ocupe demasiado espaço no ecrã.

No exemplo acima, o evento de ponteiro inclui um valor para hoverText. Este campo define a string a apresentar na UI enquanto o jogador aponta para a entidade. Por predefinição, esta string é Interagir.

💡 Sugestão: A string hoverText deve descrever a ação que ocorre ao interagir. Por exemplo: Abrir, Ativar, Agarrar, Selecionar. Estas strings devem ser tão curtas quanto possível, para não desviarem demasiado a atenção do jogador.

Se uma entidade tiver vários eventos de ponteiro, as sugestões ao passar o cursor para cada um deles são apresentadas radialmente em torno do cursor.

O hoverText de um evento de ponteiro .UP só é apresentado enquanto o jogador mantém premida a tecla correspondente e aponta para a entidade.

Se uma entidade tiver um evento de ponteiro DOWN e também um evento de ponteiro UP a sugestão da ação DOWN é apresentada enquanto o botão não está premido. A sugestão muda para a do evento UP apenas quando o botão é premido e continua premido.

Para ocultar a sugestão ao passar o cursor, mas manter o realce do contorno, defina o valor de hoverText como "".

Para ocultar o realce do contorno, mas manter a sugestão ao passar o cursor, defina showHighlight como false.

Para ocultar tanto a sugestão ao passar o cursor como o realce do contorno, defina showFeedback como false. Neste caso, o cursor não apresenta ícones, texto nem qualquer realce do contorno. Também pode simplesmente remover o componente PointerEvents da entidade.

Distância máxima

Algumas entidades podem ser interativas intencionalmente apenas a curta distância. Se um jogador estiver demasiado longe de uma entidade, a sugestão ao passar o cursor não será apresentada junto ao cursor.

Por predefinição, só é possível clicar nas entidades quando o avatar do jogador está a uma distância de 10 metros da entidade. Pode alterar esse alcance definindo a maxDistance propriedade de um evento de ponteiro.

O exemplo acima define a distância máxima para as indicações ao passar o cursor como 6 metros. Certifique-se de que a lógica que trata as ações de entrada também segue as mesmas regras. Consulte Dados de uma ação de entrada para saber como obter a distância de uma ação de entrada.

maxDistance é medido a partir do avatar, pelo que se comporta da mesma forma na primeira e na terceira pessoa.

Para limitar a interação com base na distância da câmara ativa em vez disso, use maxCameraDistance. Se definir ambos, basta que uma das verificações seja satisfeita. Consulte Limites de distância para ver o conjunto completo de regras.

Indicações personalizadas avançadas

O PointerEvents component permite adicionar facilmente indicações de UI quando o cursor do jogador começa a passar sobre uma entidade. Em geral, é bom que as indicações se comportem de forma consistente com o que os jogadores estão habituados a ver noutras cenas de Decentraland. No entanto, em alguns casos, pode querer indicar de uma forma personalizada que algo é interativo. Por exemplo, pode reproduzir um som subtil quando o jogador começa a passar o cursor sobre a entidade. Também pode mostrar um contorno luminoso à volta da entidade enquanto o cursor passa sobre ela e ocultá-lo quando deixar de o fazer. Também pode ser utilizado para mecânicas de jogo específicas.

Use a inputSystem.isTriggered() função juntamente com os eventos PointerEventType.PET_HOVER_ENTER e PointerEventType.PET_HOVER_LEAVE para executar comportamentos personalizados sempre que o cursor do jogador começa a apontar para o collider da entidade e sempre que deixa de apontar para ele.

O exemplo abaixo aumenta o tamanho das entidades para 1.5 quando o cursor começa a apontar para o respetivo collider e repõe o tamanho em 1 quando o cursor deixa de apontar para elas.

Eventos de proximidade

Verifique se há pressões de botões de proximidade, independentemente da direção para a qual o cursor aponta, usando PET_DOWN numa Entity que usa InteractionType.PROXIMITY. Defina o campo interactionType na definição do evento de ponteiro, junto a eventInfo, para marcar o evento como baseado em proximidade.

Consulte Eventos de proximidade para obter mais detalhes, incluindo as funções auxiliares disponíveis.

Com auxiliares como pointerEventsSystem.onProximityDown, uma Entity pode ter um handler de cursor e um handler de proximidade ao mesmo tempo, e ambos os callbacks são executados. O que não é possível é registar dois botões diferentes para o mesmo handler. Os eventos baseados em System não têm essa limitação: define-se uma entrada por comportamento. Por exemplo, aqui está uma Entity com a qual é possível interagir apontando o cursor e premindo E, ou aproximando-se e premindo E sem apontar para ela com o cursor.

Também pode usar inputSystem.isTriggered() com os tipos de evento PET_PROXIMITY_ENTER e PET_PROXIMITY_LEAVE para reagir quando um jogador entra ou sai do raio de proximidade de uma Entity. Isto é útil para apresentar feedback adicional para Entities ativadas por proximidade, por exemplo, reproduzindo um som ou uma animação.

Para que isto funcione, a Entity tem de ter um componente PointerEvents com o tipo de evento de proximidade correspondente definido.

Dados da ação de input

Obtenha dados de uma ação de input, como o botão que foi premido, a Entity atingida, a direção e o comprimento do raio, etc. Consulte (Consultar a documentação) para ver uma descrição de todos os dados disponíveis.

Para obter estes dados, use inputSystem.getInputCommand. Esta função devolve a estrutura de dados completa com informações sobre o evento de entrada.

Se não existir nenhuma ação de entrada que corresponda à consulta, então inputSystem.getInputCommand devolve null. Certifique-se de que trata este cenário na sua lógica.

Distância máxima de clique

Para impor uma distância máxima, de modo que uma Entity só possa ser clicada a curta distância, obtenha a hit.length propriedade dos dados do evento.

Meshes diferentes dentro de um modelo

Muitas vezes, os modelos 3D .glTF são compostos por vários meshes, cada um com um nome interno próprio. Todos os eventos de botão incluem informações sobre o mesh específico em que foi clicado, pelo que pode usar estas informações para desencadear comportamentos de clique diferentes em cada caso.

Para ver como são denominados os meshes dentro do modelo, tem de abrir o modelo 3D com uma ferramenta de edição, como o Blender , por exemplo.



💡 Sugestão: Também pode descobrir o nome do mesh clicado registando-o e consultando-o na consola.

A propriedade meshName está disponível no objeto hit devolvido pelo evento de clique.

No exemplo abaixo, temos um modelo de casa que inclui um mesh com o nome firePlace. Queremos acender a lareira apenas quando o respetivo mesh for clicado.

Atualizado