WARNING: The following is a technical article. Don’t blame me if you find it boring!

I love Unity! The Unity iPhone engine is a fantastic piece of technology, allowing us to quickly develop games without having to worry about a lot of the underlying stuff. However, Unity is essentially an additional layer on top of the iPhone SDK, which means that while the iPhone SDK may advance with new features, the Unity engine is generally a step behind with adding these features in a manner that can be easily accessed through script.

Enter Objective-C: This is the language that iPhone apps are usually written in. Unity provides some support for calling native Objective-C code from Unity script, but only for Advanced licensees and only in one direction. This can be pretty limiting especially if you’re trying to use a lot of the fancy features in iPhone OS 3.0. Sure, you can pass around information using the PlayerPrefs trick. But this has the problem of not being instantaneous, and it forces the app to constantly poll for new commands, which probably isn’t a good idea performance-wise.

What follows is a method for immediately calling Objective-C code from Unity script (for both Basic and Advanced licenses) and also vice versa! That’s right, two-way communication between Objective-C and Unity script that’s instantaneous.

Unity to Objective-C (for Advanced licensees)

First, for the Advanced license users of Unity, you already have a quick and easy way of calling Objective-C code from Unity script. In C#, just do the following:

[System.Runtime.InteropServices.DllImport("__Internal")]
extern static public int AwesomeFunction(int awesomeParameter);

Then, in a C/C++/Objective-C file somewhere in your Unity-built Xcode project, do the following:

int AwesomeFunction(int awesomeParameter)
{
   // My awesome code goes here.

  return somethingAwesome;
}

You may have to wrap your function prototypes in extern “C” { … } if you’re using C++/Objective-C++ due to name mangling.

Unity to Objective-C (for Basic licensees)

Now for you Basic license users, you’ve been used to sending a command to Objective-C from Unity script like this:

PlayerPrefs.SetString("Commands",
   String.Format("AwesomeCommand|{0}|{1}", awesome1, awesome2));

Or something similar. You’ll still be sending commands this way. However, in Objective-C, you probably have an NSTimer that is constantly polling to see if the “Commands” key in NSUserDefaults has a string in it. You might even have some fancy queueing system set up so that you can call multiple commands in a row without them overwriting each other. The issue, though, is that if you need a result back from one of these commands, you can’t get it instantaneously. You have to set up some kind of polling system in Unity script to wait for a return result to show up in some other PlayerPrefs key. Messy.

But there’s a better way. Let me introduce you to Key-Value Observing. The iPhone SDK provides a method for setting up “observers” for certain things currently going on in the system. It just so happens that one of the things that you can “observe” is NSUserDefaults. That’s our ticket!

Somewhere in your Objective-C code (where you might normally set up the NSTimer for polling the NSUserDefaults), place the following code:

[[NSUserDefaults standardUserDefaults] addObserver:self
   forKeyPath:@"Command" options:0 context:nil];

Then, create a method like the following:

- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object
   change:(NSDictionary *)change context:(void *)context
{
   // Command parsing code goes here.
}

The observeValueForKeyPath method is essentially the function you had before that parsed the commands from PlayerPrefs/NSUserDefaults. What the addObserver moethod does is set self to be an observer of NSUserDefaults, meaning that every time you set the PlayerPrefs in Unity script, the observeValueForKeyPath method gets called immediately!

What this now allows you to do is to set a result key in Objective-C and immediately access it in Unity script. Here’s an example:

// Objective-C code
if([[[NSUserDefaults standardUserDefaults] getObjectForKey:@"Command"]
   isEqualToString:@"DoSomething")
{
   // Return a result by setting the key here.
   [[NSUserDefaults standardUserDefaults] setInteger:1 forKey:@"Result"];
}

// Unity C# code
int CallDoSomething()
{
   PlayerPrefs.SetString("Command", "DoSomething");
   // Before, doing something like this would be very bad!
   return PlayerPrefs.GetInt("Result");
}

As you can see, you can get immediate results from the Objective-C code! Hooray!

Objective-C to Unity (for everyone)

Where Advanced and Basic licensees meet is in the need for having Objective-C code call back to Unity script. There are many instances where you need to capture an event in Objective-C and then pass this off immediately to your Unity scripts so that you can update your game. While using NSUserDefaults to send information back to PlayerPrefs is certainly doable, a polling system would need to be set up in Unity script and it would never be instantaneous.

To get this working, you need to know a little bit about the underlying Unity frameworks. Unity uses a framework called Mono, which is an open-source cross-platform implementation of .NET. When you use something in the System namespace or String.Format, you’re actually using .NET libraries, and not something Unity-specific. While the actual invocation of the Mono runtime isn’t visible from inside the Xcode project, that doesn’t mean we can’t still have access to the Mono functions.

You can do amazing things with C. You can also do terrible things with C. That’s why it’s preferred by so many programmers, as data and memory in C is completely malleable. You can do almost anything with it. Even though we don’t have access to the Mono header files in the Unity Xcode project, by doing some handy Internet searches, we can get the function prototypes of all of the Mono functions we’ll need to get what we want.

In addition, many Mono functions require or return special MonoTypes. This would be a problem in C#, but in C a void pointer cures all! For our purposes, here are all of the MonoTypes that we need:

typedef void* MonoDomain;
typedef void* MonoAssembly;
typedef void* MonoImage;
typedef void* MonoClass;
typedef void* MonoObject;
typedef void* MonoMethodDesc;
typedef void* MonoMethod;
typedef int gboolean;

To be honest, you don’t even really have to set up the typedefs, but it makes the function prototypes look cleaner and more readable. Remember, since pointers simply point to memory, they don’t really need a type.

Now for the function prototypes that we’ll need. The following is the bare minimum of functions needed to accomplish calling Unity script code from Objective-C. (Remember: You may need to wrap these in extern “C” { … } if you’re using C++/Objective-C++ due to name mangling.)

MonoDomain *mono_domain_get();
MonoAssembly *mono_domain_assembly_open(MonoDomain *domain, const char *assemblyName);
MonoImage *mono_assembly_get_image(MonoAssembly *assembly);
MonoMethodDesc *mono_method_desc_new(const char *methodString, gboolean useNamespace);
MonoMethodDesc *mono_method_desc_free(MonoMethodDesc *desc);
MonoMethod *mono_method_desc_search_in_image(MonoMethodDesc *methodDesc, MonoImage *image);
MonoObject *mono_runtime_invoke(MonoMethod *method, void *obj, void **params, MonoObject **exc);

Here’s where we need to explain things: We call Unity script functions by using the mono_runtime_invoke function. However, before we can call this, we need to get the MonoMethod (essentially, the pointer to the Unity script function we want to call) from the assembly file that was compiled by Unity when you hit “Build & Run”. So how do we get that?

First things first, we need to get the domain where all of the Unity scripts are running. In the vaguest of terms, a domain is kind of a box where scripts are run. So we need to grab the Mono domain first:

MonoDomain *domain = mono_domain_get();

Simple enough. We now have the location where all of the Unity scripts are being run. Now to get the MonoMethod, we first need to get a reference to the assembly that contains the function. In your Xcode project, if you look in the Libraries group, you’ll see a bunch of ‘dll.s’ files. These files get compiled by Xcode on Build into DLL files that get placed into your app’s Data folder. If you don’t believe me, take your built Unity app, Show Package Contents on it, and then browse around.

Knowing the folder structure of the built application is actually important to this process, as we’re going to be directly referencing these DLLs for the next step. We need to get the assembly itself so we can read through it and find our functions. Here’s how to do that:

NSString *assemblyPath = [[[NSBundle mainBundle] bundlePath]
   stringByAppendingPathComponent:@"Data/Assembly - CSharp.dll"]
MonoAssembly *assembly = mono_domain_assembly_open(domain, path.UTF8String);
MonoImage *image = mono_assembly_get_image(assembly);

You’ll notice we put in the path of the built DLL file from the application’s main bundle. Note that the assembly you’re looking for might be different for the class method you’re trying to access. To find out the correct assembly, highlight the script in Unity and go into Debug mode in the Inspector. The Assembly Identifier should tell you the name of the assembly. We then get the assembly from our domain. The MonoImage is something we’ll need for the next step.

We have our assembly now, and we can start accessing the functions inside it. To do this, we need to tell Mono what functions we’re looking for. (For ease of use, I’m only going to be looking for static methods in classes without a namespace. If you want to access specific objects or call non-static methods, I suggest you read up on the official documentation on Embedding Mono.)

MonoMethodDesc *desc = mono_method_desc_new("AwesomeClass:AwesomeFunction()", FALSE);
MonoMethod *method = mono_method_desc_search_in_image(desc, image);
mono_method_desc_free(desc);

Notice that the MonoMethodDesc (literally, MonoMethod Description) is created by giving mono_method_desc_new a string that contains the method that we want to call. Remember to put the class name before the function and follow it with a colon, not a period. If you want to access a method with parameters, do something like this:

"AwesomeClass:AwesomerFunction(int,int,int)"

Formatting is very important. There shouldn’t be any spaces between the method parameters. After getting the description, we then search the assembly image for the method. Doing all of this searching could impact performance in your app, so it’s recommended that you do all of this in an initialization function and store the pointers to the various MonoMethods you want to use. After we have the method pointer, we free the MonoMethodDesc that was created.

Now you have your MonoMethod! And you say you want to call it! We can do that very easily now:

mono_runtime_invoke(method, NULL, NULL, NULL);

See? Very simple. If your method had some parameters in it, you need to pass the arguments as a void pointer array to the third parameter of mono_runtime_invoke, like so:

int param1 = 1;
int param2 = 27;
void *args[] = { &param1, &param2 };

mono_runtime_invoke(method, NULL, args, NULL);

We are essentially passing the arguments by their address via way of an array.

And that’s it! There are a few caveats to using this method of invoking Unity script methods: Firstly, it’s slow. It would not be recommended to call these many times per frame or even once every frame. It’s primarily good for callbacks that occur every now and then (like for GameKit connection results, etc). Secondly, you’re putting a lot of trust in the Mono and Unity developers to not change things around too drastically. If you upgrade Unity and your code suddenly stops working, you’ll need to downgrade to the previous version of Unity or muck around until you can find out what was changed.

Conclusion

Finding all of this out was a long weekend project for me, and it has definitely been worth it. Functionality that I simply didn’t think was possible without official Unity support is now immediately available, and I am now able to bounce back and forth between Unity script and Objective-C to get access to whatever I need. There are performance issues to consider, but on the whole the flexibility outweighs the potential performance pitfalls. It just requires you to properly plan your app with these things in mind.

Some may read this article and think that the Advanced license is obsolete with these methods. However, I don’t think that’s true. The simple fact that Advanced users can use namespaces like System.Runtime.InteropServices and System.Xml are worth it alone, especially when you consider that you can’t send something as complex as a struct or class through a PlayerPrefs string (I guess you could, but it wouldn’t be very pretty). This is really just a stopgap measure to allow Basic license users access to some of the native functionality that isn’t available in Unity yet. The splash screen requirement alone was enough for us to upgrade!

In addition, using the Objective-C to Unity callback functionality is not for the faint of heart, and certainly not for those who aren’t well-versed in the art of programming. Just be sure to design your games around what you can do, not around what you wish you could do.

I hope you’ve found this both educational and useful and that you’ll consider contributing your own findings to the Unity community.

And indeed they are here at Tiny Tim Games. We’ve made a lot of progress in the last week, and I think it’s safe to say that we’ll be announcing a new game NEXT WEEK! It’s very exciting. Read on for more info.

Things are never set in stone in game development. This again proved itself last week when we got word that if we wanted to get our games in the App Store for the holidays, we needed to have them submitted about a week before we had planned to finish both of our current projects. Knowing that we didn’t have nearly enough time to finish both in that time frame, we had to choose which we want to focus on now and push to get out for the holidays.

Unfortunately, “Game 2″ will now become “Game 3″. But don’t worry. By this time next week, you shouldn’t have to keep track of our next two games via number anymore. Because the project we’re moving forward with has made some excellent progress in the last week.

We’ve settled on a name and style for the game, which allowed Shannon to begin creating the HUD and textures for the game. And let me just say that the stuff she’s doing looks amazing. I’m excited that we’ll be able to show a little of it off next week.

Meanwhile, I’ve been taking our basic gameplay prototype and fleshing out various pieces of it. We have the whole game almost completely mapped out, from main menu to final level to AGON awards (that’s right, our next game will be AGON-enabled). With the game mapped out like this, it’s been very easy for me to sit down and program the remaining pieces of our game.

Funnily enough, I’ve realized that aside from the initial tech and prototype, the remaining pieces of this game are actually less development intensive than Sheepstacker, even though I would argue this game has more variety and depth. Game development is always surprising.

This should be the last post where we have to be annoyingly cryptic about our next project. Thanks for sticking with us, and we hope you like what you see next week.

There’s not much to say about Game 2 at the moment, other than we have enough of the main interface to bring it into the engine and actually test it out. The hope is that we’ll have something to show of the game next week, even if it’s just a screenshot. Video would be preferable.

As for Game 3, due to some design concerns, we scaled back on some features that we initially thought were completely necessary. After weighing the options, we realized these features weren’t necessary to the core gameplay after all. We felt that by focusing on this core gameplay would allow for a better, more polished initial release. If the game is successful, I’m sure we’ll be returning to add all of these features later. That’s the beauty of digital distribution!

The week ahead is going to be a rough one, simply due to how much has to be done. The main interface for Game 2 needs to be finalized so that I can get back to programming the remaining features. And I’ve got my work cut out for me writing the behaviors for three of Game 3′s antagonists. Strangely, I seem to have picked the most difficult one to start with. At least the next two will be simpler. Once these are written, we’ll wire up a few scenarios, and do a fun factor check. If it passes, we’re going to go all out creating final art to put into the game. I’d say we’ll be ready to show a few screens off in about two weeks. Very exciting!

For “Game 2″, we kicked around a variety of themes for the game. As we created the prototype completely abstractly (meaning, there was no story, concept, or theme in mind when we created it), we wanted to see if we could create a theme that would give the game a little bit of personality, something that we feel is very important to our games. Again, as our handicap is art, we settled on something that doesn’t quite have the personality of Sheepstacker, but should still be pleasant and fun.

For “Game 3″, the bulk of the technology for the game is actually complete. The next step is to bring it all together to create our first playable prototype. Looking forward, this game seems like it will require a lot of small tweaks to get exactly right, as there’s a balancing act to keep all of the elements of gameplay from overpowering each other. It should be an interesting experiment.

In addition to the technology, I’ve successfully modeled, unwrapped, and rigged all of the characters we’ll need for the game! The models themselves are very simple as we want to get as many of these guys on screen as possible. The biggest problem was keeping the vertex numbers down. With low vert numbers, Unity (our engine) will be able to batch the drawing of nearly all of our characters. This will greatly help performance, which is something we’re going to need help with since we want to have oodles of skinned and animated characters on screen.

The next steps for us are pretty clear: For Game 2, Shannon will continue creating mock-ups of our user interface and gameplay screens. Since the bulk of the gameplay programming is actually finished for that game, I’ll be focusing on assembling the different components for Game 3 to create a playable prototype. In addition, I’ll probably coax Shannon into creating some textures for our characters.

The project I’ve mentioned in previous posts has been giving us some grief lately. Whether it’s the looming giant-ness of the project or worries of lack of innovation in gameplay, there have been lots of roadblocks keeping us from real progress on the game (which will henceforth be known as “The Big Project”). We’ve basically been trying to make this game since Sheepstacker, even though we’ve gone through lots of very different prototypes that hardly look like the same game. Yet they’ve all had something in common… they were big. Or at least big for a two person team to accomplish.

So with release seeming further away than ever, we took a step back and began rethinking our development strategy. After many days (weeks?) of back and forth, we’ve finally figured out what we’re going to do! We’re putting the Big Project on partial hold for the moment (“partial” meaning that if inspiration strikes, we’ll work on it), and in its place we’ll be working on two (yes, TWO) other projects in tandem.

These two projects will be smaller in hopes of actually finishing them in a reasonable time frame. Since they’re small, though, the gameplay needs to be: 1) very fun, 2) engaging, and 3) completely addicting. We’ve already completed the prototype for one of the games, and after a little focus testing we feel we’ve definitely got something that fits all of those criteria. The second prototype is underway but isn’t fully playable yet. Still, we’re really excited about the idea (both the gameplay and the theme). It’s certainly a lot of fun in my head!

I’ll have more information about these two games next week. As they’re smaller games, we’ll be able to reveal more about them sooner instead of sort of talking about them in code here on the site. Stay tuned!

I got back to programming earlier this week, which was very nice after two weeks straight of modeling, rigging, and unwrapping UVs. During the previous two weeks, we made some core gameplay design changes to better fit the characters that we created, so when I got back to programming there was a fair amount of work to be done. However, the work has been extremely enjoyable. Things are starting to meld now and actually feel like we can finish this thing!

Shannon will be continuing to touch up the textures on our main characters. She’ll also be texturing all of our environments as well. I’m looking forward to having something more than a gray background to look at for once! I think that’s when it’ll really feel like we’ve got a game.

We bought ourselves a second-generation iPod touch last week so we could have an actual working iPhone OS 2.2.1 device in-house. You may remember that we flubbed up one of our Sheepstacker updates for 2.x people. We’d rather not make that mistake again. That brings our current development hardware to: two iPhone 3GSs, two original iPhones, and one iPod touch (along with the devices we finagle from family and friends).

My modeling talents were definitely put to the test this last week. As a person who has a bit of an artistic thought process but no actual artistic skill, it was a bit of a bumpy ride. With these characters being my first humanoid models, I had a lot of learning to do. I input each individual vertex by hand on my first human head. Vowing to never do that again, I began using cylinders and various tools in Cheetah (like the scalpel and weld tools) to do the brunt of the work for me.

The plan was to pass off the models to Shannon so she could rig them. However, as she had never done rigging before, and I hadn’t done rigging on anything that needed vertex weights that weren’t 100% all the way, the two of us weren’t prepared for the complexities of rigging a humanoid character.

Whereas the sheep in Sheepstacker were composed of completely separate moving parts, humanoid characters have skin that has to stretch around the arm and leg joints. This was the most difficult part to get right. Since I had more rigging experience, I took over the initial rigging job for our first character, and played around with it until I got it right… well, mostly right. There’s still a bit of pinching in some areas, but we’ll try to cover it up as best we can.

I also did a full UV unwrap of one of our characters. Again, the complexity level versus our experience level was the holdup here, but I think things worked out decently. I’m passing along my knowledge to Shannon so she can complete the rest of the characters while I start working on our fourth and final main character.

We went through a few more iterations of our logo design. We’re getting closer to having a design I feel we can call final. I haven’t been doing very much programming in the last week, though I did speak with my good friend Nathan Fouts over at Mommy’s Best Games about some technical points that we’ll be facing soon.

Friday was also Snow Leopard Upgrade Day! I’m a bit impulsive when it comes to OS updates, so it probably would’ve been better for me to wait to upgrade until a few more kinks with some of the apps we use were worked out, but I just couldn’t resist.

One app that we had just started using to keep the project synced across our machines (since Unity doesn’t play nice with SVN or Git) was Windows Live Sync, which up until the Snow Leopard upgrade worked just fine. Having gotten used to having the project auto-sync on our machines, we needed the functionality back ASAP. Since the Live Sync team has been quiet on when they’ll actually fix the issue, I went looking for an alternative. Luckily, we found Dropbox, which not only does the sync functionality we needed, but also backs up our project files online, and it works on Snow Leopard. Win-win-win.

So we’ve got a bit more character modeling and rigging to do and lots of texturing. After that, it’s character animations and the creation of our very first complete level. Very exciting stuff.

We have officially decided upon a name for our upcoming game, and we even have a logo to boot. We can’t reveal it yet as we still want a few more things finished before we reveal the game to the world. Things are starting to come together though. It’s really exciting!

I began prototyping various enemies, their behaviors and movements. In addition, I also began modeling some of the enemies for our first level. In fact, except for one or two, we have all of our enemies modeled, textured, and ready to go for the first level. After putting the finished guys into the level, it finally started to feel like a game.

Along with enemies, I also began modeling our main characters. These are the characters you’ll be controlling when you play the game. As of today, I’ve completed two models, and have two more to go. So that should give you a hint of how many characters we’re going for. I had to really stretch my modeling skills to get these characters made, but I think they turned out fairly well.

Shannon was in charge of texturing all of our enemies, and she’ll begin rigging our main characters for animation tonight. She’ll be texturing them as well, but we’re running into issues with UV seams giving Unity a hard time. For some reason our models are showing nearly 5 times the number of vertices in Unity as they are in Cheetah. So until we figure that problem out, our main characters will remain untextured for a while longer.

Shannon and I also sat down and did a bit of a brainstorming session for the game. We discussed various aspects of the game, including bad guy names and additional levels. As you can see, we’re not really working off of a set design document. We’ve found we’re more creative coming up with things as we go along. Plus this leaves us open to change course quickly if necessary. While I wouldn’t recommend doing this for a large game, when you’re making smaller iPhone games, it really helps the creative process.

We’re hoping to have made enough progress on the game that we’ll be able to show off some of it in the next two weeks.

Shannon is continuing her Cheetah 3D lessons, and seems to be grasping it quite well. She learning a lot of techniques that we’ll be desperately needing for this game, with some of those techniques being some that we could’ve used on Sheepstacker (if I would’ve known how to do it in Blender).

We’re looking to start brainstorming character, enemy, and level designs shortly, hopefully by the beginning of next week. That’s going to be an exciting time, as we’ll soon be able to actually show a little bit of the game.

First off, we submitted a quick update to Sheepstacker over this past weekend. We updated the AGON Online libraries (which now include Twitter support – yay!), and we built the game with a new version of the Unity engine, so it should be faster, better, stronger.

I’ve been continuing work on a prototype for our (hopefully) next game. It took a long time to settle on a design that: 1) wasn’t overly ambitious for a team of two working from a home office; and 2) wasn’t a complete dull-fest. We’re the picture of iterative design simply due to the number of projects that we started and threw out. One project was even in development for a full month before we finally decided to cut our losses (don’t worry, it wasn’t very fun anyways).

This particular prototype has only been in development for a little over a week, but the little bit that I have running seems to be fun, accessible, and not a 40-hour long RPG (you’d be surprised how important that is to an indie developer). We’re sticking with the “pick up and play” mentality of our earlier game Sheepstacker, but with more “hardcore gamer” sensibilities.

In particular, I’ve been focusing on the controls for the game, and I think we’ve landed on something really awesome. “Easy to learn, hard to master” sort of stuff. I’ve also been working on getting a wave management system up and running so that we can have all sorts of enemies do all sorts of things without pulling our hair out trying to put them all into the game.

Meanwhile, Shannon has been learning a bit of 3D modeling. On Sheepstacker, I was the primary modeler while Shannon did all of the texture and image works. However, when you start making a game that’s a little more complex than just “drop some sheep”, you start running out of time to do things other than programming. So she’s stepping up and taking on that primary role for this project.

We’ve decided to switch 3D packages from Blender to Cheetah 3D. While I cut my teeth on Blender and like how quickly you can make stuff in it (once you’ve learned all of the shortcuts), it’s extremely complex for someone just learning 3D to jump into, and it has more than a few issues when importing into Unity. Cheetah meanwhile has a simple interface, imports into Unity perfectly, and has all of the features that Blender has (at least for Unity game development).

That’s all for this week. Next up on the agenda: I program lots of stuff to shoot at, while Shannon draws lots of stuff to shoot at.