Faced with ample time due to Covid-19 pandemic I decided to pick up a book that has long been in my vintage Apple collection. It is a 1981 version of Jef Raskin’s excellent The AppleSoft Tutorial, acquired by someone from Bay Port High School in Green Bay, Wisconsin. As a native of that city this manual survived several collection purges through the years.
The last time I picked it up was in 2009 for the Retro Computer Challenge. My only coding attempt in my adult life resulted in a program called FIRESHOW, which launched randomized fireworks. It was largely autonomous and has little actual interactivity. In the decade interim I had forgotten nearly everything I had learned about AppleSoft BASIC.
As I was killing time I followed the subroutine on page 85 that draws a horse. The results had me giggling, so I decided to see if I could add hooves. Then I wanted to see if I could get them moving. What if I moved the horse? From that point on I just kept on going.
Design Philosophy
Games of the 1980’s were often cruel in their level of difficulty. This was a function of extending playtimes in order to justify the cost. A $50 game in 1984 cost a lot more than a $50 game in 2020 when adjusted for inflation. I never enjoyed that aspect of of gaming while growing up in that decade. As an adult I also find that my upper limit for most gaming sessions is about 20 minutes. So I wanted to create something that would be forgiving and completed in a single short sitting. If you bet the minimum for each race you will still come out with a positive wallet balance in the end, but you may not make the Top Ten list where you can add your name. This also adds a little challenge element. You can compete against yourself or others who play the game with you.
I could have kept on going with the skills I have learned the past three months. Adding multiple players, custom horses, more robust statistic variables, and other neat features are well within my means. Perhaps in HORSE RACE II: THE HORSENING? For now I am content with what HORSE RACE is. A nice little game that is easy to play and 100% complete.
Programming
It was not an easy undertaking by any stretch. Even with the modern convenience of accurate Apple II emulation I still faced hurdles. Several times I coded for hours only to make a mistake in saving, which overwrote all my work. One bug that resulted in a memory leak took 16 days to solve with a single command. Those challenges, and meager computer specs, forced me to think of creative ways to solve the problems that arose.
One particular example of where an error led to a feature was the photo finish. Although a photo finish is normal for a real world horse race, the idea had not occurred to me. But a misplaced accumulator variable determining where to draw a horse on the screen resulted in it being drawn much farther to the right than it should have. When thinking about how to contain that misplaced variable, my photography skills provided influence. Contain the horses within a box, of which could be a polaroid photo finish. It is theme appropriate and has the benefit of being consistent with real world horse racing.
The experience also forced me to reach out to the Apple II Enthusiasts community to ask for help where appropriate. There are numerous well documented resources for anyone trying to do this. Some of the code in HORSE RACE is lifted directly from those sources, namely sound generation and file handling.
If you look at the code for HORSE RACE, it is clear that its structure arose organically as I was learning. It is a spaghetti dish of GOTO, GOSUB, and FOR/NEXT loops. But if you boot the 5.25″ floppy it performs just like a retail game.
As an aside, I find it extremely satisfying that Apple’s iCloud automatically backed up my progress snapshots. A current Apple product is supporting data for their computers from three decades earlier.
File Structure
HELLO – AppleSoft
ProDOS formatted disks will automatically boot HELLO when the Apple II is turned on. HELLO contains the menu that informs the player of their options. They can start the game, read instructions, see the Top Ten list, reset the Top Ten list, see instructions for IIGS users, and a short section about me.
TRACK – AppleSoft
This is the initial file that I started programming. It is clear within lines 0 – 1000 based on the GOSUB and GOTO calls that I started with little regard to what exactly this program would contain.
The vast majority of the code handles the animation sequence from race start to race finish. A lot happens under the hood to make two little hooves move!
TITLE – AppleSoft
Pretty self explanatory.
This was split out into a separate file because I erroneously thought TRACK had eaten up too much RAM that was causing the game to crash consistently on race #3. It turned out not to be the case, but learning how to link AppleSoft files together became useful when I had to segment the expanding program.
The only other thing worth noting here is that title loads the machine code for tone generation before loading TRACK. This will reside in RAM for the duration of the game.
TOPTEN – AppleSoft
Shows the outcome of your betting. If you lose, it shows you one message. If you win it asks for your name to be added to the list. This was a huge challenge as the documentation to save and load text files was somewhat inconsistent online. In addition to that, the behavior of virtual and real world hardware treated the code with differing results. It took two weeks to make it work properly.
For some reason I could never get the modified name and score data to read or write properly when using a FOR/NEXT loop. So I did the most inefficient thing possible and typed out every adjustment line manually. If I didn’t mention it here you probably would never know that because it just works.
TOPTENVIEWER – AppleSoft
A variant of TOPTEN, sans name input or game over dialog. It took four attempts to get this because I kept overwriting it. Moral of the story: Don’t drink and code.
TOPTENRESET – AppleSoft
I created this as a development tool to reset the TOPNAMES, TOPSCORES, and SCORE text files when I was testing things. If a file got corrupted, or data needed to be cleared, it would go ahead and reset everything. I then realized there was a real world use case in the game in case someone entered an improper name.
TOPNAMES – Text File
This text file stores the ten names in the TOPTEN list.
TOPSCORES – Text File
This text file stores the ten scores in the TOPTEN list.
SCORE – Text File
This file transfers the wallet variable from TRACK to TOPTEN.
How do I play HORSE RACE?
You may download the HORSE RACE disk image here.
If you like the game I accept donations at Venmo: kenfager or Paypal: kenfager @ gmail.com.
The best experience is of course going to be on an actual Apple II computer. The game was tested on IIe (stock and enhanced), IIc, and IIGS hardware. However I am unaware of how the game will run on an original II or II+.
I highly recommend using the excellent Floppy Emu. Apple IIGS users will need to set the system speed to NORMAL.
However emulation is going to be the easiest solution for most. AppleWin for Windows, Virtual ][ for Mac, and LinApple for Linux will run the game. You will also need an appropriate ROM image to boot the a virtual Apple II.
HORSE RACE is of course available on 5.25″ floppy disk directly from me at $5 + S/H. Please email kenfagerdotcom @ kenfager.com to obtain a physical copy.