New games every week!
Monkey->iOS : After F5 Blog
10th June 2013
Apologies that this post has taken me so long to publish.
I actually wrote most of it about 3 months ago, when I first released SpikeDislike2, but it's been sat on my Mac on a Sticky Note, and I kinda forgot all about it!
I remembered it, the other day, when I submitted SpikeDislike2-Lite to Apple.

What follows is a checklist/guide for compiling your Monkey-coded game onto iOS.
-=-=-

-=-=-

1 - Getting Started

Before we begin, there are a few requirements.

1.1 - Equipment

Obviously, you'll need to get kitted out.
Monkey : To develop iOS Games with Monkey, you'll need to purchase the full package, but it's nice and cheap. It's around about ??100, for the complete package, give or take current exchange rates. This not only works for iOS, but Windows, Mac, Android, Browser, and more.
iOS Dev License : Another ??100, needed to allow you to put your games into the AppStore, or onto your device. You can do test stuff for free, but only on the "Simulator". If you want to see your game on your device, you're going to need a license.
A Mac : Yeah, you're going to need a Mac. This one's a bit more than ??100. A Mac Mini will happily do everything you need, though. My current Mac Mini is about 3.5 years old, and still going strong.

1.2 - License Shite

I'm not going to deal with this, here. I've ranted enough about it, and there's millions of similar rants all over the internet.
Suffice to say, you're going to have to wrangle with your Mac and your iPhing for about 3 to 4 months, before you can fathom the insane amount of shite that Apple makes you fight with, before your first thing properly compiles onto your device.
Once you've finally got it working, DON'T TOUCH ANYTHING, lest you somehow stop it all from working!!!!
Provisions, Certificates, Licenses and more.
Aaah, the joys of iOS Development.

Grrr..

I'm going to assume that you've managed this.
If you haven't, don't even think about tackling Monkey, yet. Keep trying to compile with XCode, until you get a result.

Once it's all working, you're ready to move on.

1.3 - Make a Game


Code your game using Monkey.
If you're like me, you might prefer to spend your time developing your game using a Windows system.
Nothing against the Mac, I'm just more comfortable in Windows. I have all my Dev-tools on there, and my Laptop is a cheap Windows one, not an expensive Mac one.
What can I say, I'm a cheapskate!

Code your game with Resolution Independence in mind, test your game on multiple resolutions, and always be aware that the iPhings have certain limitations, so don't go overboard with all your fancy effects.
It's true that Monkey can achieve an awful lot, especially since it recently got some nice GameCenter features, but try not to overdo it!

-=-=-

2 - Ready to Go


So, your game is finished. You've done everything you're prepared to do, and are ready to send off your first version to Apple.
Let's assume you've been, so far, working entirely on a PC.
It's time to get this iPhing Party started!

2.1 - Copy folder to Mac

Since we're working on the Windows, we just grab the folder, stick it somewhere (thumbdrive, dropbox, network drive, whatever) and copy it over to the Mac.
This was a fairly simple step, and we could probably have done without me spelling it out for you, but it felt like a necessary thing to write!

2.2 - Open .monkey file

Ensure iOS and Release are selected in the Target options.
Double check that you've disabled unlock, debug, cheats and anything else like that inside your code. (Although you might want to leave the cheats on for testing, it's best to disable them before you compile your final release.)

To Compile, just use the Build. There's no need to Build and Run since we're going to reopen the project using XCode in a moment.

2.3 - Open Extras folder

Whenever I'm creating a game, I have a seperate "Extras" folder, where I keep things like Icons and Launch images, as well as in-dev (raw format) sprites and other bits and pieces.
Since we'll be needing the icons shortly, open this folder up, and keep it on the side. We'll need it in a jiffy

2.4 - Open .build/ios folder

Your game should have a .build folder, and inside that is now an ios folder.
In there, you'll find MonkeyGame.XCodeproj
Double click that to open it in XCode.
Give XCode about an hour or so to sort itself out.. :
(Perhaps the slow speed of this is a sign that my 3.5 year old Mac Mini is starting to show it's age!!)
After a while, the Mac should settle down, and you'll have XCode open and ready for action, with your MonkeyGame project open.

2.5 - Name

Monkey compiles everything with the ever-bland "MonkeyGame" title. We'll want to change that.
Click MonkeyGame on the far left (folders), then Targets : MonkeyGame in the left bit of the main panel.
Next, head to the [Summary] tab, and right at the top it should say com.yourcompany.monkeygame
You can change the com.yourcompany to your company (ie, your domain name, but with the .com at the start! Not sure why it's this way round, seems to be the standard, lately.. Just go with it!!!)

You can't change the game name from here, though.
Instead, switch to [Build Settings] tab, and in the Packaging area is Product Name : MonkeyGame
Change that to your game's name.
Head back to the [Summary] tab, and you'll see it's fixed the game's title.

2.6 - Info

Back in the [Summary] tab, change the Version and Build to your current version numbers. These can be anything you'd like, but each time you upload a new version to Apple, you'll need to increase it. Keep track of your version numbers!!

You can change the Deployment Target as you see fit.
I've stuck to 6.0, since I have nothing lower that I can test it on, and would rather not attempt to sell games that might break.
It's pissed a few people off, that their older iPhing can't play my games, but I'd rather they be pissed off that I won't let them buy my game, than have them pay for a game that may or may not work on their system.

Also, in this Summary section, you can click to enable/disable orientations as you see fit. Monkey will deal with rotations as required, but it's up to you to handle the different resolutions.

2.7 - Icons

Grab your icons and launch images from the folder you left open earlier, and drop them into the left-most "folder" panel of XCode, on top of the MonkeyGame folder, below the project's name, and above "Other Sources" (!)
It's nice if these are in a folder, btw!
Immediately, you should see the Launch images appear correctly within XCode's summary, but for some stupid reason the icons don't. Not sure why, haven't figured that bit out. So we need to do a little manual tweaking, here.
Open the icons folder inside XCode, on the left, and have the Summary tab open in the main section.
Scroll down the Summary to the "Icon not specified" bit (under iPhone) and drag icon.png onto the left most one.
A little "This will replace this!" requester will pop up, telling you that icon.png will replace icon.png because icon.png already exists, and is called icon.png..
Click yes!

Icon@2x.png goes onto the Retina one, then scroll further down and put icon-72.png onto the left ipad, and icon@2x-ipad.png onto the right hand retina ipad.
Yep, quirky labelling.. Surely that should be icon-72@2x.png, shouldn't it?! Not my fault, blame Apple!!

Next, head to the [Info] tab, and in there you'll see an Icon Files (iOS 5) section that opens up.
Unfold it to reveal Primary Icon, and again for Icon Files.
Note there's 5 listed, but Icon 0 is actually blank.
Where this comes from, I've no idea, but if you try to upload your App to Apple with this in here, Apple throws a hissy fit..
Delete Icon 0, which shuffles the rest upwards.
Job done..
Your game now has an Icon.. :

2.8 - Music

If you compile now, all works (hopefully!), but if the player has any background music playing, it'll be cut off.
We need to tweak code to fix this.
.. and we DO need to do this, because if your game makes my music shut off, it'll make me delete your app!!

First, open Other Sources/main.h
and up near the top somewhere, in amongst all the other imports, add the line
#import
Then Save!

Next, open Other Sources/main.mm
Open the Find requester (WindowsKey/OptionKey + F), Search for alcOpenDevice

You should find a little area that looks like...


gxtkAudio::gxtkAudio():musicState(0),musicPlayer(0),musicVolume(1){

if( (alcDevice=alcOpenDevice( 0 )) ){
if( (alcContext=alcCreateContext( alcDevice,0 )) ){



Once you've found that, you'll want to add a small chunk to it


AudioSessionInitialize(NULL, NULL, NULL,NULL);
UInt32 sessionCategory = kAudioSessionCategory_UserInterfaceSoundEffects;
AudioSessionSetProperty(kAudioSessionProperty_AudioCategory, sizeof(sessionCategory), &sessionCategory);

UInt32 allowMixing = true;
AudioSessionSetProperty(kAudioSessionProperty_OverrideCategoryMixWithOthers, sizeof(allowMixing), &allowMixing);


.. Which makes it...


gxtkAudio::gxtkAudio():musicState(0),musicPlayer(0),musicVolume(1){

if( (alcDevice=alcOpenDevice( 0 )) ){
AudioSessionInitialize(NULL, NULL, NULL,NULL);
UInt32 sessionCategory = kAudioSessionCategory_UserInterfaceSoundEffects;
AudioSessionSetProperty(kAudioSessionProperty_AudioCategory, sizeof(sessionCategory), &sessionCategory);

UInt32 allowMixing = true;
AudioSessionSetProperty(kAudioSessionProperty_OverrideCategoryMixWithOthers, sizeof(allowMixing), &allowMixing);
if( (alcContext=alcCreateContext( alcDevice,0 )) ){


Save, and Compile!
You should now find that background music runs happily alongside your App. Huzzah!

2.9 - Test Compile

Connect your device, fiddle about with XCode for another half an hour or so, until it notices your device is connected, then Compile and Run.
Double/Triple check everything is ready for launch.
Test your GameCenter methods, double check your Accomplishments, test all the levels, try all the buttons.
Everything.
Make sure it all works, and it fit for purpose.

2.10 - Distribution Settings

Back to XCode, head to the folders, click on MonkeyGame, then in the main area, select Project - MonkeyGame, and click on the [Info] tab.
Be sure you've set the same Deployment Target as the other section.
Just below that are "Configuration" settings, and under those are little tiny, almost invisible, + / - buttons..
Click the +, then Duplicate "Release" configuration.
Name the new config "Distribution"
Next click the [Build Settings] tab, and under Code Signing there's a new Distribution setting.
Leave the "main" bit as it is, but underneath is Any iOS SDK. Change THAT to iPhone Distribution.
(If it doesn't have one listed, then good luck pissing about with all the iOS License gubbins! Seek help on getting your Provisions, Certificates and other crap sorted.)

2.11 - Switch to Distribution

I don't know where this is in the menus.. I used to know it in XCode 3, but they moved it somewhere in XCode 4, and I just can't damn well find it!!
I only know the keypress for it!
[Winkey/Option]+[Left_Shift]+[Comma/<]
This will open up a new Distribution window dialogue thing.
Within the default "Run" section, change "Build Configuration" to Distribution, then click OK.
From now on, every time you compile, it'll target the Distribution build, instead of the previous Debug build. Use the same keypress to change it back if necessary.
Now if you compile the game, you'll find that it complains about a missing Provisioning Profile.
This is normal, it just means you can't run a "Final Compilation" without it being approved by Apple. .. I think.. or some other crap like that, I can't be arsed faffing about with it!
Either way, this is the end result.

This is the App you're about to upload!!

-=-=-

3 - The Upload


The App is compiled, and you're ready to send it off, but first you need to setup an iTunes Connect page!

3.1 - Preparation


Grab all your iPhings, and start taking lots of screenshots!

You'll need at least 2 screens for each resolution that your game supports.

iPad (2048x1536), iPhone Old (640x960) and iPhone New (640x1136)
In each case, you can use either Small or Retina, but will probably be better off with Retina.

If you've not got a specific resolution'd device, either use the Simulator, or cheat like I do, and take screenshots of your Monkey App running in HTML5/GLFW mode!

You'll also want a 1024x1024 sized icon

If you're adding GameCenter elements, you'll also have to add page after page after page after page of details for all of that, ensuring you get all the Leaderboard and Achievement names labelled correctly, as well as supplying oversized 1024x1024 icons for all the badges and things.
It really is a stupid amount of work, to get it all done!

You'll also need to fill in the general blurb, as well as supplying your web address, email address, and even your real name and contact number.. ..!

Loads of stuff to fill in.

Once you've got it all sorted, click the blue "Ready to Upload" button, and.. you're ready to upload!

3.2 - The Upload


In XCode, in the folders panel, at the bottom is a "Products" folder, and in there should be YourGame.app
Right click that, and "Show in Finder"

From here, right click on the app, and "Compress"
This will give you a YourApp.zip
This is the actual file you'll be uploading.

Now open up Application Loader.
Use the Mac's Search thing to find it. If you can't find it, it might not be installed. Head to iTunesConnect and you'll be able to find the download lurking around there.... somewhere! They seem to move the damn link, every time I try to look for it!!

Once Application Loader's running, sign in, click "Deliver", select the app*, choose the file, click Send, and .. Hopefully your App gets to the other side in one piece!!
* If your App isn't listed, close Application Loader, head back to iTunesConnect, be sure you clicked "Ready to Upload", then try again.
.. oh, and make sure you've signed in to both using the same login details.. !
Fingers crossed!!

If all goes well, which it usually doesn't, the little progress bar will eventually hit 100%, and you'll hear a nice Mac'y "Ping!" and get a nice big green Tick on your screen.

If something's gone wrong. ... Head back to step 1, and double check everything!
Views 49, Upvotes 4  
Daily Blog
New games every week!
Site credits : If you can see it, Jayenkai did it.
(c) Jayenkai 2023 and onwards, RSS feed

Blog - Monkey->iOS : After F5 - AGameAWeek