MonoGame: Building Portable Solutions
In one of my previous articles I talked about how MonoGame could be used with portable libraries, this was off the back of some work I was doing with the MonoGame team to help with some of the more tedious clean up tasks that needed doing and I had the time.
Back then it was more of a dream, today it’s becoming a reality.
*Note
At the time of writing it seems that Microsoft has not implemented PCL support from the Visual Studio Express editions as they are aimed at single platform support only, if you don’t have access to a PRO edition or above, then I recommend you use XAMARIN studio for now.
If you would like to see PCL support in the VS express editions, then vote with a click over on UserVoice
Why go Portable?
Now I waffled on about the theory last time for what Portable (or PCL – Portable Class Libraries) can offer with frameworks like MonoGame, especially when you want to take you’re project to as many platforms as possible, the main thing you want to achieve is to only have to put into a specific platforms project that which is native to that platform and keep everything else simple and in one place.
So with this tutorial I’ll walk you through the practice of what it takes to go portable and what it can do for you.
Two main things come to mind as to why you should use a PCL project for the core logic and state of your game projects are:
One core project that contains all code that is completely compatible for all platforms, changes are validated by the project instead of at build time
One library for all platforms instead of separate platform libraries to share code, only have to make a change once, especially useful if you add or remove classes from the core project
Starter for 10
I’ll start with the sample I’ve used for several of my previous tutorials so that you’re familiar with what we have to use, so download the code drop for stage 3 in the previous shocking tutorials here.
*Note, yes there is a portable version on the lightning demo codeplex site but it is out of date with the current works, so ignore that one for now.
What you will find in the source is a project which currently looks like this:
What we want to get to is a project that looks more like this:
Setting up your environment
Creating and using PCL projects are simple enough so long as you have the right tools to hand:
*Note
At the time of writing it seems that Microsoft has not implemented PCL support from the Visual Studio Express editions as they are aimed at single platform support only, if you don’t have access to a PRO edition or above, then I recommend you use XAMARIN studio for now.
If you would like to see PCL support in the VS express editions, then vote with a click over on UserVoice
Visual Studio 2010 (Pro & above only
)
Studio 2010 doesn’t have PCL support by default so you need to install it first, just launch NuGet and search for “Portable Library Tools” and you should locate Microsoft’s Portable Library Tools 2 package, install it and you’re ready to go.
If you haven’t got NuGet yet, then install this VSIX (visual Studio Extension) package and then “goto 1”
Visual Studio 2012 (Pro & above only
)
Thankfully VS 2012 already comes with PCL support out of the box so you are ready to go.
Xamarin Studio
From version 4.03, PCL projects have been supported natively in Xamarin Studio
Lastly you’ll need a copy of the current version of MonoGame.Portable, you can either download the current compiled DLL here, or just clone my MonoGame.Portable branch in my MonoGame fork (if / when the PR is merged into the main MonoGame source, I’ll update the above links accordingly) and build it yourself.
Starting Fresh
To keep things simple lets just start a new project and re-use all the code from the above sample, we’ll even re-use the existing content builder project to keep it simple.
So to start off by creating a new MonoGame project of your choosing. Myself I’m going to keep it simple and create a WindowsGL project. (In Xamarin Studio ), you can also do the same in Visual Studio as well the steps are the same.
*Note If you haven’t done so already and are using Xamarin Studio, be sure to grab the Xamarin Studio add-on for the MonoGame templates here (also available for MonoDevelop if that’s your fancy)
That’ll get you a brand new MonoGame Project, next up lets add a Portable Library to the mix for our Engine, so add a new Project using the “Portable” template (in the C# folder or search for portable)
Just give the new PCL (Engine) library a simple name, in this case I’ve named it “Lightning.Engine”.
Next we’ll add our original engine code into the portable library, so copy these over from the previous sample and then rename the namespaces in each class to “Lightning.Engine” to match our project:
Now if you build the Engine project at present you will get a whole load of build errors.
At this point you might think “well I have my PCL library, why don’t I just use one of my existing MonoGame references?”, as well you should but just try it and see. You will either get:
No Error and No Reference added
No Error but the reference will be added
You’re development environment will through a wobbly and probably just crash (with or without an error)
None of which will result in a project that will build, in fact in the second case above you might think it has worked but basically, it didn’t , the answer is of course to have a PCL compatible DLL to add, namely in this case MonoGame.Portable.
So by either adding MonoGame.Portable to the solution as source and mapping a reference to it from the engine PCL library (AND ONLY the Engine library, not the platform), or by referencing the DLL from the download above in the Engine Library you should now be able to build the engine Lib.
*Note – well with one exception
, Linq in a PCL does not have the “.Find” extension, so simply replace this with “.FirstOrDefault”
Getting on with the Game
OK, so having our logic in a separate lib is nice but what about the rest of the game, well let’s take this a bit further then. Copy over the original “Game.cs” class and embed that into the library as well and for good measure and rename it to something more meaningful for our engine like “LightningGame.cs”.
To use our core game code in a PCL however (or any separate lib for that matter) there are a few things we need to take into account, first and foremost (to quote Highlander), “There can be only ONE”, or in the case of XNA and MonoGame, there can only be one class in our game solution using the XNA GAME class as its base.
To this end we need to:
Remove the base class from our game class
Remove any functions that initialise the graphics device (that’s up to the platform)
Remove any “override” statements, since this class is not inheriting anymore
Alter the scope of methods that need to be initialised or called (or add new ones) e.g Protected –> Public or Internal
Satisfy any framework dependencies that are required for the class to function. e.g. if GraphicsDevice is used, which was part of the base game class)
As an example here’s a side by side comparison of the updates I made to make the old game code ready for the PCL
|
|
||||
Old Game class inheriting from XNA Game | New Game class with no inheritance but has a constructor that takes an XNA Game class as a parameter and stores it in a private variable | ||||
|
|
||||
Old game class constructor | New game constructor, note does not initialise graphics now, that is the job of the platform | ||||
|
|
||||
Old style XNA override from the XNA Game class implementation | Updated methods whose scope has changed and accept the relevant types needed to perform function. | ||||
|
|
||||
Old style class using XNA dependancies from Game base class, like GraphicsDevice | Updated functions deriving the necessary types from the game class sent with the constructor |
Once you have finished updating the new game style class in the PCL should look like this: (note I also added a few bits from the Win 8 solution to cope with touch and multi-touch)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 |
#region Using Statements using System.Collections.Generic; using System.Linq; using Microsoft.Xna.Framework; using Microsoft.Xna.Framework.Content; using Microsoft.Xna.Framework.Graphics; using Microsoft.Xna.Framework.Input; using Microsoft.Xna.Framework.Input.Touch; #endregion namespace Lightning.Engine { /// <summary> /// This is the main type for your game /// </summary> public class LightningGame { enum Mode { SimpleLightning, BranchLightning, LightningText } Mode mode; GraphicsDeviceManager graphics; SpriteBatch spriteBatch; Game game; SpriteFont lightningFont, infoFont; KeyboardState keyState, lastKeyState; MouseState mouseState, lastMouseState; TouchCollection touches, previousTouches; List<ILightning> bolts = new List<ILightning>(); LightningText lightningText; RenderTarget2D lastFrame, currentFrame; public LightningGame(Game game) { this.game = game; } /// <summary> /// Allows the game to perform any initialization it needs to before starting to run. /// This is where it can query for any required services and load any non-graphic /// related content. Calling base.Initialize will enumerate through any components /// and initialize them as well. /// </summary> public void Initialize() { // TODO: Add your initialization logic here } /// <summary> /// LoadContent will be called once per game and is the place to load /// all of your content. /// </summary> public void LoadContent(ContentManager Content) { // Create a new SpriteBatch, which can be used to draw textures. spriteBatch = new SpriteBatch(game.GraphicsDevice); lightningFont = Content.Load<SpriteFont>("LightningFont"); infoFont = Content.Load<SpriteFont>("InfoFont"); Point screenSize = new Point(game.GraphicsDevice.Viewport.Width, game.GraphicsDevice.Viewport.Height); lastFrame = new RenderTarget2D(game.GraphicsDevice, screenSize.X, screenSize.Y, false, SurfaceFormat.Color, DepthFormat.None); currentFrame = new RenderTarget2D(game.GraphicsDevice, screenSize.X, screenSize.Y, false, SurfaceFormat.Color, DepthFormat.None); // Initialize lastFrame to be solid black game.GraphicsDevice.SetRenderTarget(lastFrame); game.GraphicsDevice.Clear(Color.Black); game.GraphicsDevice.SetRenderTarget(null); Art.Load(Content); lightningText = new LightningText(game.GraphicsDevice, spriteBatch, lightningFont, "Lightning"); } /// <summary> /// UnloadContent will be called once per game and is the place to unload /// all content. /// </summary> public void UnloadContent() { // TODO: Unload any non ContentManager content here } /// <summary> /// Allows the game to run logic such as updating the world, /// checking for collisions, gathering input, and playing audio. /// </summary> /// <param name="gameTime">Provides a snapshot of timing values.</param> public void Update(GameTime gameTime) { // TODO: Add your update logic here lastKeyState = keyState; keyState = Keyboard.GetState(); lastMouseState = mouseState; mouseState = Mouse.GetState(); if (WasPressed(Keys.Space)) mode = (Mode)(((int)mode + 1) % 3); var screenSize = new Vector2(game.GraphicsDevice.Viewport.Width, game.GraphicsDevice.Viewport.Height); var mousePosition = new Vector2(mouseState.X, mouseState.Y); previousTouches = touches; touches = TouchPanel.GetState(); for (int i = 0; i < touches.Count; i++) { if (touches[i].State != TouchLocationState.Pressed) { continue; } if (touches.Count == 1) { bolts.Add(new LightningBolt(screenSize / 2, touches[i].Position)); } else { if (i > 0) bolts.Add(new LightningBolt(touches[i - 1].Position, touches[i].Position)); } } switch (mode) { case Mode.SimpleLightning: if (WasClicked()) bolts.Add(new LightningBolt(screenSize / 2, mousePosition)); break; case Mode.BranchLightning: if (WasClicked()) bolts.Add(new BranchLightning(screenSize / 2, mousePosition)); break; case Mode.LightningText: lightningText.Update(); break; } foreach (var bolt in bolts) bolt.Update(); bolts = bolts.Where(x => !x.IsComplete).ToList(); } // return true if a key was pressed down this frame bool WasPressed(Keys key) { return keyState.IsKeyDown(key) && lastKeyState.IsKeyUp(key); } // return true if the left mouse button was clicked down this frame bool WasClicked() { return mouseState.LeftButton == ButtonState.Pressed && lastMouseState.LeftButton == ButtonState.Released; } /// <summary> /// This is called when the game should draw itself. /// </summary> /// <param name="gameTime">Provides a snapshot of timing values.</param> public void Draw(GameTime gameTime) { // TODO: Add your drawing code here // The lightning text is drawn a bit differently due to our optimization with the render targets. if (mode == Mode.LightningText) DrawLightningText(); else DrawLightning(); spriteBatch.Begin(); spriteBatch.DrawString(infoFont, "" + mode, new Vector2(5), Color.White); spriteBatch.DrawString(infoFont, "Press space to change mode", new Vector2(5, 30), Color.White); if (mode != Mode.LightningText) spriteBatch.DrawString(infoFont, "Click to make lightning", new Vector2(5, 55), Color.White); spriteBatch.End(); } void DrawLightningText() { game.GraphicsDevice.SetRenderTarget(currentFrame); game.GraphicsDevice.Clear(Color.Black); // draw our last frame at 96% of its original brightness spriteBatch.Begin(0, BlendState.Opaque, SamplerState.PointClamp, null, null); spriteBatch.Draw(lastFrame, Vector2.Zero, Color.White * 0.96f); spriteBatch.End(); // draw the new lightning bolts spriteBatch.Begin(SpriteSortMode.Texture, BlendState.Additive); lightningText.Draw(); spriteBatch.End(); // draw currentFrame to the backbuffer game.GraphicsDevice.SetRenderTarget(null); spriteBatch.Begin(0, BlendState.Opaque, SamplerState.PointClamp, null, null); spriteBatch.Draw(currentFrame, Vector2.Zero, Color.White); spriteBatch.End(); Swap(ref currentFrame, ref lastFrame); } void DrawLightning() { game.GraphicsDevice.Clear(Color.Black); // we use SpriteSortMode.Texture to improve performance spriteBatch.Begin(SpriteSortMode.Texture, BlendState.Additive); foreach (var bolt in bolts) bolt.Draw(spriteBatch); spriteBatch.End(); } void Swap<T>(ref T a, ref T b) { T temp = a; a = b; b = temp; } } } |
Time for some Platform action
So now that our entire game is hosted within the PCL project, lets update our platform project to run it, here’s where you really start to see the effort paying off, especially as you add more platforms to the mix.
*Note, don’t forget to build and add your Content to your platform project to avoid the dreaded “Could not load Content” error
, see my previous post for how to build a content builder project using the original Lightning source, or (as I did) just use copy / use one of the existing projects in the Lightning source used by this tutorial
So opening up the Game1.cs file in the platform project we just need to initialise our engine and call it from the relevant methods:
|
||
Add a property to store an instance of the game engine in the class properties |
||
|
||
Instantiate a new instance in the game constructor |
||
|
||
Get the engine to load it’s content when the platform is loading content |
||
|
||
Call the update class during update |
||
|
||
Finally tell the engine to draw in the XNA draw loop |
So now, implementing our game in each platform (in a very basic way) has been reduced to just 5 entries in our platform Game class.
Sure you could achieve something similar by using platform libraries but any change you make to the engine library could potentially break any of the platforms you support, with PCL projects you are guaranteed that all platforms will continue to work else the PCL project itself won’t build.
So now in each platform solution you can manage just what’s needed for that platform, such as Share Contract and fly-outs on Windows 8, Notifications and NFC on Windows Phone plus whatever else they do on those other platforms (so shoot me I’m not an Android or iOS expert)
Going further
Now that isn’t the end of the story (although it is the end of this tutorial), you can go a lot further with PCL solutions and it’s nice to note that PCL solutions can also reference other PCL solutions as well to expand what is the core of your project.
You can also add some abstraction in to the mix so you can plug-in / out your favourite other frameworks if you so wish.
Just keep that Core clean.
If you want to keep track of the different ways of building multi-platform / Cross platform solutions, keep an eye on my presentation repository where I’ll keep adding more code in the samples for use, alternatively there is a lot of work going on to clean up the samples for MonoGame in the MonoGame Samples repo’s so you’ll have another source of reference.