Back in May of this year, we did an episode on Cloud Cover focusing on project Orleans. Orleans is a project created by Microsoft Research that provides an easy way to build distributed high-scale computing applications. You can build these without having to spend months learning and understanding complex concurrency and scaling patterns which is always nice. If you’ve done .NET development and are familiar with the awesomeness of async / await, picking up project Orleans is very easy to do. Orleans does this using the actor model which I’ll talk more about in a minute. One of the other great things about Orleans is that it’s built from the ground-up with the cloud in mind. So getting it on to Azure is pretty easy to do.
TLDR: You can play the game here: http://adventureterre.cloudapp.net/
TLDR: You can check out the source code here.
One of the samples in the Orleans release is a simple text adventure game named, Adventure. This game is in the same style as Zork or Colossal Adventure which many people are familiar with (if you aren’t, you can actually play Colossal Adventure on AMC’s Halt and Catch Fire website!). The general idea is that everything is text based. Players read about their surroundings and then type in what they want to do. These text adventures, called Interactive Fiction, were some of the first computer games. I’ve been meaning to get back to doing some more game dev so a little over a month ago, I started on a small side project to make a text adventure game on top of Azure using the Orleans Framework. I started by combining the Adventure sample with the Azure sample for Orleans and got the basic Adventure game running on Azure. Before I go over the details of that, I should explain how Orleans works.
The actor model and Orleans
The actor model is a model for concurrent-computation set forth by Carl Hewitt in 1973. Under the actor model, the actor is the sole primitive. It handles both behavior and state. Actors interact with other actors and communicate via asynchronous messages delivered via system-generated proxies. Actors don’t contain other actors but may have a reference to them (though that reference is just used to send messages as opposed to having direct access). In Orleans, the actors are called Grains. So every actor in the system is it’s own Grain. In order to contain the grains, Orleans has Silos. As the developer, you don’t develop the silo as much as start a silo. The Orleans framework then knows how to make use of the silos to contain the grains. In addition, the “location” where the grains perform all of their actions is within the silo. When you need access to a grain, you don’t create a new instance using “new” but instead rely on a generated GrainFactory to get an activation for a grain. In this way, grains are never created nor destroyed. They are activated or deactivated as needed by the system. Additionally, grains handle their own state storage (with some work on your part in the Grain code) so persistence is transparent to the client making calls into the Grain. This all may sound a bit confusing but I’ll follow up this post with another explaining more about the architecture of Orleans and the sample I built so it will make more sense.
Azure and Orleans
When it comes to Orleans, Azure is a natural fit for deployment. Orleans includes a number of step-by-step tutorials which explain how to get started with Orleans. One of the most useful is one that explains cloud deployment. To deploy to Azure, you essentially map your application onto Worker and Web Roles inside of Azure Cloud Services. The Worker Role(s) run the Orleans Silos where all of your Grains’ functionality takes place. The Web Role(s) run the client code for your application whether it’s a web site or a web service. So the web code get’s access to your Grains and request them to perform whatever actions they need. Orleans is built around C# asynchronous programming so everything uses Async and Await. So every call you make against a grain is asynchronous and you await it from the client until you get the result. The great thing about this is that due to the Orleans framework, you get high-scalability and concurrency out of this approach without really needing to know more more than what I just described (there is more to know but I’ll get to that in future posts). You can optionally tie a GrainState to each Grain. When you do this, you can specify a Store where your grains’ state should be persisted. Orleans includes some built in storage providers that make storage super simple by just applying an annotation ([StorageProvider(ProviderName=”name”)]) on your Grain classes. For example, you can very easily start storing your grains’ state into Azure Table Storage by setting up your store, putting the connection string in your config files, and annotating the classes. Rather than assume when you want to persist data, Orleans leaves it to you to call State.WriteStateAsync(); in your Grain’s code whenever you want to store the state. Restoring the state is done automatically whenever you activate a grain that has been idle for too long. There have been a number of community contributions for storage providers but you can also easily write your own storage provider as well. You can check out a ton of community contributions for Orleans here.
Adventure Terre
The basic game sample doesn’t have a TON of functionality. Out of the box it includes the following:
- View a description of a room
- Move from room to room
- Pick up and drop things
- Kill monsters if you have the right item
This is enough to show the concept but isn’t really enough to make a game. To make the game a bit more full fledged I added the following to the public source release:
- Store a game state (essentially a collection of string-booleans to track individual flags)
- Descriptions of rooms, monsters, and NPCs that are shown based off of flags
- Ability to set flags when a descriptor is shown
- Ability to make NPCs and Monsters move throughout the world in random directions (using Orleans timers)
- Ability to send messages down to Players using SignalR (this was really cool to get going so I’ll talk about this in a future post)
- Ability to speak to NPCs and Monsters
- Non-Playable Characters (essentially monsters that can’t be killed)
- Ability to specify where monsters and NPCs should start in the world
- Ability to change directions a player can move in based off of the game state flags
- Ability to specify different descriptions for items based off of flags
- Ability to specify flags that should change when items are used (and how they can be used)
- Ability to specify State Change Actions (things that should occur when flags are changed)
So I added a ton of features. I actually added a few more features to the non-public release but very little functionality on top of the above. The majority of the time was spent working on the above as opposed to the story (that will be apparent if you give it a try).
AdventureTerre Architecture
I’ll give a little detail today on what the architecture of the game looks like to hopefully provide more detail on how something is built with Orleans. As mentioned above, everything is a Grain. So in this game the following Grains exist:
- Players
- Rooms
- Monsters
- NPCs
- GameState
- PushNotifiers (I’ll cover this in the future when I talk about SignalR)
For every player a PlayerGrain is generated and it keeps track of the rooms, monsters, NPCs, and game state. When a request comes in, the PlayerGrain figures out what needs to be done and calls out to the other grains. All of these Grains have interfaces which implement some form of IGrain and specify an interface that extends IGrainState. All of the grains also specify that they use the AzureStore so that whenever their data needs to be written or read, Azure Table Storage is used.
That all happens within the Worker Roles. However, players don’t have any direct interaction with those roles. Instead, when you want to play the game, you go to a website running in the Web Roles. The interface the player plays in resembles a terminal window (yay nostalgia) which runs locally with JavaScript. Every command is passed to a web service exposed as part of the web site. That web service handles getting the PlayerGrain and calling whatever actions on the grain are necessary.
Design Considerations
While I’m happy to consider myself done with this sample for now, there are a number of things I did that if I had thought things out better at the beginning or had more time now, I’d change. First, the original sample treated Things (items like weapons and food) not as Grains, but objects either in a RoomGrain or on a PlayerGrain. One feature I added to the final game was the ability to hide and unhide items. Leaving items as objects in the State of Players and Rooms made this more difficult than if they had been Grains as well. Another change I’d make was how I treated the GameStateGrain. Originally there was just a dictionary on the PlayerGrain that contained the state. While trying to diagnose an issue with await / async (more on this in the future) I moved the dictionary into it’s own Grain. This worked, and still works, but did make a few things more complicated. There were a few other pain points I’d change but for now, it works and it’s being shipped.
The Game
The game itself ended up being quite small (definitely smaller than Zork for example) but showed several different capabilities and it works. If you play it, you’ll easily get though doing absolutely everything there is in less than 20 minutes. I’m hoping this will spur me to get back into actual game development. For now, you can pull down the source code and deploy it yourself to Azure by going here. Finally, I encourage everyone to go play the game for a few minutes and remember that everything is running in a super scalable backend powered by Azure.
