Klaus Zimmermann's Corner

Playing free software Doom with FreeBSD and Alpine Linux

To say that Doom) has a lasting legacy into the hacker and gaming communities is a huge understatement. ID Software released the source code for its game engine in 1997, and from that point and on, game engines like Chocolate Doom, ZDoom and an infinity of mods have arised.

The hacker and modding community has kept the 1993 game well alive and thriving - true to the model of Free Software. There is even a quite impressive and ambitious new engine project called Zandronum, which is natively and heavily optimized for multiplayer a-la Quake, which shows us how to really stretch the limits of a game engine - while still keeping it old school and quite lightweight!

Yup, that's exactly what you're thinking. One of the craziest Doom mods around: MegaMan 8-bit Deathmatch. Can it still even be considered "Doom" at all?

Yet, even with all this greatness, I found myself struggling a little to get this game to work, first when I picked up FreeBSD again for a spin this week, and again with Alpine Linux.

The problems is that, unlike other "self-contained" games such as AssaultCube Reloaded or OpenArena where the moment you install the game you are good to run it, playing Doom or its mods is a two-part piece work:

  1. First, decide and install an engine - that is; the software that will get the game logic and rules running - then:
  2. Acquire data files containing the game's content, also known as a WAD file.

This confuses beginners who have never seen how Doom mods work. Because of the several possibilities to perform both (1) and (2) above, no package can truly fulfill the goal, thus requiring some user intervention to make everything work. This, at least for me, was a little painful to work out because of a chain of small difficulties adding up, including but not limited to:

After butting head with a wonderful and modern engine - ZDoom - I'll show you the step-by-step that worked for me to get the classic FreeDoom WAD up and running.

Getting an engine that works for you

For starters, there are quite a few Doom engines available for you to install - even different ZDoom engines as well! For example, this is FreeBSD 13.1-RELEASE's repo:

% pkg search doom
chocolate-doom-3.0.1           Doom/Heretic/Hexen/Strife engine port compatible with the originals
crispy-doom-5.10.3             Enhanced-resolution Doom source port based on Chocolate Doom
doom-data-1.0_1                Shareware data files for Doom, Doom II, Hexen, Heretic, and Strife
doom-freedoom-0.12.1           Complete Doom-based game IWAD that is Free Software
doom-hacx-1.0                  Full TC using the Doom II engine
doom-hr-1.0_1                  Hell Revealed is a megawad, a 32-level replacement for DooM II
doom-hr2-1.0                   Hell Revealed II is a megawad, a 32-level replacement for DooM II
doom-wolfendoom-1.0            Wolfenstein 3D levels ported to Doom II
doomlegacy-1.48.8_1,1          Improved and extended version of Doom
doomsday-2.3.1_4               Enhanced Doom, Heretic, and Hexen source port
gzdoom-4.7.1_1                 GL-enhanced source port for Doom-engine games
linux-doom3-,1       Doom III for Linux
linux-doom3-demo-1.1.1286_4    DOOM III demo for Linux
zdoom-2.8.1_8                  Source port for Doom-engine games

With so many packages with similar descriptions, which ones should you use?

The short answer is: the ones that work best for your setup! The long answer requires some testing.

First, not all engines are equal. This is true both in features (classic gameplay or modern FPS-style?) and in software/hardware requirements (OpenGL, SDL, etc). The result is that sometimes an engine can install, but will fail to run properly - not even loading correctly! After trying many of the packages above, I settled on the gzdoom engine, which runs correctly with the OpenGL stack in FreeBSD. Thanks to pkg, installation was very simple:

# pkg install gzdoom

(In Alpine, because OpenGL didn't work well, I settled for an Alpine-only lzdoom package which uses legacy graphics, but works just as well)

Another more subtle but annoying issue that came over was that even though each of the engines on the surface appear to depend on the same set of data files (like brightmaps.pk3, game_support.pk3, etc), some of them are engine-specific and vary slightly from one engine package to another despite having the same name! That variation is enough to crash so my recommendation is this: when switching doom engines, remove the previous one completely with pkg remove before installing the other one. Thankfully, the install size isn't large so the process is fast.

Then a second problem came in: the package in FreeBSD pulls in a doom-data package as a dependency that contains WADs for the original Doom Shareware version of way back. And that Shareware game is annoyingly played by default every time you choose to play - even if you install a WAD like FreeDoom afterwards.

Time for more head-butting.

Installing (and finding) the WAD files

the freedoom guy's (player's face) ouch face
A first timer's face when trying to make WADs play together nicely with Doom engines.

GZDoom's error messages were very unhelpful trying to debug why-oh-why couldn't the engine locate the freedoom1.wad file and use it instead of the original copyrighted shareware. Searching around for documentation was not very fruitful either (dev stuff, not configuration or troubleshooting).

Eventually, this is what worked for me:

  1. Download the FreeDOOM WAD files yourself from the project's website.
  2. Extract the WAD files to a same single directory. Say, ~/.local/share/wads.
  3. Open a shell, go to that directory. Ex: cd ~/.local/share/wads.
  4. Run your Doom engine from there: gzdoom

Here's the thing: these Doom Engines look for WAD files first sitting in the directory they're called (cluttering places like /usr/local/bin/ together with the binaries) and since the Shareware is right next door, it gets called in first. If you call it from a directory full of WADs first, you get to choose - complete with a GUI menu!

So there you go. A script like this doomlauncher.sh can work wonders:


# Change to your WAD repository:

cd "$WADS"

Call this script instead of gzdoom directly, and happy fragging!


Whew! Though the separation between engine and content may cause some confusion at first, it does give us a pretty large source of games to choose from. Plus, there is nothing that some good ol' shell scripting can't solve, especially after you understand what is going on under the hood. FreeBSD is now fun again with more old school-but-revamped gaming and with extensive modding possibilities, and likewise for Alpine!

If you're looking for more mods and WADs to try out, definitely check out the DoomWiki pages on them. Older archives such as Doomworld are pretty dated and hard to find interesting things there. Also, do try several engines to see which ones are better for your machine!

Have you tried playing Doom and its derivatives on FreeBSD or Linux? What Engine + WAD stack did you use? Let me know on Mastodon!

This post is number #34 of my #100DaysToOffload project. Follow my progress through Mastodon!

Last updated on 08/21/22