--- /dev/null
+Reconstructed Commander Keen 4-6 Source Code\r
+Copyright (C) 2021 K1n9_Duk3\r
+===============================================================================\r
+\r
+This is an UNOFFICIAL reconstruction of the original Keen 4-6 source code. More\r
+specifically, it is a reconstruction of the version 1.4 (and 1.5) EGA and CGA\r
+releases.\r
+\r
+The code is primarily based on the Catacomb 3-D source code (ID Engine files).\r
+The text view code (CK_TEXT.C) is based on Wolfenstein 3-D, and the main game\r
+and actor code is loosely based on Keen Dreams.\r
+\r
+Catacomb 3-D Source Code\r
+Copyright (C) 1993-2014 Flat Rock Software\r
+\r
+Wolfenstein 3-D Source Code\r
+Copyright (C) 1992 id Software\r
+\r
+Keen Dreams Source Code\r
+Copyright (C) 2014 Javier M. Chavez\r
+\r
+This program is free software; you can redistribute it and/or modify\r
+it under the terms of the GNU General Public License as published by\r
+the Free Software Foundation; either version 2 of the License, or\r
+(at your option) any later version.\r
+\r
+This program is distributed in the hope that it will be useful,\r
+but WITHOUT ANY WARRANTY; without even the implied warranty of\r
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\r
+GNU General Public License for more details.\r
+\r
+You should have received a copy of the GNU General Public License along\r
+with this program; if not, write to the Free Software Foundation, Inc.,\r
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\r
+\r
+\r
+Getting this code to compile\r
+============================\r
+\r
+You will need Borland C++ 2.0, 3.0 or 3.1 to compile this code. Newer versions\r
+may work, but have not been tested.\r
+\r
+In addition to the compiler and this source code, you will also need to extract\r
+some data files from the original executables. I have provided patch scripts to\r
+extract that data from the original executables. To use these patch scripts,\r
+you will need one of the following tools:\r
+\r
+CKPatch v0.11.3 (unofficial) - 16 bit DOS application\r
+http://ny.duke4.net/files.html\r
+\r
+K1n9_Duk3's Patching Utility v2.3 - Win32 application\r
+http://k1n9duk3.shikadi.net/patcher.html\r
+\r
+Copy the patching programs into the "static" subdirectory, along with copies of\r
+the original Keen 4-6 executables. The Keen 4-6 executables should be named\r
+KEEN4*.EXE, KEEN5*.EXE and KEEN6*.EXE respectively, otherwise the patching\r
+programs might have trouble recognizing the files.\r
+\r
+If you are going to use CKPatch, you should only copy one KEEN4*.EXE file, one\r
+KEEN5*.EXE and one KEEN6*.EXE file into the "static" directory. CKPatch will\r
+always use the first file matching this pattern, so if you have both KEEN4C.EXE\r
+and KEEN4E.EXE in that directory, for example, CK4PATCH will always operate on\r
+KEEN4C.EXE and ignore KEEN4E.EXE.\r
+\r
+These patches will only work on very specific versions of the original game's\r
+executables (v1.4/v1.5 CGA/EGA). The GT versions are not supported by CKPatch,\r
+so you will need K1n9_Duk3's Patching Utility to extract their data with the\r
+patch scripts included in the "static" directory. CKPatch may also be unable to\r
+open the FormGen release of Keen 4 (and Keen 5, if it exists). Decompressing\r
+the game's executable with UNLZEXE may fix that problem.\r
+\r
+If you are using K1n9_Duk3's Patching Utility, simply run it and open the patch\r
+file (*.PAT) you want to use. If K1n9_Duk3's Patching Utility found more than\r
+one supported version of the executables (or none at all), it will ask you to\r
+open the executable manually. Save the extracted files into the "static"\r
+directory using the suggested file names.\r
+\r
+If you are going to use CKPatch, just copy the files as described above, then\r
+use the provided batch files as described in the following section.\r
+\r
+\r
+Setting up a working environment in DOSBox\r
+------------------------------------------\r
+\r
+The Borland C++ compilers, as well as CKPATCH, MAKEOBJ and LZEXE, are all DOS\r
+programs, so you will need a system that is capable of running DOS programs or\r
+you will have to use an emulator like DOSBox to run these programs.\r
+\r
+If you are going to use DOSBox, start out by preparing a base directory on your\r
+system that you are going to mount as drive C: in DOSBox (mounting your real C:\r
+drive as C: in DOSBox is NOT recommended). Let's assume your base directory is\r
+"C:\BASE". Extract the contents of this package into that directory. Also copy\r
+the Borland C++ compiler(s) you are going to use into that directory,\r
+preferably into subdirectories named "BC20", "BC30" and "BC31" to make things\r
+easier for you. You can use different names, but then you will have to edit a\r
+couple of files and settings later on.\r
+\r
+You could just start DOSBox and manually mount your base directory as the C:\r
+drive in DOSBox, but this project comes with a couple of batch files that make\r
+the process much easier, as long as things are set up correctly.\r
+\r
+In case you didn't know, dragging and dropping a file onto DOSBox.exe will\r
+start DOSBox and mount the directory in which that file is located in as the C:\r
+drive in DOSBox, then it will try to execute that file in DOSBox.\r
+\r
+At this point, your base directory should have the following contents:\r
+\r
+ BC20 - Borland C++ 2.0\r
+ BC30 - Borland C++ 3.0\r
+ BC31 - Borland C++ 3.1\r
+ KEEN4-6 - main source directory\r
+\r
+ lzexe.exe - for compressing executables\r
+ rck4.bat - opens RCK4.PRJ with the correct compiler version\r
+ rck4c.bat - opens RCK4C.PRJ with the correct compiler version\r
+ rck5.bat - opens RCK5.PRJ with the correct compiler version\r
+ rck5c.bat - opens RCK5C.PRJ with the correct compiler version\r
+ rck6.bat - opens RCK6.PRJ with the correct compiler version\r
+ rck6c.bat - opens RCK6C.PRJ with the correct compiler version\r
+ rck4gt.bat - opens RCK4GT.PRJ with the correct compiler version\r
+ rck5gt.bat - opens RCK5GT.PRJ with the correct compiler version\r
+ rck6e15.bat - opens RCK6E15.PRJ with the correct compiler version\r
+ rck6c15.bat - opens RCK6C15.PRJ with the correct compiler version\r
+ ripnmake.bat - extracts data files and converts them into .OBJ files\r
+ readme.txt - this file\r
+\r
+The first order of business is to drag and drop RIPNMAKE.BAT onto DOSBox.exe or\r
+onto a shortcut to DOSBox.exe. This will try to extract the required data files\r
+from the original executables via CKPatch and then convert the data files into\r
+.OBJ files that the compiler can include when generating the new executables.\r
+The .OBJ files will be created in the KEEN4, KEEN5 and KEEN6 subdirectories.\r
+\r
+Note that you should do this step even if you already extracted the data files\r
+using K1n9_Duk3's Patching Utility. The RIPNMAKE.BAT file may not be able to\r
+run the CKPatch programs in that case, but as long as the extracted data files\r
+are present in the "KEEN4-6\static" directory, it will still convert them into\r
+.OBJ files and place the .OBJ files into the correct directories.\r
+\r
+If you are using CKPatch and you want to extract the data for both the EGA and\r
+the CGA versions, you need to delete the KEEN*.EXE files from the "static"\r
+directory after running RIPNMAKE.BAT and then copy the other executables into\r
+that directory and run RIPNMAKE.BAT again.\r
+\r
+\r
+Check the KEEN4, KEEN5 and KEEN6 directories and make sure the following files\r
+are in them:\r
+\r
+ CK?ADICT.OBJ\r
+ CK?AHEAD.OBJ\r
+ CK?CDICT.OBJ (for the CGA version)\r
+ CK?CHEAD.OBJ (for the CGA version)\r
+ CK?EDICT.OBJ (for the EGA version)\r
+ CK?EHEAD.OBJ (for the EGA version)\r
+ CK?INTRO.OBJ\r
+ CK?MHEAD.OBJ\r
+ CK6ORDER.OBJ (only for Keen 6)\r
+\r
+You can exit from DOSBox after this is done. Simply type "exit" at the prompt\r
+and hit Enter.\r
+\r
+\r
+Compiling the code:\r
+-------------------\r
+\r
+The other batch files in your base directory (RCK*.BAT) are provided to make\r
+compiling the code easy. Simply drag and drop the batch file onto DOSBox.exe\r
+(or onto a shortcut to DOSBox.exe) and it will open the respective project in\r
+the correct version of the compiler.\r
+\r
+ RCK4 - EGA version 1.4 - Apogee and FormGen release\r
+ RCK5 - EGA version 1.4 - Apogee (and FormGen?) release)\r
+ RCK6 - EGA version 1.4 - FormGen release\r
+ RCK4C - CGA version 1.4 - Apogee and FormGen release\r
+ RCK5C - CGA version 1.4 - Apogee (and FormGen?) release)\r
+ RCK6C - CGA version 1.4 - FormGen release\r
+\r
+ RCK4GT - EGA version 1.4 - GT release\r
+ RCK5GT - EGA version 1.4 - GT release\r
+ RCK6E15 - EGA version 1.5 - FormGen release\r
+ RCK6C15 - CGA version 1.5 - FormGen release\r
+\r
+The first six are set up for use with Borland C++ 3.0 by default, the later\r
+four are set up for use with Borland C++ 3.1. If you want to compile them with\r
+a different version of the compiler, edit the batch file and change the\r
+compiler directory (in the "SET PATH=" line) to the one you wish to use. Then\r
+open the project (drag and drop the batch file onto DOSBox.exe) and then select\r
+"Options" -> "Directories" from the main menu. Make sure that the Include and\r
+Library directory settings point to a version that you actually have installed.\r
+\r
+Note that RCK4, RCK4C, RCK5, RCK5C, RCK6 and RCK6C are set up to compile with\r
+BC30, but using the Library directory from BC20. This is required for\r
+recreating the original executables, but if you don't have both of these\r
+versions and you don't care about creating 100% identical copies, you can just\r
+change the directory settings to point to the compiler you have.\r
+\r
+To actually compile the code, press F9 or select "Compile" -> "Make" from the\r
+menu.\r
+\r
+Compiling all of the files may take a while, depending on your CPU cycles\r
+settings in DOSBox. By default, DOSBox should automatically switch to maximum\r
+cycles mode when Borland C++ 3.0 or 3.1 are started, but not when Borland C++\r
+2.0 is started. You can simply enter the command "cycles max" at the DOSBox\r
+prompt (or add it to the batch files) to switch DOSBox into maximum cycles mode\r
+if the automatic switch doesn't work for you.\r
+\r
+With the current code base, it is completely normal to get 3 or 4 warnings as\r
+the code is compiled. One may come from CK_KEEN2.C ("Condition is always true")\r
+when compiling Keen 6 v1.5. The other three of them should come from ID_US_1.C\r
+(2x "Condition is always true" and 1x "Unreachable code"). You can ignore these\r
+warnings.\r
+\r
+Once the code has been compiled, simply press ALT+X or select "File" -> "Quit"\r
+from the menu. Don't just close DOSBox while Borland C++ is still running, you\r
+would just end up with lots of useless swap files in your project directory.\r
+\r
+Type "exit" at the DOS prompt to quit DOSBox.\r
+\r
+Please note that you should always quit DOSBox after compiling a project.\r
+Trying to compile a second project after the first one may cause issues with\r
+the provided batch files and the way they adjust the PATH environment variable.\r
+For example, DOSBox may end up starting the wrong version of the compiler.\r
+\r
+\r
+Recreating the original executables\r
+===================================\r
+\r
+Here's the TL;DR for advanced users:\r
+\r
+RCK4.PRJ, RCK5.PRJ, RCK6.PRJ, RCK4C.PRJ, RCK5C.PRJ, RCK6C.PRJ:\r
+- Use same compiler settings as in the provided RCK?.PRJ files\r
+- Use LIB directory from Borland C++ 2.0\r
+- Use INCLUDE directory from Borland C++ 3.0\r
+- Compile with Borland C++ 3.0\r
+- Compress compiled EXE file with LZEXE version 0.91\r
+\r
+RCK4GT.PJR, RCK5GT.PRJ, RCK6E15.PRJ, RCK6C15.PRJ:\r
+- Use same compiler settings as in the provided RCK?GT.PRJ/RCK6?15.PRJ files\r
+- Use LIB and INCLUDE directories from Borland C++ 3.1\r
+- Compile with Borland C++ 3.1\r
+- Compress compiled EXE file with LZEXE version 0.91\r
+\r
+To create 100% identical copies of the original v1.4 EGA executables, you will\r
+need a copy of Borland C++ 3.0 as well as a copy of Borland C++ 2.0 (or at\r
+least the LIB directory from Borland C++ 2.0).\r
+\r
+Make sure to start with the original project files included in this package.\r
+Those have all of the compiler options set to the correct values. Different\r
+settings may produce slightly different code and the whole point of this is\r
+to get code that's 100% identical to the original executables.\r
+\r
+Unlike Borland C++ 3.1, version 3.0 will not recompile every file when you\r
+select "Build all" from the "Compile" menu if neither that file nor the header\r
+files used by that file have changed since the last time that file was\r
+compiled. Therefore I recommend that you delete all *.OBJ files from the\r
+"KEEN*\OBJ" directory to make sure everything gets recompiled. The CLEANUP.BAT\r
+file will take care of that (can be run in Windows as well as in DOSBox).\r
+\r
+Open the project in BC30 and select "Options" -> "Directories" from the menu.\r
+Change the "Include Directories" path to the INCLUDE directory from BC30 and\r
+change the "Library Directories" path to the LIB directory from BC20.\r
+\r
+Compile the code (select either "Make" or "Build all" from the "Compile" menu)\r
+and once the compiler is done, quit to DOS(Box) and compress the new executable\r
+with LZEXE. To compress RCK4.EXE, you must type "LZEXE RCK4.EXE" and hit Enter.\r
+The program will display a message in French about additional information at\r
+the end of the executable that will be lost after compression and ask if you\r
+want to abort. Type "N" and hit Enter to compress the file.\r
+\r
+\r
+For reference, these are the results you should be getting after compression:\r
+\r
+Keen 4 EGA version 1.4 (Apogee) : size = 105108 bytes, CRC = 6646B983\r
+Keen 4 EGA version 1.4 (FormGen) : size = 105140 bytes, CRC = F91E558B\r
+Keen 4 EGA version 1.4 (GT) : size = 106178 bytes, CRC = 0A05442E\r
+Keen 4 CGA version 1.4 (Apogee) : size = 98007 bytes, CRC = F544DD41\r
+Keen 4 CGA version 1.4 (FormGen) : size = 98007 bytes, CRC = 018FA365\r
+\r
+Keen 5 EGA version 1.4 (Apogee) : size = 106417 bytes, CRC = 2A45589A\r
+(No FormGen release of Keen 5 EGA version 1.4 is known at this time.)\r
+Keen 5 EGA version 1.4 (GT) : size = 107611 bytes, CRC = 5E450B12\r
+Keen 5 CGA version 1.4 (Apogee) : size = 98880 bytes, CRC = FB9EB429\r
+(No FormGen release of Keen 5 CGA version 1.4 is known at this time.)\r
+\r
+Keen 6 EGA version 1.4 (FormGen) : size = 107719 bytes, CRC = 9CDACDAE\r
+Keen 6 EGA version 1.5 (FormGen) : size = 109058 bytes, CRC = 5B828EE2\r
+Keen 6 CGA version 1.4 (FormGen) : size = 100964 bytes, CRC = F36A4C51\r
+Keen 6 CGA version 1.5 (FormGen) : size = 102166 bytes, CRC = D2F379B8\r
+\r
+The GT versions appear to have been compiled with Borland C++ 3.1 and its LIB\r
+directory, but otherwise using the same compiler and optimization settings as\r
+in the earlier Apogee/FormGen versions.\r
+\r
+The only difference between the Apogee/FormGen and the GT versions of the Keen\r
+4 and 5 executables (obvious differences in the included OBJ files aside) is\r
+that the GT version has only four entries in the help menu instead of five\r
+(the Order Info section has been removed) and that the GT version has a\r
+different set of default high scores. You must have GOODTIMES defined to\r
+compile these versions (already set in the RCK?GT.PRJ files).\r
+\r
+Keen 6 EGA/CGA version 1.5 was also compiled with Borland C++ 3.1 and its LIB\r
+directory, but it uses completely different compiler and optimization settings\r
+and also has one new variable in CK_PLAY.C that is never used but still has to\r
+be present to recreate the original code. It appears that somebody just pressed\r
+the "Fastest code" button in the compiler optimizations window before version\r
+1.5 was compiled, which was a bad idea for this code. None of the variables in\r
+the ID Engine are marked as "volatile", not even the ones that may be changed\r
+by an interrupt. That means the optimizations may end up generating code that\r
+leads to endless loops, as is the case with the "while (!LastScan);" loop in\r
+the PicturePause() routine.\r
+\r
+To recreate the exact same files as the original Keen 6 v1.5 executables, you\r
+need to compress the generated executables with LZEXE and then hex-edit the\r
+compressed files to replace the "LZ91" signature at offset 0x1C in the EXE file\r
+with four 0 bytes. If you don't have a hex editor, you can use K1n9_Duk3's\r
+Patching Utility for that step. Simply open the "fix_RCK6_v15.pat" or the\r
+"fix_RCK6C_v15.pat" patch file (located in the KEEN4-6\KEEN6\OBJ and\r
+KEEN4-6\KEEN6C\OBJ directories, respectively) with K1n9_Duk3's Patching Utility\r
+and let it patch the compressed executable for you.\r
+\r
+\r
+Borland C++ 2.0 issues?\r
+=======================\r
+\r
+Any versions of Keen 4-6 prior to version 1.4 appear to have been compiled with\r
+Borland C++ 2.0. Version 1.4 is where they switched from 2.0 to 3.0 (without\r
+changing the Library directory to the one from 3.0 for some reason).\r
+\r
+The code in this package can be built with Borland C++ 2.0 and the compiled\r
+executables appear to be working perfectly fine. But when that version of the\r
+compiler was used to compile the "Return to the Shadowlands" source code (which\r
+is based on an earlier incarnation of this source code recreation), it caused\r
+problems. The code compiled without errors, but the compiled executable would\r
+always quit with the error message "Abnormal program termination".\r
+\r
+The reason for this error was that the compiler appeared to have forced the\r
+"grneeded" array (declared as "far" in ID_CA.C) into the main data segment\r
+instead of giving it its own far data segment. With this additional data in the\r
+main data segment, there was simply not enough space left for the stack and\r
+that is why the program aborted with an error message.\r
+\r
+It is unclear what caused this problem. The same source code compiles perfectly\r
+fine with Borland C++ 3.1 and produces an executable that actually works. If\r
+similar issues arise when working on mods based on this source code, try using\r
+Borland C++ 3.1 instead of whatever version you were using before.\r
+\r
+\r
+Special Thanks\r
+==============\r
+\r
+I would like to thank Jason Blochowiak, Adrian Carmack, John Carmack, Tom Hall,\r
+John Romero and Robert Prince for creating Commander Keen 4-6 in the first\r
+place.\r
+\r
+Special thanks to John Carmack (and the rest of id Software) for releasing the\r
+Wolfenstein 3-D and Spear of Destiny source code to the public in July 1995.\r
+\r
+Extra special thanks to the late Richard Mandel of Flat Rock Software and\r
+everybody else involved in the process of getting the source code of some of\r
+the games id Software made for Softdisk (Catacomb series, Hovertank, Keen\r
+Dreams) released to the public. I have learned a lot from the source code of\r
+these games and this project certainly would not have been possible without it.\r
+\r
+Thanks to PCKF user Multimania for supplying additional information regarding\r
+the names of functions and variables for Keen 4 and Keen 5.\r
+\r
+And last, but not least, I would like to thank NY00123 for figuring out how to\r
+get the compiler to recreate Keen 6 v1.5 and also for sharing a lot of valuable\r
+information about the "gamesrc-ver-recreation" project in various public posts\r
+on the RGB Classic Games Forum (among other places). That's where I first heard\r
+about the TDUMP utility, which is certainly a much better way to extract names\r
+from the debugging information that some executables came with. And using IDA\r
+to open executables and then make IDA generate ASM files that can be compared\r
+more easily using tools like FC in Windows/DOS is pretty much the best way to\r
+track down differences between those two executables without going insane.\r
+\r
+[END OF FILE]
\ No newline at end of file
projects / 16.git / blobdiff