Rogue Example

Files:

• statemachine/rogue/movementtransition.h
• statemachine/rogue/window.cpp
• statemachine/rogue/window.h
• statemachine/rogue/main.cpp
• statemachine/rogue/rogue.pro

The Rogue example shows how to use the Qt state machine for event handling.

This example implements a simple text based game. Do you see the @ in the screenshot? That's you, the rogue. The # characters are walls, and the dots represent floor. In a real game, other ASCII characters would represent all kinds of objects and creatures, for instance, ancient dragons (Ds) or food rations (%s). But let's not get carried away. In this game, the rogue is simply running around in an empty room.

The rogue is moved with the keypad (2, 4, 8, 6). That aside, we have implemented a quit command that triggers if the player types q. The player is then asked if he/she really wants to quit.

Most games have commands that need more than one key press (we think of consecutive presses, i.e., not of several keys being pressed at the same time). In this game, only the quit command falls under this category, but for the sake of argument, let's imagine a fully-fledged game with a rich set of commands. If we were to implement these by catching key events in keyPressEvent(), we would have to keep a lot of class member variables to track the sequence of keys already typed (or find some other way of deducing the current state of a command). This can easily lead to spaghetti, which is--as we all well know, I'm sure--unpleasant. With a state machine, on the other hand, separate states can wait for a single key press, and that makes our lives a lot simpler.

The example consists of two classes:

• Window draws the text display of the game and sets up the state machine. The window also has a status bar above the area in which the rouge moves.
• MovementTransition is a transition that carries out a single move of the rogue.

Before we embark on a code walkthrough, it is necessary to take a closer look at the design of the machine. Here is a state chart that shows what we want to achieve:

The input state waits for a key press to start a new command. When receiving a key it recognizes, it transitions to one of the two commands of the game; though, as we will see, movement is handled by the transition itself. The quit state waits for the player to answer yes or no (by typing y or n) when asked whether he/she really wants to quit the game.

The chart demonstrates how we use one state to wait for a single key press. The press received may trigger one of the transitions connected to the state.

 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;

 protected:
     void paintEvent(QPaintEvent *event);

 private:
     void buildMachine();
     void setupMap();

     QChar map[WIDTH][HEIGHT];
     int pX, pY;

     QStateMachine *machine;
     QString myStatus;
 };

 Window::Window()
 {
     pX = 5;
     pY = 5;
     ...
     setupMap();
     buildMachine();
 }

 void Window::buildMachine()
 {
     machine = new QStateMachine;

     QState *inputState = new QState(machine);
     inputState->assignProperty(this, "status", "Move the rogue with 2, 4, 6, and 8");

     MovementTransition *transition = new MovementTransition(this);
     inputState->addTransition(transition);

     QState *quitState = new QState(machine);
     quitState->assignProperty(this, "status", "Really quit(y/n)?");

     QKeyEventTransition *yesTransition = new
         QKeyEventTransition(this, QEvent::KeyPress, Qt::Key_Y);
     yesTransition->setTargetState(new QFinalState(machine));
     quitState->addTransition(yesTransition);

     QKeyEventTransition *noTransition =
         new QKeyEventTransition(this, QEvent::KeyPress, Qt::Key_N);
     noTransition->setTargetState(inputState);
     quitState->addTransition(noTransition);

     QKeyEventTransition *quitTransition =
         new QKeyEventTransition(this, QEvent::KeyPress, Qt::Key_Q);
     quitTransition->setTargetState(quitState);
     inputState->addTransition(quitTransition);

     machine->setInitialState(inputState);

     connect(machine, SIGNAL(finished()), qApp, SLOT(quit()));

     machine->start();
 }

 class MovementTransition : public QEventTransition
 {
     Q_OBJECT

 public:
     MovementTransition(Window *window) :
         QEventTransition(window, QEvent::KeyPress) {
         this->window = window;
     }

 protected:
     bool eventTest(QEvent *event) {
         if (event->type() == QEvent::StateMachineWrapped &&
             static_cast<QStateMachine::WrappedEvent *>(event)->event()->type() == QEvent::KeyPress) {
             QEvent *wrappedEvent = static_cast<QStateMachine::WrappedEvent *>(event)->event();

             QKeyEvent *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;
         }
         return false;
     }

     void onTransition(QEvent *event) {
         QKeyEvent *keyEvent = static_cast<QKeyEvent *>(
             static_cast<QStateMachine::WrappedEvent *>(event)->event());

         int key = keyEvent->key();
         switch (key) {
             case Qt::Key_4:
                 window->movePlayer(Window::Left);
                 break;
             case Qt::Key_8:
                 window->movePlayer(Window::Up);
                 break;
             case Qt::Key_6:
                 window->movePlayer(Window::Right);
                 break;
             case Qt::Key_2:
                 window->movePlayer(Window::Down);
                 break;
             default:
                 ;
         }
     }