Bungie released Marathon in 1994, the same year Doom II came out. Marathon was also a first-person “run around picking up guns to kill aliens with” game, but had a comparatively robust plot with multiple conflicting AI characters, multiple settings, a relatively fleshed-out picture of the bad guys, effectively moody atmospheric music, and some additional universe flavor text here and there.

I never really played much of Doom II, so I’m not sure if Marathon’s gameplay was also a step above. But it was beloved by Macintosh users because it was a rich, advanced FPS with fantastic network play levels, which was exclusive to a platform that was usually left behind by game publishers. Apple wasn’t at the top of their game in that beige Performa, pre- Steve Jobs return era, but Marathon was a celebrated bright spot.

Not long before Microsoft bought them in 2000, Bungie GPL’d the Marathon 2 game engine, which is what the current Aleph One project originated from. Bungie later released the whole trilogy of Marathon games for free, so the scenario/content files can now be distributed with the engine (though I don’t know the license details). They’re still 25-30 year-old games, so (for example) there aren’t many save points, but the open source project has been very successful at making them pleasant to play decades later.

Since the pandemic my household has used a Raspberry Pi 4B running RetroPie as a retro game emulation system, so I was excited to see that RetroPie has a built-in option to install the Aleph One Marathon games under “ports”. These installs do run, and are playable with a keyboard, but they never worked with our 8BitDo bluetooth controllers. Until today, that is! I finally figured out how to get them running with our controllers, so I thought I should write down what I did.

Aleph One uses SDL, a software library used by many games (among other things) to work with hardware components like controllers, keyboards, displays, etc. If your Linux install of Aleph One is also failing to work with controllers, you might find log entries like this:

No mapping found for controller "8Bitdo SN30 Pro" (05000000c82d00000161000000010000) (joystick_sdl.cpp:66)

On our RetroPie this was in the file /opt/retropie/configs/ports/alephone/Aleph One Log.txt. The “joystick_sdl.cpp” in the log entry is the clue that this is an SDL issue, and that led me to a helpful guide on Reddit for making controllers work with SDL games on Linux.

That included a link to a script to download the SDL game controllers database, grab the Linux section, save it to a dot file in the home directory called .controller_config, and then add a line to your .bashrc (or similar) to add those controller mappings as an environment variable called “SDL_GAMECONTROLLERCONFIG”. I ran that script on our RetroPie box.

To briefly explain what this is for: one of SDL’s jobs is to take input from many different kinds of controllers and present them to games as, simply, “D-Pad Up”, “D-Pad Down”, “A Button”, “B Button”, etc. That game controllers database has the actual mappings for that—it basically says, “controller XYZ identifies itself with the number 1234, and on that controller the right trigger is button code b4”, etc, etc, for all of the buttons on all of those controllers. By adding those mappings as an “environment variable” (a value available to every program that you run), you’re telling the SDL code in the game you’re trying to play how to work with the buttons of your controller.

Adding that entire controllers database as an environment variable presumably must work in many cases, but it’s also a bit blunt. The Linux section of that controller database is over 500 lines long! In fact, it’s so long that adding all of that to your environment variables will make ordinary bedrock tools like rm or mv break with “argument list too long” errors. If that happened to you and now you’re panicking because you can’t even delete your .controller_config file, you just need to un-set that environment variable by running unset SDL_GAMECONTROLLERCONFIG in a terminal.

Anxious to see if I could get things working, tonight I just took the .controller_config file generated by the script above and deleted everything except for the couple dozen 8BitDo lines (since that’s the brand of all of our assortment of controllers). You should similarly trim your controller file down—just remember to leave the very first line and the very last line of the file untouched, or to otherwise make sure that the file still begins with export SDL_GAMECONTROLLERCONFIG=" and ends with a closing quote mark.

You could improve upon my blunt edit by looking in .controller_config for the long numeric string(s) in your Aleph One Log.txt “joystick_sdl.cpp” error, and just including the matching line(s)—in my error example above the number to look for would be “05000000c82d00000161000000010000”.

So now you should have a .controller_config file with a small subset of the giant game controller mapping database, and a line like this in your .bashrc (or similar) file:

. "$HOME/.controller_config"

To make your controllers work with Marathon when launched from EmulationStation (the frontend used by RetroPie), however, you’ll need to copy that line to the launch scripts for the Marathon ports. Those are in ~/RetroPie/roms/ports/, with names like Aleph One Engine - Marathon.sh. In that file, you need to add that line from your .bashrc as the second-to-last line (just before the long final line that runs the game). Here it is again:

. "$HOME/.controller_config"

That’s a period for the first character—you’ll need to copy that line exactly, including that period and the quotes.

But once you do that, you should be able to run the Marathon ports from RetroPie and have your wireless controllers work!

Another time I’ll have to improve upon this. PortMaster (a system for installing ports on handheld emulator consoles) does a great job of handling controller mapping for games that use SDL, so their scripts are probably something I should look at. Ideally, the Marathon launch scripts would look at what controllers are attached (possibly with evtest), look up only those lines in the game controller database, and then set those mappings to the SDL_GAMECONTROLLERCONFIG environment variable before launching the game. Presumably that controllers database already exists somewhere in a normal RetroPie distribution? Who knows—for now I’ve got a score to settle with the Pfhor still occupying the colony ship Marathon.