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.
Por el camino verás:
- Un menú es una UI (
.uip) con su propio código, yUiManager.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.
1. Partir del plataformas
Sección titulada «1. Partir del plataformas»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.
2. Teclas que el jugador puede cambiar
Sección titulada «2. Teclas que el jugador puede cambiar»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:
| Tecla | Mapping Name | Display Name |
|---|---|---|
| A (move, con Negate) | move_left | Move left |
| D (move) | move_right | Move right |
| Espacio (jump) | jump | Jump |
- 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.
3. El aspecto de los menús
Sección titulada «3. El aspecto de los menús»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:focuses 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.
4. El menú principal
Sección titulada «4. El menú principal»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), ClassTitle, con el textoPixel Platformer.Gap(Control), Custom Minimum Size 0 × 12: un poco de espacio.Play,ControlsyQuit(Button).
Su código:
module MainMenu
# Los botones del menú y la pantalla de Controles que abre.use actor::Play as play_button : Buttonuse actor::Controls as controls_button : Buttonuse actor::Quit as quit_button : Buttonuse 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.
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ú.
5. La pantalla de Controles
Sección titulada «5. La pantalla de Controles»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 debase.gss.Column(VBoxContainer), Separation 8:Title(Label), ClassTitle, textoControls.- Tres filas,
MoveLeftRow,MoveRightRowyJumpRow(HBoxContainer, Separation 12), cada una con un Label (MoveLeftLabel, Custom Minimum Size 110 × 0, con el textoMove left) y un Button (MoveLeftKey, 90 × 0). Lo mismo paraMoveRightyJump. Hint(Label), ClassHint.Buttons(HBoxContainer, Alignment Center):ResetyBack(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ú ⋮.
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 : Buttonuse actor::MoveRightKey as move_right_key : Buttonuse actor::JumpKey as jump_key : Buttonuse actor::Hint as hint : Labeluse actor::Reset as reset_button : Buttonuse actor::Back as back_button : Buttonuse 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, sumapping_name, sudisplay_namey 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 enuser://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.
6. El menú de pausa
Sección titulada «6. El menú de pausa»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 : Buttonuse actor::Controls as controls_button : Buttonuse actor::Menu as menu_button : Buttonuse ui::Controls as controls_uiuse 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().pausedpara 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 : Labeluse actor::Heart1 as heart1 : TextureRectuse actor::Heart2 as heart2 : TextureRectuse actor::Heart3 as heart3 : TextureRectuse actor::Message as message : Labeluse interface::game as gameuse 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.
7. Volver al menú después de la bandera
Sección titulada «7. Volver al menú después de la bandera»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 gameuse 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")}8. Pruébalo
Sección titulada «8. Pruébalo»Pulsa Play (F5). El juego empieza en el menú:
- 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.
- 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.
- 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.
Lo que has usado
Sección titulada «Lo que has usado»| En el código | Dó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 |






