```
____ ____ ____ _____ ____ ______ ______
/ __ \ / __ ) / __ \ ____ ____ ____ ___ |__ / / __ ) / ____// ____/
/ /_/ // __ |/ / / // __ \ / __ \ / __ `__ \ /_ < / __ |/ /_ / / __
/ _, _// /_/ // /_/ // /_/ // /_/ // / / / / /___/ // /_/ // __/ / /_/ /
/_/ |_|/_____//_____/ \____/ \____//_/ /_/ /_//____//_____//_/ \____/
_______________________________________________________________________
```
RBDOOM-3-BFG Readme - https://github.com/RobertBeckebans/RBDOOM-3-BFG
Download it from the [RBDOOM-3-BFG Mod DB Page](https://www.moddb.com/mods/rbdoom-3-bfg)
For discussions join the id Tech 4 Discord: https://discord.gg/Q3E9rUFnnP , #rbdoom3bfg
# Table of Contents
This file contains the following sections:
1. [About the Port](#about)
2. [".plan"](#plan)
3. [May or may not ".plan"](#plan2)
4. [Renderer Features Explained](#render)
5. [TrenchBroom Mapping Support](#trenchbroom)
6. [General Notes](#notes)
7. [License](#license)
8. [Getting the Source Code ](#source)
9. [Compiling on Windows](#compile_windows)
10. [Compiling on Linux](#compile_linux)
11. [Compiling on macOS](#compile_macos)
12. [Installation](#installation)
13. [New Console Variables](#console)
14. [Known Issues](#issues)
15. [Bug Reports](#reports)
16. [FAQ](#faq)
---
# About the Port
`RBDOOM-3-BFG is a modernization effort of DOOM-3-BFG.`
RBDOOM-3-BFG is based on DOOM-3-BFG and the goal of this port is to bring DOOM-3-BFG up to latest technology in 2023 making it closer to Doom 2016 while still remaining a DOOM 3 port regarding the gameplay.
I started this project in 2012 and focused on making this code being future proof so other cool projects can build interesting things on top of it without the need to fix a lot of stuff first. Over 40 people all over the world contributed cool patches. Some results are:
## Gaming / Graphics Related
* DX12 / Vulkan support through NVRHI (NVIDIA Rendering Hardware Interface) (thanks to Stephen Pridham for major porting effort)
* Physically Based Rendering using GGX Cook-Torrence as in other modern engines (UE4, Unity) and 3D authoring tools like Blender 3.x or Adobe Substance
* Baked Global Illumination using Irradiance Volumes and Image Based Lighting that fix the pitch black areas
* Soft shadows using a fat shadow mapping atlas:
* All 3 light types (point, spot, parallel/sun) are supported which means parallel lights (sun) use
scene independent cascaded shadow mapping.
* True internal 64 bit HDR lighting with filmic ACES tone mapping and gamma-correct rendering in linear RGB space
* Temporal Antialiasing (TAA) as a cheap alternative for MSAA and that works well with HDR and also improves PBR lighting
* Filmic post process effects like Chromatic Aberration and Dithering
* Screen Space Ambient Occlusion used to only dim down the Global Illumination contribution like in the Frostbite engine
* Bink video playback through libbinkdec (thanks to Daniel Gibson) or FFmpeg (thanks to Carl Kenner)
* Cinematic sequences can be skipped (thanks to Biel Bestué de Luna)
* Netcode fixes to allow multiplayer sessions to friends with +connect (manual port forwarding required)
## Programming and Code Quality
* Flexible build system using CMake allowing to add optional features like FFmpeg for videos or OpenAL for sound
* Linux support for both GCC and Clang with a proper SDL 2 OS layer including gamepad support
* Win64 support and Visual Studio support up to VS 2019-2022
* macOS support (updated in 2023 thanks to Stephen Saunders)
* OpenAL Soft sound backend primarily developed for Linux but works on Windows as well
* Sourcecode cleanup using the Artistic Style C++ beautifier to ensure the Git diffs and logs are clean
* Fixed tons of warnings using the Clang compiler
* Fast compile times using precompiled header support which allows to compile the entire engine and builtin tools in less than 30 seconds on a Ryzen 9
* Although not really supported but runs on exotic hardware like MIPS64, PPC64, ARM64 and E2K architectures
* Updated idRenderLog with new markers to support RenderDoc and Nvidia's Nsight
## Modding Support
RBDOOM-3-BFG allows mod editing and has many tiny fixes so custom content can be put into mod directories and the engine accepts it like vanilla Doom 3.
* TrenchBroom Mapping Support - see more information in the TrenchBroom section
* New PBR related material keywords like basecolormap, normalmap, rmaomap
* invertGreen( normalmap.png ) material keyword to allow flipping the Y-Axis for tangent space normal maps
* glTF2 .glb model support for static and skinned models (thanks to Harrie van Ginneken)
* Added back dmap and aas compilers as `standalone rbdmap.exe` tool (thanks to Pat Raynor) and improved them to work with TrenchBroom and Blender
* Changed dmap to support compiling maps straight from glTF2 .glb models instead of .map files using a new polygon based workflow
* Wavefront OBJ model support to make it easier getting static models from Blender/Maya/3D Studio Max into TrenchBroom
* Added in-engine Flash debugging tools and new console variables
* Added support for Mikkelsen tangent space standard for new assets (thanks to Stephen Pridham)
* Bumped the static vertex cache limit of 31 MB to roughly ~ 128 MB to help with some custom models and maps by the Doom 3 community
* com_showFPS bigger than 1 uses ImGui to show more detailed renderer stats like the original console prints with r_speeds
* .png .exr .hdr image support
* .ogg sound file support
* .pk4 archive support
* Reworked virtual filesystem so .resources and .pk4 archives in mod directories have a higher priority than in base/
* Native C++ AI & Weapons framework instead of Doomscript in the IcedHellfire mod by Justin Marshall (`mods/icedhellfire` Git branch)
If you want to start mod from a directory, you should first specify your mod directory adding the following command to the launcher:
"+set fs_game modDirectoryName"
so it would end up looking like: RBDoom3BFG +set fs_game modDirectoryName
IMPORTANT: RBDOOM-3-BFG does not support old Doom 3 modifications that include sourcecode modifications in binary form (.dll)
You can fork RBDOOM-3-BFG and create a new renamed binary that includes all required C++ game code modifications.
---
# ".plan"
If you want to see what is planned or in progress in a Trello/Kanban style manner look here: [RBDOOM-3-BFG projects](https://github.com/RobertBeckebans/RBDOOM-3-BFG/projects)
Short term goals:
* Node based Imgui particle editor
* Flash support through Adobe Animate or Blender
* Raytracing for accelerating the probe baking and optionally adding realtime global illumination
---
# May or may not ".plan"
* Replace traditional multipass forward shading with a faster forward+ solution
* [Volumetric Lighting](http://www.alexandre-pestana.com/volumetric-lights/)
* ReSTIR or some other realtime path tracing
* Optional alternative collision detection and physics with PhysX 5 or Jolt
---
# Renderer Features Explained
## Physically Based Rendering
Implementing Physically Based Rendering (PBR) in Doom 3 is a challenge and comes with a few compromises because the Doom 3 content was designed to work with the hardware constraints in 2004 and that even meant to run on a Geforce 3.
The light rigs aren't made for PBR but it is possible to achieve good PBR lighting even with the old content by tweaking the light formulars with a few good magic constants. However I also want to support the modding scene to allow them to create brand new PBR materials made with Substance Designer/Painter or other modern tools so multiple rendering paths have been implemented.
PBR allows artists to create textures that are based on real world measured color values and they look more or less the same in any renderer that follows the PBR guidelines and formulars.
***RBDOOM-3-BFG only supports the standard PBR Roughness/Metallic workflow.***
Adding PBR is a requirement to make the new content look the same in RBDOOM-3-BFG as in Blender 3.x with Cycles or Eevee and Substance Designer. PBR became the standard material authoring since 2014. With RBDOOM-3-BFG modders can work with modern tools and expect that their content looks as expected.
The PBR implementation is restricted to standard PBR using the Roughness/Metallic workflow for now. Specialized rendering paths for skin, clothes and vegetation will be in future releases.
## PBR Texture format
In Doom 3 a classic simple materials looks like this:
```
textures/base_wall/snpanel2rust
{
qer_editorimage textures/base_wall/snpanel2rust.tga
bumpmap textures/base_wall/snpanel2_local.tga
diffusemap textures/base_wall/snpanel2rust_d.tga
specularmap textures/base_wall/snpanel2rust_s.tga
}
```
It's usually rendered with Blinn-Phong specular with a fixed specular exponent.
Specularmaps are more or less Gloss maps.
In RBDOOM-3-BFG it uses the PBR GGX Cook-Torrence formular and you can vary the roughness along the material like in other modern engines and you usually define a texture with the _rmao suffix.
RMAO Image Channels | Description
:----------------------------- | :------------------------------------------------
Red | Roughness
Green | Metalness
Blue | Ambient Occlusion
Example material:
```
models/mapobjects/materialorb/orb
{
qer_editorimage models/mapobjects/pbr/materialorb/substance/metal04_basecolor.png
basecolormap models/mapobjects/pbr/materialorb/substance/metal04_basecolor.png
normalmap models/mapobjects/pbr/materialorb/substance/metal04_normal.png
rmaomap models/mapobjects/pbr/materialorb/substance/metal04_rmao.png
}
```
The engine will also look for _rmao.[png/tga] overrides for old materials and if it finds those it will render them using a better PBR path. Old school specularmaps also go through a GGX pipeline but the roughness is estimated from the glossmap.
The Ambient Occlusion will be mixed with the Screen Space Ambient Occlusion and will only affect indirect lighting contributed by the environment probes.
## Baked Global Illumination using Irradiance Volumes and Image Based Lighting
*To achieve the typical PBR look from an artistic point of view it also means to that it is necessary to add indirect lighting.
Doom 3 and even Doom 3 BFG had no indirect lighting.*
Doom 3 BFG is a big game. Doom 3, Resurrection of Evil and Lost Missions sum up to 47 big single player levels with an average of ~60 - 110 BSP portal areas or let's call them rooms / floors. Each room can have up to 50 shadow casting lights and most of them are point lights.
I needed a good automatic solution that fixes the pitch black areas without destroying the original look and feel of the game.
I also needed to add environment probes for each room so PBR materials can actually reflect the environment.
So RBDOOM-3-BFG comes with 2 systems to achieve this and both are automatic approaches so everything can be achieved in a reasonable amount of time.
The first system are environment probes which are placed into the center of the rooms. They can also be manually tweaked by adding env_probe entities in the maps. They use L4 spherical harmonics for diffuse reflections and GGX convolved mip maps for specular reflections.
The second system refines this by using a light grid for each room which provides a sort of a localized/improved version of the surrounding light for each corner of the room.
### Irradiance Volumes aka Light Grids
RBDOOM-3-BFG 1.3.0 brings back the Quake 3 light grid but this time the grid points feature spherical harmonics encoded as octahedrons and it can be evaluated per pixel. This means it can be used on any geometry and serves as an irradiance volume.
Unlike Quake 3 this isn't radiosity which is limited to diffuse only reflections. The diffuse reflectivity is built using all kinds of incoming light: diffuse, specular and emissive (sky, light emitting GUIs, VFX).
Lightgrids can be baked after loading the map and by typing:
```
bakeLightGrids [...]
limit[num] : max probes per BSP area (default 16384)
bounce[num] : number of bounces or number of light reuse (default 1)
grid( xdim ydim zdim ) : light grid size steps into each direction (default 64 64 128)
```
This will generate a ***.lightgrid*** file next to your .map file and it will also store a light grid atlas for each BSP area under ***env/maps/***
Limit is 16384 by default and means the maximum number of light grid points in a single light grid.
Quake 3 had one light grid that streched over the entire map and distributed lighting every 64 x 64 x 128 units by default.
If the maps were too big then q3map2 made the default grid size broader like 80 x 80 x 144, 96 x 96 x 160 and so on until the maximum number of light grid points was reached.
The Quake 3 approach wouldn't work with Doom 3 because the maps are too big and it would result in up to 800k probes for some maps or the grid density would very coarse.
RBDOOM-3-BFG uses the bounding size of the BSP portal areas and puts smaller light grids into those BSP areas.
This way we can maintain a good grid density and avoid wasting storage because of light grid points that are in empty space.
> But what is an Irradiance Volume or Light Grid exactly?
It tells each model or lit pixel how the indirect diffuse lighting is coming from any direction. The Probulator page by Yuri O'Donnell has some good examples:
Left: The captured view using a panorama layout. Right: The Diffuse lighting using Level 4 Spherical Harmonics aka Irradiance.
Now think of this for each of the grid points in RBDOOM-3-BFG. If a model is placed between those probes the lighting will be interpolated by the nearest 8 grid points similar like in Quake 3.
Quake 3 only stored the dominant light direction, the average light color of that direction and an ambient color term for each grid point.
In RBDOOM-3-BFG you basically can have the diffuse lighting information for **any** world space direction instead.
This is a way more advanced technique.
### Image Based Lighting and Environment Probes
Environment probes supplement the light grids. While light grids provide diffuse lighting information the signal isn't good enough to provide plausible specular light reflections. This is where environment probes are needed.
If a level designer doesn't put any env_probe entities into a map then they are automatically distributed through the map using the BSP area bounds and placed in the center of them.
Environment probes can be computed after loading the map and by typing:
```
bakeEnvironmentProbes
```
This will generate EXR files in ***env/maps/***.
The environment probes use an octahedron encoding and the specular mipmaps are convolved using the Split Sum Approximation by Brian Karris [Epic 2013]. Convolving the environment probes is done on the CPU using the id Tech 5 multi threading code so it will consume all your available cores.
For artists this basically means if you increase the roughness in your material then you increase the mip map level of the environment probe it samples light from and it gets blurier.
### Fallback for Missing Data
If you haven't downloaded the additional baked light data from the [RBDOOM-3-BFG ModDB Page](https://www.moddb.com/mods/rbdoom-3-bfg) and just run RBDOOM-3-BFG.exe with the required DLLs (or you built it yourself) it will use an internal fallback.
RBDOOM-3-BFG.exe has one prebaked environment probe that is compiled into the executable.
It's the light data from the Mars City 1 lobby in the screenshot above. Using this data for the entire game is inacurrate but a better compromise than using a fixed global light direction and some sort of Rim lighting hack like in version 1.2.0.
The default irradiance / radiance data gives the entire game a warmer look and it fits for being on Mars all the time.
### Some Examples of Indirect Lighting
Single spot light render with direct lighting only
Single spot light render causing indirect light bounce using the new irradiance light grid in RBDOOM-3-BFG combined with SSAO
`Raytraced` reference in Blender 2.83 with Cycles raytracing
Left: No global illumination. Ambient is pitch black like in original Doom 3. Right: Extra ambient pass for global illumination with r_forceAmbient 0.5.
## Filmic Post Processing
If you enable it with r_useFilmicPostProcessing 1 then you play DOOM 3 BFG the optics of a Zack Snyder movie.
It adds chromatic abberation and filmic dithering using Blue Noise.
The effect is heavy and is usually aimed in Film production to mix real camera footage with CG generated content.
Dithering demonstration: left side is quantized to 3 bits for each color channel. Right side is also only 3 bits but dithered with chromatic Blue Noise. The interesting fact about the dithering here is shown in the upper debug bands.
The first top band is the original signal. The second shows just 8 blocks and if you dither the those blocks with Blue Noise then it is close to the original signal which is surprising.
# TrenchBroom Mapping Support
***The goal of the TrenchBroom support is to make mapping for RBDOOM-3-BFG as easy as for Quake 1.***
Mapping for Doom 3 BFG using TrenchBroom requires an extended unofficial build that is bundled with the official RBDOOM-3-BFG 7z package.
You can find the customized TrenchBroomBFG version under tools/trenchbroom/.
More information about this custom TrenchBroomBFG and the source code is here:
https://github.com/RobertBeckebans/TrenchBroomBFG
Doom 3 BFG also requires some extensions in order to work with TrenchBroom.
The Quake 1/2/3 communities already adopted the Valve 220 .map format in the BSP compilers and I did the same with dmap in RBDOOM-3-BFG.
### TrenchBroomBFG speficic Changes
* idMapFile and dmap were changed to support the Valve 220 .map format to aid mapping with TrenchBroom
* Added exportFGD `[nomodels]` console command which exports all def/*.def entityDef declarations to base/_tb/fgd/ as Forge Game Data files. TrenchBroom has native support to read those files https://developer.valvesoftware.com/wiki/FGD.
If the nomodels argument is not given then it will also export all needed models by entity declarations to base/_tb/ as Wavefront OBJ files.
* Support ***angles*** keyword again for TrenchBroom like in Quake 3
* Added cmd convertMapToValve220 `