Our thoughts, knowledge, insights and opinions

Event-sourced game implementation example - Part 2/3: It's time to play - building web application

Welcome to the 2nd part of event-sourced game post series! In case you haven’t yet read previous part, I highly recommend reading it before.

Today we’ll focus on the frontend server part, the one that’ll be responsible for handling user interface interactions as well as backend server communication.

What do we have so far?

Quick recap of what has been done so far in part 1:

  • we’ve implemented a backend server that lets us play games using its REST API
  • we’ve been able to peek at generated game events in RabbitMQ console

Now it’s time to create an UI that’ll seamlessly combine the two to create decent user experience. Here’s how it will look like:

Demo

For this, we’ll use:

  • Play! Framework as our frontend server
  • WebSocket for realtime browser <-> frontend server communication
  • Reactive rabbit to receive game events from RabbitMQ
  • AngularJS on the UI side

The action flow from UI point of view will be as follows:

  • user creates new game (the command is sent)
  • the game is created (the response is received)
  • UI binds itself to events from newly created game (websocket connection is created)
  • user chooses players count and starts the game (the command is sent)
  • GameStarted event is received through websocket connection, the UI is updated
  • user chooses the player and rolls the dice (the command is sent)
  • DiceRolled events is received, the UI is updated

Looking at these, our Play! server will need to handle:

  • routes to execute commands
  • websocket route to receive events from given game

Controllers

First, let’s add these routes to our Play! application:

[conf/routes]

POST ones are for commands and the GET route is for websocket connection. Let’s take a look at the implementation.

Commands routes:

[MainController.scala]

Nothing special here, commands are just forwarded to our backend server (with some additional responses mapping).

Websocket route is a little bit more complex:

[MainController.scala]

acceptWithActor takes two type parameters: one for incoming messages (it’s just a String, since we don’t send anything to the server anyway) and another for outgoing messages, which are GameEvents.

[GameEvent.scala]

To make it work that way we need to tell Play! how to actually send GameEvent through WebSocket. It’s done by bringing implicit FrameFormatter[GameEvent] to the scope. We’ll format GameEvents as JSON and use FrameFormatter.jsonFrame which Play! provides:

[MainController.scala]

What’s next in acceptWithActor is a method that takes a HTTP request and an ActorRef out (which is used to send messages from server to client) and returns Props to create WebSocket connection handling Actor. We’re telling it to create one WebsocketEventPublisher for every WebSocket connection, we also pass out reference to it, which it can later use to send messages through the connection.

Receiving and passing events

Let’s have a closer look at WebsocketEventPublisher.

[WebsocketEventPublisher.scala]

What we do, when the actor starts, is create a new queue and bind it to the events from given game. It’s the last parameter in queueBind - arguments which says “hey, I want to receive only events from the game with id == gameId”.

Once the queue is bound, we create a Source out of it, which we attach Sink to. Our sink is an EventSubscriber actor, which will receive every incoming event (or, at this point, rather a message that represents an event).

[EventSubscriber.scala]

Once it receives an event, it’ll pass it back to WebsocketEventPublisher (that’s why we pass self reference to its props). WebsocketEventPublisher will pass it further, to out reference (which will use FrameFormatter to serialize the message and send it through WebSocket connection).

[WebsocketEventPublisher.scala]

requestStrategy in EventSubscriber tells streams implementations how many more messages the actor wants to receive.

Here it’s implemented to always be at least 1, meaning we want to receive as much messages as there are. It may not however be always appropriate elsewhere. I don’t want to focus too much on back pressure in this post, so we’ll just stick with this.

Those watchful may say that it doesn’t look good to pass these rather backend-side events directly to the browser. It’s true, usually some additional processing/validation would be added before passing them to WebSocket, but it’s not necassary in our simple application.

Frontend part

Now that we have our backend stuff ready, lets see how can we use it on the frontend.

Services

Let’s start with two Angular services:

  • one for sending commands (create game, start game, roll the dice)
  • and another for susbcribing to events for a given game (using our WebSocket endpoint)

Here’s how they both look like:

[services]

There’s really nothing special here, I won’t even comment the command part - these are just http POSTs.

On the event side, we simply broadcast every incoming message, were the name parameter of $broadcast contains an event type so that we can later easily listen for particular game event.

Controllers

User at given time can see one of three pages (stored in rootScope):

[app.js]

This variable determines currently shown content (and used controller) with ng-switch:

[index.scala.html]

Each controller handles different set of user actions, let’s examine them:

The first one is CreateGameController:

[create_game_controller.js]

It’s really simple. It just POSTs to create a new game and upon success connects the event service to the event stream, changing currently shown page to choose_players with corresponding StartGameController:

[start_game_controller.js]

Which gives user a possibility to specify players count and handles “Start game” button click. It also shows a popover in case of error.

If there were no errors and the game was started, GameStarted event is handled in the main application:

[app.js]

The game state is stored in the game variable in rootScope and is updated according to the events received:

[app.js]

Finally, we have GameController that handles user inputs when the game is running:

[game_controller.js]

It also listens to game events to update the view accordingly. When the game is finished the “Play Again” button is visible which, upon clicking, redirects the user back to the “create” view.

You can find all the related views in index.scala.html file.

Summary

That’s it for the 2nd part. Our game is ready :)

We can now consume events from RabbitMQ and send commands to our backend server. Both functionalities are seamlessly integrated in our modest interface and the distincion is invisible for the user. But the fun is not over yet. In the 3rd part we’ll see how easy it is to grab some statistics from the games played and expose collected data.

As usual, full source code is available on GitHub.

Other parts:

You like this post? Want to stay updated? Follow us on Twitter or subscribe to our Feed.