[The translation of the first part is here .]

Inherited code

Build is an outstanding engine, and the many games that used it brought great and deserved fame to both Ken Silverman and 3D Realms.
')
Ken Silverman fulfilled the terms of the contract: he provided a binary file of a stunning 3D engine with well-documented methods and resource formats . In recognition of his achievements, 3D Realms indicated his name in the credits as "Ken 'I can do that' Silverman" (Ken "I can do it" Silverman). But Build's development was focused on features and speed, not the convenience of porting and reading. After studying the code, I think that open source developers have avoided it for the following reasons:

• It is discouragingly difficult to read and learn from it.
• It was not portable.

In this article, I have listed some of the difficulties encountered. I also released the Chocolate Duke Nukem 3D port to solve these problems. I wanted people to remember what level of genius was needed to create a 3D engine at the time. In addition, I wanted them to realize how a teenager driven by passion could contribute to one of the greatest games of all time.

Difficulty in understanding

• The entire code base consists of only three modules, so it’s difficult in mind to break them down into sub-modules.
• typedef and struct not used internally (used only for public data: sectortype , walltype and spritetype ). Only arrays of primitive data types are used (for example: GRP file system ):
  
  

   static long numgroupfiles = 0; static long gnumfiles[MAXGROUPFILES]; static long groupfil[MAXGROUPFILES] = {-1,-1,-1,-1}; static long groupfilpos[MAXGROUPFILES]; static char *gfilelist[MAXGROUPFILES]; static long *gfileoffs[MAXGROUPFILES]; static char filegrp[MAXOPENFILES]; static long filepos[MAXOPENFILES]; static long filehan[MAXOPENFILES] 

  
  
• There are few comments. Therefore, mathematical methods are difficult to understand (for example: inside ):
  
  

   inside (long x, long y, short sectnum){ walltype *wal; long i, x1, y1, x2, y2; unsigned long cnt; if ((sectnum < 0) || (sectnum >= numsectors)) return(-1); cnt = 0; wal = &wall[sector[sectnum].wallptr]; i = sector[sectnum].wallnum; do{ y1 = wal->yy; y2 = wall[wal->point2].yy; if ((y1^y2) < 0){ x1 = wal->xx; x2 = wall[wal->point2].xx; if ((x1^x2) >= 0) cnt ^= x1; else cnt ^= (x1*y2-x2*y1)^y2; } wal++; i--; } while (i); return(cnt>>31); } 

  
  
• The drawing procedures were written in a manually optimized x86 assembler. Later they were ported back to C, but they are still incredibly difficult to read .
• Symbolic names are sometimes contradictory :
  
  

   static long xb1[MAXWALLSB], yb1[MAXWALLSB], xb2[MAXWALLSB], yb2[MAXWALLSB]; static long rx1[MAXWALLSB], ry1[MAXWALLSB], rx2[MAXWALLSB], ry2[MAXWALLSB]; static short p2[MAXWALLSB], thesector[MAXWALLSB], thewall[MAXWALLSB]; 

  
  
• In the code there are mysterious "magic" numbers (especially when manipulating the walls, floor and ceiling).
• The main translation modules (game.c and engine.c) are so large that they slow down the IDE. Sometimes right up to xcode crash.

Porting complexity

• It assumes the use of processor with direct byte order (Little-Endian).
• Use in the long type engine assumes that the data will always be 32 bits long.
• 32-bit addresses are assumed and they are processed as integers.
• Manually optimized x86 assembler without C code counterpart
• 120 cycles per frame are expected: this is how the DOS timer worked.
• No layer of abstraction. Raw calls file system / renderer.

Lost resources

Ken Silverman once contributed to the creation of the JonoF port and published many explanations for his algorithms. Unfortunately, the forum is no longer working because of spam. It seems that all this valuable information is lost!

I regretfully closed the forum on the site. Because of the spam bots, it became impossible to manage it, and although there is valuable content in the posts, my time and the moderator time are not worth it.

If you want to keep in touch with the community, then I suggest to refer to the forums on Duke4.net.

Chocolate Duke Nukem 3D

Chocolate Duke Nukem 3D is a Duke Nukem 3D port for training . Its main goal is to streamline the code so that programmers can conveniently get knowledge from it and are better aware of what it was like to program game engines in the 90s.

Like an archaeologist working with bones, it was important for me to keep everything “as it is,” and to get rid of “dust” only, focusing on:

• Readability: make the code easy to understand.
• Portability: make the code easy to compile, run, and conduct experiments.

Binary code

This is a port for game developers who want to learn about Duke Nukem 3D architecture and source code. If you just want to play a game, I recommend using EDuke32 .

If you still want to play Chocolate Duke Nukem 3D, then simply download the source code, which is a XCode / Visual Studio project, and build it: link to the source code .

Portability

Lack of portability was a problem. Now Chocolate Duke Nukem 3D is compiled under Windows, Intel MacOS X and Linux. Here is how it was done:

• Using internal type aliases now provides the correct size of integers. The long type was used everywhere, because during development it was believed that this type would always be 32 bits long. This is one of the reasons why the engine could not be compiled in 64-bit mode. Used int32_t from standard inttypes.h .
• Getting rid of char for arithmetic operations: since depending on the platform it can be signed or unsigned , using char for mathematical calculations led to an unpleasant shift; char should only be used for strings. For arithmetic operations in Build , int8_t or uint8_t from inttypes.h now explicitly used, which guarantees the presence of a sign.
• Elimination of platform-specific API . When the accuracy of the SDL timer was average, the port had problems ensuring the required 120 cycles per frame. Now the engine either uses SDL or provides a platform implementation for POSIX and Windows.

The code has become much more portable, but still not ready for 64 bits: you need to work more on the interface between the engine module and the drawing module , in which memory addresses are processed as 32-bit integers. It is necessary to spend many hours for this part, and I am not sure that I can spend so much time.

Comprehensibility

Most of the effort went into simplifying the readability of the code. Here is how I achieved this:

Reassign Modules

The "vanilla" source code essentially consisted of three broadcast modules:

• Engine.c : approximately 95% of the code.
• ac : contains a rough C implementation of what was once an optimized assembler.
• cache1d.c : contains the caching system and the GRP file system.

The code was repartitioned into modules, giving a clear idea of ​​what is contained inside:

• Engine.c : Now 50% of the code is in it.
• display.c : buffers of SDL surfaces in which the screen is rendered, palette utilities.
• draw.c : implementation of assembler procedures in C.
• tiles.c : sprite engine.
• filesystem.c : everything to create an abstraction of the GRP file system.
• network.c : multiplayer mode is not here.
• cache.c : random memory allocator and caching service.
• math.c : most fixed-point arithmetic functions here.

I was tempted to break Engine.c into a frontend and backend in imitation of the Quake3 / Doom3 architecture, which consists of two parts, exchanging data via the stack. But as a result, I decided that I would be too distant from the spirit of the original engine, so I rejected this idea.

Data structure

For data exchange with the game module through build.h, the Build engine used a struct , but inside everything was organized through arrays of primitive data types, without a struct and typedef .

I made changes, especially in the part related to the definition of visible surfaces (Visual Surface Determination) and the file system:

Before :

 long numgroupfiles = 0; long gnumfiles[MAXGROUPFILES]; long groupfil[MAXGROUPFILES] = {-1,-1,-1,-1}; long groupfilpos[MAXGROUPFILES]; char *gfilelist[MAXGROUPFILES]; long *gfileoffs[MAXGROUPFILES]; char filegrp[MAXOPENFILES]; long filepos[MAXOPENFILES]; long filehan[MAXOPENFILES]; 

After :

 //    GRP: // - 12     // - 4     typedef uint8_t grpIndexEntry_t[16]; typedef struct grpArchive_s{ int32_t numFiles ;//   . grpIndexEntry_t *gfilelist ;//,   . int32_t *fileOffsets ;//,   . int32_t *filesizes ;//,   . int fileDescriptor ;//fd      . uint32_t crc32 ;//    GRP: Duke Shareware, Duke plutonimum  .... } grpArchive_t; //  GRP     typedef struct grpSet_s{ grpArchive_t archives[MAXGROUPFILES]; int32_t num; } grpSet_t; 

Improving symbolic names

I changed those variable names that were of little help in understanding their purpose:

Before :

 static long xb1[MAXWALLSB], yb1[MAXWALLSB], xb2[MAXWALLSB], yb2[MAXWALLSB]; static long rx1[MAXWALLSB], ry1[MAXWALLSB], rx2[MAXWALLSB], ry2[MAXWALLSB]; static short p2[MAXWALLSB], thesector[MAXWALLSB], thewall[MAXWALLSB]; 

After :

 enum vector_index_e {VEC_X=0,VEC_Y=1}; enum screenSpaceCoo_index_e {VEC_COL=0,VEC_DIST=1}; typedef int32_t vector_t[2]; typedef int32_t coo2D_t[2]; //  ,      . //       . typedef struct pvWall_s{ vector_t cameraSpaceCoo[2]; //      .    vector_index_e. int16_t sectorId; // ,    ,    . int16_t worldWallId; //     . coo2D_t screenSpaceCoo[2]; //      .    screenSpaceCoo_index_e. } pvWall_t; //       . pvWall_t pvWalls[MAXWALLSB]; 

Comments and documentation

• Documentation: since the posts on the JoFo forum are lost, I hope that the first part of the article on Build guts will help developers understand the high-level architecture of the engine.
• Comments: I tried to put the most effort into this point. I am absolutely sure of the advantage of the abundance of comments in the code ( Dmap is a great example of source code, where there are more comments than code).

"Magic" numbers

I did not have time to get rid of all the "magic" numbers. Replacing decimal literals with enum or #define will significantly improve readability of the code.

Memory allocation

In Chocolate Duke, I tried to avoid global variables. Especially if they are used during the lifetime of the frame. In such cases, the memory used will be on the stack:

Before :

 long globalzd, globalbufplc, globalyscale, globalorientation; long globalx1, globaly1, globalx2, globaly2, globalx3, globaly3, globalzx; long globalx, globaly, globalz; static short sectorborder[256], sectorbordercnt; static char tablesloaded = 0; long pageoffset, ydim16, qsetmode = 0; 

After :

 /* FCS:      ( -     nextsector >= 0).   ,        . */ static void scansector (short sectnum) { //,  ,   . short sectorsToVisit[256], numSectorsToVisit; . . . } 

Note: Be careful when using the stack frame to store large variables. The following code was normally executed when compiling into clang and gcc, but resulted in an error in Visual Studio:

 int32_t initgroupfile(const char *filename) { uint8_t buf[16] ; int32_t i, j, k ; grpArchive_t* archive ; uint8_t crcBuffer[ 1 << 20] ; printf("Loading %s ...\n", filename) ; . . . } 

A stack overflow error occurs because by default, Visual Studio reserves only 1 MB for the stack. Attempting to use chkstk results in a stack overflow, which is not good at chkstk digesting. This code will run normally in Clang on Mac OS X.

Source

Source code is available on Github .