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