games.greggman.com

Designing Better APIs

Is there a best design for an API? I don't know but I do have my own guidelines for good vs bad design. One guideline I try to follow is that it's good to design an API to make it hard to use incorrectly. Here's a couple of examples I've run into recently.

Here's an API for allocating shared memory.
$gatcode0[f]Can you see why this is a bad design? First off, 65535 inputs of 65536 inputs are bad. Why design an API where most of the time the program will fail? Of course if you're lucky the programmer will try some value that will fail and he'll catch the error before he ships. He may or may not get an error message depending on the environment his application runs in but at least he can spend a some time debugging until he finds out that he has to pass in an multiple of page size for bytes.

Some programmers might switch to this as a better design.
$gatcode1[f]That fixes the problem of most inputs being bad. It has another problem though which is the user has no idea that it's going to allocate a page each time. He has no idea that if he makes lots of shared memory allocations for small sizes lots of memory will be wasted.

Here's a better design.
$gatcode2[f]This design has the advantage that it doesn't have any bad inputs and by design it makes it very clear what is happening under the hood. No documentation is needed for the user of this function to know that units of page size will be allocated and knowing that he also knows he needs to find out what size those pages are and that allocating lots of small pieces will quickly gooble up the memory.

Of course there's the idea that sometimes you don't want the user of the API to have to know the underlying implementation but in this case he needs to know what's happening if he wants his program to perform well.

Here's another example. I was working with a shared memory system. The shared memory is shared between an untrusted piece of code and a trusted piece of code. The trusted piece code needs to make sure that anything it reads out of shared memory is valid. For example the untrusted piece might pass the trusted piece a shared memory id, an offset into that shared memory and a size and the trusted piece needs to verify the id is a valid piece of shared memory and the offset and size are in range for that piece of shared memory.

The API that was given was something like this:
$gatcode3[f]When using this API, every time the trusted code accesses shared memory it has to check that everything is valid. For example:
$gatcode4[f]The problem with that API is that it pushes the burden of validation on each and every piece of code that accesses shared memory.

Here's a better design.
$gatcode5[f]With this design there there is no easy way to get a pointer to shared memory unless it's a valid pointer. In other words, it's much harder to use this API incorrectly. The example gets much simpler.
$gatcode6[f]I would even go one step further for code like this which is I'd add a template so I can remove the cast from code that users this API.
$gatcode7[f]This change means I can get rid of the pointer arithmetic in code that uses this API so the example becomes.
$gatcode8[f]That's important because every time you use a cast it's another chance for an error. If you can compartmentalize any casting out of your code then you can avoid more errors.

I hope I've convinced you to consider designing your API to make it easy to use correctly and hard to use incorrectly. It's often not much work, it often makes the usage of the API far more clear without having to resort to documentation and could possibly save you and your team hours of debugging and frustration.

p4reconcile

If you are using Perforce (p4), sometimes you need a way to reconcile a folder. Both P4WIN and P4V have this feature to some degree. The command line p4 does not so here's a small program to do just that.

In p4 generally you are supposed to check things out. This tells p4 that you are editing the file and makes the file modifiable. When you go to submit your changes p4 knows what files you've edited, added or deleted since you already told it.

Sometimes though it's not easy to tell p4 what you've edited, added or deleted. Two common examples come to mind.

You are working offline.

p4 generally requires you to be able to connect to the p4 server so you can tell it that you are editing a file. If you are on an airplane or just somewhere where you can't connect to the p4 server then you have to remember to tell it which files you edited when you get re-connected. P4WIN and P4V both have options to help with this but the command line does not.

You have some automated process that creates files that need to get checked in to p4.

For example my current project has a documentation generation system. The build always generates the docs but for each release we actually want to check the built docs into perforce since our release system gets its files from perforce to make public.

After the docs are built it would suck if we had to manually tell p4 what changed. We could just delete the whole tree and then add all the files again but that would lose any history of what was edited.

So...

Introducing p4reconcile.

It's a python script so you'll need to have python installed. On OSX and Linux it's usually installed by default. On Windows you'll need to install it if you don't already have it.

Assuming python is in your path you can type

./p4reconcile

or

python p4reconcile.py

on windows

Where folder is one of your local folders that is being managed by p4. p4reconcile will create a p4 changelist that adds, edits or deletes files from p4 to make p4 match the state of that folder. Note that p4reconcile only creates a changelist. It is up to you to submit the changelist to make the changes permanent.

You can get p4reconcile here.

I hope you find this useful.

PS: One other thing you might find useful is looking at the source code. p4 provides a way for python to talk directly to p4 using the -G option. The -G option makes p4 communicate to python through python objects. This removes the need to parse p4 output which could lead to errors. You can see this being used by looking at p4manager.py which is a small python class to manage p4.

My $345 Quest for a Space Channel 5 part 2

This is the story of how I spent $345 for a video game, Space Channel 5 part 2.

It's no secret that I *LOVE* the Space Channel 5 series of games. I understand that they are simple rhythm games but the combination of style, musical dance numbers, music, characters, just everything about them made it one of my more cherished video game experiences. I loved the first one so much I made my computer desktop a Space Channel 5 theme and I made 2 Space Channel 5 clocks and sent one to the lead artist. I heard she had it on her desk for a few years.

The sequel came out in early 2002 and it was just as good. It might have only taken me 2 or 3 tries to clear it but it didn't matter. Like a good movie I just totally enjoyed that time.

So, about 8 months ago my nephew asked about Space Channel 5 part 2. He had played part 1 because I had given him my Dreamcast to when I moved to Japan in 2000, but he had never played part 2. "Never played part 2!!! Come over!!" So, one day he was over at my place. I had a Japanese PS2 I had traded for a PSX when I left Japan since you can't use a PSX in the states as they only have a Japanese tuner.

We popped in the disc and .... grind grind ... the PS2 would not play the game. I thought maybe the PS2 was broken so I got out another Japanese game but it played fine. That suggested it was the disc. Ugh, getting a copy of a Japanese game from 2002 from America is not going to be easy. So I thought, I know, I'll get the American version. Hopefully the localization will not have ruined it with bad voices and writing.

So, I order it from Amazon. $10 gets me the "Space Channel 5 Special Edition" which contains both the original and part 2. I only have an American PS3 so I pop in part 2 and start playing. It feels a little harder than I remember but I make it through the first 2 levels. Then I get to the 3rd level and I can't finish it for the life of me. In fact I can't even make it half way through. It could be that I suddenly suck at playing but I cleared the first one the 2nd or 3rd time I played. My skills couldn't have gotten that bad could they?

I start think maybe the issue is that I'm using a PS3. My older PS3 does some emulation for PS2 games and maybe that emulation is adding some lag. That is common for emulators. Try playing a Gameboy rhythm game on an emulator. It's impossible.

So, I'm like, WTF, I'll buy an American PS2. I order one from Amazon for $120. A few days later it arrives and I'm all excited to check it out. I come home, setup the PS2, pop in American Space Channel 5 part 2. Work my way to level 3. FUDGE!!!! It's still impossible to pass. My nephew is over and he tries. He's one of those gaming gods who plays Guitar Hero or Rockband on expert and he can't pass level 3 either.

Now I'm really curious. Could it be that this is a slim line PS2 and something has changed since the old full sized PS2s? Maybe they changed construction of the controllers? Well, I'm going to Japan in February so I'll go to the used game stores and try to find a copy of the Japanese version. When I'm in Japan I go looking and about the 4th store I find a BRAND NEW COPY for $25. I buy it all excited.

A couple of weeks later I get back to America, take a cab home, set my suitcase down and the first thing I do is unwrap the disc and pop it in to my Japanese PS2 and ..... grind grind. The exact same sounds as before. I'm so angry I go grab my hammer and SMASH the PS2!! Of course in my fit of rage I didn't take the new Space Channel 5 disc out and so that has been shattered as well. Ugh!!!

After I recover I look online to see if I can get a new Japanese PS2. Play-Asia sells them but there's no point in buying one unless I can get another Space Channel 5 part 2 disc.

Sooo, I ask a friend in Japan to not go out of his way but if he happens to wander by a used game store from time to time to please keep an eye open for Space Channel 5 part 2.

A couple of months go by and he tells me he found one! Yay! It's used but it looks like it's in good shape. By that time I luck out, my company is sending me to Japan to give a talk in just a few weeks. So, in June I get to Japan, my friend gives me the Japanese Space Channel 5 part 2 and I'm praying it works. I go to buy a new Japanese PS2. They are $150. Sheesh! I thought they'd be down to $99 or less by now. Well, I've come this far. I buy it and take it to a friend's. I plug it into his TV and .... I play all the way to level 5 without dying once. The Japanese version IS way easier than the American version.

Here's what I suspect happened. In Japan it's illegal to rent video games but not in America. Given that the game is so short the American publisher was worried they wouldn't sell any copies because people would just rent it, finish in a few plays and then return it. So, they instructed Sega to make it nearly impossible to clear hoping that would make it take longer and prevent rentals. Instead it just made the game impossible and absolutely no fun.

Honestly, I guess they were in a lose lose situation. Leave the game fun but short and no sales. Make the game frustrating and no sales. Maybe today with downloadable games they wouldn't have to make that decision. Games like Flower, Flow, etc can have a market when they can both be sold at a reasonable price and can not be rented or resold.

So there you have it.

Original copy in 2002:  $40
American version:       $10
American PS2:          $120
Japanese version:       $25
Japanese PS2:          $150
Used Japanese version: free (my friend gifted it to me)
-------------------------------------------------------
Total                  $345 ... chaCHing!

Yes, and I still love this game. And even more apropos, Micheal Jackson is in it! (advance to 7:00 on the video below)

Infinite Journey

I suppose technically this isn't the first O3D game since there are a few in our samples but this is the first O3D game created by a 3d party.

The developers said it took them about 5 weeks with no JavaScript experience and no O3D experience. They've clearly got some smart people there.

O3D Presentation at Google I/O 2009

I gave a presentation at Google I/O about O3D. In it I show getting started creating a small game in about 20 minutes.

(the sound cuts out for 30 seconds at 16:48)

You can download the a PDF for the slides here.

O3D

You want to know what I've been working on for the last year? This is it!

You can learn the details and try some of the demos at http://code.google.com/apis/o3d/

I think it's incredibly awesome but then I'm bias. For me what makes it awesome:

It runs on 3 platforms (Windows, OSX, Linux) and 4 browsers (IE, FF, Safari, Chrome)

Using it feels like the good old days of BASIC programming. Instant feedback.

You type some code, you press refresh, you see the results. You can even open the FireBug console in Firefox or the javascript console in Safari and type commands live, replace functions while your app is running, tweak variables, etc.

On top of that, it's easy to make your app editable in realtime. For example if you check out the beach demo, press 'e' to edit shaders or 'm' to edit material properties. Both of those editors took less than 1 or 2 hours to get working, if that.

It's easy to install and usable from anywhere.

Unlike say downloading a C++ compiler or some other dev environment this one will work anywhere you have a browser and the plugin installed and it's easy to install.

*) It makes a lot of things possible that were not before.

It's not just about flying teapots and games. It opens up the ability to make apps that were not possible with just HTML. A multi-image editor, a presentation application, a 3d mapping application, really, the sky is the limit. Vista runs on top of DirectX and OSX runs on top of OpenGL so if you want, make a windowing system on top of O3D.

2 things I hope I find time to do now that it's out.

1) Make a tiled map editor (ie, tUME Online). Using plain HTML it would be too slow to draw the tiles but using this it will be easy. I can make an online tiled map editor (tUME online?) and target it to a few popular indie games and then provide a way to target more.

2) Write a simple game programming tutorial. Because other than notepad, nothing else is needed. If you can browse the net you can run O3D and walk through my tutorials.

I hope I can find the time to do these inbetween continuing to work on O3D. I'm really excited about the possibilities.

BTW: I've got to put the standard disclaimer. The views expressed on these pages are mine alone and not those of my employer.