Friday, 17 May 2013

A simple two-player QML game for Ubuntu Touch using the Ubuntu SDK: noughts and crosses (aka tic-tac-toe)!

Inspired by Rick's recent blog posts, and keen to write a blog post with a ridiculously long title, I've been reading up on QML recently. Still bearing the scars from the XML horrors of working with J2EE in the early days, that 3-byte acronym ending in "ML" initially subconsciously somewhat filled me with trepidation. However, as soon as I actually saw some QML, I could see these fears were unfounded (! :-)  And in fact I now love QML. It's clean, elegant, powerful, declarative and (OMG YAY!) you can even "%-bounce" on the braces in vim! :-) That said, the qtcreator IDE is extremely good, managing to provide just enough of what you want without requiring endless additional configuration.

But it doesn't stop there. The Design Team have done some incredible work in creating the Ubuntu SDK components: not only do they look fantastic (if you have the ubuntu-ui-toolkit-examples package installed, try running /usr/lib/ubuntu-ui-toolkit/demos/launch_componentshowcase), they are also extremely flexible and powerful.

As Rick has mentioned, it does take a while to grok the "QML-ish" way of doing things. And if like me you spend most of your time writing in imperative languages, initially you just think "all this QML is wonderful, but where do I actually put the code?". But then you have the epiphany moment when you realise you're already writing "the code" - in many cases, you don't need anything beyond the declarative QML itself.

I Need an Itch to Scratch

The only real way to learn a new language is to use it. But what to do? I wanted to code something simple and fun, like a game. There are already few games on the Collections page so I needed to think of a really simple one that is also fun to play. How about a game that even children can appreciate? Of course - Noughts and Crosses (aka tic-tac-toe)!
Note that the code is pretty rudimentary right now, but it's just about usable ;-)


This is a simple game so we only need a few objects: Cell, Game and MainView.

The MainView is the container for the application and includes a Page and the actual Game object. The only property we specify for the game is the boardSize of 3 giving us a 3x3 board. Technically, we don't actually even need to specify this since -- as we're about to see -- 3x3 is the default board size anyway. So, the Game object could be specified minimally as "Game {}". However, I've left it specified as a reminder to myself that ultimately I'd like to pass a variable to allow the board size to be specified at game creation time.

Here is a slightly simplified version of the MainView (noughts-and-crosses.qml):

import QtQuick 2.0
import Ubuntu.Components 0.1

MainView {
    Page {
        title: "Noughts and Crosses"

        id: page

        Game {
            // change this to whatever value you want for an NxN-sized board
            boardSize: 3

The Game object is a Column and comprises a Label, to show some text relating to the game, and a Grid to actually represent the game. There is some magic going on in the grid as it uses the very cool Repeater object to make laying out the grid easy: for a 3x3 board it creates 9 Cell objects and packs them into the grid. Here's a cut-down version of the Game object:

Column {

    property alias boardSize: gameGrid.boardSize

    Label {
        id: text
        text: "Noughts goes first"

    Grid {
        id: gameGrid

        // Default to a 3x3 board (we only support square boards).
        property real boardSize: 3

        // toggled between "O" and "X". The value specified below denotes
        // which side goes first.
        property string player: "O"

        columns: boardSize
        rows: boardSize

        // layout the appropriate number of cells for the board size
        Repeater {
            id: gridRepeater
            model: boardSize * boardSize

            Cell {
                width: 100
                height: width

Note the property alias for boardSize in the Column object - it exposes a boardSize variable which is just a way to access the real variable of the same name within the Grid object. Note too that we tell the Grid object its dimensions by setting its columns and rows properties.

The Game object also contains a chunk of Javascript in the form of the checkForWin() function to determine whether a move resulted in the game being won.

The Cell object is the most interesting object. A Cell represents an individual location on the board. It is constructed from a Rectangle and comprises a Text value. The text value is either a middle-dot (to denote the cell has not yet been selected), a "O" or a "X". It also includes a MouseArea that specifies the new cell state to apply when the cell is clicked. Initially, the state is middle-dot but when the cell is clicked, the state is changed to the value of the parent (Game) objects player property. The Cell object specifies 3 states to represent every possible value a Cell can display. What's neat here is that changing the cells state also toggles the parent (Game) objects player property which allows the game to proceed with each player taking a turn. Clicking a cell also calls the checkForWin()function to determine if a particular turn results in the game being won. Here's the complete Cell object:

Rectangle {
    id: cell
    state: gameGrid.defaultText

    property alias textColor: cellText.color

    Text {
        id: cellText
        text: parent.state
        color: "silver"
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter
        font.pointSize: 48

    states: [
        State {
            name: cell.parent.defaultText
            PropertyChanges { target: gameGrid; player: "" }
        State {
            name: "O"
            PropertyChanges { target: gameGrid; player: cell.state }
        State {
            name: "X"
            PropertyChanges { target: gameGrid; player: cell.state }

    // when clicked,
    MouseArea {
        anchors.fill: parent
        onClicked: {
            cell.state = (gameGrid.player == "O" ? "X" : "O");
            gameGrid.numberTurns += 1

Winning Algorithm

The approach I've taken is very simplistic: just scan each row, column and diagonal looking for a winning run. This isn't particularly efficient (we're scanning the board multiple times) but that's not a problem for small board sizes. However, it has two fairly compelling attributes:

  • It's simple to understand
  • It works for arbitrary-sized boards.

My favourite alternative algorithm is to make use of the properties of Magic Squares. Using these, you can scan the board a single time to determine if a player has one. This is achieved by determining if a cell has been selected by a player and if so incrementing their counter based on the magic square value for that index. For a 3x3 board, if a players total equals 15, they win!


So, what does it look like at this early beta stage...?

Start of a new game:

We have a winner!

Another winner on a 7x7 board (the person playing crosses needs more practice me thinks :-):

What's Next

  • The javascript code is currently horrid and needs to be refactored with dynamite.
  • Add ability to play "the computer".
  • Config option to allow variable-sided playing grids.
  • Once the game is stopped, we need to disallow further board clicks.
  • Leverage more QML facilities to simplify the code further.
  • Visual improvements (animation for a winning run maybe?)
  • Ability to change player that starts.
  • Score-keeping and "best of 'n' games " support (particularly useful when the kids beat you repeatedly ;-)
  • Menu to start new game.
The code is on github, so get forking!

In Conclusion

My "clean-room" implementation is far from perfect at the moment, but it's been a fantastic learning exercise so far and a lot of fun!

There are of course other QML noughts-and-crosses games out there. They come with varying licenses, some use C++ for the game logic, and most -- if not all -- are hard-coded to produce a 3x3 board only. Additionally, they generally use graphical representations for the noughts and crosses whereas here, I'm just using styled text. If you're interested, compare my github code with, for example, the Qt version to see the different approaches taken:

See Also