• real time view of the opponent’s actions isn’t working at all, probably due to the increased delay in communication with the server;
• the game is very heavy on the CPU (around 90% on my Core 2 Duo when moving letters around);
• animations are kinda messy and not always executed at the right times;
• overall it is quite unstable, crashed often during tests (although reloading worked very well and never lost a move).

On the design side, I found the game to be too plain and, honestly, quite boring. I concentrated much of my programming effort in making the game board work and less on creating an immersive game experience, which I think is what Calliope lacks right now. Maybe this can be corrected by adding more information on what is going on than just the turn number and the name of the user playing; anyway, I’ll have to look into this carefully and maybe sketch some mockups.

To counterbalance the technical problems I’m afraid I will have to do some radical changes in the implementation. To achieve better responsiveness I’ll have a look at how other real time applications handle it (I’m having a look for example at long-polling mechanisms like Comet); in order to decrease CPU usage and gain better control on animations I’ll have to leave SVG and Raphael and turn to HTML5 Canvas, maybe by using some javascript game development framework. Last but not least: instability, I will have to fight it with better design and thorough testing.

The road ahead is longer than expected, but I certainly still want to pull this off.

• Fix some bugs in the board related to z-order and overlapping;
• Redesign the game-choosing screen; (see screenshot below)
• Provide a button to create a new game;
• Provide a simple registration interface for new users.

I am going to document every step forward in this post, adding short comments and striking off items as soon as I implement them.

Update 12/6/2011 - Online preview of Calliope has been delayed after a set of private tests gave not-so-encouraging results, read here for more.

Update 9/5/2011 - The new front screen of the application:
In a future version, the icons on the left will depict the current progress of the game.

Would you like to join development? Let me know!

Game (aka Local) data source (..continues from Part II)

Before going further, let’s recap what data the application has to deal with during its operations:

1. The last turn of the selected game, along with its letters’ configuration (service */turns/{number});
2. The list of pivotal actions belonging to the game and to its last turn (service */actions?pivotOnly&turn={turnNumber});
3. Periodically, the list of new actions to perform (service */actions?afterAction={actionId}).

where * stands for /me/games/{id}.

The first item – related to the current turn and letters – has been pointed out in Part II. In this part I’m going to dig deeper into the last two points.

The second and third point of the list are threatened in a uniform way, with the usage of a remote query.

Given the information above, remote queries where the choice to go for action retrieval. I started by declaring two static methods in Calliope.Action to act as helpers in creating the queries themself; each method supporting one of the points above:

Calliope.Action.query_PIVOT = function(turnNumber) {
  return SC.Query.remote(Calliope.Action, {pivotOnly: YES, turn: turnNumber});
};
Calliope.Action.query_LIVE = function(lastActionId) {
  return SC.Query.remote(Calliope.Action, {afterAction: lastActionId});
};

The creation of queries is really straightforward, you can fill an object with all the information you need in the fetching phase and pass it as the second argument of SC.Query.remote. In the first example I’m passing in the flag pivotOnly and the number of the turn to retrieve (case 1 above); in the other example I’m passing just the id of the last seen action as afterAction (case 2 above).

Let’s now have a look at how these queries are used inside the application. The usage is really simple:

(case 1)
var actions = store.find(Calliope.Action.query_PIVOT(currentGame.get("turnCount")))

(case 2)
var actions = store.find(Calliope.Action.query_LIVE(lastSeenActionId))

When the find method is issued, as stated above, Sproutcore invokes the fetch method in the data source, passing along the query that was issued. The implementation of that method must provide an explicit result for the query. Here is the implementation part relative to the queries on Action:

  fetch: function(store, query) {
    // check whether the query is a remote query on Calliope.Action
    if (query.get("isRemote") && query.get("recordType") === Calliope.Action) {
      // build the url with parameters afterAction, pivotOnly and afterAction
      var url = "/actions";
      var reqQuery = [];
      if (!SC.none(query.afterAction)) {
        reqQuery.pushObject("afterAction=%@".fmt(query.afterAction));
      }
      if (!SC.none(query.turn)) {
        reqQuery.pushObject("turn=%@".fmt(query.turn));
      }
      if (query.pivotOnly) {
        reqQuery.pushObject("pivotOnly");
      }
      if (reqQuery.length > 0) {
        url += "?" + reqQuery.join("&");
      }

      // issue the remote request
      Calliope.session.createRequest({
        address: this.getUrl(url)
      }).notify(this, this._didFetchActions, store, query)
      .send();
      return YES;
    }

    return NO;
  }

The method checks the query to see if it is remote and is relative to Calliope.Action, and then uses the parameters passed to the query (which, as you can notice, are accessible directly in query) in order to build the full url of the remote request. In the first case the url would look like this:

/actions?turn={query.turnNumber}&pivotOnly

whilst in the second case it would look like this:

/actions?afterAction={query.afterAction}

As seen in Part II, the url is then completed by calling getUrl (line 22), which prepends /me/games/{gameId} to it.

Each of the service calls above return a list of actions similar to the following one (more details here):

[
  {
    "type":"letter_drag_end",
    "attributes":"{ ... }",
    "time":"2011-04-08 09:05:00",
    "t":"1302246300040",
    "actionId":24456,
    "pivot":true,
    "player":1
  },
  ...
]

This data is then passed to the notify method _didFetchActions which is in charge of loading it into the store as a series of Calliope.Actions, and of explicitly setting the results of the query. Here is the implementation:

  _didFetchActions: function(response, store, query) {
    var body = this._getResponseBody(response, store, query);
    if (!SC.none(body)) {
      // load the actions into the store to retrieve the store keys
      var storeKeys = store.loadRecords(Calliope.Action, body);
      // load query results
      store.loadQueryResults(query, storeKeys);
    }
  }

As you can see there is nothing complicated here. The two steps described above are handled literally by two lines of code. The first call to loadRecords loads the server data into the store as Calliope.Action instances and receives, as a result, the list of the associated store keys; the second call to loadQueryResults does nothing but explicitly setting the results for the query, which finally gets accessible to the caller of find.

As already pointed out in Part II, the call to the server happens asynchronously, so the list of actions retrieved that way isn’t already available at the end of the call to find. What is returned is an instance of SC.RecordArray with an empty storeKeys variable. By observing the array for changes you can be notified when data is ready to be used; here is an example on how to do it:

Calliope.SomeObject = SC.Object.extend({
  _actionsArray: null,
  loadActions: function() {
    this._actionsArray = store.find(Calliope.Action.query_LINE(15));
  },
  _actionsArrayDidChange() {
    if (!SC.none(this._actionsArray.storeKeys)) {
      // DO STUFF
    }
  }.observes("*_actionsArray.[]")
});

Last note

This is the end of my first article about the basics of Sproutcore data sources. Hope you liked it and if you did – or didn’t – please drop a line.

There is more about data sources I would have liked to share, in particular the usage of chain to create nested data stores, and the handling of data saving; I’m planning a series of articles about those subjects as well, if you are interested just let me know.

There is also one open point I have not faced yet in the application but I will eventually have to: what’s the right way of refreshing the data store for “global” data like games and players? (for example in order to know that a new game has been created, or a new player has registered).

« Go to Part II
« Go back to the index

Game (aka Local) data source

In the local scenario the user has logged in, has selected one of its open games (which list if handled by the global data source) and is taken to the board in order to be able to play the game. In this scenario, the application must load the current game state (that is, the position of all the letters in the game), present it to the user and update it continuously, replicating the actions of the other players.

Notice that this task is more complicated, and cannot be solved using the “load-all-retrieve-by-id” approach used previously: the data involved is potentially quite big (imagine a game with a hundred turns, for example) and could take more than a while to load; actions are pumped in continuously, and as such cannot be loaded once and for all, but must be refreshed constantly.

In order to reduce bandwidth usage and loading times, here is what the application has to load in detail:

1. The last turn of the selected game, along with its letters’ configuration (service */turns/{number});
2. The list of pivotal actions belonging to the game and to its last turn (service */actions?pivotOnly&turn={turnNumber});
3. Periodically, the list of new actions to perform (service */actions?afterAction={actionId}).

where * stands for /me/games/{id}.

Notice that in doing this, the application loads from the server only relevant data, not the whole dataset. In order to handle this scenario effectively, in a modular way – and given that each and every service call above includes a game id – I decided to write separate data source, that I called (surprisingly) GameDataSource.

Creation

An instance of GameDataSource is created as soon as a game id is available, that is, when the user has selected the game to play. The new data source is then cascaded to the global one and assigned to the data store. This way, every request issed to the data store is forwarded to the game data source first, and to the global data source as a second try.

In order to build such a structure, the following code is used:

Calliope.store.cascade(Calliope.GameDataSource.create({
    gameId: selectedGameId
  }), Calliope.store.get("dataSource"));

Implementation

With reference to the three above points let’s have a look at what requests are issued to the data store and how they’re handled by the GameDataSource.

(1) The last turn of the selected game, along with its letters’ configuration

The application already has the number of the last turn of the selected game: it is found in the turnCount field of the game model itself. So, loading in a specified turn is only a matter of issuing a direct find by id:

store.find(Calliope.Turn, currentGame.get("turnCount"));

This call is similar to the ones used for the global portion of data, but since in this case we don’t preload records through a query, the data source cannot contain the requested record. All this translates to a call to the retrieveRecord method in the data source. The retrieveRecord method is called every time the data source must load a record by id (which can happen by a direct call as above, or by the automatic following of a relationship) and it doesn’t have a copy of that record already available. Here is the implementation of retrieveRecord:

  retrieveRecord: function(store, storeKey, id) {
    // retrieve the id from the storeKey
    if (SC.none(id)) {
      id = SC.Store.idFor(storeKey);
    }
    // retrieve the record type
    var recordType = store.recordTypeFor(storeKey);
    if (Calliope.Turn === recordType) {
      Calliope.session.createRequest({
        address: this.getUrl("/turns/%@".fmt(id))
      })
      .notify(this, this._retrieveRecordDidComplete, recordType, store, storeKey)
      .send();
      return YES;
    }
    return sc_super();
  }

The implementation is pretty straightforward: if the find request is related to a turn (Calliope.Turn record type), a GET is sent to the URL /turns/{id}, where {id} is the parameter passed in the call to find, that is: the turn number. The method getUrl is a simple utility method that prepends /me/games/{gameId} to the passed string; in the example above, the full URL becomes: /me/games/{gameId}/turns/{id}.
The service call above returns the turn information along with its letters (details here), in the following form:

{
  "time":"2011-03-11 21:56:44",
  "ended":false,
  "player":1,
  "turnNumber":1,
  "letters": [
    { "id":10369, "lid":1, "l":"A", "c":"s" },
    { "id":10370, "lid":2, "l":"A", "c":"s" },
    ...
  ]
}

This data is passed to the notify method _retrieveRecordDidComplete, which is in charge of decoding it and loading it into the store as one Calliope.Turn entity and a number of related Calliope.TurnLetters. Here is the code:

  _retrieveRecordDidComplete: function(response, recordType, store, storeKey) {
    var body = this._getResponseBody(response, storeKey);
    if (!SC.none(body)) {
      if (recordType === Calliope.Turn) {
        // load turn letters
        var letters = body.letters;
        // replace body letters with just the ids
        body.letters = letters.map(function(letterDescr) {
          return letterDescr.id;
        });
        // fill letters with the turn reference
        for (var i = 0; i < letters.length; i++) {
          letters[i].turn = body.turnNumber;
        }
        // load letters into the store
        store.loadRecords(Calliope.TurnLetter, letters);
      }
      // load record into the store
      store.loadRecord(recordType, body, body.turnNumber);
    }
  }

Sproutcore expects related records to be expressed as a list of ids; the letters field of the data structure above is not in the expected format, because it contains the whole objects instead of just the ids. What the _retrieveRecordDidComplete essentially does is extracting the list of letters from the original data structure, pre-loading them into the store with a call to loadRecords and then replacing them into the original structure with the list of the ids only. After doing that, the data structure is then in the format that Sproutcore expects, and can be loaded directly into a record of type Calliope.Turn. And this is everything that must be done in order to load the turn.

Notice that the call to the server takes place asynchronously, so the turn record cannot be returned immediately after the call to the initial find. What is instead returned is an empty SC.Record in state BUSY_LOADING, that you can observe in order to know when the data is ready to be used, like this:

  var turn = this.get("store").find(Calliope.Turn, currentGame.get("turnCount"));
  // add a status observer to the record
  turn.addObserver('status', this, function() {
    if (turn.get('status') === SC.Record.READY_CLEAN) {
      // remove the status observer
      turn.removeObserver('status', this, arguments.callee);
      // DO STUFF
    }
  });

End of Part II

If you read this far please take the time to leave a comment to let me know what you liked, what you didn’t, and what you would do differently. Thank you.

« Go back to the index

Here comes the first screenshot:

You can already notice a couple differences here from the first screenshot:

• Buttons are labelled in English;
• The graphics of the letters has changed slightly;
• Rack has been redesigned too, and own letters have been highlighted in dark gray.

There are also some new elements: first of all there is a simple label on the top of the screen, indicating what the turn number is and what the current player is; there is also a green frame surrounding the word “preview”. That, as you can easily guess, means that the word is correct.

Now, if I move the letter “S” from my rack up into the board…

…the letter fades a little, and a blue marker appears, showing where the letter will be placed on release of the mouse button. Say I want to put the word “song” in place using the trailing “g” of “preparing” and the letters on my rack; after placing “so”, the board would look like this:

You got it right: a red highlight means the word is wrong. Placing the “N” in the right spot fixes it:

But you are not playing alone. Suppose now to hit the “End Turn” button on the top right corner of the screen. Here is what happens:

1. The control passes to your opponent (or the next player, if playing in more than two);
2. Your black letters on the board turn white, becoming part of it;
3. You are locked out of the board: you cannot drag letters on it;
4. You begin to see your opponent actions happening on the board, like you were doing them yourself.

After a little dragging and dropping, here is what your opponent come up with:

Notice here that your opponent’s letters are painted with a different shade of gray, so that you can distinguish them from your own and from what’s was already on the board at the beginning of the turn.

The image above was the last of the series, did you like them? Leave a comment!

In this post I’m covering the problems I encountered while implementing data access in the client-side of Calliope using Sproutcore data sources. If you are starting now to have a look at Sproutcore way of handling data, I suggest you have a look at these pages in the official documentation:

• Guide about records
• Guide about using data sources
• Wiki page about data stores (a little older, but contains more details about certain subjects)

The official documentation is well written, but it uses very simplistic examples that fall short in real word applications (even a simple one like Calliope) and it is missing the “big picture” of how things work. These, I think, are the main reasons why I – and I am not the only one – had such a hard time figuring out how to use the data store effectively.

With this post I hope to fill some of the gaps of the official documentation, by showing what problems I faced and how I resolved them.

For Calliope I have defined 5 Sproutcore models:

• Player
• Game
• Turn
• TurnLetter
• Action

Since definitions are really simple I won’t paste them here, for a general description of the fields involved have a look at the data model post.

I think at the models as they were divided into two kinds: globals and locals. I put Player and Game into the “globals” definition, since they are located at the root level – that is, they have no parent model. For games this is not really precise: if you read the post about the design of services you could object that games are children of players; this is essentially true, but since a player can only see his/her games I will threat them as global entities.

Turn, TurnLetter and Action are instead viewed as local entities, with a game as the parent.

This logical differentiation between global and local entities is represented in the program in the structure of the data sources: I coded a first data source to feed the data store with global data, and a second one – cascaded to the first – to handle local data related to a specified game. In the following I am going to cover the design of both data sources and how they are used to support the execution of the game.

Global data source

The global data source is implemented in a very simple way. There is essentially one local query defined for each global entity; those queries are defined as follows:

Calliope.Player.ALL_PLAYERS = SC.Query.local(Calliope.Player);
Calliope.Game.ALL_GAMES = SC.Query.local(Calliope.Game);

These queries are used to retrieve the whole list of players and games from the server, by issuing a find on the data store, like this:

Calliope.store.find(Calliope.Player.ALL_PLAYERS);

When this call is done for the first time in the life of the application, Sproutcore automatically calls the method fetch of the data source associated with the store (the global data source), passing in the query. That method essentially does a check on the query: if it matches one of the two defined above it calls the remote service for games (or players), saving the result into the store. The code related to the players is:

Calliope.DataSource = SC.DataSource.extend({
  fetch: function(store, query) {
    if (Calliope.Player.ALL_PLAYERS === query) {
      Calliope.session.createRequest({
        address: "/players"
      }).notify(this, this._didFetchAllPlayers, query, store)
      .send();
    }
    return YES;
  }

  _didFetchAllPlayers: function(response, query, store) {
    var body = undefined;
    if (SC.ok(response)) {
      body = response.get("body");
    }
    if (SC.ok(response) && SC.ok(body)) {
      // load the players into the store
      store.loadRecords(Calliope.Player, body);
      // notify store that we handled the fetch
      store.dataSourceDidFetchQuery(query);
    } else {
      // handle error case
      store.dataSourceDidErrorQuery(query, response);
    }
  }
});

Games case is handled in a very similar way.

So, the call to find loads in the store all the records of players and games. After doing that, issuing a find to the store using a record type and id let us retrieve instantly the record we are looking for. Here is a simple example (assuming that player “foo” has id 1):

var playerFoo = Calliope.store.find(Calliope.Player, 1);

And this is about everything you have to know about my usage of global stores: the calls to find on the queries of player and games are performed as long as the user logs in, and then the retrieved data is used throughout the rest of the application.

End of Part I

If you read this far please take the time to leave a comment to let me know what you liked, what you didn’t, and what you would do differently. Thank you.

Go to Part II »

« Go back to the index

In this post I’m going to describe how the web services forming the backend of Calliope have been designed and built. I didn’t concentrate much on designing them because I was eager to reach a visual result, so I know they’re not the best possible; I’m open to criticism and I hope with your help to improve the design.

Introduction

At the time I was beginning to develop Calliope I didn’t even know what RESTful was meaning, but there was quite a big hype around the word, so I decided to do some reading and figure out if that was the way to go. The book I chose for my research was RESTful Web Services by Richardson and Ruby (Kindle Edition of course).

After the reading it was clear that RESTful services where the right choice for my kind of application, mainly because of the promised lightness, which is well suited to reduce bandwidth occupation and, as a consequence, response time.
After a little thinking I also decided that a good format for the services would be JSON: JSON is well understood by JavaScript and PHP, is lightweight and expressive enough for almost anything. JSON has no built-in way to connect services together (like writing links in XHTML), but this shouldn’t be a problem for my application.
Last but not least, I decided to build my services as completely stateless in order to exploit all the advantages that statelessness brings with it.

To summarize, here are my choices:

• be RESTful;
• use JSON as the format;
• be stateless.

The Services

RESTful services means thinking at your system as a bunch of resources, deciding one (or more) URI for each resource, and deciding how to represent it. With reference to the data model I described earlier, the main resources I can identify in Calliope are:

• players;
• games;
• turns;
• letters;
• actions.

Every player can have a number of open games, every game is made of turns and actions. Actions can be linked either only to a game or to a game and specific turn; letters are linked to turns in order to implement the snapshot feature. As an additional information, not everyone can see every game: one can only see the games he or she is taking (or has taken) part in.
Every resource is identified in the data model by a numeric id; that id is the natural choice for addressing the resource through an URI but, as we will see later – is not always the best one.

Players

Let’s talk about players first. Players are the simplest resource of the group, and I decided to model the service as follows:

GET    /players                  retrieve list of players
POST   /players                  create a new player

GET    /players/{name}           retrieve info on player {name}
PUT    /players/{name}           edit info of player {name}
DELETE /players/{name}           delete player {name} 

GET    /players/{name}/avatar    retrieve avatar of player {name}
PUT    /players/{name}/avatar    edit avatar of player {name}
DELETE /players/{name}/avatar    delete avatar of player {name}

Explanation for this is quite obvious: by issuing a GET on /players one can retrieve the complete list of players registered to the game (right now there is no restriction, in the future the results could be restricted to only the “friends” of the current user, or such). Here is an example of the response in JSON format:

[
  {
    "name":"barfoo",
    "displayName":"Foo",
    "playerId":2
  },
  {
    "name":"foobar",
    "displayName":"Bar",
    "playerId":1
  }
]

Once you have the list you can then retrieve detailed information on a certain player (say its username is “foobar”) by building an URI with the second rule above (in the example: /players/foobar). The response will look like a single object of the list response, with additional information (maybe about the user’s profile, or game stats) added to it; at the current stage of development a request of a single player produces exactly the same object as the list request.
Anyway, by having the player username, you can also retrieve its avatar. Retrieving it is as simple as issuing a GET on /players/foobar/avatar. As a representation of the avatar an image is returned, it can be in one of the common formats of the internet, and could also be in a specific size.

In the previous paragraphs I only described the read part of services; there is also a write part, involving the other http methods:

• issuing a POST on /players let you creating a new player (“posting” a new player);
• issuing a PUT or a DELETE on /players/foobar (or on the avatar) let you respectively edit or delete the specified item.

In order to make one’s own stuff at hand, I decided to alias the resource /players/{my_username} with the simpler /me. Methods allowed, formats and semantics remain the same as stated above.

Games

Since there is no such thing as a “public” game, I decided to put all the games stuff under the /me resource, as such:

GET    /me/games                 retrieve list of my games
POST   /me/games                 create a new game
GET    /me/games/{id}            retrieve info on game {id} 
PUT    /me/games/{id}            edit info of game {id}

These services are similar to the one for players, except for the fact that the DELETE method is not supported, and that the numeric id is used for games whilst the username was used for players. I decided not to allow the deletion of games but only the hiding/archiving of them (action, this, that can be performed through a PUT on the game).

The representation of the game is quite simple, here is an example:

{
  "time":"2011-03-11 21:56:44",
  "ended":false,
  "gameId":10,
  "turnCount":19,
  "players": [ 1, 2 ]
}

As you can see there is the game creation time, a flag stating whether the game has ended or not, the id of the game (which is meaningful only when retrieving a list of games), the number of turns (which come in handy later) and an ordered array of player ids taking part into the game.

Turns and Letters

Turns and letters are closely linked, and since generally there is no reason one would need a single letter I decided to threat them together, so that letters are retrieved along when you ask for a specified turn. Moreover, I thought that the best way to address a turn inside a game is by its natural order number (first turn is turn 1, secondi is turn 2 and so on). This makes for a natural, compact and simple notation. Here are the routes (assume that * is replaced by /me/games/{id}):

GET    */turns            retrieve list of turns of the game
POST   */turns            create a new turn
GET    */turns/{#}        retrieve info and letters for turn {#}

A turn is viewed as a static snapshot of the game state and as such, once created, is immutable. For such reason neither PUT nor DELETE methods are allowed on it.
When retrieving the list of turns only a brief information is returned about each turn, for example:

{
  "time":"2011-03-11 21:56:44",
  "ended":false,
  "player":1,
  "turnNumber":1
}

This doesn’t add much to the information given by retrieving the game itself, anyway this method is present for coherence with the others. What is instead interesting is that by retrieving a single turn one also receives the complete list of the letters forming the game snapshot at the beginning of the retrieved turn. Letters are retrieved in a “compressed” form, in order to occupy the less space possible, here is an example:

{
  "time":"2011-03-11 21:56:44",
  "ended":false,
  "player":1,
  "turnNumber":1,
  "letters": [
    { "id":10369, "lid":1, "l":"A", "c":"s" },
    { "id":10370, "lid":2, "l":"A", "c":"s" },
    ...
  ]
}

Where:

• id is the letter data model identifier;
• lid is the letter id in the current game;
• l is the letter string;
• c is the letter container (b for board, r for rack, s for sack).

In order to create a new turn issuing a POST on */turns one has to provide the full snapshot of the game in the form of letters and their position, in the same format as the one described above. You can of course start a new turn only if you’re playing in the current one.

Actions

As I said above, actions can be linked to a game alone (and is the case of chat messages), or to a game and a specified turn. In order to account for the two possibilities I defined these 4 routes (as before, assume that * is replaced by /me/games/{id}):

GET    */actions            retrieve list of actions of the game
POST   */actions            add a new action to the game
GET    */turns/{#}/actions  retrieve list of actions of the turn {#}
POST   */turns/{#}/actions  add a new action to the turn {#}

So, POSTing to */actions means creating a “global” game action, as opposed to POSTing to */turns/{#}/actions, which means posting a new action relative to the specified turn only.

By common sense and coherence with the other routes, GETting */actions should return only global actions, whilst GETting */turns/{#}/actions should return only local actions. But this choice is not ideal when seeing the game as an ordered stream of actions (this kind of view was introduced in the data model article, and is essential to the reconstruction of game state through actions). In order to effectively support this kind of view of the game I decided to make local turn actions also available via the “global” */actions. In such a way, when one issues a GET on */actions, the response will contain not only the global actions of the game, but also the local actions linked to a turn.
Moreover, since the number of actions can become quite large, there is a need for filtering and selection of the results. As of now, I defined these additional parameters for */actions:

• afterAction={actionId} – tells the service to return only actions with an id larger that the one specified in {actionId}, this is useful during online actions re-execution, in order to receive only the new actions (remember that the services are stateless, and so there is no way for the server to know which actions are already been received by the client);
• pivotOnly – tells the service to retrieve only pivotal actions, in order to speedup the re-execution of a large set of actions;
• turn={turnNumber} – tells the service to retrieve only those actions belonging to the specified turn.

A typical call sequence for this service – which is the core of the whole application – looks like:

1. GET */actions?turn={lastTurn}&pivotOnly
2. GET */actions?afterAction={lastSeenAction1}
3. GET */actions?afterAction={lastSeenAction2}
4. …

Where {lastTurn} is the number of the last turn of the game, as received getting information on the game itself; {lastSeenAction1} and {lastSeenAction2} are the ids of the last action received by the client respectively after call 1 and after call 2.

The representation of a single action looks like this:

{
  "type":"letter_drag_end",
  "attributes":"{ ... }",
  "time":"2011-04-08 09:05:00",
  "t":"1302246300040",
  "actionId":24456,
  "pivot":true,
  "player":1
}

As you can see this provides for the actionId, that can be used to set the value of the parameter afterAction.

Reference

Here is the complete list of the designed services. The ones in italic are yet to be implemented, whilst the others are more or less stable.

GET /players                  retrieve list of players
POST /players create a new player

GET /players/{name}           retrieve info on player {name}
PUT /players/{name} edit info of player {name}
DELETE /players/{name} delete player {name} 
GET /players/{name}/avatar    retrieve avatar of player {name}
PUT /players/{name}/avatar edit avatar of player {name}
DELETE /players/{name}/avatar delete avatar of player {name}

GET /me/games                 retrieve list of my games
POST /me/games                create a new game
GET /me/games/{id}            retrieve info on game {id} 
PUT /me/games/{id} edit info of game {id}

and with * = /me/games/{id}:

GET */turns               retrieve list of turns of the game
POST */turns              create a new turn
GET */turns/{#}           retrieve info and letters for turn {#}

GET */actions             retrieve list of actions of the game
POST */actions            add a new action to the game
GET */turns/{#}/actions   retrieve list of actions of the turn {#}
POST */turns/{#}/actions  add a new action to the turn {#}

Last Note

If you read this far please take the time to comment on this one, to let me know what you liked of the design, what you didn’t, and what you would do differently. Thank you.

« Go back to the index

Click here to see the demo

The code of the demo is open source and you can find it on github at this address, you can use it as a brief sample code for the library while I put up something more detailed.

RaphaelWrapper basically gives access to Raphael functions through a Sproutcore-friendly view called CanvasView. I’m using this framework as the basis for my bigger project Calliope, but since it is a completely independent component of the application I thought it could have been useful to make it public.

In the next days I will publish an usage example, and hopefully a little online demo as well.

Understanding the game

The first step I took in building the data model for Calliope was trying to figure out how a game was structured, keeping in mind that a game is meant to be played in real time by different persons on different machines, and that the whole state of the game must be persisted in order for a player to be able to shut the game and go back to it anytime.

Obviously there are two or more players taking part in a game, and the game itself can be split into turns in which players interact. But what are the building blocks of a turn? During a turn a player can pick letters from the sack to put them on his/her rack, move letters around (between his/her rack and the board), chat with the opponents, and pass the turn. Each of these steps must be recorded by the system in the current player’s machine, in order to be reproducible on the other connected machines. I decided to threat the above steps all in the same way and to call them actions.

A fundamentally right choice would have been to forget the turns separation, and to model a game just by a single stream of actions. By following and re-executing the actions from start to end, the current game state could have always been reconstructed. Performance-wise anyway, that would have been an error. Imagine a very long game, build up of several turns: that would mean tons of actions (thousands, maybe), tons of actions to reproduce in order to be able to reconstruct the game’s state. In the scenario we are considering this is not acceptable.

In order to avoid an eccessive accumulation of actions I decided to introduce in the model the ability to take snapshots of the game’s state along the way, to allow for a snappier state reconstruction (that is, the state itself can be persisted at a given time, so that only the actions taken after the snapshot must be re-executed to reach the current game state). I thought that the best way to model the game’s state was by means of the letters involved: every game is played using 128 letter tiles; at the beginning all letters are in the sack and from then on – after each action of the game – they move:

• on the board, in a specific position (which can be modelled as a 2D point);
• on someone’s rack.

By saving the position of every letter in the game I can take an exact snapshot of the game’s state. From this point of view even actions can be rethought: every action – except from chat messages and turn passing, which are threatened apart – can be thought of as a movement of a letter from one location to another (from sack to rack, from rack to board, etc.).

Now that I have a way to represent snapshots I just have to decide when to take them. I decided to go for the simplest solution, and to take one snapshot per turn.

To summarize:

A game is split into turns and played by two or more players; every turn is associated with a snapshot – which contains the position of letters at the beginning of the turn itself – and a set of actions – which tell what happened in the turn after the initial snapshot. To reconstruct the current game’s state one has to:

1. fetch the last turn;
2. read the snapshot and position letters accordingly;
3. read the actions and re-execute them.

In a similar way, one can “travel” through the game starting from the first turn and reconstruct every single step that was taken.

The data model

After the game structure has been made clear, it was time to translate it to database tables. Here is an E/R showing the model:

The game entity is linked may-to-many to the players by a middle entity called game_player, which add the information of the play order (and other less important stuff). The relation between turn_letter and turn implements the snapshot feature seen in the description above: every turn has 128 associated turn_letters, specifying the location (attribute container) and ownership (attribute player_id) of every letter in the game, effectively saving the state of the game at the beginning of the turn.

The action entity has a reference to the turn it was executed in, as expected, and is also linked directly to the game.
The additional reference to the game has been added to account for what I call game-wide actions, that is: actions that are executed by a player during a game but are not related to any turn in particular. Chat messages are an example of game-wide actions.
In order to account  for the maximum possible flexibility, an action has been modelled using a type – that can be any string describing the kind of action – and an attributes field. The attributes field is a CLOB, in which the system can store additional information necessary for the re-execution of the action, in whatever format (at current state attributes are stored as JSON).
There is another additional field in action: the pivot flag. The pivot flag has been added in order to identify those actions that must absolutely be re-executed in order to properly reconstruct the game state; the identification of pivotal actions adds a little awareness to the system that can be useful in certain situations (e.g. if a game is reloaded while a turn was in progress a large set of actions must be re-executed, to boost performance the system can discard all non-pivotal actions and execute only relevant ones).

Just to give you a more concrete view on this stuff, here are the type of actions that I’ve defined:

• “message” – a chat message, attributes contains just the string that was typed;
• “letter_drag_*” – letter drag related actions; there’s an action type for the beginning of the drag, one for the movement of the letter while dragging, one for successful drop and one for unsuccessfull drop; attributes contains the identifier of the letter that was dragged, its initial location (before the drag) and the current one;
• “turn_end” – issued when a player passes his/her turn, there’s always an action of this kind at the end of every turn.

« Go back to the index