LModKeen 2 release Two - a Windows & GNU/Linux port of ModKeen 2.0.1
ModKeen 2.0.1 source code is Copyright (C) 2002-2004 by Andrew Durdin <andy@durdin.net>
LModKeen is derived work from the above, Copyright (C) 2007 by Ignacio R. Morelle <shadowm2006@gmail.com>
Table of Contents
0. Legal Disclaimer
1. Introduction
2. What's new
    2.1. ModKeen 2.0.1 versus ModKeen 1
    2.2. LModKeen 2 versus LModKeen I
3. Building and installing
4. Usage
5. Outputs
6. Contact information
7. Acknowledgements
8. Changelog
    8.1 LModKeen
    8.2 ModKeen
9. Known bugs
10. To-do List

0. LEGAL DISCLAIMER

This software is provided as-is, without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:
  1. The origin of this software must not be misrepresented; you must not  claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.
<< back to contents
1. INTRODUCTION

ModKeen allows the creation of Commander Keen mods. It is a command-line utility that will export graphics from Commander Keen into BMP files, and import those BMPs back into Commander Keen's graphics files. ModKeen allows you to:
 In fact, ModKeen allows you to totally recreate the appearance of Commander Keen.

The version of ModKeen this port was based on (2.0.1) supported importing/exporting graphics to/from Commander Keen: Invasion of the Vorticons series (Keen 1-3), Goodbye Galaxy! series (Keen 4-5) and Aliens Ate My Babysitter! (Keen 6). This port used existing code from Andy Durdin's FIN2BMP utility, and integrated it in the Keen 1-3 import/export routines.
<< back to contents
2. WHAT'S NEW

2.1 MODKEEN 2.0.x VS. MODKEEN 1

Andrew Durdin's ModKeen version 2.0 supports modification of Commander Keen episodes 4, 5, and 6. In order to modify these episodes, you will need either UNP or UNLZEXE to decompress your Commander Keen EXE files, and also Admiral Bob's CKxPatch utilities, version 0.9.0 or later. You can get these here:
 ModKeen 2.0 has a totally reworked command-line interface and slightly different operation to version 1.0, so users of the previous versions should briefly review the "Usage" section below.

Some weeks later, a bug-fix release was published by ModKeen 2.0's author, targeted to solve issues involving Keen 1-3 data manipulation routines.
<< back to contents

2.2 LMODKEEN 2 VS. LMODKEEN I

Although the "official" source code/binary distributions of ModKeen are specifically targeted to protected-mode DOS and the DJGPP compiler, some people have trouble trying to make it work under Win32, UNIX, MacOS and GNU platforms. As the author of this port was not able to get the official ModKeen 2.0.1 working under GNU/Linux, the idea of a new port was born. And so, after three days of careful revision, testing and code writing, LModKeen I was released, one day before Keen day 2007, that is, March 13, 2007 .

That first port of the official ModKeen contained two nice features: the possibility of using the ncurses library for console I/O procedures, and the -nowait parameter, intended for scripts in which no user interaction is expected and the program cannot undefinitely wait for a keypress to end. The port also contained a few incredible bugs.

And now, I have the pleasure to bring you a "new" port, LModKeen 2. What's so new about it? Read on:
Precompiled Windows (32-bit PE) and GNU/Linux (ELF) binaries are included with the source code in the root directory of the distribution. They might or might not work on your system. If you are an advanced user who has development libraries and/or Mingw32 installed, I recommend you compiling from the source code instead of using these executables.

If you used Andy's ModKeen 2.0.1 (official) before, you might want to have a look at the "Usage" section below, since a new parameter has been added and some functionality has been modified. If you used FIN2BMP before, you'll find out that you no longer need it with LModKeen 2.
<< back to contents
3. BUILDING AND INSTALLING

IMPORTANT: If you don't know about compiling programs, you don't need to read this section. Just use the provided LModkeen.exe (Windows 95/98/ME, 32-bit Windows NT/2000/XP/2003/Vista) or LModkeen (GNU/Linux on Intel x86), which should be in the root directory of this package.

First of all, make sure your GNU/Linux installation satisfies the following requirements:
 If you want to build LModKeen 2 for Windows (Win32) using Mingw32's tools, you'll need the following:
 I've successfully compiled LModKeen 2 for Windows using a Mingw-based cross-compiler that runs on GNU/Linux. If you get it to work on native Win32 Mingw or more exotic environments (i.e. MacOS X, *BSD UNIX, Solaris, BeOS, etc.), see Section 6 (Contact info) below and send me your recipe. :)

No additional libraries are required, since the original ModKeen 2.x did not depend on any. The ncurses library is currently required to replace DOS console I/O routine calls on UNIX operating systems. The Windows-based build uses the kernel library (kernel32.lib) and platform header (windows.h) only.

Unpack the source code .tar.gz with the following commands, assuming you copied the archive in the desired folder. The sub-directory "lmodkeen2-rel1" will be automatically created:
$ tar -jxvf lmodkeen2-rel1.tar.bz2
 $ cd ./lmodkeen2-rel1

Now, change to subdirectory "build-gnulinux" if you want to build for GNU/Linux, or to "build-mingw32-linux" if you want to build for Win32 from GNU/Linux. Then, run "make" (I assume you have GNU Make installed and its binary is called "make"; if it's name is something else, replace it in the command line).
$ cd ./build-<config name>
$ make

If it refuses to build, make sure you have all required libraries and development files installed. After that, everything should compile correctly. If it doesn't, see section 6 (Contact Information). The resultant executable will be named "lmodkeen" and it will be located in the same folder where "build" is located. If you want to run the program, make sure it is in your $PATH and simply write:
$ lmodkeen

(See below section for usage information.) Most Linux distros create automatically a folder named "bin" in the root of your user's account (normally located at /home/yourname). You should copy lmodkeen there so that it'll be always in your, and only *your* account's $PATH. If the folder does not exist, try to create it and copy lmodkeen there, and then try to run it from anywhere without specifying the full path to it.

In the almost-the-worst case, you can manually copy the executable to /usr/bin if you know the root password using:
$ su -c "cp ./lmodkeen /usr/bin/lmodkeen"

And, in the worst case, copy it to any folder you can easily remember and run it from there using the full path. Anyways, my personal recommendation is to copy it in your Keen mod's folder if you can't put it in your $PATH.
<< back to contents
4. USAGE

Before using ModKeen, set up a copy of the episode you wish to mod in its own directory to avoid the risk of data loss. It is recommended to create a subdirectory in there to hold the BMP files, but it's not necessary. You'll surely need to decompress the EXE file with UNP or UNLZEXE, and you'll need CKxPatch to run the game after you've imported the graphics, so copy that into your mod directory also. Decompressing the EXE does not alter the program, it only decompresses it, and it does not have any negative effects, except that it will take some extra kilobytes of disk space (not important unless you are using a floppy disk).

Open a Linux terminal, with your favourite client (native, xterm, rxvt, Konsole, etc.), and change to the directory where your mod will be. To export the graphics into Windows Bitmap (*.BMP) files, run ModKeen with the -export command (see below for details of the switches). After editing the bitmaps, you can use the -import command to load them back into Commander Keen.

ModKeen accepts the following switches:

-nowait
        Normally, after finishing any import/export procedure, this port prints the message "press any key" and waits for a keypress to terminate. If you add this switch, it won't wait for any key to terminate, something that could be useful if you write scripts that import/export mod files automatically.

-episode=N
        Specifies the episode that you wish to work with. Give N as 1, 2, 3, 4, 5, 6 or D (Keen Dreams). This switch is required.

-export
        Specifies that you wish to export all the Keen data into BMP files. Either this switch or -import must be specified.

-import
        Specifies that you wish to import the BMP files into Keen. Either this switch or -export must be specified.

-keendir="DIRECTORY"
        Specifies the directory where the Commander Keen files to export from or import  to can be found. If the directory does not exist, then ModKeen will abort with an error message. If this switch is not specified, then ModKeen will look in the current directory.

-bmpdir="DIRECTORY"
        Specifies the location where the BMP files to export to or import from should be created. If the directory does not exist, then ModKeen will abort with an error message. If this switch is not specified, then ModKeen will create the bitmaps in the current directory.

-backup
        Specifies that ModKeen should backup all the files it changes. ModKeen will create backups by appending ".bak" and a number onto the filename. ModKeen will never delete or overwrite a previous backup, but will create a new backup instead.

-help
        ModKeen will provide a brief summary of the switches that it supports.

In the case you experience error messages like "cannot find EGAGRAPH.CK4", and you have the file "egagraph.ck4" in the folder, a filename normalizer script has been included in the directory "tools" of this distribution. See its readme file in the same directory.
<< back to contents
5. OUTPUTS

When exporting, ModKeen outputs the graphics into 16-colour BMP files in the directory specified with the -bmpdir switch. Below is a listing of the files it produces. In the filenames, "x" is the episode number (Keen Dreams is numbered as episode 7), and "nnnn" a four-digit number; the first BMP file for each type of data is numbered 0000.

xBMPnnnn.BMP
        The variable-sized bitmap images used in the menus, ending sequences, and menus. These BMP files must always be a multiple of 8 pixels wide.

xEXTnnnn.BMP
        The external, variable-sized bitmap images used for the previews menu and finale screen in Keen 1-3. These follow the same size rule described above. They are called external because they are not stored directly in Keen's EGAGRAPH file, but in separate external files such as PREVIEW2.CK1, PREVIEW3.CK1, and FINALE.CKx. They could also be imported/exported manually using the external tool FIN2BMP, written by Andrew Durdin.

xMBMnnnn.BMP
        Episodes 4, 5, and 6 only: Masked variable-width bitmaps used in-game. These BMP files must always be a multiple of 16 pixels wide. The right-hand half of the bitmap is the transparency mask; it is white where the bitmap should be transparent, and black where it should be opaque.

xSPRnnnn.BMP
        The variable-sized sprite images used in the game. These BMP files must always be a multiple of 24 pixels wide, and consist of three equal sections. The left hand section is the sprite image; the middle is the transparency mask; and the right-hand edge shows the clipping rectangle for the sprite. In the game, the clipping rectangle marks the part of the sprite which collides with other objects. For episodes 1, 2, and 3, you can set the clipping rectangle by changing the size and/or location of the bright red rectangle. For episodes 4, 5, and 6, see the xSPRITES.TXT entry below.

xTILnnnn.BMP
        These are the tiles used in the game. For episodes 1, 2, and 3, only xTIL0000.BMP will be present, containing all the 16x16 tiles, organised into 13 columns. For episodes 4, 5, and 6, xTIL0000.BMP will contain all the 16x16 background-layer tiles, organised into 18 columns; xTIL00001.BMP contains all the 16x16 foreground-layer masked tiles, organised into 18 columns, with the right-half of the bitmap containing the transparency masks; xTIL0002.BMP contains all the 8x8 tiles used in the game, arranged in a single column; and xTIL0003.BMP contains all the 8x8 masked tiles used in the game, also in a single column.

xFONnnnn.BMP
        These are the fonts used in the game. The fonts are divided into 16x16 equal-sized cells, each containing a single character. For episodes 1, 2, and 3, only one font file is present; it is a multicoloured font with an opaque background. For episodes 4, 5, and 6, all the fonts are black and white only, although they can have variable-width characters: each character is drawn in white on a black background the width of the character, with dark grey filling the rest of the cell.

xSPRITES.TXT
        Episodes 4, 5, and 6 only: This file contains extra information about each sprite. Each line in the file has the sprite number, followed by the four clipping rectangle co-ordinates in square brackets [top, left, bottom, right], followed by the sprite origin in square brackets [top, left], followed by the number of shifts the sprite uses. The origin of the sprite image is the point from which its location is calculated. For example, the hand sprite in Keen 5 (5SPR0291.BMP) has several images. The origin for each of these images is in the centre of the "eye", so that as the hand rotates, the different sprite images all appear to rotate about the eye. The origin coordinates are given in pixels from the top-left corner of the sprite image. The shifts is the number of different copies of the sprite image that are stored in memory, and can be 1, 2, or 4. As a general rule, the more shifts a sprite has, the smoother it moves, but the more memory it takes up. If you are making a very large sprite, you can reduce the number of shifts to save memory. But if you have a small sprite and want it to move more smoothly, increase the number of shifts.

xTXTnnnn.TXT
        Episodes 4, 5, and 6 only: These text files contain the help, story, and end-game text. Each file consists of plain text, with embedded commands for displaying pictures and creating new pages. The commands you can use are:
        ^P                       Marks the beginning of a page.
        ^Gy,x,n              Displays bitmap number (n - 6) at pixel location x,y on the screen.
        ^Cc                    Changes the text to colour c, which is a single hex digit, 0-9 or A-F.
        ^Ly,x                  Following text will be written beginning at pixel location x,y.
        ^Ty,x,n,t            After a delay of t time units (t/100 seconds?), displays bitmap number (n - 6) at pixel location x, y on the screen.
        ^By,x,w,h,c       Fills the w-by-h-pixel rectangle at pixel location x,y with colour 4 (the c parameter is ignored in version 1.4).
        ^E                      Marks the end of the text.

xMSCnnnn.BIN
        Episodes 4, 5, and 6 only: These are binary files needed for correct operation of Keen. Two of them are the low-memory error and the final "Thanks for Playing" color text screens, which you can edit with an ANSI editor. The other .BIN files should not be modified.

xDOSnnnn.BIN
        Episodes 4, 5, and 6 only: text-mode Initialization screen, which you can edit with an ANSI editor. Note that this is exported from the game executable file, and will not be imported back onto it. However, when you import data, the generated patch file will contain an additional line (%patchfile $yyyy xDOSnnnn.BIN) for each of these screen files.

 DEMOn.CKx
        Episodes 4, 5, and 6 only: These are the demos that are shown in the game. Using the F10+D cheat, you can record your own demos, and then import them back into the game, so that you have demos of your own levels.

KEENx.PAT
        Episodes 4, 5, and 6 only: After importing, this .PAT file is created in the directory specified with the -keendir switch. It contains the command "%egahead EGAHEAD.CKx", which causes CKxPatch to load the new EGAHEAD file into memory. After importing, you must run Keen using CKxPatch with this patch file, or it will crash.
<< back to contents
6. CONTACT INFORMATION

You can always post in Keen: Modding (www.keenmodding.org) or the Public Commander Keen Forum (www.pckf.com), Modding sub-forum, to ask for help if you have trouble when making a mod.

This port was written by me, Ignacio R. Morelle, more known in the Keen: Modding and Public Commander Keen forums as the "Shadow Master". Since I wrote this port using and modifying Andy Durdin's code, I'm responsible for answering your GNU/Linux port-specific questions and problems. You can contact me in Keen: Modding, by posting a bug report/complaint/wish-list in the ModKeen sub-forum, topic "LModKeen", or sending me a personal message. If for some reason I never get to respond, you might want to try sending me an e-mail. My main address is shadowm2006@gmail.com.

Any other messages related to ModKeen in general should be posted as new topics in the ModKeen sub-forum.
<< back to contents
7. ACKNOWLEDGEMENTS

Thanks go to Andrew Durdin for publishing the complete source code to his ModKeen 1.0/2.x and Fin2BMP modding tools. Without him, this port would not have been possible. Most of it consists of slightly modified ModKeen 2.0.1 source code and some code copied from Fin2BMP in order to support Keen 1-3 external graphics files.

Thanks to Malvineous for the generic script and mini-program that convert lowercase filenames to uppercase.

Also thanks to Szevvy for the useful information he gave me on Bio Menace data files, and Sarah "Levellass" for the hacked ModKeen 2 source code that handles Shadow Knights and Dangerous Dave 2 graphics.

The method fileexists() in utils.c was copied from Supertux 0.1.3 source code (setup.cpp) for replacing DOS-specific code that was there in the original ModKeen 2.0.1 source.

ModKeen 2.0.1 is Copyright (C) 2002-2004 by Andrew Durdin (andy@durdin.net). He greets and thanks Anders Gavare and Daniel Olson for their assistance.
Fin2BMP is Copyright (C) 2002 by Andrew Durdin.
LModKeen 2 is derived work from the above, Copyright (C) 2007 by Ignacio R. Morelle (shadowm2006@gmail.com).

Commander Keen is property of Id Software Inc. The original Keen 1-5 games were developed by Id Software for Apogee Software. Keen Dreams and Keen 6 were developed by Id Software for Softdisk.

Bio Menace is property of Apogee Software. The game engine (Keen 4-6) was developed by Id Software and licensed to Apogee Software.

Dangerous Dave 2 is property of Softdisk ????
Shadow Knights is property of ????

No penguins were harmed during the production of this software, although some windows were broken in the process.
<< back to contents
8. CHANGELOG

The changelog to LModKeen 2 and later is provided here for historical purposes only, although you might learn about new features coming soon.
Dates specified here are in yyyy-mm-dd format.

8.1 LModKeen

This is the changelog to LModKeen 2 and 3, by Shadow Master:
2007-05-23: EModKeen 3 alpha 1 (not released)
     - Started from scratch
     - Changed project name from LModKeen to EModKeen

2007-05-23: LModKeen 2 release 2
     - Fixed file-name case for Linux according to msdos/vfat FAT name conversion

2007-05-??: LModKeen 3 alpha 1 (not released)
     - Added LModKeen II beta 4 unstable source code.
     - Converted C makefiles to C++ ones.

2007-04-20: LModKeen 2 release candidate 1
     - Removed unstable code.
     - Proper GNU/Linux makefile (GCC).
     - Proper Win32 makefile (Mingw32 - GCC x86).
     - Fixed do_output messing up the output to Win32 console.
     - Fixed setcol setting wrong intensity value on Win32 pconio.c section.
     - Updated internal version/license banners with proper text.
     - Now error/help messages display the actual binary name instead of "modkeen".
     - Win32-specific help message added.
     - Renamed normalize_filenames script to prep_names. Added more generic helper scripts.
     - Updated URLs to external utilities in HTML Readme.
     - Updated package uncompressing instruction since it now uses BZip2 tars instead of GZip.

2007-04-05: LModKeen II beta4:
     - Renamed linconio.c to pconio.c. Added Win32 console I/O compatibility.
     - Renamed linconio.h to pconio.h. Added Win32 console I/O compatibility.
     - More code optimizations.
     - Code clean-ups.
     - First Win32 build (MinGW GNU/Linux cross-compiler).
     - Added symbols for Bio Menace exe files header lengths.
     - Started adding Bio Menace data info.
     - Adding code for DOS title screen data extraction/patch file generation.
     - Adding code for Scrolling text screen data extraction/patch file generation.
     - Added directory layout-independent makefiles for GNU/Linux and Mingw32-on-Linux.
     - Read huffman dictionary from external EGADICT.BMx for Bio Menace.
     - Added methods that return filenames for EGAHEAD, EGAGRAPH, AUDIOT, AUDIOHED, GAMEMAPS, MAPHEAD,
       EGADICT, (exefile), GFXINFOE.
2007-04-01: LModKeen II beta3:
     - Lots of code optimizations.
     - Removed unused code.
     - Added console output coloring.
     - Fixed quit() not displaying messages properly under ncurses mode.
     - Fixed keen456_import_begin() and keen456_export_begin() bugs that caused improper detection
       of EXE information and segment violations.
     - UNIX switches style compatibility (i.e. --episode=3 is the same as -episode=3).
     - Extended --episode parameter to support Dangerous Dave 2 and Bio Menace.
     - Added --debug parameter to add "debug mode" functionality.
     - Renamed keen123_export_finaleimg() to keen123_export_external(). Added progress info to procedure.
     - Renamed keen123_import_finaleimg() to keen123_import_external(). Added progress info to procedure.
     - Marked as stable with Keen 1-3, Keen 4-6 (not Dreams) for importing/exporting data.
2007-03-28: LModKeen II beta2:
     - Fixed bug which caused application to always display help text and ignore command line (GCC bug?).
     - Added bmp_unpack for fin2bmp code compatibility.
     - Fixed bug that caused Lmodkeen to look for KEEN7E.EXE instead of KDREAMS.EXE.
     - Extended get_exe_image_size() for future compatiblity with non-Keen games.
     - Wrote proper code for KDREAMS.EXE executable image size calculation.
     - Adapted EGA header and graphics initialization for Keen Dreams support.
     - Tested Keen1 and KDreams support (last one is still not working for export).
2007-03-27: LModKeen II beta1:
     - Various miscellaneous modifications.
2007-03-23: LModKeen II alpha1:
     - Fixed bug involving ncurses calls.
     - Added Keen Dreams support based on MultiMania's code.
     - Integrated Fin2BMP code on Keen 1-3 import/export procedure.
2007-03-13: LModKeen I
     - Initial public release by Shadow Master

<< back to contents
8.2 ModKeen

This is the changelog to ModKeen 2.0.1 (official), from modkeen.c by Andrew Durdin:
2004-04-01: Version 2.0.1:
     - Bug-fix release. Fixed bug in Keen 1-3 importing where different data types were not
       paragraph-aligned.
2004-03-14: Version 2.0:
     - Initial public release.
2004-03-13: Version 2.0-beta4:
     - Fixed bug with EGAHEAD reading, made extraction automatic, and added more sanity checks.
2004-03-08: Version 2.0-beta3:
     - Fixed bugs with too many chunks and with progress displaying.
2004-03-07: Version 2.0-beta2:
     - Supports importing from Keen 4, 5, 6.
004-03-05: Version 2.0-beta1:
     - Supports exporting from Keen 4, 5, 6.
2004-02-22:  Version 2.0-alpha:
     - Began adding support for Keen 4.
2002-04-01: Renamed to MODKEEN version 1.0:
     - Full support for editing sprites and bitmaps in all three Keen: Vorticons episodes.
2002-03-27: ModLatch version 1.1:
     - Added LZ routines and Keen 1 support, and BMP I/O routines so it compiles under plain DJGPP.
2002-03-25: ModLatch implicit version 1.0:
     - Initial release, DJGPP + Allegro.
<< back to contents
9. KNOWN BUGS IN THIS RELEASE

Yeah, there are some bugs in this program. There should be more, but here's the list of bugs that I'm currently aware of. If you discover a bug that you can reproduce, see Section 6 (Contact Information) to know how to report it.
<< back to contents
10. TO-DO LIST

Although I try to have everything done for each release, my spare time or knowledge is not enough for that. As a result, there are still some features missing, not tested or not implemented. Here is a list of them. They might be implemented in future releases.
<< back to contents

Last updated on 2007-04-01, 8:12 PM UTC by Shadow Master