fabiensanglard / gebbwolf3

Book about wolfenstein 3D

Game Engine Black Book: Wolfenstein 3D

This is the source code for the Game Engine Black Book: Wolfenstein3D. I am releasing the source code (.tex) under GPL license. I retain ownership of all drawings and only provide them so the overall thing is compilable.

Note: For all systems, make sure you have Inkscape version v1.0.0 or above. If you don't, the conversion from SVG to PNG will fail.

To compile on Mac OS X:

• Install golang: https://go.dev/
• Install Inkscape (min v1.0.0):
  • via installer: https://inkscape.org/download/
  • or via Homebrew: brew cask install xquartz inkscape
• Install MacTeX library (for epstopdf and pdflatex):
  • via installer: https://tug.org/mactex/mactex-download.html
  • or via Homebrew, with GUI: brew cask install mactex
  • or via Homebrew, without GUI: brew cask install mactex-no-gui
• Make sure inkscape binary is in your PATH or symlink it where your PATH points to.
• Run:
  • ./make.sh

To compile on Debian GNU/Linux and derivatives (Ubuntu):

• Install Inkscape and TeX Live library (for epstopdf and pdflatex):
  • sudo apt install inkscape texlive texlive-font-utils texlive-fonts-recommended texlive-latex-extra golang-go
• Run:
  • ./make.sh

To compile on Windows:

• Install WSL1 or WSL2.
• Follow Linux instructions.

To speed up compilation:

• Build with ./make.sh debug (uses 100 DPI assets)
• Comment out the part you are not working on in src/book.tex

Fabien Sanglard

gebbwolf3's Issues

Errata: 3dFx to 3dfx

https://github.com/fabiensanglard/gebbwolf3/blob/master/src/epilogue.tex#L25

3dFx's Voodoo has wrong capitalization, should be 3dfx's Voodoo

v2.2: p167 Aardwolf room is sealed

In the E2M8 drawing, notice there are no push walls leading to the red triangle; the room is sealed.

is sealed is a bit confusing. It seems that there is no way into the room.
However, the Aardwolf room does have a door (not a push wall though). Upon opening it, players will see the Aardwolf sign.

Source: https://wl6.fandom.com/wiki/Aardwolf_sign and https://joesiegler.blog/2016/08/call-apogee-and-say-aardwolf/
Video Demo: https://youtu.be/WPaMyyimbtc?si=wTRgQVoZSFfGjiAW&t=558

make.sh fails identically on Ubuntu 22.04 and WSL2

Installed all required packages and ran ./make.sh.

book.log shows:

! Emergency stop.
<*> \def\forrelease{} \input{src/book.tex}
End of file on the terminal!

book_ubu2204.log

EDIT: was able to resolve by adding an \end{document} line to src/team.tex

AMD/Cyrix statment

Reported via email by Troy Wilkins:

On p29:

Trivia : Two other companies produced Intel 386 clones: AMD and Cyrix. Their mediocre
performance did not justify the lower cost and as a result they never gained significant market share. Almost all PCs featured an Intel CPU. Interestingly, AMD evolved to become a
serious challenger while Cyrix merged with National Semiconductor in 1997.

AMD didn't produce a 386 until 1991, and before that, the 8088, 8086 and 80286 CPUs they made performed pretty much identically to the same clock speed CPU of the same type made by Intel. The reason they didn't produce 386s until 1991 was because of Intel taking legal action to try to prevent them, and successfully delaying AMD until they had started producing 486s. Once AMD were able to produce 386s, they produced the worlds fastest 386s, with the Am386DX @ 40MHz, while the fastest i386 was 33MHz. So the reason AMD didn't gain significant market share was because of Intels legal action,NOT because of " mediocre
performance", and this "trivia" is, at best, misleading in my humble opinion.

Errata: KB to kB

https://github.com/fabiensanglard/gebbwolf3/blob/master/src/hardware.tex#L369

The IEC notation of kilobyte is kB with a lower case K.

286 back to Real-Mode sources?

"Various tricks had to be used, among them faking a keyboard Ctrl-Alt-Del reboot to reset the CPU without actually rebooting." The keyboard controller (really a microcontroller) on the system board was used to reset the CPU directly, by generating a RESET signal. Please remove the bit about Ctrl-Alt-Del unless you can show at least one piece of software which actually did that. The keyboard controller reset was designed in, because the PC/AT BIOS itself needed to switch to protected mode and back when testing extended memory.

"Various tricks had to be used, among them using the keyboard controller to reset the CPU without actually rebooting."

Missing Pages in v2.2

v2.2 is about 5 pages shorter than the previous versions due to missing pages in Team Chapter. The reason for that seems to be \end{document} before the missing text.

Errata: p48 Integraph -> Intergraph

https://github.com/fabiensanglard/gebbwolf3/blob/master/src/hardware.tex#L601

Integraph -> Intergraph (eg, missing first 'r')

Wrong extension name for VSWAP.WL1 file

In page_manager_architecture.svg / page_manager_architecture.eps file,
file extension for "VSWAP" file should be "WL1", not "WL"

Script make.sh does not convert SVG images when launched from its root directory

Script does not convert SVG images when launched from its root directory and outputs an error message instead.

• Steps to reproduce
  Launch the compilation with:

cd gebbwolf3/ && ./make.sh 

• Result
  The script outputs an error message:

find: screenshots_svg: No such file or directory

• Expected result
  The script should walk through src/screenshots_svg and compile SVG images in PNG (if newer)

Compilation script does not work for Inkscape 0.92 or older

Compilation script make.sh defines Inkscape executable path as /Applications/Inkscape.app/Contents/MacOS/inkscape.
This path does not work for Inkscape 0.92 or older with executable in /Applications/Inkscape.app/Contents/Resources/bin/inkscape.

Either adapt the path to manage Inkscape 0.92 (with PATH system variable) or specify 1.0 as Inkscape minimum version.

Steps to reproduce

1. Install Inkscape 0.92
2. Remove PNG already converted from SVG drawings to force conversion calls to Inkscape:

rm src/screenshots/386_layout_drawing.png src/screenshots/386_packaging_die.png src/screenshots/bsp_map.png src/screenshots/clear_screen_pixels.png src/screenshots/lines.png
rm src/screenshots_300dpi/386_layout_drawing.png src/screenshots_300dpi/386_packaging_die.png src/screenshots_300dpi/bsp_map.png src/screenshots_300dpi/clear_screen_pixels.png src/screenshots_300dpi/lines.png

3. Remove 2>&1 from Inkscape command lines (make.sh lines 52 and 60) to display errors
4. Launch the compilation with:

cd gebbwolf3/ && ./make.sh 
# or, see issue #7:
cd gebbwolf3/src/ && ../make.sh

Result
The script outputs an error message (and launch Inkscape GUI) for each call to Inkscape:

Convert screenshots_svg/bsp_map.svg to PNG (100dpi).
/BuildRoot/Library/Caches/com.apple.xbs/Sources/AppleFSCompression/AppleFSCompression-96.200.3/Common/ChunkCompression.cpp:49: Error: unsupported compressor 8
/BuildRoot/Library/Caches/com.apple.xbs/Sources/AppleFSCompression/AppleFSCompression-96.200.3/Libraries/CompressData/CompressData.c:353: Error: Unknown compression scheme encountered for file '/System/Library/CoreServices/CoreTypes.bundle/Contents/Resources/Exceptions.plist'
/BuildRoot/Library/Caches/com.apple.xbs/Sources/AppleFSCompression/AppleFSCompression-96.200.3/Common/ChunkCompression.cpp:49: Error: unsupported compressor 8
/BuildRoot/Library/Caches/com.apple.xbs/Sources/AppleFSCompression/AppleFSCompression-96.200.3/Libraries/CompressData/CompressData.c:353: Error: Unknown compression scheme encountered for file '/System/Library/CoreServices/CoreTypes.bundle/Contents/Library/AppExceptions.bundle/Exceptions.plist'
[...]

Expected result
The script should convert SVG images to PNG without error(s).

Infos
MacOS 10.14.6
Inkscape 0.92.2

v2.2: Missing table of contents

The current version (v2.2) of the book at https://fabiensanglard.net/b/gebbwolf3d.pdf lacks table of contents, unlike the previously released one that was available there (v2020.11.26).

It's also worth noting that table of contents in current version of GEBB:Doom (V1.2) lacks some entries in table of contents (e.g. "IBM PC / The Intel 486 / Die"), while the corresponding sections are still present, so there are "holes". I'm not sure if this is not just as intended, thus not creating a separate issue for this.

Compilation script does not check properly for Inkscape executable

Compilation script make.sh does not check properly for Inkscape executable presence.

The check (make.sh lines 9-15) checks for $INKSCAKE which does not exist instead of $INKSCAPE

if [ ! -f $INKSCAKE ]; then
  echo "Inkscape executable is invalid"
  echo "Was expected at $INKSCAPE"
  exit 1
fi

but the condition is written with simple brackets [ ] which do not properly manage empty variables without double quotes, thus not detecting missing argument to -f test.

• Steps to reproduce

1. Do not install Inkscape, uninstall Inkscape, or change INKSCAPE variable value (make.sh line 4) to point to a non-existent path
2. Remove PNG already converted from SVG drawings to force conversion calls to Inkscape:

rm src/screenshots/386_layout_drawing.png src/screenshots/386_packaging_die.png src/screenshots/bsp_map.png src/screenshots/clear_screen_pixels.png src/screenshots/lines.png
rm src/screenshots_300dpi/386_layout_drawing.png src/screenshots_300dpi/386_packaging_die.png src/screenshots_300dpi/bsp_map.png src/screenshots_300dpi/clear_screen_pixels.png src/screenshots_300dpi/lines.png

3. Remove 2>&1 from Inkscape command lines (make.sh lines 52 and 60) to display errors
4. Launch the compilation with:

cd gebbwolf3/ && ./make.sh 
# or, see issue #7:
cd gebbwolf3/src/ && ../make.sh

• Result
  The script does not stop at Inkscape check, continue and outputs an error message for each call to Inkscape:

Convert screenshots_svg/bsp_map.svg to PNG (100dpi).
../make.sh: line 53: /Applications/Inkscape.app/Contents/MacOS/inkscape: No such file or directory
[...]

• Expected result
  The script should have stopped at Inkscape check and display:

Inkscape executable is invalid
Was expected at /Applications/Inkscape.app/Contents/MacOS/inkscape