Rebuilding ACK-3D for DOS

In my last post, I talked about my recent experience in revisiting the book "Amazing 3-D Games Adventure Set" by Lary Myers (published in 1995) for the first time in 20 years. I was never able to build the code back when I first got the book as a kid and it always bothered me. But it didn't stop me from playing with the map editor a bunch and dreaming of what could have been.

When I revisited the code included on the book's CD recently, I had a bunch of trouble building it even though I finally, after all this time, had the required compilers!

As I talked about in my previous post, there were three versions of ACK-3D included on the book's CD. I naturally started with the DOS-based one that was intended to be built with Watcom C++. That one resulted in executables that would crash. However, the pre-built executable included on the book's CD did not exhibit the same crashing behaviour, leading me to believe that the pre-built executables were built with a different version of the code than what was included on the CD. At any rate, that belief would not help me at all, so no sense in dwelling on it. Fortunately, the Windows version of the code and example projects were all buildable with relative ease and did not crash in random ways. So at the very least, I could start with that working code base. As a bonus, according to the book, the Windows version was the latest version of the ACK-3D code anyway (well... the "latest" at the time the book was published, in 1995).

In my last post I decided to try diving into the DOS code that did crash to see if I could fix it. After I wrote that post, I continued playing with that code a bit more but I was not able to track down the apparent memory/linked-list corruption bug that I had found. Eventually, I figured it was probably not worth the effort and that I should instead focus my efforts on porting the Windows version of the code back to DOS. Additionally, comparing the code listings printed in the book with the code included on the CD, it is quite clear that all of the chapters that dissect the ACK-3D code in detail are all doing so with the Windows version.

I'm pleased to say that I have now finished doing porting and cleanup/fixing work and am pretty happy with the result which I have published to a repository on Github.

Here's a summary of the changes from what was included on the book's CD:

• Removal of Windows compatibility. I am not interested in it (currently), and anyone who is can just use the code that was on the book's CD. Adding it back so you could compile a Windows version with Watcom C++ should be fairly simple though.
• Replacing the build scripts for Lary's custom MK.EXE tool with Watcom makefiles.
• Copying keyboard and timer interrupt handling from the FDEMO/MALL demo project sources to ACKLIB itself, replacing the existing interrupt handlers. The FDEMO and MALL projects were originally built with Watcom and their interrupt handlers were built for DOS/4GW compatibility, versus what was leftover in the Windows sources for ACKLIB which was intended for the Borland PowerPack for DOS.
• Re-adding GIF bitmap support. This was talked about in the book and was removed because of GIF patent issues in the '90s. That patent has since expired and fortunately Lary accidentally included a fully implementation of ACKGIF.C on the book's CD anyway! Oops. So I just added it back in.
• Removal of some unneeded source files (e.g. KIT.H), and other minor code cleanups of that sort.
• Fix MOD player issues in the FDEMO and MALL projects. Background music never worked, even in the pre-built FDEMO and MALL executables included on the book's CD. But it turned out to be fairly simple to fix.
• Sorted out the mess that was the DOS map editor source files and build scripts. There were actually two versions of the DOS map editor included on the book's CD and the source files for both were jumbled together in the same directory. Ugh.
• Fixed assumptions about paths to files being loaded by the DOS map editor and BPIC.EXE tool for building ACK-3D resource files. These tools both always assumed everything was in the current working directory, which usually meant you needed to copy the tools around to each project's asset directory (that is also how the files on the book's CD were laid out). Quite annoying. Now you can simple place MAPEDIT.EXE and BPIC.EXE somewhere on your PATH and be done with it.
• Probably other things that I've now forgotten.

Comparing my re-built version of both the FDEMO and MALL projects with the pre-built executables included on the book's CD, it does feel like the performance was faster with whatever version of the code Lary had used to build them with. It's not a super massive difference, but it is noticeable to me. I have not yet dug into this however. Doing a simple diff between both versions of ACKLIB shows there are a bunch of changes so it will take some time to compare.

One thing I thought would be a fun mini-project for myself to add to this was to build an example project from scratch. Chapters 11 and 14 of the book talk about what is needed to actually write an application from scratch using the ACK-3D engine. Chapter 11 is mostly just about the initialization steps, while chapter 14 is a full-blown "how to build a Windows ACK-3D application" tutorial. The result is nothing special, but it is quite useful. However, it is Windows-specific. I wanted something like this project but for DOS. And actually, it was quite easy to get up and running.

(I drew the blue frame in Deluxe Paint II, excuse my rather simplistic "art", heh).

This project just re-uses assets from the FDEMO, MALL and Station Escape demo applications included on the book's CD. It was kind of fun revisiting the map editor after all this time. Less fun was figuring out how to set up all the configuration files necessary to first, get everything loaded into the map editor, and then to build an ACK-3D resource file (the pics.dtf files that all the demo projects use). It's not the worst thing in the world, and thankfully there is literally a book written on the subject to assist me with it, but it definitely could have been simplified I think. Actually part of that simplification process was the Windows version of the map editor which could read ACK-3D resource files directly. The DOS version of the editor is not capable of this.

Most of the existing bugs in ACK-3D remain. Things like the "push-wall" secret doors (ala. Wolfenstein 3D) not rendering correctly in many cases. It looks kind of funky sometimes actually:

The secret doors otherwise function perfectly. It just appears to be solely a rendering glitch. I suspect a problem with the ray casting distance calculation but my initial attempts at fixing it proved unsuccessful. One more reason to re-read the book, as I'm sure with better understanding of the math and the engine's internals it would be simple to fix.

Otherwise, everything is now working great! I'm quite happy with the result (heh, it only took me 20 years...). That all being said, I'm not sure that I would actually want to base any project off this code as-is. As I've spent time dissecting this code I've become somewhat turned-off by it, heh. Tons of global variables, large functions that do a ton of things, messy formatting, etc, etc. It is largely a product of the time it was written honestly, so I cannot fault Lary alone for this. The industry has grown quite a bit in the last 25+ years.

That all being said, now that I can successfully build the code, I would now like to re-read this book from start to finish and use it to write some type of similar engine from scratch using the techniques Lary discusses. I'm not sure when I'll get to this though, as I've been fiddling with Turbo Pascal related things a lot recently (upcoming post on that hopefully sometime soon, maybe).