CocosSharp – The Foundation

This post is part of my Mobile Game Development series. Start at the beginning to catch up. This series was inspired by the things I learned developing a new game for Android and iOS called Mirror Maze.

Getting started with anything new can be daunting and CocosSharp is no exception. I certainly felt a little overwhelmed as I started to play around with test applications. Once I started to get an understanding of how CocosSharp works, I found it easier to focus on what I needed to learn one part at a time. My hope with this post is to help you gain enough understanding of the basics to be able to do the same.

As I said earlier in this series, CocosSharp is an implementation of the Cocos2D game engine. That’s important to remember because documentation on CocosSharp can sometimes be lacking. However, it opens up the door if you can find examples of what you are looking for with Cocos2D, then translate it to CocosSharp. That being said, Xamarin does have some CocosSharp documentation available to check out.

A quick note before I go any further. For the purposes of this series, I’ll be talking about CocosSharp in the context of Android and iOS. However, CocosSharp will run on many more platforms than just those two. Most of the topics I plan to discuss should apply to all the platforms CocosSharp is available on, though.

CocosSharp has a Game View (CCGameView) that will be placed either in your MainActivity for Android or your main ViewController for iOS. That Game View will contain your entire game. That means your app lives entirely in a single Activity or view. All navigation between “pages” within the game is only logical navigation. As far as your device is concerned, your app doesn’t navigate anywhere.

That Game View will need to be initialized in order to know how big your design resolution is and where to look for things. In some examples you’ll see that initialization code copied into each platform’s project, but I found it was the same code and moved it into my common project.

Below is my initialization code for Mirror Maze, followed by how it gets wired up in an Android Activity and an iOS ViewController.

What is Design Resolution?

The design resolution topic is rather interesting. You specify the resolution of the Game View by giving it a width and a height. That is the logical size, not the pixel size. CocosSharp will take that resolution and scale it to fit whatever size device your app is running on. That means that all the sizing and positioning you do in your application doesn’t necessarily directly relate to the actual pixels on the device. This fact is actually really cool. It takes away the need to handle different sized devices in your code. There are some drawbacks, however. The first is that you can’t make your game look different on tablets vs phones, at least not without a lot of extra work. Second, if your defined resolution doesn’t fit perfectly on the device that your app is running on, you will get what is known as “letterboxing”.

Letterboxing is where there are bars either above and below or to the left and to the right of your Game View. That is because your Game View will size your game to fit the device’s physical aspect ratio, position it in the center of the screen, then fill in any remaining space with a default color (black on Android and white on iOS). I found that to be rather annoying when I was getting serious about my game’s look-and-feel, but I did find a way to change the color of the bars to blend into my app. Don’t worry, I’ll share that in a later post.

The design resolution doesn’t need to match your physical device’s actual resolution. I learned this the hard way. I thought it needed to match the width and height to the pixel, so I added code that made the design resolution dynamically match the device when the app started up. All that did was make my aspect ratio goofed up on any device other than the one I targeted first, causing things to be sized and positioned wrong within my game. Take my word for it: don’t do that. Instead, pick an aspect ratio that you want to work with, then find a comfortable size with that aspect ratio to set your Game View. A smaller design resolution will make a 10×10 sized object look bigger and a bigger design resolution will make that same object look smaller. What resolution you choose will depend on your app’s UI needs.

Asset Location

The other thing your Game View setup code will need to do is tell the Game View where to look for assets, such as image files for sprites, audio files, and fonts. Most of the examples you see will show the Images folder containing two sub-folders: Hd and Ld. Hd is for High density devices and Ld is for Low density devices. You can also write your app to have more options than that, if you like. I found that the image files I needed for Hd were twice the pixel size as those I needed for Ld. Which brings me to another interesting point: use vector-based graphics for your source. I used Inkscape to create my graphics. That allowed me to resize easily, without losing image quality.

Another lesson I learned regarding the Hd vs Ld concept was that fonts also need to be different sizes for your labels to be scaled correctly on different sized devices. The way I handled this is to add a static property called FontSizeMultiplier, which I set along with the Game View initialization stuff. For Hd devices, the multiplier is 2.0. For Ld devices, the multiplier is 1.0. Then, every label would have whatever font size I wanted to use * that multiplier. Now all my labels are sized as I expect them to be. I didn’t even notice this was an issue until I tried testing my app on a tablet, instead of the usual phone, and saw that all the labels were way too small.

One thing that isn’t immediately clear until you look at a sample project is that the Images folder (containing Hd and Ld), as well as the Fonts and Sounds folders all reside within a Content folder. That Content folder is NOT part of the common project where most of your code will go. This is because the files contained within the Content folder need to be included in the output generated by each platform’s project. Android references those files differently than iOS does. As a result, both the Android project and the iOS project have a Content folder containing your sounds, images, and fonts. On Android, the Content folder resides within the Assets folder. On iOS, the Content folder resides in the root.

Since you will likely be using the same files on both Android and iOS, it makes sense to only create those files once, then reference them in both places. I did this by adding all the files to my Android project, then adding them as Links in my iOS project. Believe me, you’ll want to do something similar so save yourself the headache of double maintenance.

In the next post we’ll start taking a look at the classes you’ll be working with to build CocosSharp games.

Why I Chose Xamarin and CocosSharp

Disclaimer: I’m not a mobile game developer by trade. It’s just a fun hobby for me and a nice departure from my day job of enterprise software development. My perspective is that of someone who does it on his own time, not for an employer. My experiences may be different than yours.

This post is part of my Mobile Game Development series. Start at the beginning to catch up. This series was inspired by the things I learned developing a new game for Android and iOS called Mirror Maze.

Once you’ve decided on a game idea and committed to moving forward with development, you have to decide what technologies to use to build your app. There are a lot of resources out there that provide details about the different options available to you, so I’m not going to talk about any of the choices I didn’t go with. I’m just going to talk about why I chose the technologies I did.

First, a little background about myself. I am primarily a .NET developer who works with Visual Studio all day writing C# code. I am also a native Android developer and am comfortable working with Java in the Android world. In the last few years, I have begun to work with Xamarin to do Android and iOS development as well. I started off learning Xamarin.Forms, then branched out and learned a bit about Xamarin.Android and Xamarin.iOS.

As far as cross-platform solutions go, I was really impressed with Xamarin. It wasn’t perfect, and there was plenty of frustration that came along with it, but I saw a lot of potential. However, that was all with my day job, including the Xamarin license. Which meant I could learn Xamarin and work with it for presentation projects. But, if I wanted to use it for my own personal projects, I had to to pony up for a Xamarin license of my own. The license was a very expensive pill for an indie developer like me to swallow. Add to that the fact that I didn’t have a Mac of my own to develop iOS apps on and I was looking at a very steep cost to get started.

Then came the game changer. Microsoft bought Xamarin and rolled the Xamarin offerings into their own. That was awesome because they also had recently announced the release of a Community edition of Visual Studio, which indie developers can use for free. Once the deal was finalized, Xamarin released Xamarin Studio for free as well. No longer was there the need to pay for the expensive license. I still didn’t have a Mac, but the fact that I could get a community edition of Xamarin for free made cross-platform development much more appealing to me. I decided I needed a dev machine for myself anyway and bought a Mac Mini. Suddenly I was in business.

My driving force for getting into cross-platform development on my own time was to develop games. Since games are a different kind of animal than regular apps, they have different concepts to work with. Games have the concept of game engines, which drive the processing and rendering of the game. There are a number of game engines out there, but the one that caught my eye was CocosSharp.

Cocos2D Logo

CocosSharp is an implementation of Cocos2D on the Mono Game framework. Mono Game is built on Mono, which is the foundation of Xamarin. CocosSharp also has a built-in implementation of Box2D, the popular 2D physics engine. CocosSharp is open source and looked very promising to me at the time, so I decided to go with the Xamarin/CocosSharp combo. That decision had its ups and downs for me, which I plan to cover with future posts in this series.

Overall, I can say I’ve been mostly happy working with Xamarin and CocosSharp. Working Xamarin Studio on a Mac Mini allows me to develop games and apps for both Android and iOS. I also have the option of purchasing a Windows license and using Parallels to run it on my Mac, allowing me to install Visual Studio Community Edition and develop my games for Windows as well. I’m still unsure if that will be worth the cost to me yet, so we’ll have to see how it goes.

The main reason I chose Xamarin as the foundation for my development efforts is that it allows me to write mobile apps in a language I am comfortable with (C#), particularly keeping me from having to learn Swift or Objective-C for iOS development. That comfort is the name of the game when choosing technologies. Learning new technologies may be one of your motivations for doing the app in the first place. If it’s not, you’ll want to consider technology choices that keep you in your comfort zone.

There are a lot of choices out there, but I chose Xamarin and CocosSharp because I wanted as low a barrier for entry as I could get, particularly for iOS. From here on out, the posts in this series are going to deal with that technology combo. Things I wish I knew to begin with, tricks I learned along the way, and problems I encountered.

We’ve covered enough non-technical stuff around game development. Now it’s time to get into the nuts and bolts.

Mirror Maze Now Available on the App Store and Google Play!

As I recently announced, I’ve been working on a new mobile game for Android and iOS called Mirror Maze. I’m happy to announce that Mirror Maze is now available for download on the App Store and Google Play!

Mirror Maze is a fun and challenging new take on maze games and I’m very excited to share it with the world. Go download it for your device and give it a try today. It’s good fun for all ages. If you like it, help an indie developer out and give it a good review 🙂

I developed Mirror Maze with Xamarin and CocosSharp and have already begun writing drafts for upcoming posts to share what I learned along the way. Stay tuned for my upcoming Mobile Game Development series right here.

Announcing Mirror Maze!

I’ve gone dark on this blog for quite some time now, but I’m coming back out into the light to share my latest project. I’m excited to announce a new mobile game I’ve been working on for many months. Mirror Maze!

Mirror Maze is a fun and challenging new take on maze games. With Mirror Maze, your movements are mirrored as you try to complete mazes of varying complexity and difficulty. Learn more about Mirror Maze over at the marketing page.

I’ve been a mobile developer for many years now, and games have been a fun thing to develop on my own time. But this marks the first time that I’ll have an app out on the App Store, let alone the same app deployed both on Google Play and the App Store. As of this writing, v1.0 of Mirror Maze is published out on Google Play, available for Android users to enjoy, and in private beta testing out on the App Store, available for some my friends with iPhones and iPads to play with and provide feedback. I still have some hoops to jump through before going live on the App Store, but hope to finish jumping through those hoops in the next week or two.

I developed this game using Xamarin and CocosSharp. The process was a mix of lots of fun and lots of frustration. In fact, I learned so much from developing Mirror Maze that I plan to resurrect this blog to write up a series of posts outlining all the things I wish I had known before starting an app with Xamarin and CocosSharp.

Stay tuned!