e6quisitory / wolf3d-clone

An attempt at making a clone of Wolfenstein 3D with a custom engine

Wolfenstein 3D Clone

1. Introduction & Demo
2. Pre-compiled Binaries
3. Build Instructions
   • Windows
   • macOS
   • Linux (Debian-based)
4. Controls & Map Loading
5. Immediate Goals
6. Later Goals
7. Credits
8. 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.

1. Install MSYS2 from here.

2. 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.

3. 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
   

4. 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
   

5. Clone this repo and cd into it.

   git clone https://github.com/e6quisitory/wolf3d-clone.git
   cd wolf3d-clone
   

6. Run the following to build the project into a .exe executable:

   mkdir build
   cd build
   cmake -G "Ninja" ../src
   ninja
   

7. Finally, run the executable like so:

   ./wolf3d-clone.exe
   

macOS

1. Ensure CMake and Ninja are installed on your Mac through Homebrew:

   brew install cmake
   brew install ninja
   

2. 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

3. Clone this repo and cd into it:

   git clone https://github.com/e6quisitory/wolf3d-clone.git
   cd wolf3d-clone
   

4. Run the following to build:

   mkdir build
   cd build
   cmake -G "Ninja" ../src
   ninja -j $(sysctl -n hw.physicalcpu)
   

5. 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.

1. Update your package lists

   sudo apt update
   

2. 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
   

3. Clone this repo and cd into it:

   git clone https://github.com/e6quisitory/wolf3d-clone.git
   cd wolf3d-clone
   

4. Run the following to build:

   mkdir build
   cd build
   cmake -G "Ninja" ../src
   ninja
   

5. 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 doors
• Esc 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
• 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)