Controles na Tela

Configure os controles nativos de toque na tela para a sua scene.

No client móvel, os jogadores interagem com a sua scene por meio de um conjunto de controles nativos na tela — um joystick virtual, uma mira e um gamepad de botões. O para ocultar os controlos nativos e substituí-los pela sua própria UI tátil — a forma recomendada de disponibilizar um esquema de controlos totalmente personalizado. componente permite que sua scene reformule esse HUD: reduza a desordem, oculte o joystick ou a mira, altere o que o grande botão central faz, troque o glifo de um botão pelo seu próprio ícone ou oculte botões por completo e substitua-os pela sua própria UI.

Os controles padrão na tela, antes de qualquer personalização

O componente é aplicado automaticamente enquanto o jogador estiver dentro da sua scene e reverte para os padrões (nada oculto, pulo como botão central) no momento em que ele sair — então as scenes que não o usam não são afetadas. Ele afeta apenas plataformas com controles nativos na tela: no desktop ele não faz nada e não tem efeito em VR.

Como o layout dos botões funciona

Os botões do gamepad formam uma única pilha de prioridade. A ordem é fixa:

1. IA_JUMP

2. IA_POINTER

3. IA_PRIMARY (E)

4. IA_SECONDARY (F)

5. IA_ACTION_3 (1)

6. IA_ACTION_4 (2)

7. IA_ACTION_5 (3)

8. IA_ACTION_6 (4)

As posições na tela também são fixas. Os visíveis botões preenchem essas posições do topo da pilha para baixo — então o que você altera é quais botões ficam visíveis e qual deles lidera, não a ordem deles.

Quando você…	Os controles…
Oculta um botão (qualquer botão, incluindo o pulo)	Cada botão de menor prioridade sobe para preencher o espaço. Oculte o pulo e IA_POINTER assume o lugar central.
Não altere a pilha	O primeiro botão (IA_JUMP) é o grande botão central; os botões seguintes preenchem os slots ao redor.
Defina um botão principal com mainAction	Essa ação vai para a frente e se torna o botão central; todos os outros botões mantêm sua ordem normal.
Defina um botão principal que também esteja oculto	A ocultação vence — o botão permanece oculto.
Deixe 5 ou menos botões visíveis	Todos eles aparecem diretamente (o botão central mais até quatro ao redor); não há menu "+".
Deixe mais de 5 botões visíveis	O "+" ocupa o último slot, então quatro aparecem diretamente (o botão central mais três) e o restante fica atrás do alternador de excesso "+".

Como os botões se reorganizam com a contagem visível. Esquerda (7 botões): o botão principal, um arco de 1–3 e o "+" segurando o excesso (4–7) em uma coluna que sobe para cima. Centro (5 botões): o mesmo arco, com uma coluna de excesso mais curta (4–5) atrás do "+". Direita (4 botões): todos os quatro aparecem diretamente e o "+" desaparece.

É assim também que você exibe os 1/2/3/4 botões, que de outra forma ficariam escondidos atrás do "+": oculte botões suficientes de maior prioridade para reduzir a contagem visível para cinco ou menos, e eles aparecerão diretamente.

Tarefas comuns

para ocultar os controlos nativos e substituí-los pela sua própria UI tátil — a forma recomendada de disponibilizar um esquema de controlos totalmente personalizado. traz um conjunto de helpers práticos. Cada um grava o componente no RootEntity da scene (onde o client o lê) e faz a mesclagem com o valor atual, então você pode chamá-los de qualquer lugar.

Alterar o botão principal — faça o grande botão central disparar uma ação diferente:

import { TouchScreenControls, InputAction } from '@dcl/sdk/ecs'

export function main() {
	TouchScreenControls.setMainAction(InputAction.IA_PRIMARY)
}

Ocultar o joystick ou a mira — remova o stick de movimento e/ou o retículo de mira e traga-os de volta com seus equivalentes de mostrar :

TouchScreenControls.hideJoystick()
TouchScreenControls.hideCrosshair()

// e para trazê-los de volta:
TouchScreenControls.showJoystick()
TouchScreenControls.showCrosshair()

Ocultar botões específicos — passe as ações que você quer remover (o restante sobe em cascata):

TouchScreenControls.hide([InputAction.IA_SECONDARY, InputAction.IA_JUMP])

Ocultar ou mostrar todos os botões — limpe o HUD, ou redefina-o:

TouchScreenControls.hideAll()
TouchScreenControls.showAll()

showAll() afeta apenas os botões do gamepad — ele não restaura um joystick ou uma mira ocultos. Use showJoystick() / showCrosshair() para isso.

Substituir o ícone de um botão — para controle total (ícones personalizados, várias alterações ao mesmo tempo), escreva o componente bruto em engine.RootEntity:

import { engine, TouchScreenControls, InputAction } from '@dcl/sdk/ecs'

export function main() {
	TouchScreenControls.createOrReplace(engine.RootEntity, {
		hideCrosshair: true,
		mainAction: InputAction.IA_PRIMARY,
		touchInputs: [
			{
				inputAction: InputAction.IA_PRIMARY,
				icon: { tex: { $case: 'texture', texture: { src: 'images/grab.png' } } },
			},
		],
	})
}

Os helpers em resumo:

Helper	O que faz
setMainAction(action)	Define qual ação o grande botão central dispara.
hideJoystick()	Oculta o joystick virtual nativo.
showJoystick()	Mostra novamente o joystick virtual nativo.
hideCrosshair()	Oculta a mira / retículo na tela.
showCrosshair()	Mostra novamente a mira / retículo na tela.
hide(actions)	Oculta os botões de gamepad fornecidos (mesclados com a configuração atual).
hideAll()	Oculta todos os botões do gamepad.
showAll()	Mostra todos os botões do gamepad (limpa a lista de botões ocultos). Não afeta o joystick/a mira.

Propriedade

Escreva isso diretamente quando usar createOrReplace:

Tipo	Descrição	actions
hideJoystick	boolean	Oculta o joystick virtual nativo de movimento.
hideCrosshair	boolean	Oculta a mira / retículo na tela.
mainAction	InputAction	Move essa ação para a frente da pilha, tornando-a o grande botão central; os outros botões mantêm sua ordem. Apenas ações de gamepad são válidas (veja abaixo). Quando não definido, o primeiro botão visível (IA_JUMP por padrão) lidera. Veja Como o layout dos botões funciona.
touchInputs	array	Substituições por botão. Um botão que não estiver listado mantém seu padrão (mostrado, com seu glifo padrão).

Cada touchInputs entrada tem:

Campo	Descrição	actions
inputAction	InputAction	Qual botão na tela esta entrada configura.
hide	boolean	Oculta este botão. O padrão é false (mostrado). Qualquer botão pode ser ocultado, incluindo IA_JUMP — o restante sobe em cascata para preencher o lugar dele.
icon	TextureUnion (opcional)	Substitui o glifo do botão por uma imagem da scene. Use a variante texture com um src mapeado para conteúdo (uma imagem incluída na sua scene) — { tex: { $case: 'texture', texture: { src: 'images/grab.png' } } }. Apenas caminhos de conteúdo da scene são suportados (não URLs externos, avatar ou texturas de vídeo). Para o botão de pulo isso substitui todos os seus estados dinâmicos (pulo / pulo duplo / deslizamento). Se o caminho não puder ser resolvido, o glifo integrado é usado.

Quais ações se mapeiam para quais botões

O InputAction os valores aqui são os mesmos usados em toda Input on mobile e para a lista completa de. Estas são as ações que se mapeiam para os botões na tela:

InputAction	Botão na tela
IA_JUMP	O grande botão central (padrão)
IA_POINTER	O botão de interação
IA_PRIMARY	O botão E
IA_SECONDARY	O botão F
IA_ACTION_3 / IA_ACTION_4 / IA_ACTION_5 / IA_ACTION_6	Os botões 1 / 2 / 3 / 4

IA_ANY e IA_MODIFIER são valores meta — eles não se mapeiam para um botão e não podem ser usados aqui.

Exemplo

Para ocultar o joystick, guardar os botões numerados e dar ao botão central de pulo um ícone personalizado incluído na sua scene:

import { engine, TouchScreenControls, InputAction } from '@dcl/sdk/ecs'

export function main() {
	TouchScreenControls.createOrReplace(engine.RootEntity, {
		hideJoystick: true,
		touchInputs: [
			{ inputAction: InputAction.IA_ACTION_3, hide: true },
			{ inputAction: InputAction.IA_ACTION_4, hide: true },
			{ inputAction: InputAction.IA_ACTION_5, hide: true },
			{ inputAction: InputAction.IA_ACTION_6, hide: true },
			{
				inputAction: InputAction.IA_JUMP,
				icon: { tex: { $case: 'texture', texture: { src: 'images/banana.png' } } },
			},
		],
	})
}

O resultado: joystick removido, botões numerados ocultos (então o "+" desaparece) e o botão de pulo com novo ícone

Para substituir os controles nativos por completo, oculte-os aqui e construa seus próprios botões de toque com UI Input Binding.

Relacionados

• UI Input Binding

• Input on mobile

• para a lista completa de

• Detectar a plataforma pelo código