# Chocolate Doom: a Doom source port that treats the DOS original as the spec

> A C source port for Doom, Heretic, Hexen and Strife whose stated goal is to reproduce the DOS binaries accurately, bugs included, which makes it the reference point rather than the comfortable choice.

**chocolate-doom/chocolate-doom** — Chocolate Doom is a Doom source port that is minimalist and historically accurate.

- Repository: https://github.com/chocolate-doom/chocolate-doom
- Website: https://www.chocolate-doom.org/
- Stars: 2,423 · Forks: 723
- Language: C
- License: GPL-2.0
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/chocolate-doom-chocolate-doom

## Five stated aims, one of which is to reproduce the bugs

The README is unusually short and does not need to be long. It lists five aims for the project, and the third is the one that decides everything else: accurate reproduction of the original DOS versions of the games, including bugs.

The fourth aim is compatibility with DOS demo, configuration and savegame files, and the fifth is an accurate retro feel, where display and input should behave the same. Those two together explain why the port looks the way it does. Chocolate Doom reads the same `default.cfg` that DOS Doom wrote, and if you already have one it works, with any extra settings kept separately in `chocolate-doom.cfg` so the original file stays untouched.

The remaining aims are political rather than technical: always be free and open source software, and be portable to as many operating systems as possible. Those are stated as aims, not as side effects, which is a useful signal when you are choosing between ports.

## The tree reads like a 1997 source distribution

Nothing about the repository layout has been modernised for appearance. You get `src/` for the engine, `textscreen/` for the startup and configuration screens, `opl/` for the OPL emulator, `pcsound/` for PC speaker and digital sound output, `data/` for the bundled assets, `man/` for manual pages, `win32/` for the Windows front end, `cmake/` alongside a classic `Makefile.am` and `configure.ac`, and `autogen.sh` to bootstrap autotools. `rpm.spec.in` and `vcpkg.json` are there for packaging on Linux and Windows respectively, and `.travis.sh` is the CI script from before the project moved to GitHub Actions.

`HACKING.md`, `CODE_OF_CONDUCT.md`, `PHILOSOPHY.md`, `NOT-BUGS.md`, `TODO.md`, `NEWS.md`, `RELEASE_NOTES.md` and `ChangeLog` sit in the root as plain text files, not wiki pages. That is the structure of a project that has kept one convention since the source was first distributed, and `.clang-format` and `.lvimrc` are there to keep it that way.

The point worth taking from the tree is that this is a port, not a reimplementation. There is no engine redesign hiding in there. The subsystems are the ones the DOS executable had.

## Total conversions need -merge rather than -file

Mods are the practical reason people pick a port, and Chocolate Doom handles the classic Total Conversion case in a way that is worth understanding. Vanilla Doom has no way to put sprites inside a PWAD, so a TC is normally distributed as a PWAD that has to be merged into the main IWAD, with a tool like DEUSF.EXE doing the merge on disk.

`-file` behaves exactly as it does in Vanilla Doom, so adding TC files that way does not work, and the README says so directly. The `-merge` option simulates the merge in memory instead:

```bash
chocolate-doom -merge thetc.wad
```

Two worked examples follow in the README, one for Batman Doom and one for Army of Darkness Doom, each pairing a `-merge` with a `-deh` for the DeHackEd patch:

```bash
chocolate-doom -merge batman.wad -deh batman.deh vbatman.deh  (Batman Doom)
```

Because the merge happens in memory rather than on disk, your IWAD is not modified, which matters if you care about keeping your game data pristine. Version 3.1.0 added an autoload folder where WAD and DEH files are picked up automatically at every game start, which is a better answer to the same problem than remembering command line flags.

## Four games from one engine, plus OPL and PC speaker emulation

The project started as a Doom port and now also ships Heretic, Hexen and Strife, which the README confirms and the repository topics list as well. The Strife port has its own README file, `README.Strife.md`, which tells you the coverage is uneven enough that each game needs its own documentation.

Sound is where the accuracy argument gets most expensive, and it is where the code layout pays off. `opl/` and `pcsound/` are separate directories because the DOS original had two distinct sound paths: the Yamaha OPL chip and the PC speaker. Emulating OPL correctly means reproducing a chip that never existed in the same form on a sound card, and release 3.1.0 moved to Nuked OPL3 v1.8 for that. That same release added the ability to run PC speaker and OPL emulation simultaneously, which the DOS original could do and which a single audio path could not.

Music playback has its own README, `README.Music.md`, and version 3.1.0 simplified its configuration by detecting `.flac` and `.ogg` files by filename in a folder, added MP3 support, and allowed music packs to fall back to OPL when no sample playback is possible.

## Internet play through a PID controller and UDP hole punching

Chocolate Doom supports networked play, and the 3.1.0 release notes are specific about how. Network synchronisation now uses a PID controller by default instead of a fixed adjustment, which is described as making games smoother and more stable for internet play. UDP hole punching makes a server behind a NAT gateway reachable without manual port forwarding.

This is worth pausing on, because it is the part of the port that is not about accuracy. A PID controller is a modern input, not a faithful reproduction of a 1993 network stack, which tells you where the project draws its line: the simulation matches the original, and the transport does what players need.

Version 3.1.0 also added drag and drop loading of WAD, Dehacked and demo files on Windows, so a file can be dropped onto `chocolate-doom.exe` instead of typed on a command line. That is the other place the project stops being a historical replica, and it is a change most users would want anyway.

## What the release notes reveal about the project's priorities

Release 3.1.1, dated 2025-08-14, is mostly housekeeping, and the housekeeping is informative. It fixes compilation on GCC 15, hides public IP addresses for privacy, switches to a native OpenGL texture format for performance, adds long NTFS path support up to 32768 characters, fixes directory handling for paths with a postfix dot, adds an option to turn smooth pixel scaling off, and makes the setup tool use the correct EGA palette. It also adds Emscripten support, which is how a 1997 engine ends up running in a browser.

Two entries stand out. Initial support for Doom version 1.5 is listed under the Doom heading, which is the kind of compatibility work that only matters if you care about the exact shareware release. And the setup tool's background change to Romero Blue is filed under Setup rather than General, which says the tool is treated as part of the retro presentation rather than as neutral configuration software.

The 3.0.1 point release from 2023-10-10 shipped only a security fix, CVE-2020-14983, an unchecked field in the server logic that could let a remote attacker run code against a Chocolate Doom server. It was found by Michał Dardas of LogicalTrust and credited in the release. For a project whose servers are still reachable, that is the entry to remember, and it is the argument for building from a current release rather than an old package.

## Conclusion

Chocolate Doom is worth choosing when accuracy is the goal, because it accepts worse presentation in exchange for matching the original's behaviour, including the parts other ports have spent twenty years quietly fixing. Its code is also a good reference for how the Doom engine actually worked, since `src/` still separates the same subsystems the DOS executable had. Two practical notes before you start: total conversions need `chocolate-doom -merge` rather than `-file`, and `NOT-BUGS.md` explains which odd behaviour is deliberate. The last push was on 2026-09-08, and release 3.1.1 is the current line, with the SDL, OPL and networking details in `README.Music.md` rather than on the main README.

## FAQ

### Is Chocolate Doom free?

Yes. The project states that it is always 100% free and open source software and is distributed under the GNU GPL, with the licence text in `COPYING.md`. There is no paid edition and no in-game store.

### Can Chocolate Doom run mods?

It can, with one caveat. Classic Total Conversions must be loaded with the `-merge` option, which merges the WAD directory in memory instead of modifying the IWAD on disk, because Vanilla Doom cannot hold sprites inside a PWAD. Version 3.1.0 also added an autoload folder where WAD and DEH files are picked up at every game start.

### Which games does Chocolate Doom support?

Doom is the original target, and the project also ships ports of Heretic, Hexen and Strife. The README aims at reproducing the original DOS versions of these games accurately, including their bugs, and Strife has its own README file in the repository.

## Sources

- [chocolate-doom/chocolate-doom on GitHub](https://github.com/chocolate-doom/chocolate-doom)
- [License: GPL-2.0](https://github.com/chocolate-doom/chocolate-doom/blob/master/LICENSE)
- [Project website](https://www.chocolate-doom.org/)
- [README](https://github.com/chocolate-doom/chocolate-doom/blob/master/README.md)
- [Releases](https://github.com/chocolate-doom/chocolate-doom/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chocolate-doom-chocolate-doom