DoomToolbox

DoomToolbox is a collection of add-ons for Doom-based game engines which support ZScript, like UZDoom and LZDoom.

The goal of DoomToolbox is to increase replayability of compatible games and mods, make gameplay more enjoyable, and to have fun both while playing and developing this project. The development is done under "Move slow and fix things" flag.

DoomToolbox is free and open source software. Add-ons are mostly licensed under GPLv3. Modules are mostly licensed under BSD-3-Clause. See SPDX-License-Identifier tag in each .org file for details. For third-party resources, such as image and sound files, see REUSE.toml files in their directories for licenses.

Acknowledgments

HTML pages for DoomToolbox should be available here. The source code is available on GitHub and Codeberg.

DoomToolbox has a Doomworld topic and a Mastodon page. Some add-ons and modules also have ZDoom forums threads.

This project doesn't use any AI tools or resources.

Add-ons	Description	Forum topic
10.5x	enemy number multiplier	link
ClematisM	ZScript unit test framework
DoomDoctor	mod development and debugging utilities
FinalCustomDoom	gameplay customization options	link
Gearbox	more convenient ways to select weapons and items	link
HitImpact	textured particles when level geometry is hit	link
Nomina	enemy names helper	link
SoundToScreen	shows where sounds come from	link
TargetSpy	enemy health bar	link
Typist.pk3	turns FPS games into typing exercises	link
WarmReception	alters enemy behavior on level start	link
Modules
Hint	hints for menu items
LazyPoints	points scoring
libeye by KeksDose	level and screen projections
LispOnZscript	toy Lisp-like language on top of ZScript	link
MD5 by 3saster	MD5 Implementation in ZScript
PlainTranslator	enables translation for plain text menu items
PreviousWeapon	provides a key to select a previous weapon
StringUtils	string manipulation library
VmAbortReporter	prints a report when VM abort happens

Add-ons can be included and used in your own projects. However, this is not recommended, because when add-ons update, players won't be able to use new versions with your project until you update the included add-on inside your project.

Modules are intended to be included as a part of other projects. Some DoomToolbox add-ons include them.

10.5x:

FinalCustomDoom:

Gearbox:

HitImpact (with BTSX E1 MAP01):

SoundToScreen:

Typist.pk3:

• playtesting: compatibility with games and mods, multiplayer
• UX suggestions: visuals, wording, usability
• code reviews: errors, style, readability
• code contributions: optimizations, features (try to keep project scope)

Where are the project files?

Build is supported on recent versions of GNU/Linux and Microsoft Windows.

To build:

1. Install Python, version >= 3.13
2. Install Emacs, version >= 30.1
3. Install UZDoom, version >= 4.14.3
4. Install development tools (probably from a venv): pip install -r tools/requirements-dev.txt
5. In console in project directory, see what can be built with command: scons --help
6. Build what you need.

To build an add-on PK3, for example FinalCustomDoom, use this command: scons FinalCustomDoom.pk3. It will create FinalCustomDoom-NNNN.pk3 in directory build.

To build a module so you can use it in your project, for example, StringUtils, use this command: scons StringUtils. It will create directory StringUtils in directory build, which will contain StringUtils.zs, in which you can replace NAMESPACE_ with your unique namespace, and then include in your project.

All commands require that PATH environment variable has Emacs, tests also require UZDoom in PATH. All commands put their results in directory build, and may remove files and directories there.

⚠ !WARNING!

• Scons scripts contain code. Only run scons for projects you trust.
• Org files may contain code, extracting the source files may execute it. Only extract files from Org files from the sources you trust.

Tests use Miniwad: minimalist IWAD internally.

Used languages:

• add-ons, modules: ZScript (main), Emacs Lisp (supporting macros)
• build: Python (main), Emacs Lisp (helper functions)

Python or Emacs Lisp knowledge is not needed to contribute to add-ons and modules.

prek must be installed in Git repository for pre-commit checks.

Optional: Org mode extension for your preferred text editor, if it's not Emacs. Org mode files can be edited as plain text, but an extension should add convenience features such as syntax highlighting.

Documentation:

• Code of conduct
• Code style
• Made with
• Org Cheat Sheet