1. About Dave GNUkem
2. Credits
3. License
4. Requirements
5. Installation
6. Playing the game
7. The level editor
1. Sprites
2. Creating new levels
3. Editing levels
4. Mission packs
8. Tips and comments
9. Fullscreen mode
10. Compiling the sourcecode

About Dave GNUkem

Dave Gnukem is a 2D scrolling platform shoot-em-up. It is very similar to (and inspired by) Duke Nukem 1. The main character has been "borrowed" from DN1, perhaps temporarily.

This started out as an exercise for me in learning C/C++, back in 1995, using DOS and EGA graphics. It has now been converted to run on Linux, using GGI for the graphics library. It is playable, but still in development.

The game is OpenSource - contributions of levels, code, and especially ideas are all more than welcome! (And probably necessary if this thing is ever going to get finished ..)

Credits

• David Joffe - Coding, sprites, levels.
• Felix Richter - Documentation contributions.
• Steve Merrifield - Level contribution.

License

This software is Copyright (C) 1998,1999 by David Joffe. There is ABSOLUTELY NO WARRANTY for this product. This software is distributed under the terms of the GNU General Public License. Please read the file COPYING in the distribution for details, or visit www.gnu.org.

Requirements

• Linux: Dave Gnukem was developed and tested under Linux (RedHat in particular), although in theory it should also run on other UNIX platforms. See http://www.linux.org/.
• GGI: Dave Gnukem uses GGI (General Graphics Interface) for graphics. GGI is roughly analogous to DirectX in the Windows world. See http://www.ggi-project.org/ for obtaining GGI, or some further information and tips on GGI here at ggi-en.html.
• Hardware: I don't know what the minimum requirement is. I would *guess* a lower-range Pentium or higher-range 486, depending on what color depth you run in. I'm developing on a Pentium 120 with a somewhat flaky 2MB S3 Trio64V+ graphics card.

Installation

Dave Gnukem is distributed as a "tarball" (a .tar.gz archive) of the sources and precompiled executables. Sorry, no package formats (such as rpm or deb) yet.

Unpacking the tarball: If you are using Midnight Commander, you can just hit "enter" on the file. You can also unzip it with KDE's "kzip" utility, and probably with GNOME's "guitar". Real men, however, use the command line:

$ tar -xvzf djg0.43.tar.gz

Change to the subdirectory created, g/src. There you will find two executables:

djg - the game
ed - the sprite and level editor

To run the game from the commandline, type

$ ./djg

(For now, the game must be run from the g/src directory, because of where it looks for data files.)

If there are errors, and you have installed GGI, you may need to recompile the source code. See the relevant section of the documentation.

Other files:

HISTORY - Program changelog
TODO - Project TODO/buglist
FILEFORMATS - Documentation of game file formats
COPYING - GNU General Public License

The game

Keys:

Arrow left/right	Move hero
Arrow up	Action key (open doors, activate teleporters etc)
Ctrl or P	Jump
Alt	Shoot
Arrow up + L	Cheat - next level
Escape	Bring up game menu

The level editor

Important note: The format for levels and sprites does sometimes change between releases of the game. Do not worry - just send me any levels or sprites you created with any particular version, tell me what version you created it with, and I'll convert it and send you the converted files.

The level editor ed allows for editing of levels and sprites, and has two modes for these tasks, level edit mode and sprite edit mode. The two modes can be switched between with F4 and F5. The editor starts up in sprite edit mode.

Each game level consists of a 128x100 2D grid of cells. These cells are filled with sprites. The grid contains 2 layers of sprites. The first layer is the "background layer", and on this you place background stuff like walls, floors etc. The second layer (the "foreground layer") is superimposed on top of the background layer, and on it you place things with special functions: doors, keys, monsters, food, etc.

The sprites are divided into "sprite sets"; each set contains 128 sprites. From version 0.43, there can be up to 256 different sprite sets, and each sprite set used in a level must be given a unique number from 0 to 255 (see section on mission packs.) The first 16 (0 to 15) will be the game's default sprite set. Any sprite sets you create additionally should be numbered from 16 up.

NB: The Escape key acts as a "quick exit" to the editor. No saving, no questions asked. Be careful with it.

The F1 will save all sprite sets when in sprite edit mode, and will save all levels when in level edit mode. You must save your changes before you press Escape if you do not wish to lose them.

Draw/edit sprites

Each sprite contains various attributes describing it's purpose. There is a "type" attribute, and 12 extra numerical attributes (0 to 11), which I have called "extras". There is also a "color" attribute, which is not used in the game, but which is used in the level editor to display sprites placed on the large grid.

• Choosing sprite set: Cycle through sprite sets with M and N.
• Choosing sprites: Use the arrow keys or the mouse to select the current sprite.
• Drawing sprites: You can choose two drawing colors (left mouse button and right mouse button) from the 16x16 palette of colors in the top right of the screen. These can be placed on the main 16x16 grid with left and right mouse buttons.
• Transparency: The last color of the palette, number 255, is treated as a transparent color.
• Sprite attributes:
  • Sprite type: This can be selected by clicking on the desired type in the list.
  • Sprite color: Use left/right mouse button to choose a sprites color by clicking in the block underneath and to the right of the color palette.
  • Sprite extras: To change the numerical values of the 12 extras, use left mouse button to decrement a value, and right mouse button to increment a value. [FIXME: describe meanings of values] The fifth extra value, number 4, is used for sprite flags, describe next.
  • Sprite flags: The sprite flags can be set by crossing/uncrossing fields in the lower left of the screen with the mouse. They are:
    • SOLID - makes this sprite solid.
    • ANIMATED - animated object, belongs together with next 3 sprites
    • FALLS - object will fall down from above when hero arrives
    • COLLECTABLE - hero can pick it up
    • INVENTORY - object will be stored in "Inventory"
• Remember, no changes will be written unless you press "F1"!

To switch into level edit mode, press F5.

Create levels

To create an "empty" level file, change to the g/data directory and copy the file template.lev to a new file, eg spaceship.lev. You must add an entry for this level in your mission file (see section on mission packs.)

Change levels

• Cycle through existing level files using  Ctrl+M or Ctrl+N. The level filename will show up, and there will be a magnified view (1:1) of the current selection.
• The magnified portion of the level that is shown on the top right of the screen can be selected either by using the arrow keys, or with Alt+LeftMouseClick in the level overview on the left.
• Still use M and N to cycle through sprite sets.
• You can choose two sprites to draw with, using left mouse button and right mouse button. You can click in both the overview area and the magnified view to place sprites.
• By default, you will be drawing on the background layer. Use X to switch to and from editting on the foreground layer.
• No changes will be written unless you press "F1"!
• Some sprites (usually placed on the foreground) are special; they will never appear as is in the actual game. Rather, they are just used to mark the positions of real objects in the game.
1. Positioners:
• The yellow stick man will act as hero's starting position, the arrow indicates the direction he will be facing when he starts. Only place one of these! If you place more than one, the bottom-most one in the level will be used.
• The purple stick men will be replaced by real monsters. The small number next to the stick men indicate which type of monster is placed. Do not place the sprite for the actual monster graphics - they will appear in the game but do nothing at all.
• There is a blue "EXIT" in the first sprite set. Use this one to mark the level's exit. It will automatically be replaced by a more decorative graphic in the game. Do not place the decorative version in the level.
• To set teleporters, use the "T" sprites with a number. There is more than one teleporter, and each is numbered. There must be exactly two teleporters of the same number in one level!
2. Object types:

Here are some examples of how the sprite "type" attribute is used:
• LookAtHero:Arrow (Camera), turns to face hero
• Conv left/right:left, right conveyor belts
• Key, DoorActivator, Door:keys, keyholes, doors. Note that each key, door etc is numbered (extra[0]). So door no 2 goes with key no 2 and dooractivator no 2.
• HeroStart:Hero's starting position
• TYPE_BOX An object of type BOX can contain (optionally) other sprites. These sprites can be any valid sprite that you place in the level, including other boxes :) When you shoot the original box, a new object is spawned, based on the values in extras[10] and extras[11]. Extras[10] is the spriteset of the new sprite, and extras[11] is the sprite index. Use 0,0 for an empty box. The boxes currently contain the following: RED(coke,apple,banana); BLUE(); GRAY(emptybox,G,N,U,K,E,M)
• TYPE_LETTER There are six letters. These SHOULD be placed using the gray boxes that contain them. Traditionally the hero must collect these letters in the correct order to get some bonus points. Extras[11] contain the sprite number, as a zero-based offset into the word GNUKEM.
• Animated objects consist of 4 sprites. E.g. use the first of four sprites to set a door. It is marked as ANIMATED - the next three following the one marked as ANIMATED will then automatically be used for animation. Similar situation for LookAtHero: You have to set the middle sprite of the three for LookAtHero as LookAtHero type. The others are nothing but images inserted automatically while playing the game.

---

Tips and comments

• I suggest you design your levels on paper first. PLAN YOUR LEVELS!
• To draw a long straight line of something in the editor (at least until I write decent fill functions), hold down mouse on real-size view and then hold down an arrow key. There is also now a horizontal fill which NB NB only fills on the background.
• Some things only work when on the foreground layer. Some of these are meant to be that way but some are bugs; eg the (Mac) Apple is meant to work on the background but doesn't.
• Powerboots: When you design your levels, *know in advance* whether or not our hero already has the powerboots. He keeps them from level to level. Typically he will pick them up midway through a game.
• You should never allow the hero to get close enough to the edges for edge scrolling to stop (nothing bad will happen if you do, but you should avoid it if possible. The scrolling behaviour becomes "odd" near the edges.) See the "test" level for how close you can get to the top of the level (without power boots) - those pieces of ground are at the highest they can be without any behaviour that would be unusual for the player. This may change later if I increase the size of the viewport again, so try give yourself reasonable space at the edges.
• The hero can jump (normally; without power boots) 3 blocks high (4 with power boots). Make sure you have a good feel for how he jumps, before you "jump" in and make levels.
• Send me your levels!! I will pick the best ones for the "actual game" (by vote perhaps?), but also include the rest for people to play. Credit will always be given to the designers of the levels.
• Yes the editor sort of sucks. That's what the source code is for ;)

Mission packs

Sets of levels and sprites can now be grouped together into "missions".

Each mission is described in a .gam file in the data directory. The list of missions available to the game is in the file g/data/games. So to create a mission pack, create a .gam file (perhaps by doing a "cp g/data/default.gam g/data/spaceship.gam") and then add the line spaceship.gam to g/data/games.

Look at g/data/default.gam to get an idea for the layout of a mission file. Each mission pack has a name (one line) and a description (multiple lines.) Then there is a list of levels, then there is a list of spritesets.

Each level in the list of levels is formatted like this:
filename.lev,Name Of Level,Author Name

Each spriteset in the list of spritesets is formatted like this:
IDNUMBER,filename.spr,filenamespr.dat,Name of spriteset

filename.spr contains the actual sprite images. filenamespr.dat is a file containing the attributes associated with sprites (sprite type, extras, color etc.)

The IDNUMBER is a number from 0 to 255. It is important to understand how this is used. The first 16 (ID's 0 to 15) are "reserved" by the actual game. Currently, only the first 8 are actually used (0 to 7) and 8 to 15 are reserved for future use, so we'll ignore spritesets 8 to 15 for now.

NB: The first 8 spritesets, with ID's 0 to 7, must still be defined in your mission file! If you do not, the game will probably crash. Typically, you will use the supplied default 8 sprite files to define spritsets 0 to 7; that is, def0.spr,def0spr.dat etc. See default.gam and foo.gam for examples of this. Your first 8 spritesets will probably look like this then:

0,def0.spr,def0spr.dat,General
1,def1.spr,def1spr.dat,General
2,def2.spr,def2spr.dat
3,def3.spr,def3spr.dat
4,def4.spr,def4spr.dat,Hero graphics
5,def5.spr,def5spr.dat,Bullets etc
6,def6.spr,def6spr.dat,monsters
7,def7.spr,def7spr.dat,monsters


Advanced: For ID's 0 to 7, you do not strictly have to use the supplied sprite files (defN.spr etc). However, the game references sprites in these sets explicitly by ID number and offset, meaning that if you change them, the game will still try draw certain things (like exits and teleporters) from where it expects them to be in the spritesets. Thus, you will be able to change the appearance of (say) exits and monsters in your supplied spritesets, but you will never be able to change where the exit is located in the spritesets.

If all this has confused you, then don't worry. Just copy the 8 lines above, as is, into your list of spritesets and then never worry about it again.

Once you have set the "default" spritesets, and you wish to create more sprites not supplied with the game, you can start adding your own from 16, eg:

16,mine.spr,minespr.dat,My sprites
62,ocean.spr,ocean.dat,Ocean sprites
~

Note that your own spritesets are added from 16 onwards. Also note that each section ends with a "~".

It is important to note that the ID number is used in the level files. Thus, if you later on change the ID numbers, the ID numbers in the level files will point to the wrong spritesets (or none at all.) So, once you have decided that (for example) your spriteset for the spaceship graphics is ID 25, stick with 25.

All of the above should be telling you: planning is important!

Later on, I may make it possible to use pcx format for the sprites, if people want that.

Fullscreen mode

There are two ways to increase the size of the window in X: double-size window mode, and full-screen mode.

Running the game "./djg -d" will give you double-size mode. I hope you have a fast computer. This is really a fall-back for people who can't get fullscreen mode to work.

Running the game "./djg -f" will give you fullscreen mode. However:

• Fullscreen mode uses the X DGA extension. This requires you to be root. Running the included script "./fullscreen" will handle setting this up for you.
• For the DGA extension to work, it seems you need a 320x200 modeline set up for your X setup in your "Screen" section. You may need to edit /etc/X11/XF86Config to get this to work.

There is an alternative way to use fullscreen mode, without using "-f" or the fullscreen script. GGI can be instructed to use DGA by default, by exporting an environment variable:

$ export GGI_DISPLAY="dga"

Lastly, when DGA sets the screen mode, it seems to maintain a normal-size virtual screen, and just draw in the top left 320x200 of the screen. You may need to use the mouse to scroll to the top left of the screen.

Compiling the sourcecode

Change to the directory g/src.

Edit the Makefile if you want/need to make changes to the setup.

Make options:

make - compile the game, djg
make ed - compile the editor, ed
make fixme - display list of FIXME's in the code.
make linecount - count the number of lines of code :)
make clean - remove binaries, object files etc.
make dist - same as clean, except doesn't remove binaries.

Speed optimizing: If you want/need to coax a bit of extra speed out of Dave Gnukem, you can do a couple of things. In the Makefile:

• Remove "-DDEBUG" from CFLAGS.
• Add "-O" to CFLAGS to enable optimizations.
• Add "-m486" to CFLAGS to enable 486-specific optimizations. (-m586?)

This should get you between 5 and 20 % speed improvement.