1 Reconstructed Commander Keen 4-6 Source Code
\r
2 Copyright (C) 2021 K1n9_Duk3
\r
3 ===============================================================================
\r
5 This is an UNOFFICIAL reconstruction of the original Keen 4-6 source code. More
\r
6 specifically, it is a reconstruction of the version 1.4 (and 1.5) EGA and CGA
\r
9 The code is primarily based on the Catacomb 3-D source code (ID Engine files).
\r
10 The text view code (CK_TEXT.C) is based on Wolfenstein 3-D, and the main game
\r
11 and actor code is loosely based on Keen Dreams.
\r
13 Catacomb 3-D Source Code
\r
14 Copyright (C) 1993-2014 Flat Rock Software
\r
16 Wolfenstein 3-D Source Code
\r
17 Copyright (C) 1992 id Software
\r
19 Keen Dreams Source Code
\r
20 Copyright (C) 2014 Javier M. Chavez
\r
22 This program is free software; you can redistribute it and/or modify
\r
23 it under the terms of the GNU General Public License as published by
\r
24 the Free Software Foundation; either version 2 of the License, or
\r
25 (at your option) any later version.
\r
27 This program is distributed in the hope that it will be useful,
\r
28 but WITHOUT ANY WARRANTY; without even the implied warranty of
\r
29 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
\r
30 GNU General Public License for more details.
\r
32 You should have received a copy of the GNU General Public License along
\r
33 with this program; if not, write to the Free Software Foundation, Inc.,
\r
34 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
\r
37 Getting this code to compile
\r
38 ============================
\r
40 You will need Borland C++ 2.0, 3.0 or 3.1 to compile this code. Newer versions
\r
41 may work, but have not been tested.
\r
43 In addition to the compiler and this source code, you will also need to extract
\r
44 some data files from the original executables. I have provided patch scripts to
\r
45 extract that data from the original executables. To use these patch scripts,
\r
46 you will need one of the following tools:
\r
48 CKPatch v0.11.3 (unofficial) - 16 bit DOS application
\r
49 http://ny.duke4.net/files.html
\r
51 K1n9_Duk3's Patching Utility v2.3 - Win32 application
\r
52 http://k1n9duk3.shikadi.net/patcher.html
\r
54 Copy the patching programs into the "static" subdirectory, along with copies of
\r
55 the original Keen 4-6 executables. The Keen 4-6 executables should be named
\r
56 KEEN4*.EXE, KEEN5*.EXE and KEEN6*.EXE respectively, otherwise the patching
\r
57 programs might have trouble recognizing the files.
\r
59 If you are going to use CKPatch, you should only copy one KEEN4*.EXE file, one
\r
60 KEEN5*.EXE and one KEEN6*.EXE file into the "static" directory. CKPatch will
\r
61 always use the first file matching this pattern, so if you have both KEEN4C.EXE
\r
62 and KEEN4E.EXE in that directory, for example, CK4PATCH will always operate on
\r
63 KEEN4C.EXE and ignore KEEN4E.EXE.
\r
65 These patches will only work on very specific versions of the original game's
\r
66 executables (v1.4/v1.5 CGA/EGA). The GT versions are not supported by CKPatch,
\r
67 so you will need K1n9_Duk3's Patching Utility to extract their data with the
\r
68 patch scripts included in the "static" directory. CKPatch may also be unable to
\r
69 open the FormGen release of Keen 4 (and Keen 5, if it exists). Decompressing
\r
70 the game's executable with UNLZEXE may fix that problem.
\r
72 If you are using K1n9_Duk3's Patching Utility, simply run it and open the patch
\r
73 file (*.PAT) you want to use. If K1n9_Duk3's Patching Utility found more than
\r
74 one supported version of the executables (or none at all), it will ask you to
\r
75 open the executable manually. Save the extracted files into the "static"
\r
76 directory using the suggested file names.
\r
78 If you are going to use CKPatch, just copy the files as described above, then
\r
79 use the provided batch files as described in the following section.
\r
82 Setting up a working environment in DOSBox
\r
83 ------------------------------------------
\r
85 The Borland C++ compilers, as well as CKPATCH, MAKEOBJ and LZEXE, are all DOS
\r
86 programs, so you will need a system that is capable of running DOS programs or
\r
87 you will have to use an emulator like DOSBox to run these programs.
\r
89 If you are going to use DOSBox, start out by preparing a base directory on your
\r
90 system that you are going to mount as drive C: in DOSBox (mounting your real C:
\r
91 drive as C: in DOSBox is NOT recommended). Let's assume your base directory is
\r
92 "C:\BASE". Extract the contents of this package into that directory. Also copy
\r
93 the Borland C++ compiler(s) you are going to use into that directory,
\r
94 preferably into subdirectories named "BC20", "BC30" and "BC31" to make things
\r
95 easier for you. You can use different names, but then you will have to edit a
\r
96 couple of files and settings later on.
\r
98 You could just start DOSBox and manually mount your base directory as the C:
\r
99 drive in DOSBox, but this project comes with a couple of batch files that make
\r
100 the process much easier, as long as things are set up correctly.
\r
102 In case you didn't know, dragging and dropping a file onto DOSBox.exe will
\r
103 start DOSBox and mount the directory in which that file is located in as the C:
\r
104 drive in DOSBox, then it will try to execute that file in DOSBox.
\r
106 At this point, your base directory should have the following contents:
\r
108 BC20 - Borland C++ 2.0
\r
109 BC30 - Borland C++ 3.0
\r
110 BC31 - Borland C++ 3.1
\r
111 KEEN4-6 - main source directory
\r
113 lzexe.exe - for compressing executables
\r
114 rck4.bat - opens RCK4.PRJ with the correct compiler version
\r
115 rck4c.bat - opens RCK4C.PRJ with the correct compiler version
\r
116 rck5.bat - opens RCK5.PRJ with the correct compiler version
\r
117 rck5c.bat - opens RCK5C.PRJ with the correct compiler version
\r
118 rck6.bat - opens RCK6.PRJ with the correct compiler version
\r
119 rck6c.bat - opens RCK6C.PRJ with the correct compiler version
\r
120 rck4gt.bat - opens RCK4GT.PRJ with the correct compiler version
\r
121 rck5gt.bat - opens RCK5GT.PRJ with the correct compiler version
\r
122 rck6e15.bat - opens RCK6E15.PRJ with the correct compiler version
\r
123 rck6c15.bat - opens RCK6C15.PRJ with the correct compiler version
\r
124 ripnmake.bat - extracts data files and converts them into .OBJ files
\r
125 readme.txt - this file
\r
127 The first order of business is to drag and drop RIPNMAKE.BAT onto DOSBox.exe or
\r
128 onto a shortcut to DOSBox.exe. This will try to extract the required data files
\r
129 from the original executables via CKPatch and then convert the data files into
\r
130 .OBJ files that the compiler can include when generating the new executables.
\r
131 The .OBJ files will be created in the KEEN4, KEEN5 and KEEN6 subdirectories.
\r
133 Note that you should do this step even if you already extracted the data files
\r
134 using K1n9_Duk3's Patching Utility. The RIPNMAKE.BAT file may not be able to
\r
135 run the CKPatch programs in that case, but as long as the extracted data files
\r
136 are present in the "KEEN4-6\static" directory, it will still convert them into
\r
137 .OBJ files and place the .OBJ files into the correct directories.
\r
139 If you are using CKPatch and you want to extract the data for both the EGA and
\r
140 the CGA versions, you need to delete the KEEN*.EXE files from the "static"
\r
141 directory after running RIPNMAKE.BAT and then copy the other executables into
\r
142 that directory and run RIPNMAKE.BAT again.
\r
145 Check the KEEN4, KEEN5 and KEEN6 directories and make sure the following files
\r
150 CK?CDICT.OBJ (for the CGA version)
\r
151 CK?CHEAD.OBJ (for the CGA version)
\r
152 CK?EDICT.OBJ (for the EGA version)
\r
153 CK?EHEAD.OBJ (for the EGA version)
\r
156 CK6ORDER.OBJ (only for Keen 6)
\r
158 You can exit from DOSBox after this is done. Simply type "exit" at the prompt
\r
162 Compiling the code:
\r
163 -------------------
\r
165 The other batch files in your base directory (RCK*.BAT) are provided to make
\r
166 compiling the code easy. Simply drag and drop the batch file onto DOSBox.exe
\r
167 (or onto a shortcut to DOSBox.exe) and it will open the respective project in
\r
168 the correct version of the compiler.
\r
170 RCK4 - EGA version 1.4 - Apogee and FormGen release
\r
171 RCK5 - EGA version 1.4 - Apogee (and FormGen?) release)
\r
172 RCK6 - EGA version 1.4 - FormGen release
\r
173 RCK4C - CGA version 1.4 - Apogee and FormGen release
\r
174 RCK5C - CGA version 1.4 - Apogee (and FormGen?) release)
\r
175 RCK6C - CGA version 1.4 - FormGen release
\r
177 RCK4GT - EGA version 1.4 - GT release
\r
178 RCK5GT - EGA version 1.4 - GT release
\r
179 RCK6E15 - EGA version 1.5 - FormGen release
\r
180 RCK6C15 - CGA version 1.5 - FormGen release
\r
182 The first six are set up for use with Borland C++ 3.0 by default, the later
\r
183 four are set up for use with Borland C++ 3.1. If you want to compile them with
\r
184 a different version of the compiler, edit the batch file and change the
\r
185 compiler directory (in the "SET PATH=" line) to the one you wish to use. Then
\r
186 open the project (drag and drop the batch file onto DOSBox.exe) and then select
\r
187 "Options" -> "Directories" from the main menu. Make sure that the Include and
\r
188 Library directory settings point to a version that you actually have installed.
\r
190 Note that RCK4, RCK4C, RCK5, RCK5C, RCK6 and RCK6C are set up to compile with
\r
191 BC30, but using the Library directory from BC20. This is required for
\r
192 recreating the original executables, but if you don't have both of these
\r
193 versions and you don't care about creating 100% identical copies, you can just
\r
194 change the directory settings to point to the compiler you have.
\r
196 To actually compile the code, press F9 or select "Compile" -> "Make" from the
\r
199 Compiling all of the files may take a while, depending on your CPU cycles
\r
200 settings in DOSBox. By default, DOSBox should automatically switch to maximum
\r
201 cycles mode when Borland C++ 3.0 or 3.1 are started, but not when Borland C++
\r
202 2.0 is started. You can simply enter the command "cycles max" at the DOSBox
\r
203 prompt (or add it to the batch files) to switch DOSBox into maximum cycles mode
\r
204 if the automatic switch doesn't work for you.
\r
206 With the current code base, it is completely normal to get 3 or 4 warnings as
\r
207 the code is compiled. One may come from CK_KEEN2.C ("Condition is always true")
\r
208 when compiling Keen 6 v1.5. The other three of them should come from ID_US_1.C
\r
209 (2x "Condition is always true" and 1x "Unreachable code"). You can ignore these
\r
212 Once the code has been compiled, simply press ALT+X or select "File" -> "Quit"
\r
213 from the menu. Don't just close DOSBox while Borland C++ is still running, you
\r
214 would just end up with lots of useless swap files in your project directory.
\r
216 Type "exit" at the DOS prompt to quit DOSBox.
\r
218 Please note that you should always quit DOSBox after compiling a project.
\r
219 Trying to compile a second project after the first one may cause issues with
\r
220 the provided batch files and the way they adjust the PATH environment variable.
\r
221 For example, DOSBox may end up starting the wrong version of the compiler.
\r
224 Recreating the original executables
\r
225 ===================================
\r
227 Here's the TL;DR for advanced users:
\r
229 RCK4.PRJ, RCK5.PRJ, RCK6.PRJ, RCK4C.PRJ, RCK5C.PRJ, RCK6C.PRJ:
\r
230 - Use same compiler settings as in the provided RCK?.PRJ files
\r
231 - Use LIB directory from Borland C++ 2.0
\r
232 - Use INCLUDE directory from Borland C++ 3.0
\r
233 - Compile with Borland C++ 3.0
\r
234 - Compress compiled EXE file with LZEXE version 0.91
\r
236 RCK4GT.PJR, RCK5GT.PRJ, RCK6E15.PRJ, RCK6C15.PRJ:
\r
237 - Use same compiler settings as in the provided RCK?GT.PRJ/RCK6?15.PRJ files
\r
238 - Use LIB and INCLUDE directories from Borland C++ 3.1
\r
239 - Compile with Borland C++ 3.1
\r
240 - Compress compiled EXE file with LZEXE version 0.91
\r
242 To create 100% identical copies of the original v1.4 EGA executables, you will
\r
243 need a copy of Borland C++ 3.0 as well as a copy of Borland C++ 2.0 (or at
\r
244 least the LIB directory from Borland C++ 2.0).
\r
246 Make sure to start with the original project files included in this package.
\r
247 Those have all of the compiler options set to the correct values. Different
\r
248 settings may produce slightly different code and the whole point of this is
\r
249 to get code that's 100% identical to the original executables.
\r
251 Unlike Borland C++ 3.1, version 3.0 will not recompile every file when you
\r
252 select "Build all" from the "Compile" menu if neither that file nor the header
\r
253 files used by that file have changed since the last time that file was
\r
254 compiled. Therefore I recommend that you delete all *.OBJ files from the
\r
255 "KEEN*\OBJ" directory to make sure everything gets recompiled. The CLEANUP.BAT
\r
256 file will take care of that (can be run in Windows as well as in DOSBox).
\r
258 Open the project in BC30 and select "Options" -> "Directories" from the menu.
\r
259 Change the "Include Directories" path to the INCLUDE directory from BC30 and
\r
260 change the "Library Directories" path to the LIB directory from BC20.
\r
262 Compile the code (select either "Make" or "Build all" from the "Compile" menu)
\r
263 and once the compiler is done, quit to DOS(Box) and compress the new executable
\r
264 with LZEXE. To compress RCK4.EXE, you must type "LZEXE RCK4.EXE" and hit Enter.
\r
265 The program will display a message in French about additional information at
\r
266 the end of the executable that will be lost after compression and ask if you
\r
267 want to abort. Type "N" and hit Enter to compress the file.
\r
270 For reference, these are the results you should be getting after compression:
\r
272 Keen 4 EGA version 1.4 (Apogee) : size = 105108 bytes, CRC = 6646B983
\r
273 Keen 4 EGA version 1.4 (FormGen) : size = 105140 bytes, CRC = F91E558B
\r
274 Keen 4 EGA version 1.4 (GT) : size = 106178 bytes, CRC = 0A05442E
\r
275 Keen 4 CGA version 1.4 (Apogee) : size = 98007 bytes, CRC = F544DD41
\r
276 Keen 4 CGA version 1.4 (FormGen) : size = 98007 bytes, CRC = 018FA365
\r
278 Keen 5 EGA version 1.4 (Apogee) : size = 106417 bytes, CRC = 2A45589A
\r
279 (No FormGen release of Keen 5 EGA version 1.4 is known at this time.)
\r
280 Keen 5 EGA version 1.4 (GT) : size = 107611 bytes, CRC = 5E450B12
\r
281 Keen 5 CGA version 1.4 (Apogee) : size = 98880 bytes, CRC = FB9EB429
\r
282 (No FormGen release of Keen 5 CGA version 1.4 is known at this time.)
\r
284 Keen 6 EGA version 1.4 (FormGen) : size = 107719 bytes, CRC = 9CDACDAE
\r
285 Keen 6 EGA version 1.5 (FormGen) : size = 109058 bytes, CRC = 5B828EE2
\r
286 Keen 6 CGA version 1.4 (FormGen) : size = 100964 bytes, CRC = F36A4C51
\r
287 Keen 6 CGA version 1.5 (FormGen) : size = 102166 bytes, CRC = D2F379B8
\r
289 The GT versions appear to have been compiled with Borland C++ 3.1 and its LIB
\r
290 directory, but otherwise using the same compiler and optimization settings as
\r
291 in the earlier Apogee/FormGen versions.
\r
293 The only difference between the Apogee/FormGen and the GT versions of the Keen
\r
294 4 and 5 executables (obvious differences in the included OBJ files aside) is
\r
295 that the GT version has only four entries in the help menu instead of five
\r
296 (the Order Info section has been removed) and that the GT version has a
\r
297 different set of default high scores. You must have GOODTIMES defined to
\r
298 compile these versions (already set in the RCK?GT.PRJ files).
\r
300 Keen 6 EGA/CGA version 1.5 was also compiled with Borland C++ 3.1 and its LIB
\r
301 directory, but it uses completely different compiler and optimization settings
\r
302 and also has one new variable in CK_PLAY.C that is never used but still has to
\r
303 be present to recreate the original code. It appears that somebody just pressed
\r
304 the "Fastest code" button in the compiler optimizations window before version
\r
305 1.5 was compiled, which was a bad idea for this code. None of the variables in
\r
306 the ID Engine are marked as "volatile", not even the ones that may be changed
\r
307 by an interrupt. That means the optimizations may end up generating code that
\r
308 leads to endless loops, as is the case with the "while (!LastScan);" loop in
\r
309 the PicturePause() routine.
\r
311 To recreate the exact same files as the original Keen 6 v1.5 executables, you
\r
312 need to compress the generated executables with LZEXE and then hex-edit the
\r
313 compressed files to replace the "LZ91" signature at offset 0x1C in the EXE file
\r
314 with four 0 bytes. If you don't have a hex editor, you can use K1n9_Duk3's
\r
315 Patching Utility for that step. Simply open the "fix_RCK6_v15.pat" or the
\r
316 "fix_RCK6C_v15.pat" patch file (located in the KEEN4-6\KEEN6\OBJ and
\r
317 KEEN4-6\KEEN6C\OBJ directories, respectively) with K1n9_Duk3's Patching Utility
\r
318 and let it patch the compressed executable for you.
\r
321 Borland C++ 2.0 issues?
\r
322 =======================
\r
324 Any versions of Keen 4-6 prior to version 1.4 appear to have been compiled with
\r
325 Borland C++ 2.0. Version 1.4 is where they switched from 2.0 to 3.0 (without
\r
326 changing the Library directory to the one from 3.0 for some reason).
\r
328 The code in this package can be built with Borland C++ 2.0 and the compiled
\r
329 executables appear to be working perfectly fine. But when that version of the
\r
330 compiler was used to compile the "Return to the Shadowlands" source code (which
\r
331 is based on an earlier incarnation of this source code recreation), it caused
\r
332 problems. The code compiled without errors, but the compiled executable would
\r
333 always quit with the error message "Abnormal program termination".
\r
335 The reason for this error was that the compiler appeared to have forced the
\r
336 "grneeded" array (declared as "far" in ID_CA.C) into the main data segment
\r
337 instead of giving it its own far data segment. With this additional data in the
\r
338 main data segment, there was simply not enough space left for the stack and
\r
339 that is why the program aborted with an error message.
\r
341 It is unclear what caused this problem. The same source code compiles perfectly
\r
342 fine with Borland C++ 3.1 and produces an executable that actually works. If
\r
343 similar issues arise when working on mods based on this source code, try using
\r
344 Borland C++ 3.1 instead of whatever version you were using before.
\r
350 I would like to thank Jason Blochowiak, Adrian Carmack, John Carmack, Tom Hall,
\r
351 John Romero and Robert Prince for creating Commander Keen 4-6 in the first
\r
354 Special thanks to John Carmack (and the rest of id Software) for releasing the
\r
355 Wolfenstein 3-D and Spear of Destiny source code to the public in July 1995.
\r
357 Extra special thanks to the late Richard Mandel of Flat Rock Software and
\r
358 everybody else involved in the process of getting the source code of some of
\r
359 the games id Software made for Softdisk (Catacomb series, Hovertank, Keen
\r
360 Dreams) released to the public. I have learned a lot from the source code of
\r
361 these games and this project certainly would not have been possible without it.
\r
363 Thanks to PCKF user Multimania for supplying additional information regarding
\r
364 the names of functions and variables for Keen 4 and Keen 5.
\r
366 And last, but not least, I would like to thank NY00123 for figuring out how to
\r
367 get the compiler to recreate Keen 6 v1.5 and also for sharing a lot of valuable
\r
368 information about the "gamesrc-ver-recreation" project in various public posts
\r
369 on the RGB Classic Games Forum (among other places). That's where I first heard
\r
370 about the TDUMP utility, which is certainly a much better way to extract names
\r
371 from the debugging information that some executables came with. And using IDA
\r
372 to open executables and then make IDA generate ASM files that can be compared
\r
373 more easily using tools like FC in Windows/DOS is pretty much the best way to
\r
374 track down differences between those two executables without going insane.
\r
projects / 16.git / blob