We made it! 249 days since the first source code commit, TextTumble is finished. At around 11:30 PM, I cracked the champagne

and sat back to enjoy the prospect of a job completed. While there is still some additional features that will be fit into the online scores and profiles, I feel very happy labeling the package with “1.0″ (A version number whose significance can be daunting to a first timer like myself). As it sits in Apple’s review queue now, I’d like to give you an abbreviated history of the game’s development. I’m not going to offer much in the way of advice or instruction here; this is just telling a story.
Sometime near mid September 2008, I went out for lunch with now co-owner of Magellan Media, Matt Rogers. Matt and I were co-workers at the Indianapolis Star (Matt recently left the Star to work at mediasauce), where we worked with a team of other artists and programmers to create local community sites.

Matt asked me to work together with him on a new game concept: create a falling-letter-tile word game for the iPhone. At the time, one of the more popular games on the iPhone app store, Wurdle, was gaining in popularity, yet seemed to be generating a lot of derivative apps in the App Store. Matt felt (a point which I believe to be still valid) that a new type of word game would capture the public’s attention as an alternative to the Wurdle-style game.

I was definitely interested; to say that I have long desired to enter into the game industry would be an understatement. While in college, I had hacked together some simple mods for Unreal Tournament and Rune, but I had never stuck with a project long enough to see it polished and complete. While many of the upper echelon of iPhone games on the App Store seem to be coming from game industry veterans breaking out on their own, the game that Matt and I would make would be our first.

Invigorated from that lunch, I told Matt that I would create a prototype and have it ready for him to check out a few days. On September 29, 2008, I sent Matt a video of the iPhone simulator that looked something like this:

I think that programming is full of many images like this: screenshots that on their own merits are entirely forgettable, but hold huge significance to the creator. This image represents the very beginnings of not only the first game I intended to follow through to completion, but also the first publicly used application I’ve written using OpenGL, a long time career goal of mine.

Matt and I, both pleased that a prototype of the game’s basic interaction was put together so quickly, set a deadline for ourselves: finish the game by Christmas. It would be some hard, late nights, but I felt it would be possible. And yes, I mean Christmas 2008.

Over the course of October and November, I began working late nights, trying to pull in the necessary components of the game: the word dictionary, the tile texturing, and the interface elements. As I did this, I kept one goal in mind: keep all the code as simple as possible. I knew that attempting my first game would mean that I’d be spending more time rewriting code than writing new code, as I discovered newer and better ways to accomplish things. I also knew that I could easily fall into the trap of writing over-architectured code when I encountered a problem, as an attempt to insulate myself from the dirty details of the problem. Commits would look like this:

at once both encouraging me that I was accomplishing work quickly, and infuriating me that I was committing code that I knew was not what I intended to be there later on.

On November 19th, we hit our next big milestone: eliminating valid words.

I was pleased that I was able to get this piece of functionality working, but I was concerned about our Christmas 2008 finish date. The game was not nearly polished enough, and I had not done nearly enough code quality checks to feel anything close to happy regarding the game. Additionally, there were features that I was beginning to feel were critical to the game’s success (in-game word definition lookup, global high scores and spelling statistics, pictowords, letter crashing) that were either nonexistent or so basic as to be laughable. I told Matt that I was afraid we’d miss Christmas, but that I’d work hard on trying to be done as soon as possible.

Now would be a good time to mention that the game really had 3 people working on it. While Matt worked on art resources and the website and I did the programming, my wife was consistently involved throughout the game’s creation as our sanity check. As we began to reach a more iterative feature-bugfix-internal release cycle (that was nowhere near that formal), my wife began to be more involved in critiquing the basic flow and style of the game. While Matt and I were avid video game players and had certain expectations of interface and game behavior, my wife was not: her analytical nature combined with her lack of prior bias began to reveal flaws in our assumptions as to the game’s readiness for the public. Our Christmas 2008 release became our Christmas 2008 hard-vacation-push to complete more work items. I told relatives that I’d be spending the majority of my vacation programming for the game, but that I believed I’d have the majority done by February 2009.

I finished the year 2008 staying up late coding, trying to meet my own deadline.

The months of January and February were difficult. Personally I was having to work my day job at hospitals throughout most of those months, as my family was going through a difficult medical time. (I should note that I am very thankful to my department managers for allowing me the ability to even /do/ this) Additionally, I learned just weeks into the new year that the entirety of the Gannett corporation (the parent company that owns many of the newspapers across the US, including the Indianapolis Star) would be enacting a furlough (unpaid week of leave) program to help account for huge losses in revenue:

I’d be lying if I didn’t say I was secretly overjoyed that I would be able to spend a week doing game development instead of web development; that joy was slightly bittersweet, however. I was reaching the awkward phase of a first-time project where certain rusty mechanisms in the game seemed like they might be better rewritten; would I benefit more by continuing a design that I was increasingly dissatisfied with, or by taking more time to redesign large internal components of the game? I began to doubt many of my earlier decisions, but could not bring myself to wholesale remove whole sections of the game to make way for a rewrite. I compromised:

and, despite my own pessimism, succeeded:

Throughout this time period, Matt had been revising our interface designs, collecting sounds for the game, and working on the promotional website. While we were not finished by the end of February, we were ready for a beta. We put out the call on Twitter, and began to aggregate a collection of friends, co-workers, and some complete strangers, to check out our game, and help us figure out what might be broken, and what might just need some tweaking. On March 1st, we packaged up the application and distributed it to our 15 beta testers.

Immediately after having released the beta, I went right back to work. The fact that people were using it served as fuel for me to become reinvested in the game, and I began to work longer and more nights throughout the week, polishing things, adjusting interface designs to meet Matt’s mockups, and generally get the game ready. We received some very nice compliments from friends who we had play the game, but the game was definitely buggier than we had realized.

Towards the end of March, things were progressing slowly, but well, when it happened:

Gannett had been steadily losing money, and was forced to institute another week of unpaid leave for all its workers. I was once again enthusiastic at having a week to spend working on the game, but was cynical as well. Two financial quarters involving furlough programs does not indicate that the rest of the year will be stable and secure to a pessimist such as myself; and, if my day job were to be lost, I would not have the liberty to continue working on the game for some time. Whole months of work would be put on hold as I found another job and settled into that environment.

My wife and I talked, and we decided: if there was to be any hope of finishing the game before I became unemployed, I would need to use my vacation time along with my furlough time, and work at top speed on getting the game to a polished, playable and fun state.

We released our second beta on April 14th to a larger (20+) yet much less active group of beta testers. While we were achieving very favorable responses from players who we engaged in person, we weren’t receiving any feedback or significant recorded play time from any of our testers.

This was our fault. The phrase “beta test” implies something entirely different than what it is. When we released /any/ beta test, it should have been with a stable and mostly realized game, instead of an unstable game that we were using to gauge user reactions from. In other words, our beta was our very first form of public display of the game, and should have been more representative of what we wanted users to see in the end.

Work continued. I had stopped attempting to predict when we would be “finished”, and jokingly just said “when it’s done” when asked. I had no idea when the game would be done. I had stopped primary gameplay development several times to add new features to the game, or improve gameplay performance.

I created a tool called AtlasMaker (which I will put on GitHub sometime in the next month or so) that let us bundle our delivered graphics in memory easily, and added a decompress-word-dictionary-to-users-hard-drive-on-first-launch feature to the game that dropped our application size to 6MB. I then promptly removed that feature, and removed our SQL database of words entirely for an in-memory structure called a DAWG which offers much more efficient querying of words and storage on disk, allowing us to have much more performant pictowords (I’ll explain what I mean by pictowords in a future post).

Things were nearing the end. I could feel like everything I had wanted to be in the first version of the game was done. I felt relaxed about the game. It was stable, nearing bug free, and polished. We released the third beta on June 3rd, along with a survey. Our analytics program for the game was reporting low usage, though we were expecting that after the pretty slow uptake on beta 2. Our survey, though on the large part favorable in terms of disposition of response, saw fairly poor rates of response. On June 11th, Matt and I met for lunch, and we set ourselves our final tasks for completion before submitting the game to Apple.

June 18. Not quite Christmas 2008. Not by a long shot. And what does the body of TextTumble look like, now that we’ve completed it? Well, according to David A. Wheeler’s ‘SLOCCount’ (an entirely arbitrary and only used to get some sort of wild ballpark look):

Is this entirely accurate? No. It’s not accurate because I didn’t keep track of actual hours spent creating the game; when I began, why would I? I was overjoyed to be working on my own video game. When I began to actually question myself and wonder what the degree of profits the game must make to make video game making a sustainable personal activity, it was long since past the point where I could attempt to recall with any accuracy how much time I had spent on the game in the nights before then.

The number is very instructive though. Our next games will be informed very much by the experience with TextTumble, and there will be a lot of thought given in the future as to how we can bring you the most fun experience while at the same time not overextending ourselves on the development effort.

I could not be happier, though. It’s finished. I expect that there might be one or two bugs that slipped by, but it is finished. I can’t wait to have our first game available on the App Store, and moreso, I can’t wait to tell people about it. One of our earliest testers told me on Twitter: “I spent over half an hour to playing your game last night”; I was overjoyed, because this is something I’ve wanted to do for a very long time.

We’re still waiting to hear from Apple about TextTumble’s status in the store. In the mean time, we’ll be creating videos, blog posts, and screenshots of the game, and showing you as much as we can about the game that we’re proud to have made. I’ll also be releasing the source code for the internal tools I’ve built to help creating the game, as well as talking a bit more on the blog about development effort and techniques learned (largely from other iPhone developers), now that we’ve submitted the game.

Maybe it’s best summed up by:

Time for the next level.

Clearly, a month has passed since the original time of this post, and I have not done any of the source code release things I intended to do. I’m publishing this post on the eve of the game’s availability in the app store, and right now all I can think about it is the next release. Priorities change. -CZ

I was looking for a way to recreate the behavior shown by some Core Foundation objects in that they may be cost-free casted to their equivalent type in the Cocoa framework. An example:

CFStringRef my_string = CFSTR("a string");
NSString* also_my_string = (NSString*) my_string;

It turns out that, should you have a need to represent a struct also as a subclass of some NSObject, you can do so by having your struct include a member of type Class (or struct objc_class*) named isa. The isa member is used by Objective C to access the table of methods and class hierarchy that your object (or struct, but we’re splitting hairs) is associated with. A much more elaborate discussion regarding the isa member can be found at Mike Ash’s website, which is damn near invaluable for learning more about Objective C.

Once you’e added the isa member to your struct, all that remains is to reflect your struct’s internal structure in the NSObject representation you’re creating. While it may seem obvious to some, it should bear worth noting that the order of declaration in your NSObject subclass should mimic the order of declaration in your struct. Here’s an example:

typedef struct {
  Class isa;
  int   some_number;
  BOOL  some_flag;
} MyDumbStruct;

@interface MyDumbObject : NSObject {
  int some_number;
  BOOL some_flag;
}
-(int) someMethod;
@end

Now that you’ve done this, you’ll be able to cast a properly created MyDumbStruct to a MyDumbObject instance. I say properly created because you will need to populate the isa member of your struct with the pointer to the Class object that correctly represents the class your struct will be associated with. You can do this by accessing the class method of the, ur, class in question. For example:

MyDumbStruct s;
s.isa = [MyDumbObject class];

That’s it – and here’s what you end up with in terms of capability:

MyDumbStruct s = { .isa = [MyDumbObject class],
                   .some_number = 2,
                   .some_flag = TRUE };
MyDumbObject *o = &s;
NSLog("My dumb object has a number: %i", [o someMethod]);

In my next post, I’ll show what I’ve been working on that actually uses this technique.

Addendum: This link elaborates on what I described above; it also describes usage of the @defs keyword, which will allow you to only have to declare the member variables for your Object once, and have them inserted in your struct at compile time.

• Feel an app has a shortcoming
• Work with shortcoming
• Curse shortcoming in bars / Twitter / work
• Spend 10 minutes googling to see if someone else has experienced the problem, and find out the feature has been there all along, and has some shortcut key assigned to it
• Facepalm

So, predictably, when I was griping over the lack of a quick file navigation feature like Emacs’ C-X b or Textmate’s ⌘-T, a few minutes googling solved my complaint.

The Open Quickly option (shortcut: ⇧⌘D ) not only gives you quick file navigation, it also (as shown by the screenshot) gives you quick jump-to-symbol navigation. I can only say: sweeeeet. (And also, facepalm.)

Visitors to the site might notice that there was a drastic (and long called for) redesign of the site. It is not, I assure you, the sudden manifestation of artistic ability on my part; rather, it was some great work done by Erik Goens, which has made the website look like something a little better than “derelict”.

I’ve got lots to say about Text Tumble, and maybe even a little bit to contribute about Objective C (pending some exploratory work on my own part), but I’m afraid I don’t have enough ready yet to go in depth. So, in the short term, allow me to share a little bit of undocumented ERB capability that came to me by way of Eric Hodel’s Cached ERB Template class.

Background: ERB is the library used to drive most Rails templates. When you write a view template and use this form:

This is my html file, <%= @some_ruby_variable %>

it will be processed by the ERB library (which is part of your Ruby Standard Library) and turned into Ruby code which may be executed. You can see it for yourself in irb:

> require "erb"
> doc = ERB.new("this is my template <%= @var %>")
> puts doc.src.inspect

The “src” attribute of the doc variable is the Ruby code that will be executed when the template is rendered. You can evaluate it yourself, like so:

> eval(doc.src)

or use the .result method to obtain the evaluated template result, like so:

> doc.result

Each time you do this, you will evaluate the generated Ruby code anew. The cost of evaluating Ruby code programmatically is not trivial – it requires parsing and interpreting the string of Ruby code as if it were a separate file that had been loaded into the specified context.

You can bypass this by using some undocumented functions in the ERB library. The important method to consider in this case is the method named: “def_method”. def_method is a method that allows you to evaulate the ruby code and “compiles” it into a method, allowing you to call the method later on without re-evaluating the string.

For instance:

> doc = ERB.new("foo bar <%= @baz %>")
> class Test; end
> doc.def_method(Test, "call_dynamic_method")
> t = Test.new
> puts t.call_dynamic_method

def_method will take the generated Ruby source and evaluate it in a manner similar to this:

> doc = ERB.new("foo bar <%= @baz %>")
> method_name = "call_dynamic_method"
> method_source = "def #{dynamic_method}; #{doc.src}; end"
> Test.module_eval(method_source)

You can see a more elaborate version of this technique in the Rails source in ActionView::Renderable#compile!. That means that, if you are using Rails, that the performance gains from this are already applied to you (and have been since Rails 1.0). However, if you are using ERB on its own, it’s a good technique to have at hand.

* Normalize your data. If you are querying the database for words, for example, ensure that your input data form matches your database data form before you issue your query. Using a dictionary as an example, make sure the words in your dictionary are either all upper-case or all lower-case, and that your input data matches. The difference between SELECT word FROM dictionary WHERE UPPER(word) = UPPER(?) and SELECT word FROM dictionary WHERE word = ? is at least n + 1 calls of UPPER. Buy yourself that time with in advance data treatment.

* Query on change. Chances are, your game state will only need to query when some user input or game event occurs. Should this be the case, your data structures should be such that they only query the database when absolutely necessary. For instance, using a word based game as an example again: if the user has spelled CAPITULATE, and the I in CAPITULATE is removed, your data structure should already recognize that CAP and LATE are still words (based on the previous query that also showed CAPITULATE to be a word), and not query the database again to rediscover this. While it places more of a burden on your game logic, you’ll avoid the cost of another scan across your dictionary against each potential word candidate.

* Indexes. This should be obvious, but your database should be aggressively indexed if it will be queried during the update loop. Create UNIQUE and PRIMARY indexes as relevant, and do so in advance.

* VACUUM. The VACUUM statement cleans up fragments left behind from successive INSERTs and DELETEs. You should VACUUM before shipping your database to clean up any work you’ve done in development, and if your database will be modified by the game, it’s a small thing to issue the statement during your game’s quit-cleanup phase.

* Cache failures or successes. Consider creating an in-memory cache of failures or successes ( whichever is more likely to happen based on your requests ), and use it often. You can whip together a simple ring buffer in no time, or you can create something more complex that expires stale data based on access count or time of last access.

Most of this advice has been inferred through repeated performance optimization of Text Tumble. If you’ve decided to do your database access in the update loop, this should help you shave off a few hours from your optimization work (and get closer to your target constant FPS ).

@obj = SomeClass.new
# Do stuff
def @obj.a_new_method
  # add functionality
  # to obj, specifically
end

Without entering into the mostly futile discussion regarding the numerous goods / evils of this sort of monkey patching, it was a cool piece of Ruby functionality I hadn’t yet seen.


$("div.of_interest").css("border", "solid 1px black").show()


A useful technique in situations where you plan on performing multiple operations on a given set of data.

I went straight to the source to determine how to create that sort of functionality – the JQuery source, mirrored on GitHub by JackDanger.

The relevant code was in jquery/src/core.js. The simplified version of the technique could be stated like:

var jQuery = function(selector, context){
  return new jQuery.fn.init(selector, context);
}

jQuery.fn = jQuery.prototype = {
  init : function(selector, context){
    /*
      Acquire the elements in question
    */
    return this;
  },
  // The rest of jQuery's functionality would
  // be defined in this prototype, such as
  // .each, .find, etc.

};

jQuery.fn.init.prototype = jQuery.fn;

The line of particular interest is the line:


jQuery.fn = jQuery.prototype = { // etc.


Here we assign the prototype to a separate variable, jQuery.fn, in order to refer to its members (namely the init function) in the main jQuery function. Then, in order to make sure that new instances of jQuery.fn.init have the methods declared in jQuery.prototype, we assign the jQuery.fn.init.prototype to the jQuery.prototype.

Now at this point, the jQuery function can return instances of “itself”. In order to chain from one function to the next, functions of the jQuery.prototype will either return this or jQuery(collection_of_elements) to allow the chain to continue.

There are lots of other cool techniques in the jQuery source – they’re obviously having fun pushing Javascript to what limits they can find.

So, I decided I’d write Spatial Query, a small JS library that lets you do all the gruntwork Vector/Matrix/Polygon work easily. And some not so gruntwork stuff, that I just needed anyways – like generating a convex hull, or the union of two polygons.

  $p([[0,0], [0, 10], [10, 10], [10, 0]]).convex_hull_2d();
  $p([[0,0], [0, 10], [10, 10], [10, 0]]).union_2d([[5,5], [5, 7], [15, 7], [15, 5]]);

Since the project that spawned this library dealt with geometric data, there is also some functionality that will allow you to compute distances between latitude and longitude, as well as conversion between Latitude / Longitude and WSG84 coordinates:

  $ll([lat1, lon1]).distance_to([lat2, lon2]);
  $ll([lat1, lon1]).vector();

Better explanation and more is available in the README

There are still some kinks in this version that I’ve got to iron out, so I’ve not even bothered assigning a number to it. Consider it version zero point ugly.

Thanks to my employer, the Indianapolis Star, for letting me open this to the public.

Now, here I am at 28, finally doing that. While I’ve worked on video game mods in the past, those really aren’t quite the same thing as doing a from scratch video game. (Even one that, were it not my own, I would think of simplistic – embarrassingly so, when compared to other games) And, while I certainly can make my way among the major points of a more explicit memory management language (additionally, where resources may be constrained, though saying that the iPhone is memory constrained may receive different reactions from different developers), it’s rather like saying I can speak Spanish. I’ve been trained to do so, and have been able to in limited situations, but my day to day usage is far different- (see, Ruby, JavaScript, Python, et al)

So getting started on iPhone development, while not impossible for me, introduced me to a different set of problems than I’m used to solving in web based apps.

* OpenGL: I’ve played with OpenGL in trivial apps off and on for years, always swearing I’d do a better job learning it, then never getting around to it. Now that I actually AM using it, I feel like I have a lot to learn when it comes to how colors combine when objects are rendered over each other, or image bit alignment. These aren’t things I need to know in the simple case, but I can see how becoming much more familiar with these things in the future will open a lot of graphical options to me.

* Data structures: Believe it or not, this one actually bothers me quite a bit. I’ve spent a lot of time thinking about how to represent a list of entities in memory where my primary method of access would be spatial. It may be naive, but I’ve been constantly thinking about how a “spatial hash” may work, and be implemented. I’m kicking myself now for my silly list style representation, when I could have spent just a day looking through the Algorithms book beforehand and implemented a balanced interval tree instead. This is a common thing for me, working with real time “physical” objects now – learning to reference my books and the internet FIRST, not after the fact.

* Appreciation for physics: I feel like knowing and learning more about physical simulation will change me from being an average developer to being a /good/ developer. While I don’t think I’ll ever author a paper on a topic, being more aware of where to turn for an equation that describes some physical phenomenon that accomplishes what I need (and being comfortable in how to translate that to actual code) will be invaluable.

* State : This is infuriating for me, as I should have known better. Maintaining state, changes to state, and centralizing access to this information is something I should have known right from the beginning of TextTumble. While the code is by no means unmaintainable, I see now the bad habits forming through independent has_done_x state flags littered through the code. Surprisingly (to me), abstracting all this not only would reduce the noise in source code, it could also lead to efficiencies in rendering by abstracting the state change facility of OpenGL. Only sending state changes to the hardware when they are necessary (obviously in retrospect) leads to an increase in framerate, which will obviously pay off later on.

There’s more of course, but the sum is: I really couldn’t be any happier than I am right now, (re)learning things and finally making a game.