A fork of ericw-tools — the modern Quake/Half-Life/Source
map compiler suite (qbsp / vis / light, Embree 4) by Eric Wasylishen, itself descended from Tyrann's
tools and id Software's originals. Maintained by ProtoAus
(same author as the slopbroom TrenchBroom fork), primarily to sharpen the
light compiler and its ergonomics for the FTEQW workflow.
Repo: https://github.com/ProtoAus/protoanus-tools
Implemented
- Non-zero exit code on argument errors. Upstream
qbsp/vis/lightprinted their help text and returned 0 on an unknown/invalid option or wrong operand count — so build front-ends (TrenchBroom compile profiles, scripts) saw "success" and silently shipped a map with no lighting. These tools now return a non-zero status on a genuine argument error (while-help/-h/-?still returns 0), so the failure is actually detected. SeeCHANGES.md. light -denoise— OIDN lightmap denoising. An optional Intel Open Image Denoise pass over the baked lightmap, so far fewer samples give clean GI / AO / soft shadows (no denoiser exists upstream). The whole lightmap is denoised as one atlas in a single pass (one consistent exposure + cross-face context, so no per-face tiling/grid), not face-by-face. Optional dependency: if OIDN isn't found at build time,-denoiseis a graceful no-op. SeeCHANGES.md.- External mesh occluders (Source
-StaticPropPolys).lightcasts accurate mesh-shaped shadows from real prop meshes (.obj/.iqm) instead of collision-hull/brush-proxy approximations. Point it at your existing props with-propshadowclasses "prop_static prop_detail ..."(reads each entity's model/origin/angles/scale — no map edits), or place a one-off_light_meshentity. No new dependency (minimal in-repo loaders). SeeCHANGES.md. light -propvertexlight— static-prop per-vertex lighting (Source-StaticPropLighting). Bakes the finished world lighting at every vertex of each placed IQM prop — one record per placement — into a newRGBPROPLIGHTBSPX lump, so an engine can light a prop's sunlit top and shadowed underside differently instead of sampling one point for the whole model. Uses the same classnames as-propshadowclasses. Engine-side consumption (e.g. FTEQW multiplying it over live PBR lighting) is a separate step. SeeCHANGES.md.
Roadmap (planned; see CHANGES.md for design + status)
- Denoise AOV guide buffers — feed OIDN albedo/normal guides for sharper edge preservation (the whole-atlas denoise already removes the per-face grid without them, using replicated-border gutters).
- Alpha-tested ("fence") mesh shadows — foliage/grate props need the occluder mesh on the filter geometry with per-triangle alpha, rather than as an unconditional occluder.
This fork tracks ericw-tools 2.0.0-alpha and remains GPLv2-or-later (see COPYING / gpl_v3.txt).
All original copyrights and credits below are retained; the fork's additions are likewise GPL. Upstream is
the authority for the tools' core documentation (https://ericw-tools.readthedocs.io); build instructions
are unchanged (build-windows.ps1 / build-linux.sh, CMake + Embree 4 + oneTBB — the light -denoise
feature adds an optional Open Image Denoise dependency, auto-disabled if absent).
- Website: http://ericwa.github.io/ericw-tools
- Documentation:
- Maintainer: Eric Wasylishen (AKA ericw)
- Email: [email protected]
- Website: http://disenchant.net
- Author: Kevin Shanahan (AKA Tyrann)
- Email: [email protected]
ericw-tools is a branch of Tyrann's quake 1 tools, focused on adding lighting features, mostly borrowed from q3map2. There are a few bugfixes for qbsp as well. Original readme follows:
A collection of command line utilities for building Quake levels and working with various Quake file formats. I need to work on the documentation a bit more, but below are some brief descriptions of the tools.
Included utilities:
-
qbsp - Used for turning a .map file into a playable .bsp file.
-
light - Used for lighting a level after the bsp stage. This util was previously known as TyrLite
-
vis - Creates the potentially visible set (PVS) for a bsp.
-
bspinfo - Print stats about the data contained in a bsp file.
-
bsputil - Simple tool for manipulation of bsp file data
See the doc/ directory for more detailed descriptions of the various tools capabilities. See changelog.md for a brief overview of recent changes or https://github.com/ericwa/ericw-tools for the full changelog and source code.
Required dependencies:
Optional dependencies:
- Python, Sphinx (for building manuals)
- Qt 6 (for
lightpreviewGUI)
Bundled dependencies:
NOTE: Builds using Ubuntu's embree packages produce a significantly slower light (i.e. over twice as slow) than ones released on Embree's GitHub. See build-linux-64.sh for a better method.
sudo apt update
sudo apt install libembree-dev libtbb-dev cmake build-essential g++ qt6-base-dev
git clone --recursive https://github.com/ericwa/ericw-tools
cd ericw-tools
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j 8
# run tests
./tests/tests
# print qbsp help
./qbsp/qbsp --help
# launch lightpreview gui
./lightpreview/lightpreviewOpen a cmd window. First, obtain vcpkg and build the dependencies:
git clone https://github.com/microsoft/vcpkg
cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg.exe install embree tbb
cd ..Next, clone the ericw-tools git repository + submodules:
git clone --recursive https://github.com/ericwa/ericw-toolsOpen the ericw-tools folder in VS2022 (or higher) as a CMake project.
Go to "Project -> CMake Settings". Under "CMake Toolchain File", press the "..." button and browse to vcpkg\scripts\buildsystems\vcpkg.cmake. Then press "Save" to save your CMakeSettings.json.
Once CMake finishes, you should be able to select e.g. qbsp.exe (qbsp\qbsp.exe) in the "Select Startup Item" dropdown in the toolbar. (I had to restart VS).
-
Modify the "Google Test" run/debug configuration template to have
--gtest_catch_exceptions=0, otherwise the
debugger doesn't stop on exceptions (segfaults etc.)
brew install embree tbb qt@6 cmake
python3 -m pip install sphinx_rtd_theme
git clone --recursive https://github.com/ericwa/ericw-tools
cd ericw-tools
mkdir build
cd build
cmake .. -DCMAKE_PREFIX_PATH="$(brew --prefix embree);$(brew --prefix tbb)" -DCMAKE_BUILD_TYPE=Release
make
- Kevin Shanahan (AKA Tyrann) for the original tyrutils
- id Software (original release of these tools is at https://github.com/id-Software/quake-tools)
- rebb (ambient occlusion, qbsp improvements)
- q3map2 authors (AO, sunlight2, penumbra, deviance are from q3map2)
- Spike (hexen 2 support, phong shading, various features)
- MH (surface lights based on MHColour)
- mfx, sock, Lunaran (testing)
- Thanks to users at func_msgboard for feedback and testing
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Builds using Embree are licensed under GPLv3+ for compatibility with the Apache license.