Rogue
El ejemplo «Rogue» muestra cómo utilizar la Qt State Machine para la gestión de eventos.

Este ejemplo implementa un sencillo juego basado en texto. ¿Ves el « @ » en la captura de pantalla? Ese eres tú, el pícaro. Los caracteres « # » son paredes, y los puntos representan el suelo. En un juego real, otros caracteres ASCII representarían todo tipo de objetos y criaturas, por ejemplo, dragones antiguos (D) o raciones de comida (%). Pero no nos dejemos llevar por la imaginación. En este juego, el pícaro simplemente corre de un lado a otro por una habitación vacía.
El pícaro se mueve con el teclado numérico (2, 4, 8, 6). Aparte de eso, hemos implementado un comando « quit » que se activa si el jugador escribe « q ». A continuación, se le pregunta al jugador si realmente quiere salir.
La mayoría de los juegos tienen comandos que requieren pulsar más de una tecla (nos referimos a pulsaciones consecutivas, es decir, no a pulsar varias teclas al mismo tiempo). En este juego, solo el comando « quit » entra en esta categoría, pero, a efectos del ejemplo, imaginemos un juego completo con un amplio conjunto de comandos. Si tuviéramos que implementarlos capturando eventos de teclas en ` keyPressEvent()`, tendríamos que mantener muchas variables de miembro de clase para hacer un seguimiento de la secuencia de teclas ya pulsadas (o encontrar alguna otra forma de deducir el estado actual de un comando). Esto puede dar lugar fácilmente a un código enredado, lo cual —como todos sabemos muy bien, estoy seguro— resulta desagradable. Con una máquina de estados, en cambio, los distintos estados pueden esperar a que se pulse una sola tecla, lo que nos simplifica mucho la vida.
El ejemplo consta de dos clases:
Windowdibuja la pantalla de texto del juego y configura la máquina de estados. La ventana también tiene una barra de estado situada encima del área por la que se mueve el pícaro.MovementTransitiones una transición que lleva a cabo un único movimiento del pícaro.
Antes de embarcarnos en un recorrido por el código, es necesario examinar más de cerca el diseño de la máquina. Aquí hay un diagrama de estados que muestra lo que queremos conseguir:

El estado de entrada espera a que se pulse una tecla para iniciar un nuevo comando. Al recibir una tecla que reconoce, pasa a uno de los dos comandos del juego; aunque, como veremos, el movimiento lo gestiona la propia transición. El estado de salida espera a que el jugador responda «sí» o «no» (escribiendo « y » o « n ») cuando se le pregunte si realmente quiere salir del juego.
El diagrama muestra cómo utilizamos un estado para esperar a que se pulse una sola tecla. La pulsación recibida puede desencadenar una de las transiciones asociadas al estado.
Definición de la clase «Window»
La clase ` Window ` es un widget que dibuja la pantalla de texto del juego. También configura la máquina de estados, es decir, crea y conecta los estados de la máquina. Son los eventos de teclas de este widget los que utiliza la máquina.
class Window : public QWidget
{
Q_OBJECT
Q_PROPERTY(QString status READ status WRITE setStatus)
public:
enum Direction { Up, Down, Left, Right };
Window();
void movePlayer(Direction direction);
void setStatus(const QString &status);
QString status() const;
QSize sizeHint() const override;
protected:
void paintEvent(QPaintEvent *event) override;Direction especifica la dirección en la que debe moverse el personaje. Utilizamos esto en ` movePlayer()`, que mueve al personaje y actualiza la ventana. El juego cuenta con una línea de estado situada encima del área por la que se mueve el personaje. La propiedad ` status ` contiene el texto de esta línea. Utilizamos una propiedad porque la clase ` QState ` permite establecer cualquier propiedad de Qt al acceder a ella. Más adelante se profundizará en este tema.
private:
void buildMachine();
void setupMap();
static constexpr int WIDTH = 35;
static constexpr int HEIGHT = 20;
QChar map[WIDTH][HEIGHT];
int pX = 5;
int pY = 5;
QStateMachine *machine;
QString myStatus;
};map es un array con los caracteres que se muestran actualmente. Configuramos el array en setupMap() y lo actualizamos cuando se mueve el pícaro. pX y pY son la posición actual del pícaro, inicialmente establecida en (5, 5). WIDTH y HEIGHT son constantes que especifican las dimensiones del mapa.
La función ` paintEvent() ` se omite en este tutorial. Tampoco se tratan otros fragmentos de código que no guardan relación con la máquina de estados (las funciones ` setupMap()`, ` status()`, ` setStatus()`, ` movePlayer()` y ` sizeHint() `). Si deseas echar un vistazo al código, haz clic en el enlace del archivo ` window.cpp ` que aparece en la parte superior de esta página.
Implementación de la clase Window
Este es el constructor de ` Window`:
Window::Window()
{
...
setupMap();
buildMachine();
}Aquí configuramos el mapa y la máquina de estados. Continuemos con la función ` buildMachine() `:
void Window::buildMachine()
{
machine = new QStateMachine;
auto inputState = new QState(machine);
inputState->assignProperty(this, "status", "Move the rogue with 2, 4, 6, and 8");
auto transition = new MovementTransition(this);
inputState->addTransition(transition);Entramos en ` inputState ` al iniciar la máquina y desde ` quitState ` si el usuario desea seguir jugando. A continuación, establecemos el estado en un recordatorio útil sobre cómo jugar.
En primer lugar, se añade la transición « Movement » al estado de entrada. Esto permitirá mover al pícaro con el teclado numérico. Fíjate en que no establecemos un estado de destino para la transición de movimiento. Esto hará que se active la transición (y que se invoque la función onTransition()), pero la máquina no saldrá del estado « inputState ». Si hubiéramos establecido « inputState » como estado de destino, primero habríamos salido y luego habríamos vuelto a entrar en el estado « inputState ».
auto quitState = new QState(machine);
quitState->assignProperty(this, "status", "Really quit(y/n)?");
auto yesTransition = new QKeyEventTransition(this, QEvent::KeyPress, Qt::Key_Y);
yesTransition->setTargetState(new QFinalState(machine));
quitState->addTransition(yesTransition);
auto noTransition = new QKeyEventTransition(this, QEvent::KeyPress, Qt::Key_N);
noTransition->setTargetState(inputState);
quitState->addTransition(noTransition);Al entrar en quitState, actualizamos la barra de estado de la ventana.
QKeyEventTransition es una clase de utilidad que elimina la molestia de implementar transiciones para QKeyEvents. Solo tenemos que especificar la tecla que debe activar la transición y el estado de destino de la misma.
auto quitTransition = new QKeyEventTransition(this, QEvent::KeyPress, Qt::Key_Q);
quitTransition->setTargetState(quitState);
inputState->addTransition(quitTransition);La transición de inputState permite activar el estado de salida cuando el jugador escribe q.
machine->setInitialState(inputState);
connect(machine, &QStateMachine::finished, qApp, &QApplication::quit);
machine->start();
}La máquina ya está configurada, así que es hora de ponerla en marcha.
La clase `MovementTransition`
MovementTransition se activa cuando el jugador solicita que se mueva el pícaro (escribiendo 2, 4, 6 u 8) mientras la máquina se encuentra en el estado « inputState ».
class MovementTransition : public QEventTransition
{
Q_OBJECT
public:
explicit MovementTransition(Window *window)
: QEventTransition(window, QEvent::KeyPress), window(window)
{
}En el constructor, le indicamos a ` QEventTransition ` que solo envíe eventos ` KeyPress ` a la función ` eventTest()`:
protected:
bool eventTest(QEvent *event) override {
if (event->type() == QEvent::StateMachineWrapped &&
static_cast<QStateMachine::WrappedEvent *>(event)->event()->type() == QEvent::KeyPress) {
auto wrappedEvent = static_cast<QStateMachine::WrappedEvent *>(event)->event();
auto keyEvent = static_cast<QKeyEvent *>(wrappedEvent);
int key = keyEvent->key();
return key == Qt::Key_2 || key == Qt::Key_8 || key == Qt::Key_6 ||
key == Qt::Key_4 || key == Qt::Key_Down || key == Qt::Key_Up ||
key == Qt::Key_Right || key == Qt::Key_Left;
}
return false;
}Los eventos KeyPress vienen envueltos en objetos QStateMachine::WrappedEvent. Hay que asegurarse de que event sea un evento envuelto, ya que Qt utiliza otros eventos internamente. A partir de ahí, solo hay que comprobar qué tecla se ha pulsado.
Pasemos a la función ` onTransition() `:
void onTransition(QEvent *event) override {
auto keyEvent = static_cast<QKeyEvent *>(
static_cast<QStateMachine::WrappedEvent *>(event)->event());
int key = keyEvent->key();
switch (key) {
case Qt::Key_Left:
case Qt::Key_4:
window->movePlayer(Window::Left);
break;
case Qt::Key_Up:
case Qt::Key_8:
window->movePlayer(Window::Up);
break;
case Qt::Key_Right:
case Qt::Key_6:
window->movePlayer(Window::Right);
break;
case Qt::Key_Down:
case Qt::Key_2:
window->movePlayer(Window::Down);
break;
default:
;
}
}Cuando se invoca ` onTransition() `, sabemos que tenemos un evento ` KeyPress ` con 2, 4, 6 u 8, y podemos pedirle a ` Window ` que mueva al jugador.
La tradición «roguelike»
Quizá te hayas preguntado por qué el juego incluye un «rogue». Pues bien, este tipo de juegos de exploración de mazmorras basados en texto se remontan a un juego llamado, sí, «Rogue». Aunque superados por la tecnología de los modernos videojuegos en 3D, los roguelike cuentan con una sólida comunidad de seguidores incondicionales y devotos.
Jugar a estos juegos puede resultar sorprendentemente adictivo (a pesar de la falta de gráficos). Angband, quizás el roguelike más conocido, se puede encontrar aquí: http://rephial.org/.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.