Godot do Zero: Entrada do jogador e mapeamento de controles (Input Map)

O que é o Input Map e por que usar ações

Em vez de ler teclas específicas (como KEY_A ou KEY_SPACE) diretamente no código, a Godot incentiva o uso de ações configuradas no Input Map. Uma ação é um nome (por exemplo, mover_esquerda) que pode ter várias entradas associadas: teclado, controle, mouse, etc.

Vantagens práticas:

• Trocar controles sem mexer no código: você altera o Input Map e o jogo continua funcionando.
• Suporte fácil a controle: basta adicionar botões/axes do gamepad às mesmas ações.
• Código mais limpo: scripts centrais lidam com “intenções” (mover, pular, atacar), não com hardware.

Passo a passo: configurando ações no Input Map

1) Abrir o Input Map

No editor, vá em Project > Project Settings e abra a aba Input Map.

2) Criar as ações

Crie (Add) as seguintes ações exatamente com estes nomes:

• mover_esquerda
• mover_direita
• pular
• atacar
• pausar

3) Atribuir entradas (teclado e controle)

Para cada ação, clique no “+” e adicione eventos. Um mapeamento sugerido:

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Observação importante: para o analógico, você pode adicionar um Joy Axis ao Input Map. Em muitos controles, o analógico esquerdo horizontal é o Left Stick X. Você pode mapear o mesmo axis para mover_esquerda e mover_direita usando direções/valores apropriados no evento (dependendo da versão da Godot e do tipo de evento configurado).

Lendo input no código: is_action_pressed e get_axis

Leitura digital (botões): Input.is_action_pressed

Use quando você quer saber se uma ação está pressionada (tecla ou botão):

if Input.is_action_pressed("pular"):    # ...

Isso funciona igual para teclado e controle, desde que ambos estejam mapeados na ação.

Leitura de eixo (esquerda/direita): Input.get_axis

Para movimento horizontal, é comum transformar duas ações (mover_esquerda e mover_direita) em um valor único de direção:

var direcao_x := Input.get_axis("mover_esquerda", "mover_direita") # -1, 0, 1 (ou valores intermediários)

Quando as ações são digitais (teclas), o resultado tende a ser -1, 0 ou 1. Se você também mapear analógico, pode obter valores intermediários (ex.: 0.35), o que permite aceleração/velocidade proporcional.

Camada clara entre input e movimento (arquitetura simples e flexível)

Um erro comum é misturar leitura de input com regras de movimento diretamente no script do jogador. Uma abordagem mais flexível é criar uma camada de entrada que traduz o Input Map em um “estado de comandos” e, separadamente, um método que aplica esse estado ao movimento.

Abaixo está um exemplo prático com duas responsabilidades:

• Coletar input (o que o jogador quer fazer).
• Aplicar movimento/ações (como o personagem responde).

Exemplo: script do jogador com separação de responsabilidades

Considere um nó de jogador (por exemplo, CharacterBody2D) com este script. Ajuste nomes/constantes conforme seu projeto.

extends CharacterBody2D

@export var velocidade := 220.0
@export var forca_pulo := 420.0

var input_x := 0.0
var quer_pular := false
var quer_atacar := false

func _physics_process(delta: float) -> void:
    _coletar_input()
    _aplicar_movimento(delta)
    _aplicar_acoes()

func _coletar_input() -> void:
    # Eixo horizontal unificado
    input_x = Input.get_axis("mover_esquerda", "mover_direita")

    # Ações (botões)
    quer_pular = Input.is_action_pressed("pular")
    quer_atacar = Input.is_action_pressed("atacar")

func _aplicar_movimento(delta: float) -> void:
    # Exemplo simples: velocidade horizontal baseada no input
    velocity.x = input_x * velocidade

    # Gravidade (caso você já esteja usando uma, mantenha sua lógica)
    if not is_on_floor():
        velocity.y += 1200.0 * delta

    # Pulo: só se estiver no chão
    if quer_pular and is_on_floor():
        velocity.y = -forca_pulo

    move_and_slide()

func _aplicar_acoes() -> void:
    if quer_atacar:
        # Aqui você chamaria animação, hitbox, cooldown etc.
        pass

Por que isso ajuda? Se amanhã você quiser trocar o esquema de controles (por exemplo, usar clique do mouse para atacar, ou um gatilho do controle), você altera apenas o Input Map. Se quiser mudar regras de movimento (aceleração, atrito, pulo variável), você mexe em _aplicar_movimento sem tocar na leitura de entrada.

Pausa com ação dedicada (sem acoplar ao jogador)

A ação pausar costuma ser melhor tratada em um nó de nível superior (ex.: um nó “Game”/“Main” ou um gerenciador de UI), para não depender do jogador existir.

extends Node

func _process(delta: float) -> void:
    if Input.is_action_just_pressed("pausar"):
        get_tree().paused = not get_tree().paused

Se você tiver uma UI de pausa, pode exibir/ocultar junto com o estado de paused.

Validação prática: HUD de depuração do estado das ações

Para garantir que o Input Map está correto (teclado e controle) e que seus scripts centrais não precisam ser alterados, crie um HUD simples que mostre o estado das ações em tempo real.

1) Montando o HUD

Crie uma cena de UI (por exemplo, CanvasLayer) com um Label (ou RichTextLabel) chamado DebugInputLabel. Posicione no canto superior esquerdo.

2) Script do HUD para leitura e exibição

Anexe este script ao CanvasLayer (ajuste o caminho do label conforme sua árvore):

extends CanvasLayer

@onready var debug_label: Label = $DebugInputLabel

func _process(delta: float) -> void:
    var eixo := Input.get_axis("mover_esquerda", "mover_direita")

    var esquerda := Input.is_action_pressed("mover_esquerda")
    var direita := Input.is_action_pressed("mover_direita")
    var pular := Input.is_action_pressed("pular")
    var atacar := Input.is_action_pressed("atacar")
    var pausar := Input.is_action_pressed("pausar")

    debug_label.text = (
        "INPUT DEBUG\n" +
        "eixo_x: %0.2f\n" % eixo +
        "esquerda: %s\n" % str(esquerda) +
        "direita: %s\n" % str(direita) +
        "pular: %s\n" % str(pular) +
        "atacar: %s\n" % str(atacar) +
        "pausar: %s\n" % str(pausar)
    )

3) Como usar o HUD para validar teclado e controle

• Pressione A/D (ou setas) e veja eixo_x alternar entre -1 e 1 e os booleanos esquerda/direita mudarem.
• Pressione Espaço e confirme pular: true.
• Pressione o botão de ataque e confirme atacar: true.
• Pressione Esc/Start e confirme pausar: true (e, se você implementou a pausa, o jogo alterna o estado).
• Conecte um controle e repita os testes. Se algo não responder, corrija apenas o Input Map (sem alterar scripts do jogador/HUD).

Dicas práticas para manter o sistema de input sustentável

• Padronize nomes de ações: use verbos e intenção (ex.: pular, atacar) e evite nomes de teclas.
• Centralize leitura de input: mantenha a coleta em um método (como _coletar_input) para facilitar mudanças e testes.
• Use get_axis para movimento: mesmo que hoje seja teclado, você já deixa o caminho pronto para analógico.
• Tenha um HUD de depuração: ele reduz muito o tempo gasto procurando erro que, na verdade, é só mapeamento incorreto.