
+------------------------------------------------------------------------------------------+
| Keen 1-3 Engine Graphics Modifier                                                        |
+------------------------------------------------------------------------------------------+

Hello there and welcome to a new LassWare release! This program will allow you to extract
and modify Keen 1-3 and Shadow Knights graphics, and partially modify Dangerous Dave II
graphics.

This works by reading a script file then exporting the relevant graphics to 256-color
bitmaps, and by taking these bitmaps, modified or not and importing them into files useable
by games.

It is in short, a BASIC version of Modkeen 1, with some nifty new features.


CONTENTS:

* Features
  - Compatible games
* How to use
  - The script file
  - Commands
    - Examples
  - Outputs
* Changing graphics
  - Changing the number of graphics images
    - Limits
  - 'Blanking' images
  -Half-masked sprites (Ghosts)
  -Faster importing
* The LIST file; your friend
* Problems and limits
  -Errors
* Also from Lassware
* Credits



+------------------------------------------------------------------------------------------+
| Features                                                                                 |
+------------------------------------------------------------------------------------------+

What KEENGRAPH can do:

  * Change all the tiles in Commander Keen 1-3, Shadow Knights and Dangerous Dave
  * Change the sprites in Commander Keen 1-3 and Shadow Knights
  * Change other images used in the menus and games in Keen 1-3, Shadow Knights and
    Dangerous Dave
  * Change the fonts used in Keen 1-3
  * Change the number of graphics images

Neat feaures include:

  * Grouted bitmaps; no more filling in annoying tile masks!
  * Non 8-divisible bitmaps don't crash the program
  * Edit Dave and Shadow Knights!
  * Custom commands to make editing easier
  * Extra hitbox flexibility
  * Warnings if your graphics are too large or buggy



COMPATIBLE GAMES:

  * Commander Keen 1-3, all versions
  * Dangerous Dave II a.k.a. Dangerous Dave in the Haunted Mansion
  * Shadow Knights



+------------------------------------------------------------------------------------------+
| How to use                                                                               |
+------------------------------------------------------------------------------------------+

Basically (Haha) speaking KEENGRAPH is run in the same directory as GRAPH.TXT and will
extract or import the relevant graphics, much like Modkeen in fact.

Of course there's a bit more to it than that, but that's what this file is for.

NOTE: Before you can use KEENGRAPH with Dave II, the file HAUNTED.EXE must be UNLZEXE'd,
so that KEENGRAPH can read graphics data from it. (It will also need to be patched before
new graphics can be used.)



THE SCRIPT FILE:

The biggest difference you will notice from Modkeen is that KEENGRAPH requires the file
GRAPH.TXT (Or GRAPH.BAT) to run. If you are upset because Modkeen was command line, then I
hit you with sticks; command line is fine, but anyone with some sense will make a BAT file
to automatically enter all the commands instead of typing them out each time in command
prompt. This is, in essence, wha the script file is for.

As mentioned above, the file may be either .TXT or .BAT (Change the extension at your
lesiure.) and it will be read when KEENGRAPH is run. The file must contain a number of
commands (Or 'switches'), as shown below, to tell it what to do.



COMMANDS:

The following commands are listed with an explaination. They can usually be in any order and
are seperated by spaces. Please type them all in lowercase.


-export\-import
Tells KEENGRAPH that you either want to export to or import from bitmaps. Pretty basic. If
you do not specify this, KEENGRAPH will try to export.


-episode=N
What episode you want to work with. Keen 1-3 is 1-3, Dave II is 8 and Shadow Knights is 9.
(The letters 'd' or 's' can be used as well, in case you forget.) You MUST specify an
episode, it is the only vital command. KEENGRAPH can NOT work with Keens 4-6 or Dreams,
sorry :(


-filedir="DIRECTORY"
This is where the game files are looked for (E.g. "C:\Keen 3" The directory must NOT end
with "\" If the drive is left out (e.g. "Keen 3", "\Dave II" KEENGRAPH will insert "C:" to
the path.

If this command is not used, the current directory will be looked in. If the directory
doesn't exist, KEENGRAPH will abort with a path access error.


-bmpdir="DIRECTORY"
This is where the graphic bitmaps are looked for. The directory MUST end with "\", the
OPPOSITE of the -filedir (e.g. C:\bmps\" If the drive is left out KEENGRAPH will look for a
SUBFOLDER in the CURRENT DIRECTORY, another difference from the -filedir

If this command is not used, the current directory will be looked in. If the directory
doesn't exist, KEENGRAPH will abort with a path access error. If the -filedir command is
used then you can specify a subdirectory not in the current directory, but the FILE
directory.


-backup
When importing this will back up your old Keen files as .BAKs Note that it only backs up the
most RECCENT files. By default no backups are created.


-unmask="XX,YY,ZZ"
Not happy with the default unmasked sprite color? Is it a little hard to see? (See later.)
Then use this command. It will need three numbers each two digits long, between 00-63 and
seperated by a comma (e.g. 63,08,00) which will define the unmasked color's rgb value. By
default the unmasked color is a light green. (See later.)


-patch="FILE"
This is the patchfile used n the games; it has several uses. For Keen 1-3 KEENGRAPH will
scan the file for the palette patch, and if it is present, change the default colors in
its bitmaps to look exactly like they do in-game.

For Dangerous Dave when IMPORTING this will be the name of the patchfile created to patch
the changed graphics. (By default it is "PAT.TXT")


=> EXAMPLES:

Let's start off lazy and export Keen 1 in the current directory to the current directory:
KEENGRAPH.EXE -episode=1

Now let's export Dangerous Dave graphics to another directory, AND change the unmasked color
to a nice pink instead of green:
KEENGRAPH.EXE -episode=d -bmpdir="C:\davegraph" -unmask="63,55,63"

Here we'll import Keen 2 bitmaps from another directory, backing up our files:
KEENGRAPH.EXE -import -episode=2 -bmpdir="E:\keenstuff\mymodgraph" -backup

Finally we'll export some Keen 3 mod graphics from a folder into a subfolder in the
MOD directory, using the mod's palette patch and changing the unmasked color to a
dark grey:
KEENGRAPH.EXE -episode=3 -export -filedir="C:\mods\keen3mod\" -bmpdir="\3modgraph" -patch="patches.pat" -unmask="08,08,08"



OUTPUTS:

When exporting, KEENGRAPH outputs the graphics into 256-colour BMP files in the directory
specified with the -bmpdir command. Below is a listing of the files it produces. In the
filenames, "x" is the episode number, and "nnnn" a four-digit number; the first BMP file for
each type of data is numbered 0000. Dave and Shadow Knights use the episode number '1' for
convenience.

  xBMPnnnn.BMP:
These are unmasked graphics, used in-game for things like starting sequences and menus.
They should always be a multiple of 8 pixels wide. The bitmap will have 17 colors; 16
normal and the (Unused) unmasked color.

  xEXTnnnn.BMP

The external graphics, usually 320x200 in size. 'Screen' files used for example in the
previews section of Keen 1. For Keen these must be 320x200, but for the other games this
can vary.

  xFONnnnn.BMP
The 8x8 unmasked 'font' used in the game windows. There is a maximum of 256 font characters
for any game, outputted as a 128x128 bitmap (Though you can resize this.) In Keen this
contains all the font you need as 8x8 unmasked tiles. Dave and Shadow however have only
a few tiles and most of their font is stored seperately as a keen 4-6 style masked,
variable length characters. (These cannot yet be modified.)

  xSPRnnnn.BMP
The sprite images, mostly used... for sprites, but also in some menus. The image is divided
into two equal parts, the sprite and the hitbox. The hitbox defines what part of the sprite
is 'solid' that is, can touch both tiles and other sprites. (In all cases the redish box
hits, the greyish parts don't. For fun, the greyish bit can actually be any color.) 

Sprite images should be a multiple of 8 pixels wide (The bitmaps a multiple of 16) The 
bitmap has 32 colors, 16 normal and 16 unmasked (half transparent.) You will probably
notice the default light green unmasked color. For more on sprites, see below.

  xTILnnnn.BMP
The game's 16x16 tiles, arranged in rows of 13 tiles each. Very similar to the unmasked
graphics, you can make this bitmap any multiple of 16 in width.

  EGAHLATCH.DD2 and EGAHEAD.DD2
These contain the unmasked graphics and graphics header for Dave II; they are normally
stored in the executable, and will be extracted on export.

  LIST.TXT
This is the list file, mostly containing graphic names. However it has a few other important
functions that are detailed later.

  PATCH.PAT
This is for Dave II only, and will be produced on import, to patch the new header and
unmasked graphics. (Otherwise Dave will use the defaults.)


+------------------------------------------------------------------------------------------+
| Changing Graphics                                                                        |
+------------------------------------------------------------------------------------------+

Changing the actual graphics is simple enough, so long as you keep in mind a few things,
such as the fact that most images must be a multiple of 8 pixels wide (Or you will see...
interesting effects.) You can open the bitmaps in your favorite program (Though paint is
reccomended.)

When you have changed things to your liking, simply run KEENGRAPH again to import. There are
some tricks and tips of course to help you out:



CHANGING THE NUMBER OF GRAPHICS IMAGES:

KEENGRAPH will keep importing graphics for as long as it has bitmaps to use. Thus, if you
want to add another sprite image to Keen 2 say, simply save a sprite bitmap with a new name
(Say, open 2SPR0106 and save it as 2SPR0107.) and KEENGRAPH will add it.

NOTE: The bitmap should be the same format as the others, so you MUST start with a KEENGRAPH
bitmap and use 'Save as' (Otherwise what you see will not be what you get.) You CAN use an
unmasked graphic image to make a sprite image, but keep it simple huh?

To remove graphics, just delete the bitmap. (NOTE! KEENGRAPH only works with consecutive
bitmaps, if you delete 1SPR0055, then KEENGRAPH will stop at 1SPR0054, even though the other
bitmaps are still there, it is not smart. See 'blanking graphics' below.)

For tiles and font entries, simply erase squares in the bitmap. You will see for example
that Dave II and Shadow do not fill their font bitmaps and have a lot of empty space.
Likewise you can erase or add entire rows by resizing the tile bitmap.


=> LIMITS:

No game can have more than 256 font entries, Keen 1-3 cannot have more than 689 tiles (53
rows of 13 tiles.) Likewise there is a limit to how much graphic 'space' (Everything in
total.) that can be used for each game and on how big sprites can be, KEENGRAPH will
warn you if these limits are breached.

Dave and Shadow likewise have pre-coded numbers of sprites used for each seperate sprite
file, and KEENGRAPH automatically splits graphics into these. (If and when patches for this
are made avalible, then KEENGRAPH will use the patchfile to automatically correct this.)



'BLANKING' IMAGES:

So, you can't remove an image in the middle of some other graphics, but you don't want it;
what can you do? Sprite images can be reduced to 1x8 pixel empty graphics to save space, and
unmasked graphics can be removed entriely by making the bitmap 1x1 in size. This is a neat
way of saving space.



HALF-MASKED SPRITES:

Now say you want to make a ghost sprite; you want it to be part see through so that it
alters the background behind it. But you can't just erase the mask since KEENGRAPH uses
grouted bitmaps! What are you to do?

Simple enough; sprite bitmaps have 32 colors, 16 normal and 16 'see through' If you look
at the palette (Or try random colors) you will find a 'ghost' color for everything. Using
these colors makes a half see-through sprite. This isn't exactly that easy, but it's not
often you need to do this.

You can change the background color, and with it the ghost colors with the -unmask command.
The examples folder with this program has an example of masked and half-masked sprites.



FASTER IMPORTING

It can be annoying when you're trying to get something right to have to wait all that time
for things to import, and especially with KEENGRAPH on slower systems. A big time saving
will occur if you delete the 1EXT bitmaps; while you won't import the FINALE type graphics,
you usually don't need to do this very often and you'll save a lot of time importing since
they're quite large. This works for Dave and Shadow Knights too.

If you want a further speed boost, especially for Keen, delete the LIST.TXT file, so
KEENGRAPH doesn't waste time naming all those graphics. (The file isn't really needed
unless you're doing something special, see its section below.)



+------------------------------------------------------------------------------------------+
| The LIST file                                                                            |
+------------------------------------------------------------------------------------------+

Yes, KEENGRAPH creates a list file, and I can hear you moaning from here. Yes, it's as
complex as Modkeen's, but there are a few features that make it easier to use.

First up, for everyday purposes, the list can be TOTALLY IGNORED; for Keen all it will
really contain is the names of each graphic, the file can even be deleted and noting much
will happen.

Secondly, while in Modkeen the list file takes priority, in KEENGRAPH the bitmaps do; this
means that you only need to worry about the list file when you want to do something special.


The list file at most, is composed of four columns, a bitmap name, a graphic name, the
graphic offset and the hitbox:

1SPR0046.BMP: 'NINDUKSWD2L ' ( 16, 0)( 0, 4, 23, 42)

This is very similar to the Keen 4-6 SPRITES.TXT file. A column of information will only
be written if needed. What this means is that you DON'T need an entry for every graphic,
just the ones you want. To further explain things here is a description of the four columns:


1: Bitmap name: This is written for masked and unmasked graphics. KEENGRAPH uses this to
identify the graphic.

2: Graphic name: This is written for masked and unmasked graphics. it MUST be a fixed
length, 8 characters for unmaksed and 12 for masked graphics. To help you see this it
is enclosed in *'* marks. You probbably won't bother changing these, but they ARE the
official names for the graphics.

3: H\V offsets: Written for sprites only, and then only for Dangerous Dave and Shadow
Knights, since Keen doesn't use them. Like Keen 4-6, these 'offset' the sprite image from
the sprite. Thus if we have the values ( 0, 4) then a sprite will be sunk 4 pixels into the
ground when standing around.

4: Hitbox: Written for sprites only, and then only when the hibox is too big for its
bitmap. This allows you to have negative hitboxes or ones that extend far beyond the sprite.
For Keen, which doesn't have offsets, this can be the only way to do some real neat stuff.

As an example, say you want to make the Keen 1 Tankbot float two tiles above the ground;
then you would find the Tank entries and change them to something like:

1SPR0098.BMP: 'TANKLEFT1   ' ( 0, 0, 15, 45)

(The Tank bitmap is 16x24 in size, and 24 + 32 = 46) Likewise you can make the Yorp push
Keen while still a tile away from him ('Force field') with:

1SPR0048.BMP: 'YORPSTAND1  ' ( -16, 4, 31, 23)

(The Yorp is 16x24 in size.) This is a remarkably powerful way of doing things and has a
lot of possibilities. (Note that ANY hitbox co-ords can be used, overiding the bitmap's
ones IF they are in the list. The maximum hitobx size is 256x256, or 128 pixels in any
direction.)

The examples folder with this progam has an example list file to help explain this complex
little bit.



+------------------------------------------------------------------------------------------+
| Problems and limits                                                                      |
+------------------------------------------------------------------------------------------+

* At present Dangerous Dave cannot be imported since I cannot huffman compress in BASIC
* KEENGRAPH is rather slow, especially on older systems
* You are limited by the game's programming (E.g. graphic size and space, the number of
  sprites...)
* KEENGRAPH cannot edit the alphabet used in Dave or Shadow Knights


ERRORS:

A PARAMETER IS INVALID : This means that KEENGRAPH is too far from the C:\ to work; it can't
keep track of where it is. Put is closer to the drive.

PATH DOESN'T EXIST\FILE ACCESS ERROR: You have specified a directory that doesn't exist; or
a program is using the directory and is refusing to share. Make sure you have specified
the right -bmpdir or -filedir.

THE NEW GRAPHICS MAKE THE GAME CRASH: This is most likely your fault, KEENGRAPH has
extensive safeguards, but you never know. If in doubt, see if you can find the graphic
that is the problem. If issues continue, email me and I'll see what's up.

USED TOO MUCH GRAPHIC MEMORY: Keen is allowed 496K of memory to store its graphics in, and
you can easily exceed this, KEENGRAPH gives you a tally on how much memory you have used
and displays the memory error when this is exceeded. Note that it is best to use less than
90% of avalible graphics memory.

KEENGRAPH MKAKES FUNNY, ERROR-CAUSING IMAGES: This happens when someone has included an
'empty' graphic in thier mod of dimensions 0x0, so of course the bitmap will be useless.
If you want, you can replace it with another bitmap of actual size.

SPRITES LOOK FUNNY: The most common cause of this is a bitmap not divisible by 8 in size;
it shouldn't be too hard to see which one this might be. Unmasked graphics will auto-correct,
but sprites will not.

SPRITES FALL THROUGH GROUND, ETC: This is most likely a LIST.TXT error, though you may have
drawn the hitbox wrong. Check both to make sure.

TYPE MISMATCH: This occasionally occurs when a patch file is opened that has a confusing
patch, usually one mistaken for a palette patch. Try removing the -patch command.



+------------------------------------------------------------------------------------------+
| Also from Lassware                                                                       |
+------------------------------------------------------------------------------------------+

As of the writing of this program the following utilities were completed, and may interest
you:


KEENSCREEN: This program extracts the DOS screens from Keen 1-6 and dreams and provides an
editor for them. It also edits the 'terminator text' of Keen 4-6

KEENPAL: This program isn't really needed if you have KEENGRAPH; it changes the palette
of Modkeen graphics using the 'change palette' patch in a mod's patch file.


Lassware needs beta testers! There are literally dozens of programs in development!




+------------------------------------------------------------------------------------------+
| Credits:                                                                                 |
+------------------------------------------------------------------------------------------+

Take note of these, since they're about the only place some very deserving people are
getting any thanks; they put a lot of effort into this program and exceed me in ability
many times over:

LEVELLORD: Provided some basic information on the Keen graphics as well as some help with
           BASIC programming.

NAPALM: Wrote the LZW and Huffman decompression subroutines for KEENGRAPH; provided a LOT
        of info about various graphics formats and was a continual inspiration during the
        construction of KEENGRAPH

ANDY DURDIN: Introduced me to Napalm, tried his best to teach me about Keen graphics despite
             an almost total lack of resources.

COMMANDER SPLEEN: Inspired this program, beta tested some.


