Ir al contenido
Descargar
Tutoriales

Plataformas 2D

En este tutorial haces Pixel Platformer, un plataformas 2D corto pero completo: corres y saltas por un nivel pintado con baldosas, recoges monedas, pisas robots (o pierdes un corazón si te tocan) y llegas a la bandera del final.

No hace falta saber mucho de programación: cada trozo de código lleva comentarios (las líneas que empiezan por #) que dicen qué hace. Por el camino verás cómo se organiza Gobu:

  • Todo lo que tiene comportamiento es un prefab con su propio código: el jugador, la moneda, el enemigo y la bandera.
  • La escena es el nivel: sus baldosas y dónde está cada cosa.
  • El HUD es un .uip (una interfaz) con su propio código.
  • Lo que comparten (monedas, corazones, si ganaste) vive en una interfaz (.iface.gro).
  • El Game Mode empieza cada partida: crea al jugador donde dice el nivel, muestra el HUD y ejecuta las reglas del juego, como el GameMode de Unreal.

Cada documento (.scene, .prefab, .uip) lleva su código dentro, y ese código corre sobre su actor raíz. No hay scripts en los actores hijos.

En el gestor de proyectos pulsa Create, ponle nombre y deja activado 2D Project. Los archivos del juego van en resources/ (ahí apunta res://); Gobu encuentra prefabs, interfaces y sonidos por nombre de archivo, así que organiza las carpetas como quieras.

Es pixel art, así que abre Project Settings (Ctrl+Shift+,) y cambia:

AjusteValorPara qué
display/window/size/viewport_width × viewport_height640 × 360El tamaño al que se dibuja el juego
display/window/size/window_width_override × window_height_override1280 × 720La ventana, el doble
display/window/stretch/modecanvas_itemsEscala los 640 × 360 a la ventana
rendering/textures/canvas_textures/default_texture_filterNearestPíxeles nítidos, no borrosos
physics/2d/default_gravity900Lo rápido que cae todo (980 por defecto)

El arte es Pixel Platformer y los sonidos son Digital Audio, los dos de Kenney y de dominio público (CC0). Arrastra los archivos al panel Assets:

  • assets/art/tiles.png: el Tilemap/tilemap_packed.png del paquete, baldosas de 18 × 18.
  • assets/art/characters.png: Tilemap/tilemap-characters_packed.png, personajes de 24 × 24.
  • assets/art/sky.png: el primer fondo de tilemap-backgrounds_packed.png (96 × 72).
  • assets/sounds/: coin.ogg (powerUp2), jump.ogg (phaseJump1), stomp.ogg (pepSound1), hurt.ogg (lowDown) y win.ogg (zapThreeToneUp).

El código usa un sonido por su nombre de archivo (use audio::jump), así que los nombres importan.

El juego usa Enhanced Input (Input): el código habla de acciones (moverse, saltar), no de teclas, así que puedes cambiar las teclas sin tocarlo. En la carpeta input/ crea:

  1. move.inputaction, una acción con value_type = Axis 1D: -1 izquierda, 1 derecha.
  2. jump.inputaction, una acción con value_type = Bool: pulsada o no.
  3. controls.inputcontext, las teclas de las dos:
AcciónTeclaModificadores
moveD, →ninguno
moveA, ←InputModifierNegate (convierte el 1 en -1)
jumpEspacio, W, ↑ninguno

El contexto controls.inputcontext en el inspector

Crea un recurso TileSet, assets/world_tiles.resource, y ábrelo: abajo se abre el panel TileSet.

  1. Pon su Tile Size en 18 × 18.
  2. Arrastra tiles.png a la lista Tile Sources y responde Yes cuando te ofrezca crear las baldosas en las zonas no transparentes.
  3. En el inspector, añade una Physics Layer. Su capa 1 es el mundo.
  4. En Paint, elige la capa de física y pinta un cuadrado entero en cada baldosa de suelo: las de césped de arriba y las de tierra.
  5. Las plataformas flotantes (las baldosas finas con césped) solo te paran desde arriba: píntalas también y activa One Way en su colisión. Las atraviesas saltando desde abajo y caes encima.

El conjunto de baldosas de Kenney en el panel TileSet

5. Lo que comparte el juego: la interfaz game

Sección titulada «5. Lo que comparte el juego: la interfaz game»

La moneda suma monedas, el enemigo quita corazones, la bandera gana y el HUD lo enseña todo. Ninguno necesita conocer a los demás: comparten una interfaz global. Crea scripts/game.iface.gro:

# Lo que comparte el juego. `global`: una sola para todo el juego, la
# misma para todos los que la usan.
interface game global {
# `live`: quien la usa puede vigilarla con `watch` y reaccionar
# cuando cambia.
live coins : int = 0
live hearts : int = 3
live won : bool = false
# Verdadero durante un momento después de un golpe.
mut invulnerable : bool = false
# Quita un corazón, salvo que el jugador siga parpadeando del golpe
# anterior.
fn hurt() void {
if invulnerable or won or hearts == 0 {
return
}
invulnerable = true
# `set` avisa a quien lo vigila (HUD, jugador, reglas).
set hearts -= 1
}
}
  • Los campos live se pueden vigilar con watch: el HUD se redibuja cuando cambian.
  • hurt() quita un corazón salvo que el jugador siga parpadeando por el golpe anterior. Dentro de la interfaz el cambio se escribe set hearts -= 1: un hearts -= 1 a secas cambia el valor sin avisar a nadie (Estado reactivo). Desde fuera, game.coins += 1 ya avisa solo.

Crea prefabs/player.prefab con estos actores:

  • Player (CharacterBody), la raíz. En Collision, capa 2 y máscara 1: es el jugador y choca con el mundo.
    • Sprite (Sprite) con characters.png como Texture, Hframes 9 y Vframes 3 (la hoja tiene 9 columnas y 3 filas de personajes) y Frame 0: el alien verde.
    • CollisionShape con una RectangleShape de 14 × 18, 3 px más abajo: el cuerpo, no el casco.
    • Camera (Camera) con Position Smoothing activado y Limit izquierda 0, arriba 0, derecha 2376 (el ancho del nivel) y abajo 360.
    • AnimationPlayer (AnimationPlayer) y AnimationTree (AnimationTree): las animaciones y quién las elige, más abajo.

El prefab del jugador: el sprite, su colisión y la cámara

Sus animaciones: una máquina de estados, sin código

Sección titulada «Sus animaciones: una máquina de estados, sin código»

El jugador tiene tres animaciones, y cuál se ve depende de lo que esté haciendo. En vez de escribirlo en el código, lo dibujas como una máquina de estados, como en los Animation Blueprints de Unreal: cada animación es un estado, y las flechas dicen cuándo pasar de uno a otro.

  1. Selecciona AnimationPlayer y, en el panel Animation, crea tres animaciones con una pista de Sprite > frame (el personaje que se dibuja): idle (fotograma 0), walk (fotograma 0, y el 1 a los 0,125 s; dura 0,25 s y en bucle) y jump (fotograma 1).
  2. Selecciona AnimationTree: pon Anim Player en AnimationPlayer, Advance Expression Base Node en Player (a él le preguntan las expresiones de abajo) y Tree Root en un AnimationNodeStateMachine nuevo.
  3. En el panel AnimationTree, añade las tres animaciones como estados y únelas con transiciones. Dale a cada transición Advance Mode = Auto y, salvo a Start → idle, una Advance Expression:
DeAAdvance Expression
Startidle(ninguna)
idlewalkis_on_floor() and velocity.x != 0
walkidleis_on_floor() and velocity.x == 0
idle, walkjumpnot is_on_floor()
jumpidleis_on_floor() and velocity.x == 0
jumpwalkis_on_floor() and velocity.x != 0

El panel Animation con la animación de caminar: una pista para el fotograma del sprite

El panel AnimationTree: los estados idle, walk y jump y sus transiciones

Cada expresión se le pregunta al jugador en cada fotograma: is_on_floor() y velocity son suyos. Pulsa el ▶ de un estado para probarlo en el editor. Añadir otra animación más adelante (recibir daño, trepar) es otro estado y unas flechas, no más if en el código.

Su código:

module Player
# Los actores de este prefab que usa el código, cada uno con su tipo.
use actor::Player as player : CharacterBody2D
use actor::Sprite as sprite : Sprite2D
# Las teclas, los datos que comparte el juego y dos sonidos.
use input::controls as controls
use interface::game as game
use audio::jump as jump_snd
use audio::hurt as hurt_snd
# @editable: estos números se pueden cambiar en el inspector.
@editable mut speed : float = 130.0 # píxeles por segundo al correr
@editable mut jump_speed : float = 380.0 # fuerza del salto
# Los corazones que tenía: para notar cuándo pierde uno.
mut hearts := 3
# Se ejecuta una vez, cuando el jugador aparece en el nivel.
fn _ready() void {
controls.enable(0) # enciende las teclas
}
# Se ejecuta 60 veces por segundo, al ritmo de la física.
fn _physics_process(delta: float) void {
# -1 con A o ←, 1 con D o →, 0 si no se pulsa nada.
mut dir : float = controls.move.value()
# La partida ha terminado (la bandera, o no quedan corazones):
# quieto.
if not playing() {
dir = 0.0
}
player.velocity.x = dir * speed
# La gravedad tira de él hacia abajo un poco más en cada paso. Es la
# del mundo (Project Settings > Physics > 2D > Default Gravity), la
# misma para todos.
player.velocity += player.get_gravity() * delta
# Moverse, parando contra el suelo y las paredes. Devuelve si chocó
# con algo; no lo necesitamos, y `_ =` lo dice.
_ = player.move_and_slide()
# Se cayó por debajo del nivel.
if player.position.y > 420.0 {
fall()
}
face_where_it_walks()
}
# Se pulsa la tecla de saltar: salta, pero solo si está apoyado en algo.
on controls.jump.started() {
if player.is_on_floor() and playing() {
player.velocity.y = -jump_speed # en pantalla, arriba es Y negativa
AudioManager.play_sound(jump_snd)
}
}
# Se suelta la tecla mientras todavía sube: un salto más corto.
on controls.jump.completed() {
if player.velocity.y < 0.0 {
player.velocity.y *= 0.5
}
}
# Verdadero mientras dura la partida. Las reglas la terminan al llegar a
# la bandera o sin corazones.
fn playing() bool {
return GameMode.get_match_state() == GameMode.MATCH_IN_PROGRESS
}
# El sprite mira hacia donde camina el jugador. Qué animación se ve
# (idle, walk, jump) no es código: la elige la máquina de estados del
# AnimationTree.
fn face_where_it_walks() void {
if player.velocity.x != 0.0 {
sprite.flip_h = player.velocity.x > 0.0
}
}
# Se cayó del nivel: pierde un corazón y vuelve al PlayerStart.
fn fall() void {
game.hurt()
player.velocity = Vector2.ZERO
GameMode.restart_player(player)
}
# Se ejecuta cada vez que cambian los corazones, por un enemigo o una
# caída.
watch game.hearts(value: int) {
# Menos que antes: le han hecho daño.
if value < hearts {
AudioManager.play_sound(hurt_snd)
spawn blink() # parpadea mientras el juego sigue
}
hearts = value
}
# Una corrutina: se pausa en cada `await` mientras el juego sigue.
async fn blink() void {
# `defer` se ejecuta cuando la corrutina termina, termine como
# termine.
defer {
sprite.visible = true
game.invulnerable = false # se le puede volver a hacer daño
}
for _i : int in range(10) {
sprite.visible = not sprite.visible # se ve, no se ve, se ve...
await sleep(0.1) # espera una décima de segundo
}
}
  • use actor::Player as player : CharacterBody2D te da el actor raíz y sus métodos (self es el código, no el actor). En el código las clases llevan su nombre completo: CharacterBody2D, AnimatedSprite2D.
  • El jugador solo se mueve mientras la partida está en curso: GameMode.get_match_state() dice cuándo la han terminado las reglas (sección 11).
  • _ = player.move_and_slide(): move_and_slide() devuelve si chocó con algo. Grost avisa cuando se tira un valor sin decirlo; _ = dice que no lo necesitas.
  • El código no elige animaciones: solo gira el sprite hacia donde camina el jugador.
  • Saltar reacciona a la acción con on: started cuando se pulsa la tecla, completed cuando se suelta. Soltar antes de tiempo reduce a la mitad la velocidad de subida, así que un toque es un saltito y mantener la tecla es un salto entero.
  • Caerse del nivel cuesta un corazón, y GameMode.restart_player(player) lo devuelve al PlayerStart del nivel.
  • watch game.hearts se entera de un corazón perdido venga de donde venga (un enemigo o una caída) y lanza blink(), una corrutina que parpadea durante un segundo (Concurrencia).

Crea prefabs/coin.prefab:

  • Coin (Area), la raíz, con Collision sin capa y máscara 2: solo ve al jugador.
    • Sprite (AnimatedSprite) con una animación spin: las baldosas 151 y 152 de tiles.png (columnas 11 y 12, fila 7), 5 FPS, autoplay.
    • CollisionShape con una CircleShape de radio 7.
module Coin
use actor::Coin as coin : Area2D
use interface::game as game
use audio::coin as coin_snd
# El jugador ha tocado la moneda (su máscara solo ve al jugador). "once"
# en vez de "on": se ejecuta solo la primera vez, así que la moneda
# nunca cuenta dos veces.
once coin.body_entered(_body: Spatial2D) {
game.coins += 1 # el HUD se entera y enseña el número nuevo
AudioManager.play_sound(coin_snd)
# Se quita del nivel, al final del fotograma.
coin.destroy()
}
  • once coin.body_entered(...) conecta la señal del Area2D raíz, como on, pero solo se ejecuta la primera vez que entra un cuerpo: si el jugador vuelve a tocar la moneda antes de que desaparezca, sigue contando una vez.
  • destroy() quita un actor del nivel. Espera al final del fotograma, así que se puede usar en mitad de la física (dentro de body_entered).

El robot camina, se da la vuelta en las paredes y en el borde de su plataforma, y muere si caes encima. Si te toca de cualquier otra forma, pierdes un corazón. Crea prefabs/enemy.prefab:

  • Enemy (CharacterBody), la raíz, capa 3 y máscara 1.
    • Sprite (AnimatedSprite): walk (personajes 18 y 19, 6 FPS, autoplay) y squashed (personaje 20).
    • CollisionShape: RectangleShape de 16 × 12, 6 px más abajo.
    • Hitbox (Area), sin capa y con máscara 2, con su propia CollisionShape algo más grande (18 × 14): detecta al jugador.
    • Ledge (RayCast) en (-9, 6) con Target Position (0, 12): busca suelo justo delante de sus pies.

El prefab del enemigo: el hitbox alrededor del robot y el rayo del borde a sus pies

module Enemy
use actor::Enemy as enemy : CharacterBody2D
use actor::Sprite as sprite : AnimatedSprite2D
use actor::Hitbox as hitbox : Area2D
use actor::Ledge as ledge : RayCast2D
use interface::game as game
use audio::stomp as stomp_snd
@editable mut speed : float = 40.0 # píxeles por segundo al caminar
# -1 camina hacia la izquierda, 1 hacia la derecha.
mut direction : float = -1.0
# Pisado: aplastado un momento antes de desaparecer.
mut dead := false
fn _physics_process(delta: float) void {
enemy.velocity.x = direction * speed
# La misma gravedad que el jugador: la del mundo.
enemy.velocity += enemy.get_gravity() * delta
_ = enemy.move_and_slide()
# El rayo a sus pies busca suelo justo delante.
ledge.force_raycast_update()
# Una pared delante, o no hay suelo delante: da la vuelta.
no_floor : bool = enemy.is_on_floor() and not ledge.is_colliding()
if enemy.is_on_wall() or no_floor {
direction = -direction
# El rayo pasa al nuevo frente, y el sprite mira hacia allí.
ledge.position.x = 9.0 * direction
sprite.flip_h = direction > 0.0
}
}
# Algo ha tocado el hitbox (su máscara solo ve al jugador).
on hitbox.body_entered(body: Spatial2D) {
if dead or not (body is CharacterBody2D) {
return
}
player : CharacterBody2D = body as CharacterBody2D
# Cayendo y por encima del robot: un pisotón.
falling : bool = player.velocity.y > 0.0
above : bool = player.global_position.y < enemy.global_position.y
if falling and above {
player.velocity.y = -220.0 # el jugador rebota
spawn squash()
} else {
game.hurt() # cualquier otro toque le hace daño al jugador
}
}
# Aplastado un momento, y luego desaparece.
async fn squash() void {
dead = true # su hitbox ya no hace caso al jugador
# Deja de caminar: ya no se llama a _physics_process.
enemy.set_physics_process(false)
sprite.play("squashed")
AudioManager.play_sound(stomp_snd)
await sleep(0.4)
enemy.destroy() # lo quita del nivel
}
  • on hitbox.body_entered funciona con cualquier actor traído con use actor::, no solo con la raíz.
  • Pisar o recibir: el enemigo no sabe nada de corazones ni de parpadeos: llama a game.hurt() y la interfaz y el jugador hacen el resto.
  • Tras el pisotón el robot se queda aplastado un momento. enemy.set_physics_process(false) deja de llamar a su _physics_process, así que ya no camina; dead evita que su hitbox pise o haga daño una segunda vez.
  • body as CharacterBody2D convierte el Spatial2D que da la señal en la clase que es de verdad, después de comprobarlo con is.

Crea prefabs/flag.prefab: Flag (Area, máscara 2) con un Pole (Sprite con la baldosa 131), un Cloth (AnimatedSprite con las baldosas 111 y 112, 4 FPS) y una CollisionShape de 12 × 36. Su código tiene una línea que importa:

module Flag
use actor::Flag as flag : Area2D
use interface::game as game
# El jugador ha llegado a la bandera: el nivel está ganado. Las reglas,
# el HUD y el jugador reaccionan solos.
on flag.body_entered(_body: Spatial2D) {
game.won = true
}

Crea ui/HUD.uip:

  • HUD (Control), la raíz, a pantalla completa y con Mouse Filter = Ignore.
    • CoinIcon (TextureRect) arriba a la izquierda, con una AtlasTexture de tiles.png que enseña la moneda (región 198, 126, 18, 18).
    • Coins (Label) a su lado, con contorno.
    • Heart1, Heart2, Heart3 (TextureRect) arriba a la derecha, anclados a la derecha, con el corazón lleno (región 72, 36, 18, 18).
    • Message (Label) en el centro, grande, con el texto vacío.

El HUD en el editor de interfaces

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
# 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!"
}
}

El HUD no sabe nada de monedas, robots ni del jugador: solo vigila la interfaz.

¿Quién decide cuándo termina la partida, y qué pasa entonces? En Gobu es el trabajo del Game Mode (como en Unreal): empieza una partida en cada nivel, crea al jugador, muestra el HUD y ejecuta las reglas, un prefab con el código del juego.

Crea prefabs/rules.prefab con un solo Actor llamado Rules, y este código:

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 ha llegado a la bandera: la partida termina con victoria.
watch game.won(value: bool) {
if value {
AudioManager.play_sound(win_snd)
GameMode.end_match()
}
}
# 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()
}
  • Una partida pasa por tres estados: esperando a empezar, en curso y terminada. Empieza sola cuando el nivel está listo (con Min Players jugadores: 1); GameMode.end_match() la termina, y el jugador deja de moverse (sección 6).
  • game.reset() devuelve cada campo de la interfaz a su valor inicial antes de que el nivel se vuelva a cargar.

Ahora dile al Game Mode qué usar. En Project Settings > Application > Game Mode:

  • Player: res://prefabs/player.prefab.
  • HUD: res://ui/HUD.uip.
  • Rules: res://prefabs/rules.prefab.
  • Start Automatically sigue activado: cada nivel empieza su partida sin código.

Project Settings, Application: el Game Mode con el jugador, el HUD y las reglas

Crea scenes/level1.scene y hazla la escena principal (clic derecho → Set as Main Scene). El nivel es solo lo que hay en él; su código se queda vacío, porque la partida la empieza el Game Mode:

  • Level (Spatial), la raíz.
    • Sky (Parallax) con Scroll Scale (0.3, 1), Repeat Size (480, 0) y Repeat Times 7. Dentro, un Sprite con sky.png, Centered desactivado y escala 5: el cielo se mueve más despacio que el nivel y se repite.
    • Ground (TileMapLayer) con world_tiles.resource como Tile Set. Selecciónalo y pinta el nivel en el panel TileMap: suelo con césped arriba y tierra debajo, agujeros que saltar, escalones y plataformas flotantes. Las plantas, los árboles y el cartel son baldosas sin colisión.
    • Bounds (StaticBody) con dos CollisionShape con una WorldBoundaryShape: una en x = 0 con normal (1, 0) y otra en x = 2376 con normal (-1, 0). Mantienen al jugador dentro.
    • PlayerStart (PlayerStart) donde empieza el jugador, de pie sobre el suelo a la izquierda. El Game Mode crea ahí al jugador, y restart_player lo devuelve ahí.
    • Instancias de los prefabs (arrástralos desde Assets): monedas sobre el suelo y las plataformas, unos cuantos enemy.prefab en el suelo y flag.prefab al final. El jugador no: lo trae el Game Mode.

Pintando el nivel con el panel TileMap

El PlayerStart al principio del nivel: la cápsula marca dónde aparece el jugador

El nivel entero en el editor, con las monedas, los enemigos y la bandera

Pulsa Run (F5). Corre con A/D o las flechas, salta con Espacio, W o ↑, y mantén la tecla para saltar más alto. Cae sobre los robots para quitártelos de encima y llega a la bandera.

El juego en marcha: monedas, corazones y un robot delante

Si algo no compila, el editor marca la línea. Los sospechosos habituales son los tipos de use actor:: (el : Tipo tiene que coincidir con el actor real) y los nombres de archivo en use input::, use audio:: o use interface::.

  • Menús y controles: un menú principal, un menú de pausa y una pantalla donde el jugador cambia las teclas, en el siguiente tutorial (Menús y controles).
  • Un segundo nivel: copia level1.scene, pinta otro y, en las reglas, llama a SceneManager.load("level2") un momento después de won. El Game Mode empieza allí una partida nueva.
  • Guardar el récord: una interfaz @persistent guarda el máximo de monedas entre partidas (Guardar partida).
  • Más enemigos: los murciélagos (personajes 24 a 26) vuelan; una corrutina con loop y await sleep los sube y los baja (Concurrencia).
UsasteDónde leer más
mut, fn, module, @editable, a if c else bExpresiones, Funciones, Anotaciones
_ = para un valor que no necesitasFunciones
use actor::, use audio::, SceneManagerImportar con use
once coin.body_entered(...), on controls.jump.started()Señales, Input
live, set, watch, @onready watchEstado reactivo
Una interfaz global con una función, reset()Interfaces
spawn, async fn, await sleep, deferConcurrencia
Game Mode, reglas, partidas, PlayerStartFlujo del juego
AnimationTree, una máquina de estados con expresionesAnimationTree, AnimationNodeStateMachineTransition
Acciones, contextos, modificadoresInput

Siguiente: Arena 3D, con oleadas de enemigos y corrutinas.


Arte y sonidos: Kenney (CC0). Gracias, Kenney.