Resurrected Entertainment

Archive for the 'Programming' category

Qt for Games – Niblet #1

July 19, 2008

A few days ago, I decided to experiment with Qt as it applies to game development. You haven’t heard of Qt? Well, it’s an SDK for cross-platform development which has really started to take off in the cross-platform arena over the last couple of years. KDE, a desktop platform for Linux, is based on the Qt library; so is the VOIP application called Skype. They even have a mobile platform called Qtopia for those who are interested in small devices. You can find out more information on the Trolltech website.

To begin the project and to get the brain juices flowing (after the second cup of coffee, of course), I wanted to come up with a small, interactive demo which would make use of some of the classes related to QSceneGraph and QGraphicsItem. I also wanted to play around with the layers a little bit and see how suitable they would be for games. The first program is a simple one indeed; in fact, it’s not really a game at all – unless of course you’re really bored and you start to chase invisible dots on your screen. Just run demo, and you’ll understand what I’m talking about.

I am basing this project off a classic so that I don’t stray too far off topic. MS-DOS 5.0 shipped with a QBasic game called Nibbles. The game play revolves around a worm that you control through a maze of walls while looking for food. If your worm collides with a wall or itself, you lose one life. The difficulty revolves around the worm’s velocity; it gets faster as you advance. The idea is to use that basic game as a model at first and build on it a little as time goes on; this will help to keep the project focused, which can be a real challenge for those who are new to game programming. To get things started, I have decided to dub the codename for the project: Niblet. The real name will be decided, if and when, this Qt game comes together.

The first problem is the worm, of course. It needs to snake around and grow to certain lengths when food pellets are ingested (or numbers as was the case in the original game).; I also like the idea of it shrinking in response to an item collected during the progression through a level. Anyway, the rules can be fleshed out later. For now, let’s just get a very basic framework up and running. To compile the little demo, just run qmake and then make if you’re on Linux or open up the project in Xcode if you’re using Mac OS X; Windows users can open the project in Microsoft Visual Studio. If you’re using Mac OS X Leopard, I suggest you try out Qt 4.4 which will produce a proper project file for Xcode 3.1.

Dynamic Path Demo using Qt

As you can see, very little code is needed when using Qt. If you were to write the same program for Windows using DirectX or even through the GDI, you would need considerably more code just to handle the application start-up process and surface initialization. But that’s the beauty of these SDKs, they essentially handle a lot of the routine programming so you can concentrate on building your software faster and better using these handy libraries.

Building Software with DOSBox?

May 12, 2008

DOSBox LogoI have written about DOSBox in the past and I have nothing but good things to say about it. It’s a great project whose people continue to push for greater compatibility, speed and functionality. Over the weekend, I tried to use DOSBox as a development environment for compiling DOS applications using the DJGPP 32-bit compiler and associated development suite such as RHIDE, Allegro, GRX libraries, etc.

Sadly, it didn’t work out so well since a number of common tools simply didn’t function that well in v0.72. I’m not terribly disappointed, since the emulator takes forever to compile a project in its environment, and wouldn’t be suiteable for long term development. I’m raising the issues here in case anyone tries to use DOSBox in the same way.

First, let’s talk about what did work. DJGPP for starters. It works just fine; albeit, the compilation and linking process does take a while. Some might argue that this is all you need to develop a project, and while that might technically be true, it certainly doesn’t work out for anyone trying build something more than a “Hello World!” application.

So, what didn’t work? Well, I tried four different editors: edit (the one which ships with your MS-DOS operating system), TDE (Thomson-Davis Editor – one of my favourites), MEL (Multi-Edit Lite – another great little editor), and RHIDE (the development environment which you can install alongside DJGPP). I didn’t try VI/VIM, but I might sometime later just because I’m curious.

First out of the gates, Edit simply wasn’t suitable in an environment where tab characters are important. It simply replaces them with spaces and continues on its way. Too bad since the editor is simple and to the point. Although, it really isn’t a good solution since it lacks one of the most basic development features like syntax highlighting.

DJGPP makefiles will not tolerate spaces when there should be tab characters. No, it’s not being quirky, it’s in the POSIX standard after all but it doesn’t make it any less annoying. So, the solution is to switch to an editor which respects tab characters and does not try to convert them to nasty spaces. So I jumped to a more sophisticated editor: TDE. Sadly, I was let down again, due to a bug (could be within TDE or DOSBox) where the cursor was not visible while using the editor. It was a little like fumbling in the dark trying to find that blasted light switch.

After some research I found MEL, so I installed it and tried it out. The editor was well laid out, the cursor showed up, and it respected my tab characters. Super, finally something I can use! Alas, I soon discovered that our relationship would never last. You see, MEL doesn’t use tab characters out of the box, you need to turn it on through one of the configuration dialogs. No problem, right? Well, it doesn’t seem to remember the setting once you save it, so you need to set it every… single… time you load the editor. Hrrmph.

“Well, it’s time to bring out the big guns!” I thought. I had used RHIDE in previous development projects and found the environment quite enjoyable for the larger ones. I typed in the command to fire it up and… whammo! Congratulations, it’s a bouncing baby SEGFAULT. Sigh. I don’t know about you, but four editors is enough experimentation for one day. If you find an editor which works well and meets my humble requirements, please post it in the comments.

Anything missing which should be added? Well, you’ll certainly want to add in some basic DOS utilities such as XCOPY, DELTREE, ATTRIB, and what not. It will make your life much easier. It would also be great for DOSBox to incorporate a configuration reload command, so you don’t need to exit the emulator in order to reload the preferences file. For now, I’m going to use one of my older development boxes for this software project, and stick with DOSBox to run my games.

PGP: Source Code and Internals

April 28, 2008

PGP BookMy copy finally arrived the other day and I am elated. Now, before you make another hasty buying decision based solely on my opinion, and on a single line of text, there are a couple of things worth mentioning about the book. First and foremost, the book does lack a few structural elements like plot and little things like paragraphs. Having read about the history of Philip Zimmerman and his toil with the U.S. government, I already knew this before I purchased the book.

It does contain source code. Lots of code. The entire PGP program, in fact, including the project files. The book was sent to print because the digital privacy laws the government was attempting to enact at the time, did not cover the printed page. If all you want is the source code, you can simply find it on the Internet. Looking for a specific version, especially an older version, is more difficult and may be fraught with export restrictions.

The story behind the printing of the book is a fascinating history lesson and one we should all be concerned about, even if you live in another country, since we all know governments are not terribly adept at learning from their mistakes.

QBasic

December 5, 2007

QBasic EnvironmentWhen I mention QBasic to some people, they immediately think I’m talking about Quick BASIC. The two products, however, are a little different. They were both created by Microsoft but Quick BASIC is basically a super set of QBasic. QBasic has an interpreter and an editor built as one package; I hesitate to call it an IDE since your projects could only use one module at a time. It was also limited in the amount of memory available to the program and the amount of memory available to the editor. I experienced the latter problem only once while creating a game involving viruses and robots (I didn’t get around to naming it); the editor just started losing lines of code I had written and was behaving eradically. Eventually, I became frustrated and moved on to other and presumably smaller projects.

QBasic made its first appearance with MS-DOS 5.0. It came with a few example programs and games. One of these games was called Nibble. I love this simple game, even to this day. It’s a little similar to games like Centipede, although the game itself is far too simple to make a reasonable comparison. The goal for each level is to gobble up the numbers that appear in random locations. Each time one of those numbers gets consumed, your “snake” grows a little longer. You have to avoid running into the walls of the level, which get more complicated as you progress, and you must not run into yourself. As you attain higher levels, your snake becomes faster and faster. This game was never synchronized with the system clock, so if you play the game on a machine made today, it would move around so quickly as to render the game unplayable.

I have often thought a game like Nibbles would make an excellent game to practice your porting skills on other platforms. It is sufficiently interesting to make the project worthwhile and could be adapted to play well using almost any input device. It could also be rendered using a simple text mode, just like the QBasic version, or you could enhance it in a graphics mode using imagery, vector graphics, etc.

QBasic also introduced the concept of functions and other forms of structured programming. GW-BASIC could only remember and execute your program if each line was prefixed by a number, or right away if you are using instructions in immediate mode. As you added and removed lines from your code, there were a couple of functions to reorder or renumber your line numbers when you ran out of room.

The concept of a function didn’t really exist in GW-BASIC; instead, it allowed you to jump to a particular line number using commands like GOTO or GOSUB. The latter was more like a function since you could jump to a specific region of code and then return from that function when the code had finished. GW-BASIC also supported one line functions which were handy for calculations. Although QBasic could still use line numbers, it encouraged the use of named labels for functions instead. Despite my work with Amiga’s BASIC, I still preferred the old way since I had been doing it for so long. It took me a while to adjust to the new program structure at first, so I purchased a new QBasic book after upgrading and essentially dove in head first.

Interrupts would become increasingly important for me in the future, but at this time I knew little about them. QBasic had no direct interface for handling interrupts, but it could handle interrupts used by the system’s timer:

ON TIMER(n) GOSUB MySubRoutine

Having no functionality to manipulate interrupts meant there were no functions to gather information about input devices like the mouse. Despite this seemingly major failing, all was not lost. While it could not handle input from the mouse directly, you could make use of a machine code sub-routine which could get the information you needed, like position and button states. You could use techniques like this to gather information from other devices.

QBasic also introduced me to one of the greatest time saving features ever created: the debugger. A debugger can be a separate program or feature within an IDE which allows you to trace through your program and examine variables and addressable data as the software executes. One of the core features of a debugger would be the ability to set a break-point at a specific addressable location that corresponds to a precise line within your source code. Before debugging, I was tracing through my program by hand and using PRINT commands to dump the contents of a variable. Even today, there are professional programmers who don’t use a debugger, either by choice or lack thereof, and choose to examine how there software operates by sending information to a log file or an output stream of some sort.

GW-BASIC

November 29, 2007

GW-BASIC PromptI first discovered this little gem while poking around on my Tandy 1000 RL computer back in 1991. Because I was familiar with various versions of BASIC already, I was able to fire it up and immediately begin writing fairly simple applications. However, there were differences to Atari’s version of BASIC, and no discernable way to figure that out without a book or some other documentation. I poked around on a few of my favourite Bulletin Board Systems (BBS) and found a small cache of programs written in GW-BASIC. I downloaded each of them, spending all of my download credits in the process. I poured over them line by line and found myself having more questions than answers.

Many new programmers today expect there to be some sort of documentation available when they learn a new technology. It’s an expectation that has evolved over the years. Today, it would be practically unheard of if you couldn’t find some resource describing the software on the Internet, or some blurb in a book, or even bundled with the product. However, when I started looking for a book on GW-BASIC (version 3.23 to be exact), it was darn near impossible. The people I spoke with had no understanding of programming, let alone a specific language. The computer sections in the store were spartan compared to the sections you find in stores today. In fact, several years later, I still needed to special order the books I wanted through the book store; even today, I usually order my titles through Amazon since a store like Indigo usually doesn’t have them in stock.

I eventually wandered into a local computer store – I was attracted by a demo of Wing Commander II playing on one of their expensive new 486 machines, so I went in to ask them if they knew where I could get my hands on some material. I spoke with the owner and he seemed to recall seeing a book for BASIC in the back of the store. He left for a couple of minutes and returned with two books under his arm. One was for the exact version of GW-BASIC I was looking for and the other was a compatible book for MS-DOS. I was ecstatic and I nearly fainted when he gave them to me for free. I don’t remember what I said to the man that day, but I’m sure it wasn’t adequate.

I wrote so many programs in that environment. I think I still have a few of them today on floppy diskette. They were simple at first, like simple word games such as hangman. However, it wasn’t long before I discovered how to increase the resolution and colour depth and draw simple graphics. I had already written code for the Atari which made use of pixel plotting routines or simple geometric shapes. There were pre-canned routines the Atari provided for drawing shapes, along with a few parameters for style, colour, and shape. GW-BASIC was similar but provided several more commands and options. With a smaller font and a higher resolution, debugging within BASIC became more feasible. I still couldn’t scroll, but at least I could view a larger portion of the code on the screen.

Sound was also possible through the PLAY command, or if you were so inclined, through a custom routine written in assembly language which could be written to generate all sorts of sounds like noise or even speech. I had converted several songs using music sheets and converted them to their GW-BASIC equivalent. Not terribly exciting, but it did make for some creative demos which seemed to impress onlookers.

Some of the more interesting projects involved controlling external devices like printers. I must have programmed my software to use every conceivable option available through my Star NX 1000 II dot-matrix printer. I could instruct it to use standard type effects like bold and italics when printing text, but I could also program it to print graphical data like images and shapes. I even created printed graphics for the Mandel Brot set by rendering the fractal to my printer instead of the screen, one pixel at a time.

Perhaps the most interesting device was a robotic arm which was controlled through a series of commands dispatched through the parallel port. I didn’t have access to such a device at home but my school eventually purchased one, so one of the teachers decided to create a contest for students. Whoever could program the robotic arm first, would win a special prize. The task was to pick up a piece of chalk and draw a picture consisting of at least four shapes. It was a fun contest and I walked away with a pass which granted me as much lab time as I wanted.

Before I upgraded to a new machine and moved to a new version of MS-DOS, I was intimately familiar with every command in that book, even the more obscure commands like CHAIN and PCOPY. Although, the really obscure commands were still a mystery. I didn’t know you could actually write assembly language routines in GW-BASIC using DEF USR and USR commands until sometime later.

Neverball

September 28, 2007

While I’m waiting for OS installations or code compilations to finish, I’ve been playing this great game on Xandros called Neverball. It’s a game similar to Monkey Ball, which is one of my faviourites on the Game Cube. It’s very polished for an open source game and is complete with the exception of minor enhancements or bug fixes from time to time. Its only dependencies on Linux are the most common SDL libraries: core library, SDL_image, SDL_ttf, and SDL_mixer. It doesn’t compile so well on Intel Macs, but I should get that working pretty soon. I believe there is an Xcode project file available too for those who choose to take the quick and easy path. I may soon walk the path of the dark side, depending on how quickly I can resolve these obtuse linker errors.

Game Development: Introduction

September 18, 2007

There are two sides to every coin. Game development can be hard or game development can be easy. These are relative terms, of course. Just because writing a game can be easy, doesn’t mean your grandmother could do it (although I wouldn’t hedge any bets, especially with mine). Personally, I think writing any finished application is an achievement for any programmer working alone. With the help of my colleagues, I have produced several applications which have made it onto store shelves, but I won’t take the credit since my part was just one piece to the puzzle. Of course, some applications cannot be programmed by just one person. Oh sure, one software developer could work for years or decades to achieve their goal, but who has the time and talent required to design and engineer something as complex as Metroid Prime, Photoshop, or the KDE Desktop on their own? It just doesn’t happen in the real world because life inevitably steps in and takes over.

However, all is not lost for the eager programmer setting out to create a game. It all boils down to following a few simple rules and having a few good resources available. For the next couple of weeks, we’ll look at some of the tricks of the trade and present a list of books which I have found very useful while exploring game development. So, without further procrastination, let’s dive right in to our first topic.

Game Design – The key difference between finishing a game and an unfinished hack is managing expectations. Yes, we would all love to design and build a game like Halo, but that’s not terribly likely and will almost certainly lead to failure. Instead, try and reduce the scope of the project by carefully choosing the characteristics of a game you wish to include. Care must be taken to use only those features which are absolutlely necessary. You should spell out how you want your game to work, what features need to be written, and any third party tools you plan to use which can save you time. In essence, you need to write a bit of documentation. Yes, I know, documentation is a bore and some of you may find it difficult. But you don’t need to write a best-selling novel, just outline what you want to do and how you want it to work.

By translating those exciting images and ideas you have into something concrete, you’ll be able to assess your goals and overall design much more easily. It also makes your game much easier to digest for other people. If you wanted to hire an artist, for example, you would need to describe the concept in fragmented conversations over the phone or via the Internet. It would make the job of the artist so much easier if you had the design for the game already completed. In fact, most artists (the smart ones anyway) won’t accept a contract without a working game design in place. Without this document, you would be unable to tell the artist which assets need to be produced now and what can wait until later. If you know all of the work which must be completed before the artist draws a single pixel, he/she will be able to commit to a schedule and a price.

Over the last few years, several good books have been written on designing (and managing) game development projects. However, these books tend to focus on many details which are only relevant or important to large scale projects. Naturally, there are excerpts which you will find useful, but don’t get overwhelmed by the sheer volume of information. Generally, you don’t need to concern yourself with all of those details; the object of this lesson is to finish a fun game you want to create in your spare time. If followed some of those books to the letter, it would take ages to complete a project and you may find your interest in the project begin to drift after a year or two.

Project Management – When you are creating a game by yourself and for free, I don’t recommend setting a schedule. Schedules are for people and companies who must release the game in a timely manner because their economic futures depend on it. The bottom line for you and me, however, is that schedules aren’t very accomodating for new game developers and they aren’t very much fun when you’re ten weeks behind your target date. If you don’t need to release a game in six months, then why would you care that your line drawing algorithm is taking twice as long to craft as expected?

On the other hand, you could always use the project as a way to enhance your project management skills, which is admirable but you may find the accuracy of your estimates vary considerably. This is partly due to life, who once again chooses to interfere with your project. As a programmer at work, I can count on having at least five or six hours a day for solid work. At home, my free time will vary wildly. If you only consider the cost (in time units) and forget about dates, then you may find your estimates more useful. If you really insist on reading a book to brush up, then I recommed:

  • Joel Spolsky’s book entitled Joel on Software. It’s a compilation of articles for novice program and projects managers. It has a number of good practical tips which can benefit almost any software project, including projects done by the hobbyist.

Atari BASIC

September 11, 2007

Atari BASICMy experience using BASIC is something I cannot easily put into words. I had never been exposed to programming before, so at first I had a hard time understanding the concept. I started out slowly, playing around with some simple commands which were described in various issues of ANTIC magazine.

Actually, my first experiments were much simpler, consisting of just a single command being given to the interpreter. I loved being able to control the color of my background or make a bunch of erratic and tuneless beeping sounds through our television speaker. For the first time, I was in control of the machine, even if all the machine did was squeak and change colors. I didn’t learn about how the interpreter used line numbers until my father picked up a copy of Atari BASIC by Albrecht, Finkel, and Brown. It was during my sessions with this book that I also learned about control flow statements, looping, data types, and loads of new commands. It still took me a while before I learned how to save my creations to disk, but it was too late to go back by then. The bait had already been taken, and it wasn’t long before my parent’s saw what was happening: I was hooked and I was going to need funding for my new hobby.

For the most part, I learned most of my Atari BASIC programming skills through my father’s subscription to ANTIC. This magazine was devoted to the Atari 400/800 series of computers which were popular in the early to mid-1980s. Another popular magazine at the time was A.N.A.L.O.G., but I didn’t have access to as many of them as I would have liked. I enjoyed the latter because it had much more diverse and complex programming examples and articles. When I got my hands on our first copy, I wasn’t even pausing to read most of the articles, I just brought it straight to the computer and began entering the source code in by hand. Sometimes the process took hours and my code was often marred by spelling mistakes and missing commands. I eventually learned these mistakes were called bugs by people in the software world. Tracing through these programs taught me a lot about programming and debugging. Mostly, it taught me to be careful while typing, and began to practice my typing skills using another software program designed for this purpose. To this day, however, I am mostly a 3:4 finger typist; three being the typical number of fingers I use for my left hand, and four being the perfect number for my right.

My father eventually purchased a dot-matrix printer for the system. It was a Star NX-1000 II, and I absolutely adored this printer. I quickly learned how to use it in BASIC and began printing reams upon reams of code. I enjoyed debugging and enhancing my programs using the printed form. It was an excellent way to get a handle on the whole problem, since the environment in the interpreter prevented you from seeing the whole picture easily. The font was just too large and the software did not have the ability to manually scroll the view. In fact, the concept of a window wouldn’t be realized on desktop computers until a few years later. In order to examine a block of code, you needed to continually LIST the sections in chunks or just dump the whole thing at once and wait for the area you were interested in to come into view. The continuously scrolling source code was slow enough you could track it with your eyes, and once you saw the region of code you wanted, pressing the break key would stop the process.

Another great feature of the Atari’s BASIC language was the ability to examine and modify specific bytes in memory. At the time, I don’t think I fully understood the concept of a memory address, at least not the way I understand it now. It was more abstract for me than other concepts. I knew that writing certain integer values into locations identified by other integer values allowed me to play music and control the colors of fonts and backgrounds, but I didn’t associate these number values to a physical address in the machine. In fact, I’m not sure I even truly understood what memory did, other than the typical high-level rationalization: if you buy more RAM it will allow your computer to play this game or use that piece of hardware. I generally understood memory to be a good thing. The more you had, the better off you were.

It wasn’t until I started programming the Commodore 64 (C64) with a friend of mine that I began to understand its function and organization. A big part of that understanding came from a device called the Super Snapshot cartridge which could plug into a port on the Commodore computer. This miraculous device had a number of cool features, and one of those features allowed the user to interrupt a game (or whatever) and examine/modify the contents of RAM and then return as if nothing had happened. Initially, we used this device to cheat on games by changing the number of lives, strength, loot, whatever. All we needed to do was isolate the byte responsible for tracking these attributes in memory, modify the contents of the variable at that address, and voila! We were invincible, we could crush any opponent, or we could buy any item. Life was good. I believe the manual for the Super Snapshot explained a number of details about memory and how it was organized. This served as a great stepping stone for my next foray into the world of Atari memory.

The next big advance for me came after reading the book: Mapping the Atari by Ian Chadwick. It explained what all of those numbers meant and how they were used by the Atari. I was enthralled and began to experiment with earnest. Incidently, the commands I was using to read and write values to and from memory were called PEEK and POKE respectively. Loads of fun can be had with these commands and that great little book. As it turns out, this book became even more useful while dabbling with assembly language years later on the Atari.

Getting Dirty with DOS DOOM

July 15, 2007

The story behind the source code release goes something like this: In December of 1997, id Software released the source code for Doom to much fan fare and adulation. After only a few short weeks, web sites starting popping up and modified (or modded) versions started appear on bulletin board systems. Before the source code was even released, their were already tools available for modifying the existing graphics and levels, or for creating your own levels, on the Internet. These tools operated on the storage format for the game’s resources, which included maps, graphics, sound effects, etc. These resource files were called .WAD or .IWAD files. WAD does not stand for anything in particular, but you could choose to think of it like a wad of gum after eating a burrito. It contains all sort of unrelated bits in it, like green pepper and cheese, but together they form a chewy and cohesive whole. Yummy.

Modification to the actual game engine allows for much greater control over how the game operates. Despite this new found ability, many programmers or modders chose to leave the original code base intact, in order to give their users the freedom to play the older levels designed by the master’s at id Software. I believe this should be an important creed for any aspiring Doom hacker to follow, as it will allow your audience to experience the many thousands of levels available for immediate download. Just in case your levels fail to impress your core audience, such as Mother.

This project is intended to document what you need in order to build the DOSDoom (another port of Doom) source code on your machine. We chose to use DOSDoom, instead of the original code base, because the original requires a fair amount of modification to get it building with the available development tools and environments on an MS-DOS compatible machine. This brings me to my next point, you’re going to need a compatible DOS operating system installed somewhere in your house, if you want to compile this project; Windows 95 actually works quite well too as they are basically one and the same in many respects. As a trusty member of the classic gaming community, I trust this shouldn’t be a problem for those of you who are still reading.

DOSDoom brings a nice set of options to your exisiting Doom game. Features like mouse support, the “look” feature, CD audio, alpha blending, custom resolutions, and a whole lot more! Trust me, when you’re finished setting it up, you’ll think it’s almost like a new game.

Ok, first things first, you’re going to need the source code. It also helps to have a pre-built copy of DOSDoom on hand for comparison, and a chance to try it out just for fun. Personally, I love this version of Doom and will typically opt to play it over the original; unless we’re talking about the Playstation port, then we could be persuaded switch platforms for a while, or the Mac OS X port I wrote about a while ago. Of course, before either version will work, you need an original version of Doom. Please respect copyright laws and get yourself a legal copy; it’s not that expensive when you consider what you’re getting in return. Now would be a good time to unzip the pre-built copy of DOSDoom into your Doom game directory.

For those of you who weren’t born with a debugger in your bonnet, there’s a few pieces you need to have in place before you start unpacking the source code for DOSDoom. First, you need to understand the process by which program code gets transformed into something you can actually use. However, we’re not going to write yet another treatise on “How To Program In Such And Such A Language,” although for your reference, the core programming technologies used in this project are called C and Assembly Language. Learning to become a programmer is an iteresting but terribly long ordeal. I don’t recommend it unless you’re planning on making it a serious hobby or even a profession. Choose to play the game instead, you’ll probably be happier.

Since you’re still reading this article, I think it’s fair to assume that you’re mildly interested in the topics presented thus far, so let’s get a few terms under our belt before we begin. There is one general phase which must take place before you can use the source code provided and that phase is called compilation. A compiler is a tool used for translating source code which has been written in a high-level language, such as the C programming language, into a lower-level language more suitable for native execution within the hardware environment you are using. From a software development perspective, writing a good compiler is one of the most difficult and rewarding experiences a programmer could choose to undertake. However, simply using a compiler is usually no more difficult than learning any other moderately complex tool. Yes, there are usually a plethora of options and fancy doodads available for any aspiring geek, but many of them are rarely used and can be ignored most of the time. The compiler used for this project is part of a free development environment called DJGPP. DJGPP was primarily constructed by a man named DJ Delorie with plenty of help from the open source community. It contains numerous utilities, including a DOS port of the GNU GCC Compiler Collection.

Assembly Language, on the other hand, is much less abstract and tends to be a lot closer to a machine’s level of understanding. This source code does not need to be rigorously compiled and students of computer science will often write simple assemblers for course projects. Instead, Assembly is translated into machine language almost directly. Depending on the software used, “almost” can vary from assembler to assembler. DOSDoom’s source code contains only a couple of assembly language modules and can safely be ignored unless you’re planning on making low-level modifications to the game’s rendering engine. For this project, we’ll be using GCC’s assembler called GAS for all of our assembly needs. There is one item we wanted to mention when using GAS assembly code: it does not follow Intel’s coding conventions for instruction mnemonics, it uses the AT&T style instead. For a great book on coding for the Linux platform (which typically uses GCC as the default compiler/assembler toolkit), pick up a copy of Professional Assembly Language by Richard Blum (ISBN: 0-7645-7901-0).

Now that we’re all a little familiar with the basic process, here is the complete list of packages needed in order to compile DOSDoom:

Now what are these extra packages all about anyway, eh? They’re all required too, except for RHIDE which is a nifty Integrated Development Environment (IDE) very much like Borland’s early C/C++ IDE, and the DJ File Packer which is used to shrink the size of the resulting executable into something more manageable. The DPMI server is required by every 32-bit protected-mode application (in this case it’s DOSDoom) for DOS and gets launched automatically by the client application – just make sure it’s available via the PATH environment variable or in the applications home directory. The item listed only as Make is a set of tools used to easily build applications by managing their dependencies; although the syntax used to create Make files is anything but intuitive. Last, but certainly not least is the Allegro Game Library originally written by Shawn Hargreaves. Allegro is used to fill some of the gaps left by id Software when they released the source code for Doom. It’s a great library and can save you loads of time when you’re trying to write an application. All of these tools or libraries are relatively complex and deserve your attention if you want to make any useful contributions to this code base.

All but the last package, CSDPMI, must be unzipped into the same directory; CSDPMI goes into the Doom game directory instead. To help illustrate where everything goes, here’s a look at our build directory:

contrib
allegro
bin
doc
gnu
include
info
lib
man
manifest
projects
share
tmp

Once the packages have been decompressed, modify the DJGPP.BAT file to suit your own directory organization. For example, my batch file looks like this:

@echo off
set PATH=c:\source\dosdoom\djgpp\bin;%PATH%
set DJGPP=c:\source\dosdoom\djgpp\djgpp.env

Execute the batch file whenever you open a new console window (when using Windows 95), or after you’ve booted into DOS. Now, open the file under the Allegro directory and find a file named makefile. Remove the bit of text “-Werror” from the file using your favourite text editor. This is a compiler option which will halt the compilation process when a compiler warning is encountered; normally, it’s not a bad idea, but for the sake of simplicity we’ll remove it for now. The next step is to build the Allegro library by typing the command make.

Depending on the speed of your machine, the compilation process may take a while and you’ll see several messages displayed on screen. If you downloaded everything from this web site, you should experience no errors (provided you removed the compiler option mentioned above); although a few compiler warnings will make their appearance now and then. Once the Allegro library has been built, you should now enter your DOSDoom source code directory and type make again. This will build your DOSDoom executable file. You’ll need to copy this file (/obj/dosdoom.exe) into your Doom game folder (where the main executable file doom.exe is found) . Run the file dosdoom.exe and enjoy!

Remember: When making modifications to DOSDoom, please acknowledge all of the contributors who have made DOSDoom into what it is today. Without the tireless efforts from these people, you would have a lot of work on your plate before you even got started implementing your own vision of what you want Doom to be.

Exult v1.2 API Documentation

July 10, 2007

Since I couldn’t find any on their site, I’ve churned through the Exult engine using Doxygen to produce a usable set of API documentation. It’s a good reference to get a handle on their overall architecture in case you felt like diving a little more deeply.