Wolfenstein 3D Clone
- Introduction & Demo
- Pre-compiled Binaries
- Build Instructions
- Controls & Map Loading
- Immediate Goals
- Later Goals
- Credits
- Resources Used
Introduction
I'm attempting to make a clone of the classic 1992 id Software game, Wolfenstein 3D. Cloning most of the functionality in the game from scratch is the goal, including rendering the game world, enemies, weapons, sound system, etc. So far, I've implemented the following functionality:
- Raycasting
- Selectively textured walls with lighting
- Sprites
- GPU accelerated texture mapping
- Doors w/ automatic closing
- Map loading from a
csv
file - Smooth movement using VSYNC
- Mouse to look around
- Minimap (dev tool)
Here's a couple short videos of what the engine is currently capable of:
Engine_Demo.mp4
Minimap_Demo.mp4
The only dependacy of the project thus far is SDL2, used to open a window and render pixels into it, hardware-based texture scaling, reading keyboard and mouse inputs, and VSYNC.
The comments in the commits are full of detailed explanations on the implementation of parts of the engine, how I encountered and fixed bugs, etc. Worth looking at if you're building something like this yourself.
Pre-compiled Binaries
I've made pre-compiled binaries for Windows and macOS. Head on over to the Releases section to obtain them, and see the below instructions on how to run them.
Linux users will have to resort to building the project themselves, instructions here. Someday I'll get around to making a Linux binary as well, but for now, I've had enough of build systems and want to get back to coding.
Windows
Unzip the archive, go into the bin
folder, then double-click on wolf3d-clone.exe
.
If you're running Windows 11, there is a chance SmartScreen might flag the executable as being potentially malicious. This is due to the code not being signed (I still gotta figure that out). So for now, either turn off SmartScreen temporarily or allow the executable to bypass it (if the option is present).
macOS (x86 & ARM)
Unzip the archive. Inside you'll find a run.command
script. Double click it to launch the game. It is expected that macOS will initially not allow you to run the script; there'll be a pop up saying:
"run.command” cannot be opened because it is from an unidentified developer
This is due to the code not being signed (I have yet to figure that out). So, for now, close that pop up, then go to:
System Settings -> Privacy & Security
There, at the bottom you'll see something along the lines of "run.command" was blocked..." and next to it a button that says Open Anyway
. Hit that, after which it'll likely prompt you for your password/fingerprint, after which there'll be another dialog, hit enter on that as well, and finally the game should launch.
Build Instructions
If you'd like to compile/build the project yourself, below are instructions on how to do so for each major platform.
Windows
The following instructions assume you're running on an x86-64 Windows machine.
-
Install MSYS2 from here.
-
When the install wizard is finished, it'll launch a terminal for the UCRT64 environment. We do not want this; instead we'd like to work in a terminal for the CLANG64 environment. So, in the Windows start menu search, type MSYS2 CLANG64 and a program of that name should pop up. Click it and another terminal will pop up.
-
Inside this terminal for the CLANG64 environment, we first update all pre-installed packages by running the command below. Enter Y (for yes) when prompted to allow installation. The terminal might close, and if it does, reopen from the start menu as before.
pacman -Suy
-
Now we install the packages we need to clone this repo and compile it.
pacman -S mingw-w64-clang-x86_64-clang pacman -S mingw-w64-clang-x86_64-cmake pacman -S mingw-w64-clang-x86_64-ninja pacman -S mingw-w64-clang-x86_64-SDL2 pacman -S git
-
Clone this repo and
cd
into it.git clone https://github.com/e6quisitory/wolf3d-clone.git cd wolf3d-clone
-
Run the following to build the project into a
.exe
executable:mkdir build cd build cmake -G "Ninja" ../src ninja
-
Finally, run the executable like so:
./wolf3d-clone.exe
macOS
-
Ensure
CMake
andNinja
are installed on your Mac through Homebrew:brew install cmake brew install ninja
-
Head on over to the SDL releases page and download the latest SDL release for macOS (with a
.dmg
extension).- After download, mount the
.dmg
archive (open it) - Inside you'll see a macOS framework bundle named
SDL2.framework
. Copy it. - Open a Finder window, hit
Command
+Shift
+G
and type in/Library/Frameworks
- Now paste the copied
SDL2.framework
into this folder
- After download, mount the
-
Clone this repo and
cd
into it:git clone https://github.com/e6quisitory/wolf3d-clone.git cd wolf3d-clone
-
Run the following to build:
mkdir build cd build cmake -G "Ninja" ../src ninja -j $(sysctl -n hw.physicalcpu)
-
Now a clickable
.app
executable should be present in this build directory. You can run it from the terminal with the command below, and you can also navigate to it and simply double-click it as well to launch.open -n ./wolf3d-clone.app
Linux (Debain-based)
Note that the below instructions have been tested on Ubuntu, and should work on other Debian-based distros as well (ex. Linux Mint, etc.). I cannot ensure that they'll work on non-Debian based distros, like Arch, CentOS, etc.
-
Update your package lists
sudo apt update
-
Install the following packages
sudo apt install build-essentials sudo apt install cmake sudo apt install ninja-build sudo apt install libsdl2-dev sudo apt install git
-
Clone this repo and
cd
into it:git clone https://github.com/e6quisitory/wolf3d-clone.git cd wolf3d-clone
-
Run the following to build:
mkdir build cd build cmake -G "Ninja" ../src ninja
-
Now run the compiled executable like so:
./wolf3d-clone
Controls & Map Loading
Game controls
W
,A
,S
,D
to move- Mouse to look around
spacebar
for opening doorsEsc
to exit game
Minimap controls
- ~ (tilde) key to unlock/relock the mouse from the main window
- Left click on tiles in the minimap to spawn to them (if possible)
- Right click anywhere on minimap to change player view direction
Map loading
The map file is map.csv
, located in the assets
folder. It is ASCII encoded, not UTF-8 encoded. I find that editing the file is easiest in Excel.
As for how to construct the map, i.e. what the values in the map.csv
file mean, I have yet to type up a new guide; I will get to that soon. In the mean time, you can read this old guide and look at the values in the included map.csv
and try to piece things together.
Immediate Goals
- Enemy AI & character animation
- Weapons
- Multithreaded raycasting
- Thread pool
- Mutexes/locks for shared data access b/w threads
Later Goals
- Linux pre-compiled binary
- Write a more sophisticated CMake script that:
- In
Debug
config simply compiles into executable - In
Release
config makes a proper, signed, pre-compiled binary package for the platform (Windows, macOS, Linux) using CPack- Downloads a copy of SDL2, puts it inside the package, and links executable to that local copy (changes
RPATH
) - Puts
assets
folder inside binary package as well
- Downloads a copy of SDL2, puts it inside the package, and links executable to that local copy (changes
- In
- Darken distant walls (shadow/depth effect)
- Textured ceiling & floor
- Add joystick support
- Port to browser using Webassembly
- Networked multiplayer (aspirational)
- Proper map editor (aspirational)
- Port to iOS?
Credits
All wall and sprite textures + the logo at the top of this README are from the official Wolfenstein 3D artwork that shipped in the game back in 1992. I found them here.
Resources Used
- Game Engine Blackbook - Wolfenstein 3D by Fabien Sanglard
- Wolfenstein 3D's map renderer (video)
- Super Fast Ray Casting in Tiled Worlds using DDA (video)
- Make Your Own Raycaster Series (video)