Writing Space Invaders for Pilot v1.0 on a PC

-by Scott Ludwig (a.k.a. PilotHacker) (scott@massena.com)
28 Jun 96

Space Invaders for the Pilot was written in C on a PC running WindowsNT, Microsoft's Visual C++ Cross-Development Edition for Macintosh, and Darrin's PC based Pilot SDK, before USRobotic's SDK was available. This SDK makes writing Pilot apps on a PC a reality. Everything about Darrin's SDK was reversed engineered by Darrin with no documentation; I hope he describes everything he went through. I was able to enjoy the fruits of that work in order to create Invaders.

I'm going to document some of the issues I worked through and the tools & tricks I used to do it, in case you plan to develop Pilot apps on your PC with Darrin's SDK.

The first significant issue was debugging. With the PC based SDK there currently is no way to debug instruction by instruction. If you're running on the Pilot, the best case at this point is to use the DbgTrace() calls, which will output strings from the Pilot's com port. If you have a terminal program running, you can insert trace calls and know when things are breaking. Unfortunately this is clumsy - the equivalent to debugging with printf. This also makes HotSync-ing clumsy: you need to close down the HotSync manager and the Pilot Install Tool before using terminal and vice-versa if you are using both off the same com port. To be really fancy here, get a switch box so you can switch your Pilot between com1and com2, or get 2 pilot cradles, one connected to each com port (I didn't have to do this). For quick output, make a macro that calls WinDrawChars() and output strings that way (I did this for most Pilot debugging). The PC SDK includes a printf-style FormatString() that you can use for fancy formatting.

I approached the majority of the debugging problem by making Invaders target both Win32 and Pilot. VC++ includes this nice feature where you can select the output target. By setting all this up, I could select Win32 and build and debug major Invaders functionality under Windows. Once working, I recompiled for Pilot and for the most part this worked great. This required separating the OS specific part into a separate section; I have a version of that section for both Win32 and Pilot. I would do this again for any major app I write, at least until debugging the Pilot directly (either hardware or emulator) is fast and easy.

Most of the Pilot debugging required for Invaders was debugging this OS specific piece. This piece was made as small as possible and was debugged mostly using WinDrawChars() to output strings on the Pilot screen. There were a few other other issues to work around that were not in the OS specific piece:

Spotting these required looking at the 68000 code generated by VC++. I used pem (part of the PC SDK) to do this. Pem acts as a debug target to VC++, and allows you then to use VC++ (while in debug mode) to inspect code, look at mixed C / 68K asm, find a place in your C code and say "go to disassembly" ,etc. Very useful (pem does not allow you to execute your Pilot application, at least at this point in time).

Adding sound effects for Invaders was challenging with no documentation. My algorithm: Decode SndPlaySystemSound(), then spend a day goofing around with SndDoCmd() to make reasonably sounding effects by hand. If you have a better way, I'd love to hear it. Even after getting the Pilot SDK directly from USR, it's pretty much a mystery the exact meaning of the SndCommandType structure fields. I have decoded some of it however, and am willing to share with anyone interested.

PilHack was very useful as well. I used it to decode some of the traps I needed (in the Pilot ROM, Darrin discovered that all routines are followed by a zero terminated string which is the name of the routine!), used it to determine the TimGetTicks() timer rate, and used it to determine the event ids and key ids that flowed through an application when various buttons where hit. All very much needed by Invaders.

There you have (most of) the Pilot specific aspects of creating Invaders. I used all aspects of Darrin's SDK (PilHack, Exe2Prc, Pem, and headers) to get Invaders working, and will continue to use it for future Pilot apps.

- Scott Ludwig (scott@massena.com)

Back to Pilot Software Development