From Funtoo
Jump to navigation Jump to search

Playing Classic Doom on Funtoo

A big upgrade to Funtoo's Doom-playing ability has been merged into `next`!

This page will document how to use it.


To play Classic Doom on Funtoo, you need

  1. a source port,
  2. one or more internal game data files (IWADs),
  3. and potentially also some maps to play (PWADs).

The Doom source code has been free software for a long time; accordingly, several source ports are available for Linux. Two have been updated recently in Funtoo: GZDoom and Odamex. GZDoom is a good choice for playing alone, offline. Odamex is the preferred multiplayer source port, and can optionally include facilities for running a server.

Environment variables

Set DOOMWADPATH in `~/.bashrc` like


This variable determines the default location that other Doom software will look for game data.

Another variable that you might want to set is


but DOOMWADPATH is the better option because it allows for more than one directory to be specified.

Don't forget to refresh your environment after changing your ~/.bashrc.

Install and Configure Timidity (for Music)

Fix USE flags for sdl2-mixer by adding to /etc/portage/package.use/doom:

 media-libs/sdl2-mixer midi timidity

Emerge timidity; it would get pulled in as a dependency but it needs to be set up in any case:

 $ emerge -1v timidity 

Note the the -1 in the arguments, for --oneshot, to avoid putting timidity in the @world set. The package for Timidity++ will be in the dependency tree already as a dep of the various source ports, so keeping it out of @world makes things a little cleaner.

Set the soundfont used by timidity:

 $ eselect timidity set freepats


Install packages

 $ emerge -v doomrunner gzdoom

Install IWADs

Copy your IWADs to /usr/share/doom. Optionally install Freedoom:

 $ emerge -v freedoom-data

Set up DoomRunner

Configure DoomRunner as described further down this page.

Start the game!


Install IWADs

Copy your IWAD file(s) to /usr/share/doom. It is rare to find a Freedoom server, so you will need a commercial DOOM2.WAD file.

Install Odamex

 $ emerge -v odamex

Find a Game

Find a game to play by browsing the [server list] maintained by the Odamex Masters. Once you've found a server that seems interesting, join it with

 $ odamex +connect <server address>

Alternatively, start the Odamex Launcher (`odalaunch` at the shell), and follow the instructions.

Choose a game from the list in the Launcher and begin playing.

Source ports

Several Classic Doom source ports are available in Funtoo's tree. Of those, the following are autogenerated at the latest version:

  • games-engines/gzdoom: Good for playing single player.
  • games-engines/odamex: Preferred for multiplayer; enables an Online Doom Advanced Multiplayer EXperience.


Odamex is a very good source port for multiplayer. It has the only free software Doom server, `odasrv`.

Install the client with

 $ emerge odamex

and see the section about Timidity to ensure that the MIDI music will play.

Install the package with

 $ USE=server emerge odamex

and you'll get the `odasrv` program.

Config files

Odamex puts its configuration in files under `~/.odamex` in the user's home directory. The Odamex client config file is `odamex.cfg.` The default location where the server looks for its config file `odasrv.cfg` is also in the same directory.

Downloaded WADs

Odamex can (and will, by default) download WADs from the server if possible. If the server doesn't allow downloading, Odamex will attempt to find the WAD in one of the public repositories about which it knows. These WADs will end up in `~/.odamex/` with the config files.

Recommended Settings

A few settings in the Odamex client are worth noticing:

Resolution/etc.: Display mode

Crosshair: in Odamex, Display -> Heads-up Display -> at the very bottom

Player: Change name and color

Controls: Bind a key for Jump, e.g. Space

Mouse options: Always free look

Make the player list/scoreboard large enough to read it: Display options -> Heads-up Display -> scoreboard scaling, set to 1.0 or 0.9.

Game data

WAD files

Doom data files are organized inside a type of archive called a WAD (pronounced like the word "wad") file. The term 'WAD' is an acronym representing "Where's All [the] Data?".

There are a few types of WADs:

  1. IWADs are internal game data, often commercial; these include sprites and sounds, as well as maps.
  2. [PWADs are extra and contain map data.]

Game data files / IWADs

In order to play Doom with a Doom source port, a WAD file for the internal game data, called an IWAD, is required. Commercial IWADs for the original Doom games come with modern Doom games; so it's possible you have one already. See for reference.

Another way to acquire Classic Doom IWADs is to purchase them directly from Steam or GOG.

Most current-day maps and mods are based on the Doom II IWAD.

Doom source ports can be played without commercial IWADs by using Freedoom.

Ebuilds that install free IWADs place them in `/usr/share/doom`. It is a good idea to place commercial IWADs there, too.


The commercial and free IWADs come with a lot of great maps. In addition, the community has been making Doom maps and mods for almost thirty years.

A selection of community-produced maps are available in Funtoo's tree. It is easy to add them, and Doom resources traditionally are distributed freely; so more can be made available directly in Funtoo upon request.

Eviternity was created as a 25th birthday gift to Doom and was released on Doom's 25th release anniversary. It's sequel, Eviternity II, coincided with Doom's 30th birthday.

  • games-fps/eviternity
  • games-fps/eviternity-ii

It is a good idea to put maps in their own directory, like `~/.local/share/games/doom/maps`. Ebuilds that install maps will add them to `/usr/share/doom`; this may change in the future to `/usr/share/games/doom/maps`.


Mods differ from maps in that they make use of features in a particular source port, rather than simply changing the game's internal data, or building something with components contained within it.

Most mods seem to work with GZDoom, so if you're interested in a particular mod, it's not a bad idea to start there.

Brutal Doom

One popular mod that introduces many modern game elements is Brutal Doom:

Sprite fixes

There exists a mod that fixes various little glitches with the artwork, available at

TODO: add games-fps/doom2-sprite-fixes


DoomRunner is a launcher that makes it easy to set up profiles for combinations of the various source ports, IWADs/PWADs, and mods. DoomRunner generates command line arguments for the source port, starts it, and offers a way to kill it if it misbehaves.

DoomRunner allows to configure profiles for different game modes, something that is very useful for playing single player games with a source port like GZDoom that sets everything from command line arguments.

Install it with a simple

 $ sudo emerge games-util/doomrunner

Suggested WAD Directory Structure

Configuring DoomRunner involves first organizing your files into directories that make it easy to find your files. The recommended setup looks like this, with files stored in subdirectories under `~/.local/share/games/doom`:

 $ ls ~/.local/share/games/doom

Various Doom-related ebuilds, such as those for Freedoom, place files in `/usr/share/doom`, a common place for Doom software to look for IWADs. It is therefore not a bad idea to put your commercial IWADs there so that they will be accessible to all users on your system.

Configuring DoomRunner

Configure the engines

  1. Add engine by clicking the '+' icon
  2. Navigate in the file picker to `/usr/bin/gzdoom` (or type it in the text field)

Configure search paths

  1. maps: set it to `/usr/share/doom` or `~/.local/share/games/doom/maps`, wherever you will put your maps. Ebuilds that install maps put them in `/usr/share/doom`, so that's a good choice if you don't have any yourself yet.
  2. mods: set it to `~/.local/share/games/doom/mods`

Close the initial config window.

Configure a profile for single player

  1. Create preset: Rename "Default" to "GZDoom singleplayer"
  2. Select engine: gzdoom
  3. Select IWAD: Pick whichever game you intend to play. IF
  4. Select map pack: Leave this alone unless you downloaded maps.
  5. Select config (optional): Leave this alone.
  6. Add mods: Leave this alone unless you have mods to play.


Note: It is strongly recommended that you ensure that you can play Doom in a single-player mode with your chosen source port before attempting to play multiplayer.

Odamex is the preferred multiplayer engine.

With Odamex

It is very easy to get started with Odamex on Funtoo. First, install it as described in Doom#Odamex.

A few methods exist:

Join a game directly from the command line, as with GZDoom, if you know the host to which you want to connect:

 $ odamex +connect

Using the Odamex Launcher

Use `odalaunch`, the Odamex Launcher, to find a game:

 $ odalaunch
  1. Ignore the wxWidgets messages and optionally uncheck the box to continue showing them. They are a BUG and should be reported and fixed.
  2. In the Settings dialog (File -> Settings in the menu), in the File Locations tab, choose the Odamex Path to be "/usr/bin". If you don't perform this step, the launcher won't be able to find the executable.
  3. Ensure that the paths with your WADs and IWADs are in the list.

Using DoomRunner

DoomRunner can be used with `odamex` just as well as with `GZDoom`, but with a caveat that `odamex` can't find IWADs that are specified by absolute path in DoomRunner unless they are in a directory it knows about from its own configuration. Configure DoomRunner as described, except add an Engine for `/usr/bin/odamex`. In the Additional Command Line Arguments field, enter `+connect <server address>`, using a server you've chosen.

Finding Games

Use the Odamex Launcher as described above and choose a game from its list.

Another option is to browse the [games], choose one to join, and find its `host:port` combination from the website.

Operating a server

Useful resources:

Firewall Ports

Don't forget to open the relevant ports on your firewall.

  • `10666/udp` is the listening port
  • `15000/udp` is used as an outgoing port to contact master servers

You may need to forward these ports from your router to the machine where your server is running. There is a USE flag for upnp, but that is a glaring security hole and not recommended.

Master servers

Odamex master servers listen on `15000/udp` and maintain lists of the servers that are up and running, including information like how many players are logged in. Server operators should set a few relevant variables in the `odasrv` config file that affect the server's appearance in the list.

The master server can be installed by setting `USE="master"` and re-installing `games-engines/odamex`.

Optionally using Docker
  • Use `boxer` to build a simple Funtoo docker container from a stage3
 $ emerge -v boxer
 $ boxer --stage <stage3 tarball> docker --tag funtoo

See for more information.

  • Use that container as a base image and install `odamex` with `USE="server"` inside it

Sample Dockerfile:

 sample file here
  • Save the container as a new image (e.g. called 'odasrv-funtoo')
  • Verify that it works!
 $ docker 
  • Use `slim-toolkit` to minify the odasrv container
 $ slim build odasrv-funtoo

<Enter> when prompted

  • Sample `docker-compose.yaml`:
     image: test/odasrv-funtoo.slim
     command: /usr/bin/odasrv -config /doom/odasrv.cfg
       - "10666:10666/udp"
     working_dir: /doom
       - /usr/share/doom:/usr/share/doom
       - ./doom/odasrv.cfg:/doom/odasrv.cfg:ro
       - ./doom/wads:/doom/wads
       - DOOMWADPATH="/usr/share/doom:/doom/wads"
  • Execute like `docker compose up -d`

With GZDoom

It is possible to play small multiplayer games with GZDoom, e.g. on a local network with 2-4 players. Problematically, if one player disconnects, they can never rejoin the game again unless everyone else quits and starts over.


On the host machine, start GZDoom with the `-host <number of players>` option, like

 $ gzdoom -host 2 <other args>

DoomRunner makes it very easy to save preset command line strings that include a large number of possible options affecting gameplay in the multiplayer mode. If you will be doing this often, it is recommended to use DoomRunner. See the DoomRunner section elsewhere on this page for more information.


Other machines that are not the host should start GZDoom with the `-connect <host address>` argument, as in

 $ gzdoom -connect <other args>

As is the case with the host, connecting as a client is made easier with DoomRunner.


Note: To make the MIDI music work in various sourceports, it is necessary to set USE="midi timidity" for `media-libs/sdl2-mixer`. Then remember to run `eselect timidity set 1`. The ebuild for `games-engines/odamex` will require this condition to be true.

Alternative soundfonts exist for Timidity. A great one that is freely available is `8MBGSFX`, obtainable from It works easily with a few steps:

  • Extract the contents to `/usr/share/timidity/8mbgsfx`.
  • Change all the filenames to lowercase; they seem to come from a case-insensitive Windows system.
  • Edit `/usr/share/timidity/8mbgsfx/timidity.cfg` and change the `dir` path to the right place on a Funtoo machine.
  • From `/usr/share/timidity`:
 $ sudo rm current
 $ sudo ln -sf /usr/share/timidity/8mbgsfx current

TODO: need to make an autogen for it to perform that procedure automatically

Using a Playstation 4 or 5 Controller with Bluetooth

It's possible to play Doom with a PS4 or PS5 controller on Funtoo, using the `hid-playstation` kernel module. A bug in Odamex that makes the controller stop working after a few minutes will be fixed with a patch.

Note: Making Bluetooth work in general is not very difficult on Funtoo, and is beyond the scope of this document. It will be assumed here that other Bluetooth devices pair to the machine on which the controller will be used.

Pairing the Controller with the Computer

First you need to pair the controller with the computer.

  1. Hold down the Share button, and then hold the PS button at the same time until the controller's lights start flashing.
  2. Perform the usual procedure on the computer to pair with a device that's in pairing mode.

PS5 Controller

The DualSense PS5 controller has a Linux kernel module that enables support for all of its features, at least in principle. In practice, the buttons and sticks work, but the rumble feature is not yet supported by Doom source ports. All that is needed to enable it is to turn on the relevant joystick options in the source port's menu.

PS4 Controller

The instructions are the same as for the PS5 controller.

Other Controllers

In fact, other controllers may work with Odamex if they are supported by SDL2.

Mapping Controller Events to Mouse and Keyboard

It is not necessary to do this; but in case you want to, the instructions follow.

The DualShock4 and other third-party controllers will work with the use of `ds4drv` to map the buttons to mouse and keyboard events.

Installing Software

First you need `ds4drv`. An easy way to install it is with `pipx` that isolates python executables into their own virtual environments, and makes them available in your path.

 $ pip install pipx --user
 $ pipx ensurepath
 $ pipx install ds4drv
Dealing with Device Permissions

Get the following file and put it in the `/etc/udev/rules.d/` directory:

Then you can ask `udev` to use it immediately:

 $ udevadm control --reload-rules
 $ udevadm trigger

Configuring the Button Mapping for Doom

Now you need to configure `ds4drv`. Copy the following into ~/.config/ds4drv.conf`

 hidraw = true
 # Enables LED flash on low battery
 battery-flash = true
 # Sets LED color
 led = ff00ff
 # default mapping
 mapping = doom
 # General button to key mapping
 KEY_UP = dpad_up
 KEY_LEFT = dpad_left
 KEY_DOWN = dpad_down
 KEY_RIGHT = dpad_right
 # needed for the menus
 KEY_ENTER = button_cross
 # Turn analog stick directions into buttons
 KEY_W = -left_analog_y
 KEY_A = -left_analog_x
 KEY_S = +left_analog_y
 KEY_D = +left_analog_x
 # Map relative mouse movement to a analog stick
 REL_X = right_analog_x
 REL_Y = right_analog_y
 # Map mouse buttons
 BTN_LEFT = button_r2
 BTN_RIGHT = button_l2
 # Emulate mouse wheel on r1 and l1
 #REL_WHEELUP = button_l1
 #REL_WHEELDOWN = button_r1 && button_r2
 # it's actually more useful to set the weapons to the dpad
 # and employ those buttons for something different 
 # a key for quick turn around, in Odamex
 LEFT_SHIFT = button_r3
 # jump
 KEY_SPACE = button_l1
 # Mouse settings
 mouse_sensitivity = 0.3
 mouse_deadzone = 10
 # Scroll wheel emulation settings (values are in seconds)
 mouse_scroll_repeat_delay = 0.25 # How long to wait before continual scrolling
 mouse_scroll_delay = 0.05 # Lower this to scroll faster; raise to scroll slower
 # other keys, bound for DOOM
 # use/action button
 KEY_E = button_circle
 # yes, for leaving
 KEY_Y = button_triangle
 # map
 KEY_TAB = button_trackpad
 # esc
 KEY_ESC = button_options
 # score
 KEY_BACKSLASH = button_share

There are more functions available to `dsvdrv`, such as mapping button combinations to shell commands outside of the game. For information, see the sample config file.

Start the Program

Now if you run

 $ ds4drv

with the controller paired, you should see output in the terminal indicating that the controller has been found by `ds4drv`. You are now ready to play. Both the controller and the keyboard will work.

You might need to load the `uinput` module first:

 $ sudo modprobe uinput

To load the module automatically at boot time, you can add `uinput` to the line in `/etc/conf.d/modules` that says `modules="..."`. It might be commented out or empty initially on your system.

Creating and Editing WAD files

Follow the instructions on the Funtoo [[1]] wiki page to get started, but stop before the command to install Steam. Instead, install SLADE:

$ flatpack install net.mancubus.SLADE

To run it:

$ flatpack run net.mancubus.SLADE

A good tutorial can be found here: