Keen Source Mod Modding Tutorial

From KeenWiki
Jump to navigation Jump to search

This tutorial aims to teach Keen:Galaxy Source Mod modding. Creating a full source mod requires some basic coding knowledge that this tutorial will not cover; it will explain where and what needs to be coded, but not how.

  • Note: This tutorial was written with Windows users in mind. Linux and MacOS users might need to install WINE in order to run a couple of Microsoft Windows based tools and script/batch files.


Modding Package

Begin by downloading the core Keen:Galaxy Source Modding Package. This bundle contains a source code package with a number of pre-setup tools and files. Make sure to extract all files and keep the pre-defined folder structure.

Modding folder structure setup goes here


You will also need to download the following tools:

Tool Name Usage Description Additional Note
Abiathar Level & Tile Property Editor + Sound & Music Import/Export Version 2.11.4 Beta 1 or higher is required
Borland C++ Compiler Source Code Compiler
DOSBox Emulator for MS-DOS Environments
KeenScr Intro/Outro Graphic Text Editor
IMFCrush Converting & Optimizing IMF music files
MS Paint or GIMP or PhotoShop Drawing Tools One of the simplest tools for modifying Keen graphics is MS Paint. However, only the versions of MS Paint prior to Windows 7 will function with the Keen palette correctly.
TliExtend Tileinfo Extension This tool is a command line based tileinfo extension utility for Abiathar
uGrab Graphics Import/Export
WDC Sound Effect Editor

Editing Graphics and Texts

To begin editing graphics and most texts found in the game, go to the BMP folder. All the image, text, and other files within BMP are arranged in clusters. The following table gives an overview of each cluster.

File Name Description Additional Note
CKS_ansi_*.bin Final screen Appears after quitting the game.
CKS_fon_*.bmp Font sheets These fonts are used throughout the game.
CKS_pic_*.bmp Main menu and help section images
CKS_sprite_*.bmp Sprite images
CKS_sprites.txt Sprite definition text file Hitboxes and offset values are defined for each sprite.
CKS_terminator_* Terminator text sequence Appears at the games first start and leads to the title screen.
CKS_tile8*.bmp Drop-down menu Tilesets These tilesets contain numerous tiles. Each tile has a size of 8x8 pixel.
CKS_tile16*.bmp Fore- and Background-Tileset These tilesets contain numerous tiles. Each tile has a size of 16x16 pixel.
CKS_txt*.txt Text sheets Containing story element texts and help section information.
CKS_txt_STARWARS.txt Scrolling story text The so called Star Wars Story Screen.
CKS_DEMO*.CKS Demo recordings
EGA Color Palette

You can edit any of the images how you want but must follow two rules: you must use the original 16 EGA Keen colours, and all images must have a width that is a multiple of 8 pixels.

Import and Export Files

uGrab in action

To import / export the files located in BMP, use uGrab. uGrab is an advanced EGAGRAPH editor with a graphical user interface which can not only import / export graphics, but can also add, move or remove sprites in Commander Keen source mods.

For uGrab to work, a definition file is required, which is already included within the Source Code Modding bundle.

To begin, open uGrab and go to Import and select Import from bitmap folder.... Locate the gfx.def definition file in your project folder and open it. A dialog pops up that asks you to select the BMP folder. Do so and press OK. uGrab now renders all graphics and text files contained in the BMP folder.

To import these (edited) files into the EGAGRAPH simply go to Export and select Export as EGAGRAPH.... In the following window locate EGAGRAPH.CKS file and press Save. uGrab will then ask you to select a Huffman Compression Type; choose Best (Slowest). It will then ask if you want to update the definition file, which you should confirm.

An alternative to running an instance of uGrab is through batch files. The modding package comes with two batch files which can be used to speed up and automate the import / export process significantly. Simply double-click ugrab_in.bat to import and double-click ugrab_out.bat to export all files. To learn more about how those batch files operate, simply open them with a text editor like notepad.

The number of text and graphics files can be expanded or rearranged in source modding, but this is an advanced task which requires altering some definition files and recompiling the source code. We will focus on advanced tasks like this later.


Snippet of the foreground tilset.

Foreground and background tiles are made up of a 16 by 16 area of pixels. Those tiles are the raw basis to build a level with. It is recommended to create tiles efficiently as the tilesets come with only a limited space. (Albeit it is possible to expand both tileset which will be talked about later.) With a level editor like Abiathar you can then arrange your tiles to create levels.

Advanced graphic editors like GIMP or Photoshop come with a feature that allow placement of a 16 by 16 pixel grid as an overlay for easy editing and layout management which makes working with the tileset much easier.

The screenshot shows parts of the foreground tileset (CKS_tile16m.bmp). Note that the light green background colour is not part of the EGA colour palette. This colour designates areas of the tilset which are to be transparent. Only the foreground tileset can have transparent elements.

You can edit pretty much every tile to your liking and replace both tileset with your own graphics. Note however that the first row of tiles is generally reserved to render certain blocking elements. Those are used for debugging reasons and should stay untouched.

After editing make sure to import your changes by running the uGrab_in.bat script.

Also remember to adjust your tile properties in Abiathar like animation values, or if a tile should be solid like. You can find more information about this in the Tile Properties further down below.


uGrab extracted Keen sprite example

Sprite images are divided into two areas. On the left side you will find an image of the sprite against a transparent background colour. This is where the sprite is drawn. On the right side you can see a red box against a dark grey background. This area is used for hitbox measurement, although it doesn't directly affect hitbox size (the CKS_sprites.txt determines this, see the hitboxes section below).

  • Note: The width of sprite images must always be multiples of 8 pixels.


As mentioned above hitboxes are invisible rectangular areas used for telling a sprite how to interact with the environment or with Keen. For a point item, the hitbox is the area keen must touch to collect the item. For an enemy, it is the area of the enemy that will touch the ground and touch keen. For Keen himself, it's the area he can interact with platforms, enemies, and other objects. When changing the size of a sprite it will affect how it spawns and the 'hitbox' area it uses to interact with the environment and with Keen.

To edit the hitboxes, open CKS_sprites.txt with a text editor.

CKS_sprites.txt file with left facing Keen sprite highlighted

We'll use Keen's left facing standing frame as an example. The image name for this is CKS_sprite_0014.bmp. So in CKS_sprites.txt, look for item 14. It will look like this:

14: [-1, 0, 14, 31], [5, 0], 1

The first set of brackets controls the hitbox. The first set of numbers are x and y coordinates for the top left corner of the image. These are measured from the top left of the image (-1 pixels across and 0 down). The next coordinates are for the bottom right of the hitbox. These are also measured from the top left corner of the image (14 pixels across and 31 down).

  • Note: You need to start counting from 0 (zero).
  • Note: Even though the image is actually 32 pixels high, the hitbox is designed to be 1 pixel away from the bottom. This is important for any sprite that needs to move on a platform.

The second set of brackets are coordinates that have to do with where a sprite image appears in-game relative to where it is placed in the level editor (offset values). In the example of the Keen sprite, these are 5,0. Its usually easiest to leave these at 0,0, but if you use a sprite that changes frame size over the course of its animation, or a sprite intended to float above the ground, you may want to experiment with this. The first value is an X coordinate and will determine how far to the right or left the sprite is placed. The second value is a Y coordinate which determines how far up or down the sprite is placed.

  • Note: If you've modded an enemy and it is stuck in the ground or in the air, you'll want to edit the Y value to bring the hitbox even with the ground.

The last value is not a coordinate but has to do with animation frame rate. Since we are dealing with the source code this value can stay at 1. <explanation of why it can remain at 1>


Keen 4 help section Text, INPUT
Keen 4 help section Text, OUTPUT

Text files can be edited with notepad or a similar application. These files include the help sections, the story, and the end-game story. They employ a formatting code:

Formatting code Description
^P Marks the beginning of a page.
^Gy,x,n Displays a bitmap. The image number n used here doesn't match up with the image numbers in your BMP folder; the image shown is the image number plus seven ((n + 7)). The x,y are coordinates which determine where the image appears on the screen. The ^G command can also use sprites and both types of 16x16 pixel tiles (TILE16 and TILE16M).
^Ly,x Following text will be aligned beginning at pixel location x,y.
^Ty,x,n,t After a delay of t time units (t/100 seconds?), this timestamp displays a bitmap (n + 7) at pixel location x,y on the screen.
^By,x,w,h,c Fills the width-by-height-pixel rectangle at pixel location x,y with dimensions of w,h and the color c. c is the hexadecimal color digit, the rest are decimal digits. If the line ends before the parser can find a hex digit, the code will use the background color (for compatibility with Keen 4-6 texts).
^Mxxx Starts playing music number xxx.
^MOxxx Plays the music track number xxx only once, without repeating.
^MP Pauses the current running music track and allows to resume it later.
^MR Resumes music paused by ^MP.
^Sxxx Plays sound number xxx.
^W Waits until the current sound is done (does not update the screen).
^Dttt Waits ttt tics (screen will be updated)
^Q "quiet" - stops sounds and music.
^H Shows the high scores in any of the help texts.
^E Marks the end of the dialogue.

The specific codes for changing the color of text are:

Formatting code Description
^Cc Changes the text to color c, which is a single hex digit, 0-9 or A-F.
^CA lime text color          
^C2 green text color         
^CB cyan text color          
^C3 dark turquoise text color
^CC red text color           
^C4 red text color           
^CD magenta text color       
^C5 violet red text color    
^CE yellow text color        
^C6 brown text color         
^C9 light blue text color    
^C1 blue text color          
^CF white text color         
^C7 light grey text color    
^C8 grey text color          
^C0 black text color         

Other Texts

Some editable texts, such as level entrance messages, are not found in files within the BMP folder and instead require using a text editor to modify specific source code files located in the ../SOURCE/MAKESTR folder. To edit most text files that appear in game open up the MAKESTR.C file with a text editor. This file contains Level Names, Level Entrance Texts, In-Game Messages and related texts.

After editing these files, the game must be recompiled in order to integrate the changes. Click here to learn more about the compiling process.

Loading Window

TheDraw editing the loading screens.
TheDraw editing the final Keen 4 screen.

Where to find the loading screen file

Go to commander prompt and navigate to your keenscr folder and then type:

keenscr load

TheDraw will immediately start editing the screen, with the filename keenscr.bin.

Alt+H will display the help screen with all the commands that TheDraw supports; however, its basic use is extremely simple. Use the arrow keys or mouse to select where you want to enter text, then type it in. By default, it uses bright white color over black color; you can copy a color straight from the screen by placing the cursor over any character and pressing Alt+U, and it will use that color as you type.

You can use Alt+M to enter drawing mode, where you can use the cursor keys or the mouse to draw on the screen; you should enable Draw mode with the cursor in the place where you want to start drawing, as it will start immediately. Alt+F1 to Alt+F4 will give you different line styles for Draw mode.

Once you are done editing the screen, you can save it by pressing Alt+S. TheDraw will ask which format to save it in; press B to select Binary, and enter the filename keenscr.bin. It's important that you keep this filename (overwriting the existing one). After you exit TheDraw and KeenScr notifies you that the file has been updated.

Then you must copy 4msc0000.bin back into your BMP folder. Import using uGrab. You must also copy ck4load into your modding folder.

You can also edit the exit screen by going to the command prompt and typing: keenscr 4 in the same manner.

Level Editing

Abiathar: Link and tile properties overlays are activated

To create and edit levels we will be using Abiathar. Abiathar comes with a Documentation/Help file which is strongly recommended. It contains advanced information this tutorial cannot match. Fleexy, the author, has uploaded a video tutorial where most of the basic features are examined. To learn how to use this feature rich tool you can also head over to Abiathar's main page.

Setting up Abiathar

To get started open the level editor Abiathar. Go to File and select Open Project. Within your projects folder you should find a dependency file called abiathar.adeps which you want to choose. This is your pre-setup from where you can start building levels.

To storage modifications press Save under File. The level set's settings will be written to an *.adeps file, which only contain references and pointers to the real resources files, but don’t store any level data on their own.

Closing Abiathar for the first time, quite a few settings will get saved to the editor.aconf config file. Those settings are loaded when Abiathar starts.

Once some work has been done on a level set, it is advisable to test them in-game. let's talk about this briefly


Before getting into the specifics of using Abiathar, some general knowledge about how Keen Galaxy levels work is needed.


Keen Galaxy levels consist of three layers of tiles: the background, foreground, and info layers. The background is just there to add color to the scene; Keen and the enemies don't interact with it. The foreground layer contains tiles that Keen interacts with: platforms, point items, doors, secret passages, and so on (note that many tiles in the foreground layer actually appear behind Keen, but they are not considered 'background tiles'). Finally, the info layer contains information about sprites and special features such as switches, doors, bridges and the like. When level editing, you will generally work with only one layer at a time, although all three may be visible at once (layers can be toggled).

Word about memory usage each layer eats up

Word about making tile properties visible and editing them: press "B" on your keyboard

Level borders

Keen Galaxy levels have a rectangular border of 2 tiles. Borders should be filled with solid tiles with some exceptions. To create a level exit, leave the border empty where you want Keen to exit. By default Keen cannot exit out the top or bottom of the screen (Keen will die on the screen bottom and Keen will glitch on the screen top).

General Level Editing Issues

If there are too many sprites in a level you will get the error No space left in objarray; the game has run out of memory to store sprites. This usually occurs at the level start. To fix this, remove sprites from your level. When placing sprites, keep in mind that the more variety of enemies you use, the more memory is used up, and the larger the sprite and the more frames it has, the more memory it uses. Also, when trying to save memory, check your points items: these exist both as tiles and sprites (try to use tile points whenever possible).

Word about how many unique sprites the source code can handle. F10+C

If you have too many different types of tiles (background and foreground) then you will get the error No space left in tilearray; this means that the game does not have enough memory to store all the different tile types. Foreground tiles use 8x the memory of background tiles. You shouldn't have more than about 400 tile types total (background and foreground) in a level, usually 100 back and 300 fore. Additionally, animating tiles with many frames can increase your tile count drastically.

Word about how many unique tiles the source code actually can handle as this got improved over time.

You cannot have more than 20 actively animating tiles on-screen at any one time, this includes item tiles. This will cause an animating tile error. (Not enough memory to animate all these tiles.)

check this info as well

If a level is 'too large' for its music file, the error Not enough memory to play background music! will occur. This is an indication of either large levels or large music files. To reduce this error, either make your level smaller or change the music to a smaller file.

max music size is 64kb

If you see static gibberish instead of an animation while testing your level, then you have placed an animating background over an animating foreground. For memory reasons this is not allowed. Similarly, a sprite cannot be placed on top of an animating tile. NOPE? This will crash the game.

  • Note: All of these problems and more can be detected by Abiathar when using it's Level Inspector tool or the inspection mode (press 'I') of the Tile Property Modifier. It also provides exact points in the level where errors and possible issues appear so that you do not have to launch the game repeatedly to fix bugs.

Note about in level memory check feature

Special Tasks

Sprites and Enemies

You can place sprites like you would normally place a tile. Some enemies appear more than once in the sprite menu; this is for enemies that appear on easy, moderate, and hard. You can see little numbers that designate this, but a general rule is that the order they appear in on the menu matches the easy/medium/harder order.


Secret Passages

Some foreground tiles have properties that allow Keen to walk behind them; these are secret passages. To make these you will need to identify which tiles have the correct foreground but not blocking properties. You can identify them with the Tile Property Modifier tool in the Tool menu. When putting point items in a secret passage, you must use such from the sprite list rather than the foreground tile points.

Moving Platforms

A simple moving platform in Keen 4 can be placed by putting a moving platform sprite icon with a red arrow in the desired spot. To stop the platform moving off the edge of the screen however, you'll need to put some blocking tiles in its path: these icons look like a B in a square. Put one blocking tile to each side (for a horizontally-moving platform) or above and below (for a vertically-moving platform). A falling platform (the one with a yellow triangle below) only needs a single blocking tile beneath it. In Keen 5 and Keen 6, the platforms with green arrows (known as Goplats) need a path made of the yellow arrow icons to follow.

Switches for goplats

Often you want the player to have to turn a platform on with a switch. To do this you will need to place another blocking tile in the way of the platform between the other two. After placing the blocking tile, press L and K on your keyboard. This activates the linker tool. Make also sure that only the Infoplane is active. Next click on the switch tile first and second on the blocking tile. Abiathar will render the links as lines from the controller to the target.

Switches for bridges

To create a switch for bridges, first build the bridge using the bridge tiles and place the switch tiles somewhere (near). Then press L and K on your keyboard. This activates the linker tool. Make also sure that only the Infoplane is active. Next click on the switch tile first and second on the top left most bridge tile. Abiathar will render the links as lines from the controller to the target. If you want the bridge to begin already opened, you will need to locate the invisible bridge tiles and place these where the bridge will be located, otherwise no bridge will appear. To find these either locate them in existing levels with open bridges or use the Tile Property Modifier tool in the Tool menu.

Key Gem Doors

To place a keygem holder, first place the foreground keygem holder tile somewhere on the map (it can be anywhere). Next place a door (these are also foreground tiles) somewhere (anywhere). When making the door, there are three door tiles: a bottom, middle, and top. If you're making a door more than three tiles high, use the middle door piece for additional height. Then press L and K on your keyboard. This activates the linker tool. Make also sure that only the Infoplane is active. Next click on the switch tile first and second on the topmost door tile. Abiathar will render the links as lines from the controller to the target.


To place doors that Keen can enter, first place two sets of door tiles on the map. Then press L and K on your keyboard. This activates the linker tool. Make also sure that only the Infoplane is active. Next click on the bottom tile of the first door and after that click on one tile below the second door. Repeat this step vice versa. Abiathar will render the links as lines from the controller to the target. I suggest examining some of the original levels to get an idea how this is done.

Scroll Blocks

Some Keen levels have separate areas that act like independent mini-levels (the Pyramid of the Forbidden is a good example of this). You can place scroll blocks from the sprite menu to mark horizontal and vertical edges between these areas. The scroll blocks look like horizontal and vertical blue lines with small white stripes; I suggest examining existing levels to see how they are used before placing them in your own levels.

Music and Sounds

Using Abiathar to import/export music and sounds

Adding Music and Sounds using Abiathar to add additional music and sounds + source code editing to integrate these

Creating and Editing Sound Effects

create a pre-defined setup that can be downloaded as well to shortcut things and bypass source code incompatibilities WDC has!

Begin by installing WDC to your tools folder. Once this is complete, open up X

go to the new WDC folder and create three new folders inside: "Keen4input", "Keen4output", and "KeenSounds". You should then copy a clean version of Keen 4 into the "Keen4input" folder, specfically the files: Audio.ck4, Egagraph.ck4, Gamemaps.ck4, and Keen4e.exe.

  • Note: Make sure this version of the keen4e.exe has NOT been unlzexed.

Now run WDC.exe. After is loads, go to File then New Project. WDC will then ask you to name the project and save the project file; name it "keen4project" and save it to you WDC folder.

WDC will then bring up a window with several options. Under Base Data Folder select your folder "keen4input". You will then get a no map code file alert. When this occurs, select User Other and then select blank.wmc. Under Output Folder select your folder "keen4output". On the left side you will see a small menu, select Other Options and then check the box for Use Tile16s for maps, if they exist. Press OK to save your project settings.

You should now see the Keen 4 world map. You'll be using only one part of WDC, however, so go to View and select either PC Sounds or Adlib Sounds.

WDC will then load the list of sounds for that category. You can sample each sound by clicking it. Playback controls are located in the upper right. To edit a sound, click the small hammer icon in the lower right. WDC will then ask you where you want to save the file. Navigate to your "keensounds" folder. Name the sound in such a way that you can remember what it is: "slugslime", "jump", "item" etc.

WDC will then load it's sound editor. There are various tabs for effecting how the sound is played, and the main area allows you to use your mouse and 'draw' the sound. Sound editing is a complex task and the only real advice I can offer is to just play around in the editor and save sounds that you find good or interesting.

After you've saved some sounds, you'll want to swap these into your mod. To do so you'll first need to locate the original sound file you want to replace in the sounds folder you created when setting up Keenwave. You can do this by listening and finding the sound you want to replace in WDC and then locating the corresponding number in the sounds folder. This is easy for PC speaker sounds, but since Keenwave doesn't separate the PC speaker sounds from the adlib, you'll have to locate the last PC Speaker sound and then begin counting again from 1 in order to match the adlib sound list in WDC to that in your sounds folder.

When you've located the original sound you want to swap out, copy it's name to your new sound and then replace the file. Then run Keenwave to import your new sound effect.


Converting Midis

In IMFCreator, go to the options menu and set the tics/sec to 560. This will make your songs convert at the correct tempo.

Using IMFCrush and the KMF format advantages

Composing Music =

Compose your music using your choice of software. As long as it outputs standard General MIDI files, you should be good to go.

Please read and get an understanding of the IMF specs.

  • Note if you are using a sheet-music editor such as Finale: You may write two or more parts for one instrument. Keep inside the required 4-note polyphony, but don't be shy about using layered parts and chords, especially on piano staves.
  • Note IMFCreator seems to interpret MIDI note velocities. If your instrument track is too quiet and it is set to maximum volume, try manually adjusting the note velocites to be higher. I know that FLStudio is capable of doing this; I'm sure other studio software packages are capable of this, too. If the volume of the track is too loud after making your note velocities higher, turn down the volume of that track.
  • Note Keep percussion parts as simple as possible. It impedes the maximum polyphony limits that can be utilized by other parts. Simply put, you can write more complex parts that use this structure:

The number of dropped notes, if any, in IMFCreater is almost unnoticeable if you adhere to this formula. I've been able to push the IMF format to it's limits by doing this.

Don't be shy about using chords and complex structures -- especially if your percussion line is nonexistent or very simple.

(3) Try not to use too many midi tracks, especially if they are all simultaneous. Too many midi tracks results in dropped notes (ie- parts drop out randomly and inconsistently), and songs that exceed the filesize limits. I personally only need 4-8 tracks, counting percussion, to archive the sound that I get in my work.

(4) On the subject of percussion: To circumvent the polyphony limit that gets imposed when you use percussion parts, try using normal instruments played outside their normal range. Then in IMFCreator, tweak the patches you used by adjusting all the possible paramaters until you archive the desired percussive sound. It may not work all the time, but it should do the trick in most cases. (Credit for this tip goes to Bobby Prince)

(5) On the topic of modding instrument patches: Don't be afraid to tweak patches! It's under the EDIT, Instrument (or press CTRL+I) menu. You can edit how all the instruments sound (including percussions). Distortion guitar not distorted enough? No problem. Pad not airy enough for you? Bass drum not punchy enough, or the hi-hat not sharp enough for you? No problems there. See the help menus for the specifics of how the patch parameters are edited.

When I do this, I make a patch set for each specific song. When you close the instrument editor, you are prompted to save changes. Do so, and save the .OP2 file that is generated as something other than GENMIDI.OP2 (I like to save it by song title for easy reference). Keep the original GENMIDI.OP2 file as a base set.

After you've tweaked the patches to your liking and saved your new .OP2 file, stop any playback of the song you're previewing. Under OPTIONS and OP2 File you can choose the OP2 file that has the modded patches you created. Press play and listen to your new instruments!

  • Note: After editing an .OP2 file/patch set, you MUST stop and re-start playback of your song for the changes to take effect

(6) Be careful with pitchbends in your music. IMFCreator tends to over exaggerate them if the pitchbend scale and thresholds are not set properly. There is no ONE configuration for them; best bet is to tinker with them until you get a desirable sound. Remember: Lower numbers mean higher pitchbend scale!

As with editing the patch set, you MUST stop and re-start playback of your song for the changes to take effect.

Compiling the Source Code

Introduction into Borland C++ v.3.1