Keen Game Engine Files

------KEEN GAME ENGINE 4-------
        VERSION 0.1
        ---BETA---

Congratulations! You are now the proud owner of a
(free) copy of Keen Game Engine 4, an open-source
game engine for DOS.

KGE is meant to be an engine in the style of the early
PC games of the 1990's, such as Commander Keen (the
game's namesake). It's meant to be a super easy to
use engine for making simple and fun PC games!

What's more, it was programmed in Microsoft QuickBasic
(yes, I know, that's weird). I used the excellent
DirectQB library, plus a midi library, to get all of
the enhanced graphics and sound features necessary.

KGE runs in VGA 320x200 256-color mode, making it
super-versatile for all your graphics needs.

---System Requirements---

        (for a retro PC :-D )
   -486DX/50 or newer (Pentium/100 recommended)
   -VGA compatible video card
   -MS-DOS 5.0 or newer with EMM386 or equivalent expanded memory manager
   -2 MB of hard drive space
   -600K of conventional memory (not exactly sure about this...)
   -300K of EMS memory (not exactly sure about this either but you DO need EMS memory)
   -A Sound Blaster/OPL3 (NOT OPL2) compatible sound card would be nice, too...

        (for a newer PC)
   -Pentium 4 1.4 GHz or newer (P4 1.8 GHz recommended)
   -DOSBox 0.74 (configured with the settings provided in KGE's dosbox.conf)


---Playing the demo---

If you run the KGE4.BAT file (or if you're in Windows, run DOSBox to start the game), 
this starts the engine and plays the default demo game.
Here are the key controls:
        Arrow keys - walk around, scroll screen up/down
        Ctrl - jump
        Space - shoot
Have fun with the demo and get to know the engine, how it works, and the physics
of it. It's really quite fun!


---Editing the Source Code---

This game was programmed with a special version of DirectQB 1.71 which I combined with a MIDI library.
The library is called "DQBX" and is included with the game.
To edit the source code, just run QB45 with the command
	QB /L:DQBX.QLB /AH
and open the .bas file.

---What's in the box?---



ENGINE.EXE - the actual game. You should never have to run this (unless you
don't have a Sound Blaster card), just run KGE.BAT to play the game.
       
TED.EXE - the level editor. Here are the commands:
        Move mouse - navigate level
        Left-click - place tile in foreground
        "B" key - place tile in background at current mouse position
        Right-click - remove tiles from both foreground and background
        "C" key - clear entire level (yes, it asks for confirmation)
        "E" key - place an enemy at current mouse position
        Alt+S - save the level
        ESC - end the program (without saving, so you'd better save first)
If you want to create a new level, copy one of the existing levels to a new one.
Example: If you have three levels and you want to create a fourth one, type
this command at the DOS prompt:
	COPY LEVEL3.DAT LEVEL4.DAT
And you're good to go.

KS.EXE (in the main folder and the GRAPHICS folder) - the graphics editor.
This is the best sprite/tile graphics editor you will ever find. Ever. OK,
well, maybe that's a little embellishment, but it is really nice. And super
user friendly - all of the controls are with the mouse so I don't even have
to list any key commands!

MAKEEGA.EXE - This program combines all of the graphics in the GRAPHICS folder
into files in the main folder that the game engine can actually use. When
you start MakeEGA, it gives you a screen where you can organize the tiles
in your tileset by clicking on them and replacing other tiles with the one
you clicked on. This means you never have to worry about trying to find a
tile in TED, you can have them all organized exactly the way you want.
After you're done organizing your tiles, press the ESC key to have MakeEGA
build the graphics files.




---The Files---

GRAPHICS folder - Here the development graphics files are stored.
What are they? Let's take a look:
        -1CHRnnnn.EGA: Character files. (example: 1CHR0012.EGA)
        -xENMnnnn.EGA: Enemy files. (example: 2ENM0009.EGA)
        -TILEnnnn.EGA: Tiles. (example: TILE0015.EGA)
Information about which frames are which (for example, the "Jump" frame
for the character is 1CHR0006.EGA) are stored in the PLYRSPRT.TXT file.

LEVELS folder - Here the levels are stored. The only thing you can do with
these is change the music for each level - open the LEVELn.DAT file and change
the second line to whatever MIDI file in the MUSIC folder you want to be used
for that level.

MUSIC folder - Here the music files are stored. They are all standard MIDI
files, you can use whatever you want.

SOUNDS folder - Here the sound effects are stored. If you want to create your
own sound effects, you have to use Audacity and save them as raw 22050 Hz
8-bit WAV files.

The Main Folder - Here the executables and main graphics files are stored.
MakeEGA puts the main graphics files here after stuffing them into the
TILES.EGA, CHAR.EGA, and ENEMY.EGA files. Also here are the following
graphics files:
        -BACKn.EGA - Background files for the various levels.
                     These need to be 32x40 to work properly.
                     They are tiled over the entire background
                     for each level. These are editable with KS.
        -BACKM.EGA - Background file for the menu screen. Editable
                     with KS.
        -SHOTPIC.EGA - File for the shots that come out of the
                       player's gun. Editable with KS.
        -TILES.EGA - Main tileset file. Not editable with KS.
        -CHAR.EGA - Main character file. Not editable with KS.
        -ENEMY.EGA - Main enemies file. Not editable with KS.
        -HITECH.FNT - Font file the game uses. Not necessary
                      but makes it look a lot cooler.
        -SAVED.GAM - Saved game. Only one saved game supported for now...
        -SBMIDI.EXE - Creative's MIDI driver for the OPL3 chip.
                      Run automatically by KGE4.BAT, and required
                      for music to work.


Well, that's probably all you need to know! Happy game creating!


---Known Bugs---

If you notice one of these bugs, do NOT email or message me.
Since it is in this list, I already know about it and am working
on fixing it.

-Once in a while you will get a "Subscript out of range" error and
 the system will lock up. Don't worry, just restart and it will work
 fine, unless it doesn't... This error is very elusive, and is partially
 related to memory. Sometimes it happens when you have too many enemies
 in one level, inexplicably. Probably because my variables are dynamic
 and you're adding too much to the enemy graphics array... I'll work on
 reducing the memory usage and this problem should go away.



---Limitations of the engine, which I will probably fix
        when the need arises---

-Maximum of 9 levels (just because of the way I load them - I'll fix this)
-Only 30 shots at one time can be in the air
-The levels are limited to 100x100 tiles - a lot bigger than you think it is.
-The memory bug I mentioned above
-Backgrounds - this is the least feature-rich part of the engine; only
 32x40 tiled backgrounds are supported. If I can get a program working
 which will convert BMP to EGA files I can fix this. So far it's been a
 royal pain, mostly because of palette problems.
-The music engine only works with the OPL3 chip. If you try it with
 OPL2 it doesn't sound, and with dual OPL2 only the drumset works.

---CHANGELOG---


Version 0.1 - The first major release of this thing. Hopefully most of the
              very serious engine flaws and bugs are ironed out, although
              anyone who beta-tests this will probably find 10 more...