ECWolf – The Wolf Front

You're right. Here is the full version with platform installation and usage sections added:

ECWolf

Author: Blzut3 First Release: September 18, 2012 Latest Release: October 1, 2016

ECWolf is an advanced source port for Wolfenstein 3D, Spear of Destiny, and Super 3D Noah's Ark, built on top of the Wolf4SDL code base. It draws heavily from the Doom source port ZDoom, and is widely considered the most feature-rich and mod-friendly way to play and create content for the Wolfenstein 3D engine.

What is ECWolf?

ECWolf was created with two goals in mind: giving players a better experience, and giving modders powerful tools without requiring them to touch the source code.

For players, ECWolf offers:

Better and more flexible control binding
Support for widescreen resolutions
Unlimited save slots
All supported games playable from a single binary — no need to maintain separate installations
Accuracy to the original game roughly equivalent to how ZDoom relates to vanilla Doom

For modders, ECWolf makes it possible to create and distribute mods as a single neat package file — just like mods for Doom. This means you no longer need to distribute every sprite or asset in the game just to add one new weapon. Only the files that actually change need to be included.

History

ECWolf is based on Wolf4SDL, itself a port of the original Wolfenstein 3D DOS code to the SDL multimedia library. Building on Wolf4SDL's foundation, ECWolf adds a wide range of features pulled from ZDoom, greatly expanding what is possible for the Wolfenstein engine.

Starting in 2015, a growing number of mods and total conversions began releasing exclusively for ECWolf, with notable projects from community members AstroCreep and Executor among the most prominent examples.

Supported Games

ECWolf requires the original game data files in order to run. The following games are supported:

Wolfenstein 3D (full version and shareware)
Spear of Destiny (full version and demo)
Mission 2: Return to Danger
Mission 3: The Ultimate Challenge
Super 3D Noah's Ark

Support for additional Wolfenstein engine games is planned for future versions, including Blake Stone, Corridor 7: Alien Invasion, and Operation Body Count.

Installing and Running ECWolf

ECWolf is available for Windows, Mac OS X, Linux, and Android. Prebuilt binaries are available for most users. For those who wish to compile from source, the code is available on GitHub and can be built using CMake on all supported platforms.

In all cases, ECWolf needs your original game data files to run. These can be placed in the same directory as the ECWolf binary, in ~/.config/ecwolf (on Linux and Mac), or added manually to the ecwolf.cfg configuration file under BaseDataPaths.

Windows

To compile ECWolf on Windows you will need the following tools:

CMake 3.11 or later
Git
A C++ compiler — Visual Studio 2017 is recommended, though Visual Studio 2005 and MinGW-w64 8.1 also work

ECWolf bundles its own copies of the required libraries (SDL, SDL_mixer, SDL_net, zlib, bzip2, and jpeg), so you do not need to install these separately unless you want to.

To get started, use Git to download the source code:

git clone https://github.com/ECWolfEngine/ECWolf.git --recursive

Open the CMake GUI, set the source path to the root of the downloaded repository (not the src subfolder), and create a build folder inside it to use as the output directory. Click Configure, select your compiler (Visual Studio or MinGW), and click Finish. Once CMake has configured the project successfully, click Generate.

If using Visual Studio, open the generated .sln file and build the project. If using MinGW, open a command prompt, navigate to the build directory, and run mingw32-make.

A few tips for Visual Studio users:

Set Configuration Type to Release, not Debug
Set the Toolset to x86 (e.g. msvc_x86_x64)
If you encounter an error about OpusFile, enable INTERNAL_SDL_MIXER_CODECS in CMake to use the bundled copy

Mac OS X

To compile ECWolf on Mac OS X you will need:

CMake 2.6 or later
GCC 4.4.1 or later
libSDL 1.2
SDL_mixer for ECWolf (standard SDL_mixer 1.2 also works, but some features will be disabled)
Git

Optional dependencies include zlib 1.2.3 and bzip2 1.0.5.

Download the source using Git:

git clone https://github.com/ECWolfEngine/ECWolf.git --recursive

Then navigate into the downloaded folder, create a build directory, and compile:

cd ecwolf mkdir build cd build cmake .. make

Once compiled, run ECWolf with:

./ecwolf

If you want to create a distributable app bundle, note that the official bundles are assembled by hand. You can build the binary yourself and replace the Contents/MacOS/ecwolf binary and corresponding pk3 file in an existing bundle with your own compiled versions.

Linux

Linux users first need to install the required dependencies through their distribution's package manager. The core dependencies are GCC, make, CMake, libSDL 2.x, SDL_mixer 2.x, and SDL_net 2.x. Optional dependencies include zlib, bzip2, libjpeg, and GTK3.

Install commands for common distributions:

Debian/Ubuntu: sudo apt-get install g++ make cmake libsdl2-dev libsdl2-mixer-dev libsdl2-net-dev git zlib1g-dev libbz2-dev libjpeg-dev libgtk2.0-dev

Fedora: dnf install gcc-c++ make cmake SDL2-devel SDL2_mixer-devel SDL2_net-devel git zlib-devel bzip2-devel libjpeg-turbo-devel gtk2-devel

openSUSE: zypper install gcc-c++ make cmake libSDL2-devel libSDL2_mixer-devel libSDL2_net-devel git zlib-devel libbz2-devel libjpeg-devel gtk2-devel

Arch Linux: pacman -S --needed gcc make cmake sdl2 sdl2_mixer sdl2_net git zlib bzip2 libjpeg-turbo gtk2

Gentoo: emerge -avn sys-devel/gcc sys-devel/make dev-util/cmake media-libs/libsdl2 media-libs/sdl2-mixer media-libs/sdl2-net dev-vcs/git sys-libs/zlib app-arch/bzip2 media-libs/libjpeg-turbo x11-libs/gtk+

Solus: sudo eopkg install g++ make cmake binutils glibc-devel pkg-config sdl2-devel sdl2-mixer-devel sdl2-net-devel git zlib-devel bzip2-devel libjpeg-turbo-devel libgtk-2-devel

Once dependencies are installed, download the source and create a build directory:

mkdir -pv ~/ecwolf_build cd ~/ecwolf_build git clone https://github.com/ECWolfEngine/ECWolf.git mkdir -pv ecwolf/build

Then compile:

cd ~/ecwolf_build/ecwolf/build cmake .. -DCMAKE_BUILD_TYPE=Release -DGPL=ON make

Run ECWolf with:

./ecwolf

If ECWolf reports that it cannot find any game data, make sure your original game files are placed in the same directory as the ECWolf binary, in ~/.config/ecwolf, or listed under BaseDataPaths in ~/.config/ecwolf/ecwolf.cfg.

To install ECWolf system-wide so it can be run from any user account, create the installation directories and copy the compiled files:

sudo mkdir -pv /usr/games/ecwolf sudo cp -v ecwolf ecwolf.pk3 /usr/games/ecwolf/

Then create a launch script in /usr/bin so the game can be started simply by typing ecwolf in a terminal.

To uninstall, remove the /usr/games/ecwolf directory and the /usr/bin/ecwolf script.

To update ECWolf to the latest version, navigate to the source directory and run:

git pull

Then recompile as above.

Android

Compiling ECWolf for Android is a cross-compilation process, meaning you build it on a desktop machine (Linux is recommended as the host) and then transfer the result to your Android device.

You will need:

Java JDK 8
Android SDK 19.1.0
Android NDK r14b
CMake 3.6
A completed native build of ECWolf for your host system (required because the build process generates some files using tools that must run on the host machine)

It is strongly recommended to use the bundled copies of all third-party libraries.

After setting up the Android SDK and generating a signing key, configure CMake with the required variables including the NDK location, target architecture (typically armeabi-v7a), SDK paths, and your signing key details. Make sure to enable INTERNAL_SDL, INTERNAL_SDL_MIXER, INTERNAL_SDL_MIXER_CODECS, and INTERNAL_SDL_NET.

Once configured, run make in the build directory. If successful, a signed ecwolf.apk file will be produced. You can install and launch it directly on a connected device with USB debugging enabled using:

make runadb

After installing, place your game data files on the device at:

/sdcard/Beloko/Wolf3d/FULL/

Debug Mode and Cheat Codes

Debug mode can be enabled at any time during gameplay by pressing Shift + Alt + Backspace. Unlike the original DOS game or Wolf4SDL, no startup parameter is required to access it first.

Note: Tab can be substituted with the grave (`) or backspace key for any of the commands below — useful if you have Tab assigned to another function such as the automap.

Tab + B — Change the status bar border texture
Tab + C — Count the number of actors present in the level
Tab + D — Toggle the on-screen FPS counter
Tab + E — Exit the current level
Tab + F — Display player coordinates and viewing angle
Tab + G — Toggle God Mode (press again to also disable the red damage flash)
Tab + H — Deal 16 points of damage to the player
Tab + I — Give all weapons, full ammo, full health, and 100,000 points
Tab + K — Give keys based on lock definitions
Tab + L — Print level statistics (kill ratio, secret ratio, treasure ratio, time)
Tab + M — Enable experimental mouse look
Tab + N — Toggle no-clip mode
Tab + O — Reveal the full overhead map
Tab + P — Take a screenshot
Tab + Q — Quit the game
Tab + S — Enable slow motion
Tab + T — Disable enemy detection by sight or sound
Tab + V — Add a delay before rendering the next frame (for slower machines)
Tab + W — Warp to any level
Tab + X — Give an inventory item
Tab + Z — Spawn an actor in front of the player

Notable Engine Quirks and Fixes

ECWolf inherits the Wolfenstein 3D engine but addresses several known bugs and quirks from the original. Here is a plain-language summary of the most notable ones:

Enemy movement When enemies lose sight of the player and need to navigate around walls, the original engine had a bug causing them to only ever try moving north, northwest, or west — meaning their pathfinding was broken from certain directions. ECWolf currently preserves this behavior.

Frame rate and game speed The original engine adapted to slower computers by measuring how many fractions of a second had passed between frames and using that as a multiplier for movement, attack chances, and other calculations. While this kept the game running at a consistent pace on slow machines, it introduced subtle differences in gameplay depending on frame rate. The original game locked to approximately 17.5fps during demo recording and playback to keep things predictable. ECWolf addresses this more cleanly — the game simulation now runs independently of the frame rate at a fixed 70 ticks per second, similar to how modern Doom ports handle it.

Fake Hitler fireballs One of the most well-known quirks is that the fireballs fired by the Fake Hitler bosses slow down as your frame rate increases. This was caused by a combination of the frame rate compensation system and a coding typo. ECWolf fixes this so the fireballs always travel at a consistent speed.

Pushwalls moving too far Due to a typo in the original code, pushwalls could sometimes slide three spaces instead of the intended two, especially at higher frame rates. Wolf4SDL fixed this, and ECWolf inherits that fix. However, since some community maps were designed around the three-space movement, ECWolf allows this behavior to be restored through a custom map setting.

Picking up items while moving backward In the original engine, players could not pick up items while walking backward because item detection was tied to the 3D renderer. ECWolf moves item pickup detection to player movement instead, fixing the issue.

Player weapon hit detection Whether a shot hit an enemy originally depended on rendering information, which could cause inconsistencies. ECWolf recalculates this independently of the renderer using a proper ±9 degree cone from the player's center.

Projectile collision The original engine used two different size values for projectile collision — a smaller one for walls and a larger one for the player. ECWolf currently uses a compromise between the two, with a more accurate solution planned for a future version.

Enemy spacing and overlap Enemies claim a new tile the moment they start moving toward it, immediately freeing their current tile. This means multiple enemies can visually overlap if they stop to shoot while heading to the same space. ECWolf intentionally preserves this behavior.

Enemy hit radius Each enemy has an effective collision radius of about 42 pixels — larger than a full tile — but because enemy AI does not use collision detection when moving, they can still navigate freely. Guards flanking a doorway can block the player from moving through even if they are not visually in the way. ECWolf preserves this behavior.

Editing Tools

The following editors are compatible with ECWolf and Wolf3D modding in general:

WDC
Havoc's Wolf3D Editor
ChaosEdit — can open gamemaps files but cannot be used for exporting
Slade — recommended for lump management

Mod Format

ECWolf supports several data container formats for mods. The recommended format is PK3 (a renamed zip file), which offers fast compression and allows files to be organized into logical folders. It is strongly recommended to use the PK3 or PK7 extension rather than zip or 7z, as players are accustomed to extracting those file types rather than treating them as mod packages.

Format	Compression	Folder Paths	Notes
PK3 (Zip)	Yes	Yes	Recommended — fast and flexible
WAD	No	No	Simple uncompressed format
7z	Yes	Yes	Slow decompression
PAK	No	Yes	No standard tools available
GRP	No	No	No namespace access
RFF	No	No	No namespace access

Name Spaces

ECWolf uses a folder-based naming system to organize different types of mod content. When using WAD files, marker lumps can be used instead of folders. The main namespaces are:

graphics/ — title screens, sign-on screens, and other 2D graphics
hires/ — high resolution texture replacements
flats/ — floor and ceiling textures
maps/ — individual level files stored within WADs
music/ — background music tracks
patches/ — small textures referenced by the TEXTURES lump
sounds/ — sound files referenced by SNDINFO
sprites/ — actor sprites, which can be organized into sub-folders
textures/ — wall textures used as-is

Mod Compatibility Note

ECWolf's 1.x series does not guarantee backward compatibility between updates — fixing issues takes priority over preserving older mod behavior. Starting with ECWolf 2.0, backward compatibility will be maintained so that released mods continue to work with future engine updates.

License

ECWolf is dual-licensed. By default it uses the GNU GPL, but this can be switched to the original Wolfenstein 3D non-commercial license using the -DGPL=OFF flag when compiling. The GPL version uses the DOSBox OPL emulator for music; the non-commercial version uses the MAME OPL emulator instead.

The GPL licensing of Wolfenstein 3D was confirmed by id Software co-founder John Carmack in a 2009 statement, in which he noted that the source had originally been released under a non-commercial license and was later re-released under the GPL. The Wolf4SDL Debian packages further confirm this.

All new code contributed to ECWolf, including code adapted from ZDoom, is licensed under the 3-clause BSD license. Bundled libraries such as zlib carry their own respective licenses.