Ir al contenido
Descargar
Tutoriales

Menús y controles

En este tutorial añades menús al plataformas 2D: el juego empieza en un menú principal, Esc lo pausa y una pantalla de Controles deja al jugador cambiar las teclas. Las teclas que elige se guardan, y el juego empieza con ellas la próxima vez.

El menú principal: el título Pixel Platformer y los botones Play, Controls y Quit, con el foco en Play

Por el camino verás:

  • Un menú es una UI (.uip) con su propio código, y UiManager.show() lo pone en pantalla.
  • Una escena puede tener su propio Game Mode: el del menú principal no tiene jugador, HUD ni reglas.
  • Enhanced Input deja al jugador cambiar las teclas marcadas Player Mappable, y las guarda y las carga solo.
  • Pausar para el juego, salvo lo que tiene su modo de proceso en Always.

Abre el proyecto del plataformas. Todo lo que sigue se le añade: tres UI (MainMenu.uip, Controls.uip, Pause.uip), una escena para el menú principal y unas líneas en el HUD y en las reglas.

No hace falta que cambien todas. Aquí el jugador puede cambiar tres: A (moverse a la izquierda), D (a la derecha) y Espacio (saltar). Las flechas y la W se quedan como están, como una segunda forma de jugar.

Selecciona input/controls.inputcontext. El Inspector muestra cada acción con sus teclas. En cada una de las tres teclas pulsa su botón Edit (el lápiz, entre la flecha y la papelera), activa Player Mappable, ponle un nombre y vuelve atrás:

TeclaMapping NameDisplay Name
A (move, con Negate)move_leftMove left
D (move)move_rightMove right
Espacio (jump)jumpJump

El contexto de controles en el Inspector: bajo la A se lee "Negate, Player mappable", bajo la D y el Espacio "Player mappable"

  • El Mapping Name es como el código llama a la tecla ("move_left"). No lo cambies cuando el juego ya esté publicado: las teclas que guardaron los jugadores van por ese nombre.
  • El Display Name es para los menús que muestran las teclas por sí solos.

Las tres UI comparten un aspecto, escrito en la hoja de estilo del proyecto, style/base.gss. Ábrela y escribe:

/* La hoja de estilo del proyecto: la base de todas las UI. */
:root {
--panel: #1b1e30;
--button: #2b2f4a;
--edge: #8b93c9;
--focus: #ffd34d;
}
/* Las ventanas de los menús. */
PanelContainer {
background: var(--panel);
border: 2px solid var(--edge);
border-radius: 6px;
padding: 14px;
}
/* Los botones: oscuros con el borde claro; el que tiene el foco (el
del teclado), con el borde amarillo. */
Button {
background: var(--button);
border: 2px solid var(--edge);
border-radius: 4px;
padding: 4px 14px;
color: #ffffff;
font-size: 16px;
}
Button:hover { background: #3b4170; }
Button:pressed { background: #1d2033; }
Button:focus { border: 2px solid var(--focus); }
/* Los títulos, con la Class "Title". */
Label.Title {
font-size: 28px;
color: #ffffff;
font-outline-color: #222233;
outline-size: 8;
text-align: center;
}
/* El texto pequeño y gris, con la Class "Hint". */
Label.Hint {
font-size: 12px;
color: #b8bdd8;
text-align: center;
}
  • Button:focus es el botón en el que está el teclado: lleva el borde amarillo. Sin él, quien juega con el teclado no sabría dónde está.
  • Un título es un Label cuya Class (Inspector > Theme) es Title; un texto pequeño, Hint.

Crea ui/MainMenu.uip (una UI), con un Control como raíz, a pantalla completa:

  • Center (CenterContainer), a pantalla completa: centra lo que contiene.
    • Column (VBoxContainer), con Separation 8: uno debajo de otro.
      • Title (Label), Class Title, con el texto Pixel Platformer.
      • Gap (Control), Custom Minimum Size 0 × 12: un poco de espacio.
      • Play, Controls y Quit (Button).

MainMenu.uip en el editor: el árbol Center, Column, Title, Gap, Play, Controls, Quit, y el menú en el lienzo

Su código:

module MainMenu
# Los botones del menú y la pantalla de Controles que abre.
use actor::Play as play_button : Button
use actor::Controls as controls_button : Button
use actor::Quit as quit_button : Button
use ui::Controls as controls_ui
# Se ejecuta una vez, cuando aparece el menú.
fn _ready() void {
# El teclado empieza en Play: las flechas van de un botón a otro y
# Enter o Espacio pulsa uno.
play_button.grab_focus()
}
on play_button.pressed() {
SceneManager.load("level1")
}
on controls_button.pressed() {
# Capa 10: se dibuja sobre el menú, que está en la capa 1.
_ = UiManager.show(controls_ui, 10)
}
on quit_button.pressed() {
get_tree().quit()
}
  • grab_focus() pone el teclado en Play. Desde ahí, las flechas van a los otros botones y Enter o Espacio pulsa uno. Eso viene con el motor: los menús no necesitan código para moverse.
  • UiManager.show(controls_ui, 10) pone la pantalla de Controles en una capa más alta, sobre el menú.

El menú necesita una escena donde vivir. Crea scenes/main_menu.scene con un Spatial como raíz, llamado Menu, y un Sprite con assets/art/sky.png (Scale 7 × 7, Centered desactivado), el mismo cielo que el nivel.

El nivel recibe su jugador, su HUD y sus reglas del Game Mode. El menú no debe: selecciona la raíz y, en el Inspector, activa Game Mode > Override y deja vacíos Player, HUD y Rules.

La escena del menú principal con la raíz seleccionada: Game Mode > Override activado, con Player, HUD y Rules vacíos

Su código solo muestra el menú:

module Menu
# La escena del menú principal: el cielo y el menú encima. Su Game Mode
# está sobrescrito sin jugador, HUD ni reglas (selecciona la raíz y Game
# Mode > Override en el inspector), así que aquí no aparece nada más.
use ui::MainMenu as main_menu_ui
# Se ejecuta una vez, cuando empieza la escena: pone el menú en
# pantalla.
fn _ready() void {
# show() devuelve el menú; no lo necesitamos, y `_ =` lo dice.
_ = UiManager.show(main_menu_ui)
}

Por último, en Project Settings, application/run/main_scene pasa a ser res://scenes/main_menu.scene: el juego empieza en el menú.

Crea ui/Controls.uip. La raíz es un Control llamado Controls, a pantalla completa:

  • Dim (ColorRect), a pantalla completa, negro a media opacidad: oscurece lo que hay detrás.
  • Center (CenterContainer), a pantalla completa.
    • Panel (PanelContainer): la ventana, con el estilo de base.gss.
      • Column (VBoxContainer), Separation 8:
        • Title (Label), Class Title, texto Controls.
        • Tres filas, MoveLeftRow, MoveRightRow y JumpRow (HBoxContainer, Separation 12), cada una con un Label (MoveLeftLabel, Custom Minimum Size 110 × 0, con el texto Move left) y un Button (MoveLeftKey, 90 × 0). Lo mismo para MoveRight y Jump.
        • Hint (Label), Class Hint.
        • Buttons (HBoxContainer, Alignment Center): Reset y Back (Button).

La pantalla de Controles también se abre desde el menú de pausa, con el juego pausado. Entonces solo funciona lo que tiene su modo de proceso en Always. Selecciona la raíz y pon Process > Mode en Always. El Inspector oculta el grupo Process: escribe process en Filter Properties, o activa Show Advanced Properties en su menú ⋮.

Controls.uip en el editor: las tres filas con su etiqueta y su botón de tecla, la pista, y Reset y Back

Su código:

module Controls
# La pantalla donde el jugador cambia las teclas. Muestra las teclas
# marcadas "Player Mappable" en input/controls.inputcontext.
use actor::MoveLeftKey as move_left_key : Button
use actor::MoveRightKey as move_right_key : Button
use actor::JumpKey as jump_key : Button
use actor::Hint as hint : Label
use actor::Reset as reset_button : Button
use actor::Back as back_button : Button
use input::controls as controls
HINT :: String = "Choose a key to change it."
# La tecla que espera una nueva (su mapping name), o "" si ninguna.
mut waiting := ""
# El botón que abrió esta pantalla: recupera el foco al salir.
mut opener : Control = null
# Se ejecuta una vez, cuando aparece la pantalla.
fn _ready() void {
opener = get_viewport().gui_get_focus_owner()
# Enhanced Input muestra las teclas de los contextos activos. En el
# menú principal nadie ha activado todavía "controls".
controls.enable(0)
show_keys()
move_left_key.grab_focus()
}
# Cada botón muestra la tecla que usa ahora su acción.
fn show_keys() void {
move_left_key.text = key_text("move_left")
move_right_key.text = key_text("move_right")
jump_key.text = key_text("jump")
hint.text = HINT
}
# La tecla que usa ahora `mapping` ("A", "Space"...): la del jugador, o
# la que trae el contexto.
fn key_text(mapping: String) String {
for entry in EnhancedInput.get_player_mappable_keys() {
# Cada entrada es un Dictionary: mapping_name, display_name,
# key_text...
key : Dictionary = (entry as Dictionary) ?? {}
if key.get("mapping_name", "") == mapping {
return str(key.get("key_text", ""))
}
}
return "?"
}
on move_left_key.pressed() {
wait_for_key("move_left", move_left_key)
}
on move_right_key.pressed() {
wait_for_key("move_right", move_right_key)
}
on jump_key.pressed() {
wait_for_key("jump", jump_key)
}
# La próxima tecla que pulse el jugador será la de `mapping`.
fn wait_for_key(mapping: String, button: Button) void {
waiting = mapping
button.text = "..."
hint.text = "Press a key (Esc cancels)."
}
# Cada tecla pulsada llega aquí primero, antes de que la vean los
# botones.
fn _input(event: InputEvent) void {
key : InputEventKey = event as InputEventKey
# Solo una tecla al bajar; ni el ratón ni una tecla mantenida.
if key == null or not key.pressed or key.echo {
return
}
if waiting == "" {
# Esc sale de la pantalla, como Back.
if key.keycode == KEY_ESCAPE {
get_viewport().set_input_as_handled()
close()
}
return
}
# Esta tecla es la respuesta: los botones no la reciben.
get_viewport().set_input_as_handled()
if key.keycode != KEY_ESCAPE {
EnhancedInput.set_player_mapped_key(waiting, key)
# Se guarda en user://input_mappings.cfg: la próxima vez que
# empiece el juego, Enhanced Input la carga solo.
_ = EnhancedInput.save_player_mapped_keys()
}
waiting = ""
show_keys()
}
# Vuelve a las teclas que trae el contexto.
on reset_button.pressed() {
EnhancedInput.reset_all_player_mapped_keys()
_ = EnhancedInput.save_player_mapped_keys()
show_keys()
}
on back_button.pressed() {
close()
}
fn close() void {
if opener != null {
opener.grab_focus()
}
UiManager.hide(self)
}
  • EnhancedInput.get_player_mappable_keys() lista las teclas marcadas Player Mappable: de cada una, su mapping_name, su display_name y la tecla que usa ahora, como texto (key_text).
  • Al pulsar el botón de una tecla, la pantalla espera: la próxima tecla que baje es la nueva. _input() recibe cada tecla antes que nada. set_input_as_handled() aparta esa tecla de los botones, para que Enter no pulse otro.
  • EnhancedInput.set_player_mapped_key(name, key) cambia la tecla, y el juego la usa al momento. save_player_mapped_keys() la escribe en user://input_mappings.cfg. La próxima vez que empiece el juego, Enhanced Input la carga solo (Project Settings, input_devices/enhanced_input/load_player_mapped_keys, activado por defecto).
  • reset_all_player_mapped_keys() vuelve a las teclas del contexto.

La pantalla de Controles en el juego: Move left espera una tecla ("..."), con la pista "Press a key (Esc cancels)."

Crea ui/Pause.uip, como la pantalla de Controles: una raíz Pause (a pantalla completa, Process > Mode: Always), un Dim, un Center con un Panel, y en su Column un Title (Paused) y tres botones: Resume, Controls y Menu (con el texto Main menu).

module Pause
# El menú de pausa. El HUD lo muestra al pulsar Esc y pausa el juego. El
# Process > Mode de su raíz es Always: funciona mientras el resto del
# juego espera.
use actor::Resume as resume_button : Button
use actor::Controls as controls_button : Button
use actor::Menu as menu_button : Button
use ui::Controls as controls_ui
use interface::game as game
fn _ready() void {
resume_button.grab_focus()
}
on resume_button.pressed() {
resume()
}
on controls_button.pressed() {
# Capa 20: sobre el menú de pausa, que está en la capa 10.
_ = UiManager.show(controls_ui, 20)
}
on menu_button.pressed() {
get_tree().paused = false
game.reset() # monedas, corazones y `won` vuelven a como empezaron
SceneManager.load("main_menu")
}
# Esc vuelve al juego, como Resume. Mientras la pantalla de Controles
# está abierta, ella recibe Esc primero.
fn _unhandled_input(event: InputEvent) void {
if event.is_action_pressed("ui_cancel") {
get_viewport().set_input_as_handled()
resume()
}
}
fn resume() void {
get_tree().paused = false
UiManager.hide(self)
}
  • get_tree().paused para todo el juego: la física, los enemigos, los temporizadores y las acciones de Enhanced Input. Solo sigue lo que es Always, como este menú.
  • UiManager.hide(self) quita el menú de la pantalla.

El HUD está en pantalla todo el nivel, así que es él quien abre el menú de pausa. Añade al código de ui/HUD.uip el use ui::Pause y la función del final:

module HUD
use actor::Coins as coins_label : Label
use actor::Heart1 as heart1 : TextureRect
use actor::Heart2 as heart2 : TextureRect
use actor::Heart3 as heart3 : TextureRect
use actor::Message as message : Label
use interface::game as game
use ui::Pause as pause_ui
# Un corazón que tienes conserva sus colores; uno perdido se ve oscuro.
FULL :: Color = Color(1, 1, 1, 1)
EMPTY :: Color = Color(0.2, 0.2, 0.3, 0.6)
# @onready watch: se ejecuta al empezar y cada vez que cambian las
# monedas.
@onready watch game.coins(value: int) {
coins_label.text = str(value)
}
@onready watch game.hearts(value: int) {
# `a if condición else b`: a si se cumple la condición, si no b.
heart1.modulate = FULL if value >= 1 else EMPTY
heart2.modulate = FULL if value >= 2 else EMPTY
heart3.modulate = FULL if value >= 3 else EMPTY
if value == 0 {
message.text = "Try again!"
}
}
watch game.won(value: bool) {
if value {
message.text = "Level complete!"
}
}
# Esc durante la partida pausa el juego y muestra el menú de pausa.
fn _unhandled_input(event: InputEvent) void {
# Solo mientras sigue la partida: no después de la bandera ni de
# perder.
playing : bool = GameMode.get_match_state() == GameMode.MATCH_IN_PROGRESS
if event.is_action_pressed("ui_cancel") and playing {
get_viewport().set_input_as_handled()
get_tree().paused = true # todo se para, salvo lo que es Always
_ = UiManager.show(pause_ui, 10)
}
}

ui_cancel es la acción del motor para Esc, la que usan los menús para volver.

El juego en pausa: la ventana Paused sobre el nivel, con el foco en Resume, Controls y Main menu

Con un menú principal, el juego no debería quedarse en “Level complete!”. En las reglas (prefabs/rules.prefab), después de ganar, espera dos segundos y vuelve al menú:

module Rules
# Las reglas de la partida. El Game Mode crea este prefab en cada nivel
# (Project Settings > Application > Game Mode > Rules) y decide cuándo
# termina la partida y qué pasa entonces.
use interface::game as game
use audio::win as win_snd
# Se llegó a la bandera: la partida termina con victoria y el juego
# vuelve al menú principal.
watch game.won(value: bool) {
if value {
AudioManager.play_sound(win_snd)
GameMode.end_match()
spawn back_to_menu()
}
}
# No quedan corazones: la partida termina y el nivel vuelve a empezar.
watch game.hearts(value: int) {
if value == 0 {
GameMode.end_match()
spawn restart()
}
}
async fn restart() void {
await sleep(1.5) # tiempo para leer "Try again!"
game.reset() # monedas, corazones y `won` vuelven a como empezaron
# Vuelve a cargar el nivel: el Game Mode empieza allí una partida
# nueva.
SceneManager.restart()
}
async fn back_to_menu() void {
await sleep(2.0) # tiempo para leer "Level complete!"
game.reset()
SceneManager.load("main_menu")
}

Pulsa Play (F5). El juego empieza en el menú:

  1. Con las flechas, ve a Controls y pulsa Enter. Pulsa el botón de Move left y luego la J: ahora la J mueve a la izquierda, y la A no.
  2. Back, y Play. En el nivel, Esc pausa: nada se mueve. Controls se abre sobre el menú de pausa, y Reset devuelve las teclas con las que venía el juego.
  3. Cierra el juego y ábrelo otra vez: las teclas que elegiste siguen ahí.

En Windows el archivo está en %APPDATA%\Gobu\app_userdata\Pixel Platformer\input_mappings.cfg. Bórralo para empezar otra vez con las teclas del contexto. En un juego web, lo guarda el navegador.

En el códigoDónde se explica
use ui::, UiManager.show() / hide()Importar con use, Interfaces de usuario
on button.pressed(), grab_focus()Señales, Interfaces de usuario
El Game Mode de una escena (Override)Flujo del juego
Player Mappable, EnhancedInput.set_player_mapped_key()Input, Input
fn _input(), fn _unhandled_input()Input
for entry in ..., as Dictionary, ??Control de flujo, Expresiones
spawn, await sleep()Concurrencia