ericw-tools

• Website: http://ericwa.github.io/ericw-tools
• Documentation:
  • 2.0.0-alpha: https://ericw-tools.readthedocs.io
  • 0.18: qbsp, vis, light, bspinfo, bsputil
• Maintainer: Eric Wasylishen (AKA ericw)
• Email: ewasylishen@gmail.com

Original tyurtils:

• Website: http://disenchant.net
• Author: Kevin Shanahan (AKA Tyrann)
• Email: tyrann@disenchant.net

About

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.

Compiling

Required dependencies:

• Embree 4
• oneTBB

Optional dependencies:

• Python, Sphinx (for building manuals)
• Qt 6 (for lightpreview GUI)

Bundled dependencies:

• fmt
• jsoncpp
• nanobench
• pareto
• GoogleTest
• stb_image
• stb_image_write

Ubuntu 24.04

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/lightpreview

Windows, obtaining required dependencies via vcpkg

Open 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-tools

Open 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).

IDE Tips - CLion

• Modify the "Google Test" run/debug configuration template to have --gtest_catch_exceptions=0, otherwise the
  debugger doesn't stop on exceptions (segfaults etc.)

  (see: https://youtrack.jetbrains.com/issue/CPP-29559/Clion-LLDB-does-not-break-on-SEH-exceptions-within-GTest)

macOS 10.15+

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

Credits

• 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

License

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.