Keengraph
| Initial Developer | Levellord |
|---|---|
| Developer(s) | Levellass |
| Initial release | 2009-06-16 |
| Latest update | 2014-05-30 |
| Development status | Finished |
| Programming language | QBASIC 4.5, FreeBasic |
| Platform | DOS, (DPMI), Windows XP, 7-10, (Linux via Wine) |
| Tool Type | Graphics, Text Editor |
| Engine(s) | Keen:Vorticons, Keen:Galaxy, Keen:Dreams, Bio Menance, Catacomb 3D, Cosmo's Cosmic adventure, Dangerous Dave 3/4, Slordax, Shadow Knights, Resue Rover, Rescue Rover 2,D |
| Discussion(s) | K:M Discussion Thread |
| Download | KeenGraph v.2.2.6 newest |
KeenGraph is a Keen graphics importing/exporting utility written by Levellass. It is written using QBASIC 4.5 compiled with FreeBasic and is thus primarily a windows based utility, though builds for Linux do exist.
It is an attempt to improve on the earlier ModKeen utility by Andrew Durdin. This first version was capable of importing and exporting Keen 1-3 and Keen 4-6 graphics, including the tileset bitmap, all the sprite animation frames, and miscellaneous bitmaps used by the engine, including the character set as well as most graphics of the related games including the Dangerous Dave series and Biomenace.
It is notable in using 8-bit bitmaps for some exported graphics, removing the need to make tedious sprite masks, as well as scanning patch files, making it compatible with palette patches and file name changes.
The second version, released June 2009, was faster, created Tileinfo compatible tilesets, added command line interface similar to ModKeen's and had improved error detection.
It continues to be sporadically updated and altered, the current version being 2.2.6, as new features and functionality is added. Recently support for galaxy graphics was added and FreeBasic became the new program language, allowing increases in speed and flexibility.
Using Keengraph
Keengraph is run from the command line using a number of switches, much like ModKeen. However there are two ways this may be done, either by typing text into the file KEENGRAPH.TXT or from a batch file\the command line itself. A single string of commands will export graphics and c single string import them.
Modifying graphics
In all cases the same procedure is used to modify graphics. The first step is to take a clean copy of the game you wish to modify and copy Keengraph to its folder. (Keengraph can be run from another folder, but this is the easiest method.)
If the game is Keen Galaxy or uses the EGAGRAPH format then you will need to make sure that the executable is decompressed. (This will be necessary for patching anyway.) This can be done with UNLZEXE If this is not done, Keengraph will give an error.
To export graphics to their own directory use the following command (In this example for Keen 4):
-export -episode=4 -bmpdir='GRAPHICS'
There will be a short pause while Keengraph extracts graphics. (From two to ten seconds.) during which time you will be able to see the extraction progress. When it is finished the folder GRAPHICS will have been created and filled with extracted images.
To import the graphics from the GRAPHICS directory, the following commands are used:
-import -episode=4 -bmpdir='GRAPHICS'
This will also take time to do as graphics are imported. The first import, while DATA.BAK is being written will take longest, subsequent imports will be faster. When importing is done the new graphics will have been imported to game files. For Keen Vorticons they will now be ready to use. Keen Galaxy however is different, requiring a patch file. If the -patch switch (See below) is used then a patchfile will have been created, or, if it exists, the required patches added to it. Otherwise the modder will have to locate the correct patches in the extras folder to add to their patchfile.
DOS Screens
In Keen Galaxy several DOS screens are present in EGAGRAPH, these will be exported as raw *.BIN files. In all Keen episodes screens are present in the executable and can be extracted by Keengraph by dragging-and-dropping the executable onto KEENGRAPH.EXE. The file DOS-SCREEN.BIN will be created. In the case of Keen Galaxy you will be asked if you want to extract the entire screen or just the header.
Screens can be edited with TheDraw, a DOS-based application that will need DOSBOX to run. (There may be other applications.) Screen headers can be edited with KeenScr. Both are in Extras\DOS Screen utilities\ folder. (See below.)
Screens will need to be imported before the patches will work. This must be done every time you make a change to the DOS-SCREEN.BIN file. You will be asked to chose Keen Dreams or Keen 1-6 format. Simply pressing [enter] will give you 1-6 format, what you will be using most often. When importing Keen Dreams remember that the original .BIN file is NOT needed but the .DAT and .TXT files ARE.
Only use .bin file extension files when using TheDraw, since this is how it recognizes screen data Screens are saved as (B)inary data. Saved screens will be about 15Kb in size if you save correctly.
If the screen causes your game to crash then you most likely HAVE NOT IMPORTED IT. .BIN files should be 3.90Kb in size, exactly 4'000 bytes. (TheDraw saved .BIN files will be 15.6KB = 16'000 bytes long, hence the need for import.) Keen Dreams import will give you an error message if anything goes wrong.
Using screens will require patches in the case of those in the executable. These can be found in the Extras folder. (See below.)
Switches
The following switches are supported:
+----------------+-----------------+-------------------------------------------------------+
|Command |Example | Function |
+----------------+-----------------+-------------------------------------------------------+
| | | |
|-export/import | -export | Tells KEENGRAPH whether you want to import new |
| | | graphics or export existing ones. If absent, KEENGRAPH|
| | | will try to export. |
+----------------+-----------------+-------------------------------------------------------+
|-episode=N | -episode=3 | The episode you want to work with, values are 1-7 for |
| | -episode=x | Keen. If absent KEENGRAPH assumes episode 1. If absent|
| | | then KEENGRAPH will automatically detect |
| | | what to work with by looking for the right executable |
| | | file. (Thus use this for Dave, Shadow, etc) |
| | | |
| | | Shadow Knights is episode 11 and Dave 2 episode 12, |
| | | these can be specified if you want. (-episode=12...) |
+----------------+-----------------+-------------------------------------------------------+
|-filedir='DIR' |-filedir='C:\CK' | Where the game files are located. By default KEENGRAPH|
| |-filedir='MODS\- | looks in its directory. So in our second example the |
| | FILES' | graphics files are in the MODS\FILES subdirectory of |
| | | wherever KEENGRAPH is. |
| | | If the dir does not exist, KEENGRAPH will abort with a|
| | | path file not found error. |
+----------------+-----------------+-------------------------------------------------------+
|-bmpdir='DIR' |-bmpdir='C:\CKGR'| Where the graphics pictures are located. By default |
| |-bmpdir='NEW\- | KEENGRAPH looks in its directory, like filedir. This |
| | GRAPHICS\ | path should end with a slash, if not, KEENGRAPH will |
| | | add one. This command it totally separate from the |
| | | -filedir command, the two locations can be totally |
| | | different. |
| | | If the dir does not exist, KEENGRAPH will create it if|
| | | exporting or abort with a file not found error if |
| | | importing. |
+----------------+-----------------+-------------------------------------------------------+
|-backup | -backup | When importing graphics, backs up your old game files |
| | | as *.BAK. KEENGRAPH will only back up the latest |
| | | files, for simplicity. By default backup is off. |
+----------------+-----------------+-------------------------------------------------------+
|-translucent | -translucent | For those who want to have translucent ('half masked')|
|-tra | -tra | sprites, this command will give sprite bitmaps another|
| | | 16 colors for such 'ghost' sprites. By default this is|
| | | off, to make things simpler. |
| | | |
| | | This command is useful only when exporting bitmaps, if|
| | | it is not, then you will not be able to make such |
| | | sprites from the exported bitmaps. (KEENGRAPH will |
| | | work with any kind of 256 color bitmap it is given.) |
+----------------+-----------------+-------------------------------------------------------+
|-bcolor=X,Y,Z |-bcolor=255,0,255| What color the background color is in sprite bitmaps. |
| | | By default this is a light green, but you may want to |
| | | change it to make it more obvious or if it is messing |
| | | with a modified palette. Valid values must be |
| | | separated with spaces or commas and are RGB |
| | | respectively. They range from 0-255. You will be shown|
| | | a successful change when KEENGRAPH exports. |
+----------------+-----------------+-------------------------------------------------------+
|-patch='FILE' |-patch='PAT.PAT' | Where the patchfile is. KEENGRAPH will scan this for |
| |-patch='C:\KEEN\-| various things. With Dave II, Keen 4-6 and other games|
| | MYMOD.TXT' | this file will be CREATED if not present so that |
| | | changed graphics can be loaded. (The only patch file |
| | | complex enough to read for patches is Keen 1-3; all |
| | | others will be mostly ignored after creation. If no |
| | | name is given, PAT.TXT will be created if needed for a|
| | | game.) |
| | | |
| | | Things scanned for for Keen 1-3 are changed file names|
| | | and palette patches (So graphics look like they |
| | | should.) If you're using these sorts of things, then |
| | | you should use this command. |
| | | |
| | | If this switch is absent, not patch file will be made |
| | | or scanned. |
+----------------+-----------------+-------------------------------------------------------+
| -mod | -mod | Some games have no patch utilities or you may not want|
| | | to use them. This command will directly patch the |
| | | executable to take modified graphics (If necessary.), |
| | | allowing you to quickly test something or to work with|
| | | unpatchable games. DOING THIS IS TECHNICALLY ILLEGAL! |
| | | but useful. Note EXE's must by UNLZEXE'd and be the |
| | | |
| | | CURRENTLY NOT IMPLEMENTED. |
+----------------+-----------------+-------------------------------------------------------+
| -warn | | Don't show non-fatal errors, such as out of memory |
| -error | | or too big sprite errors. Can be useful if a modder |
| | | can work around some errors, such as by using the |
| | | 'sprite blitting' patch for large sprites. |
+----------------+-----------------+-------------------------------------------------------+
Extras
Keengraph comes with a number of utilities and extras for use when making mods.These are in the Extras folder that comes with Keengraph. They are as follows:
- ???patch Utilities used to patch Keen and other games
- Patch files for all games requiring them. These are used with the above patch utilities
- UNLZEXE the 16-bit version that may not work on some setups. This is used to decompress executables.
- TheDraw Used to edit DOS screens. Comes with required patches and an example screen.
- KeenScr Used to edit Galaxy screen headers, much simpler than using TheDraw.
Outputs
KeenGraph creates a number of different files when exporting graphics. Most of these are 16 or 256 color bitmaps. A full list as is follows where x is the episode number and n is the bitmap number. 256 color images have only 32 usable colors (Or 16 if the -tra switch isn't used.) and like all bitmaps rely on their own palette to convert their data into Keen's EGA format. Using bitmaps not originally created by KeenGraph is dangerous territory.
- xANSnnnn.BIN
These are 4'000 byte DOS screen files that can be edited with TheDraw (See above section.)
- xBMPnnnn.BMP
16 color unmasked bitmap images. These can be any height but their width must divide by 8. In-game these are used for most story graphics outside of levels.
- xEXTnnnn.BMP
16 color 'fullscreen' images. These are only present in Keen Vorticons and similar games and are mostly used for fullscreen story-related graphics. Each comes from c separate external file and is usually fullscreen 320x200. Their widths must divide by 8.
- xFONnnnn.BMP
These are the 8x8 unmasked tiles used in the game. This name is used due to tradition and not because the graphics are fonts. Keen Vorticons uses this for an in-game font, but is about the only game that does. Most other games have far fewer entries and use them for text windows and menus. The width of the 16-color bitmap created will vary depending on the game but will always divide by 8, as will the height. (1 tile.) In Galaxy these are named differently but there is no difference in format.
- xFONTnnnn.BMP
This is the true, monochrome font used in many games. While the bitmap is 16 colors, the font only has two colors, black and white. (Actually anything colored black in the font will reverse the color of anything it appears over.) Some fonts in earlier games have unknown 'mask' data that appears in light and dark grey. It is not known what this does, if anything at all.
The bitmap is 16x16 characters wide, each character 24x24 pixels (Bitmap must be 384x384 pixels in size.) and only black and white pixels will be considered part of the font. Some (indeed most) characters will be blank this is normal.
The height of all characters will be grabbed from the space character (Usually the first character with any data.) so it cannot be blank, and the width of a character is grabbed from the first line of pixels. Characters should be square. Keen Vorticons does not have this type of font.
- xMBMPnnnn.BMP
Keen Galaxy and similar games only Masked variable-width bitmaps used in-game, usually being overlaid on the screen, there are not many of them. They are 256 color images due to masking. Their width must divide by 8, but they usually have a special purpose which means their size is best left unchanged.
- xMSCnnnn.BIN
Keen Galaxy only. These are any 'miscellaneous' graphics or data that doesn't fit into any other category. For Dangerous Dave 2 this is the intro graphic and Keen 5 has the galaxy explosion data, but otherwise not much should appear here.
- xSPRnnnn.BMP
256 color sprite images used by all games. They have two sections, the image and the hitbox. The image is what it sounds like and is seen in-game, the hitbox is the same size as the sprite and is red\grey. The red section is 'solid' and is what the sprite uses to hit other sprites and tiles. Any other color is not solid, but grey is default.
If a sprite's hitbox is larger than it is in some way then the sprite bitmap's hitbox will be all grey, but the hitbox will be stored in LIST.TXT (See above.)The hitbox in the image takes precedent over that in LIST.TXT. Image width must divide by 16.
- xTXTnnnn.TXT
Keen Galaxy only. These are help texts used in the game. They use one of the monochrome fonts and bitmap images and are the basis of the game's help and ending sequences. The following commands are used in the text:
^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 color 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 color 4 (the c parameter is ignored in version 1.4). ^E Marks the end of the text.
- xTILnnnn.BMP
For Keen Vorticons these are the unmasked 16x16 tiles used in the game. By default most games have only one tileset, though this can be changed. The bitmap is 16 color and divided into 16x16 squares. The bitmap's width and height must both divide by 16 (i.e. one tile.) By default these bitmaps are 13 tiles wide. Most games have a fixed number of tiles though this can be changed. In Keen Galaxy these tiles are named xTIL16Unnnn.BMP but there is no other difference.
- xTIL8Unnnn.BMP
See xFONnnnn.BMP above. The difference in name is because of how Galaxy tiles work., in galaxy the 8x8, 16x16 and 32x32 masked and unmasked tiles are all graphics chunks. Unlike Keen Vorticons, the number of 8x8 tiles is more fluid and can be patched.
- xTIL8Mnnnn.BMP
In Galaxy only, these are 8x8 masked tiles mostly used for text windows. Like xTIL8Unnnn.BMP they are all in one bitmap of varying width depending on how many tiles there are. The number of tiles varies from game to game. The image is 256 color and must have a width divisible by 8. (1 tile.)
- xTIL16Unnnn.BMP
See the xTILnnnn.BMP above. The difference in name is because of how Galaxy tiles work.
- xTIL8Mnnnn.BMP
In Galaxy only, 16x16 masked (foreground) tiles. These are similar to the unmasked tiles above except they are masked. Bitmap width and height must divide by 16 (1 tile.)
- xTIL32Mnnnn.BMP and xTIL32Unnnn.BMP
These have not been found for any game but would be masked and unmasked 32x32 tiles. (Rescue Rover has these tiles but they do not have this name.) Bitmap width and height must divide by 32 (1 tile.)
- DATA.BAK
This file contains a backup of all imported graphics data and is used to speed up import times (Since data can be read from this file instead of from bitmaps.) Dragging and dropping this file onto Keengraph will extract all the stored graphics if something goes wrong.
- DEMOn.xxx
Galaxy only. These are the demo files outputted and used by the game. Using the demo cheat will allow you to record your own demos which can then be imported. Only demos made by the game should be used.
- DOS-SCREEN.BIN
These are 4'000 byte DOS screen files that can be edited with TheDraw (See above section.)
- LIST.TXT
This is the most important file Keengraph creates. It contains a list of the file names of all exported graphics and is used to find files containing graphics data. T(The filenames listed here are defaults and it is possible to use whatever names you like for graphics, if you specify them in this file.) A brief look at the file should be enough to discern how it works.
Vorticons and Galaxy list files are read differently. Both are composed of a number of sections which contain a number of lines giving the graphic number and the file that is storing that data. In Keen Vorticons sprites, tiles and such are separate and numbered as such. In Galaxy they are all part of one file (Except Keen Dreams title graphics.) and are numbered as such.
As well as the graphics number and file name several graphics have additional parameters defined on their lines. Keen Vorticons graphics each have a name and sprite graphics have optional hitbox () and offset [] variables. It is also possible to change the name of the sprite file(s) created on import for Keen Vorticons by changing the name of the sprite header in the list file.
The hitbox variables define the top left and bottom right of the hitbox and as such there are four terms to be defined, separated by commas and enclosed in round brackets (E.g. (-1,4,23,23)) The hitbox will only appear in the list file if it can't be fit on the sprite image and will be overruled by any hitbox drawn on the sprite. (To use a list hitbox, make sure the sprite bitmap's box is entirely grey.) It is possible for a hitbox to have negative values and to be bigger than the sprite itself. It is not wise to have a hitbox whose upper left corner is below or right of its bottom right corner.
The sprite offset is present only in some games and defines how the sprite image and hitbox is 'offset from the sprite itself. This is mostly used so that sprites of differing size can be used together without appearing in the air or stuck in the ground. There are two terms, both of which can be negative, enclosed in square brackets. (e.g. [-4,6]) The example here would place the sprite image 4 pixels higher and 6 pixels right of the previous sprite image it animated from.
Finally Galaxy sprites will have a 'smoothness' value, 1, 2 or 4 that defines how many copies of the sprite to put into memory. The higher this is the smoother the sprite will move, but the more memory it will take up, especially for large sprites.
- PATCHx.TXT
This file is created when the -patchfile switch is used and it is needed. It can be called anything specified and contains the patches needed to use the imported graphics. It will also produce a .BAT file to run the patches but you will need to copy the right patch utility to run it.
Supported games
As Keengraph is a beta at present, support for some games is shaky or absent. Some games lack the utilities needed to properly mod them (Dangerous Dave 4) while others have not yet been accounted for (Keen Dreams) The following list gives the -episode value used by all games Keengraph can work with and their compatibility. [*] is full support, [?] exports but import has not been tested, [E] is export only and [] unsupported.
[*] 1-3 Commander Keen Vorticons [*] 4-6 Commander Keen Galaxy [E] 7 Commander Keen Dreams [ ] 8 Dangerous Dave in Copyright Infringement [*] 9 Dangerous Dave in the Haunted Mansion [*] 10 Slordax [*] 11 Shadow Knights [*] 13 Resue Rover [E] 14 Rescue Rover 2 [E] 15-16 Dangerous Dave 3/4 [E] 17 Catacomb 3D [ ] 18-20 Cosmo's Cosmic adventure 1-3 [?] 21-23 Biomenace 1-3
Frequently encountered errors
- Keengraph says a file doesn't exist but it does:
-> There are several possibilities here, a file that is 0 bytes long may as well not exist, so check it's length. It's also possible the file is write protected. Or see the next error.
- Keengraph makes a folder that makes no sense or looks in a folder not specified:
-> The biggest cause of this is using a batch file containing ' marks. DOS doesn't pass these to Keengraph, so it gets confused. Always use ' marks in commands like -filedir='Keen4'
- Graphics are gibberish or crash the game:
->If the game is supported this is probably due to the files not being patched correctly.