Introduction

1. What about duke3d.grp?
2. Why Won’t This Work For v1.3d?
3. How Do I Create the Group File With kgroup?
4. How Do I Extract From a Group File With kextract?
5. Are There Easier-to-Use Programs for Making Group Files?
6. How Do I Load duke3d.exe With a Custom Group File?
7. What Files Can I Use In a Group File?
8. How Can I Easily Package My Group and Con Files With a Startup Batch File?
9. Does My Group File Have to Use the .grp Extension?
10. What Is The File Format For A Group File?
11. Where can I get the source code for kgroup and kextract?

This document applies to 3D Realms’ Duke Nukem 3D. Some information will be relevant to other Build Engine games as well.
N.B. some .grp files use .dat as there extension.

A group file can be used to store a collection of game data, such as art, sounds, or maps, so that the user can easily run a usermap or mod for Duke Nukem 3d v1.4+ without cluttering the game directory. It also prevents conflict with other usermaps and mods that may use different art and sounds. It is fairly easy to organize a collection of user files into a .grp file for easy file management.

Duke3d.grp is the main group file. It contains all the art, sounds, music, animations, etc. for Duke Nukem 3D. It also contains backup copies of the default con files. Duke3d.exe will first look in duke3d.grp for files, then at any selected user group file, and finally it will look in the directory for loose files. In v1.4+, a user group file will override files of the same name in duke3d.grp, and loose files in the directory will always override duke3d.grp and any user group file in all versions of Duke Nukem 3D.

In v1.3d, duke3d.exe will use a user .grp instead of duke3d.grp. This means that anything in duke3d.grp that is used in your map will not be accessible in a user group file.

The safest way to create a user group file is to copy all of the files you want to add to the group file to a new directory. Copy kgroup.exe to this directory as well. In DOS, go to the folder you copied these files to. Type kgroup [groupfilename].grp *.*

You can specify specific files or types of files rather than using the *.* wildcards. If you wish to add only art files and midi files, type kgroup [groupfilename].grp *.art *.mid. Or if you wanted only specific art tiles, you could type kgroup [groupfilename].grp tiles014.art tiles015.art tiles016.art.

Note that files cannot be added to a pre-existing group file with kgroup. If you try to add to add a single file to a group file using kgroup, you will overwrite the previous contents of the file.

Make sure kextract.exe is in the same folder with the group file you wish to extract from. In DOS, go to this folder and type kextract [groupfilename].grp [filename], where filename is the file or files you wish to extract, similar to the procedure for using kgroup.

Two other programs that can be used to create group files are OpenGL Build Touch and Group File Studio. See the OGLBT and GFS downloads in RTCM's Download Section, for more information.

You load group files from the command line. Go to the DOS prompt, go to your Duke3d folder, and type duke3d /gfilename.grp (replace filename.grp with the name of your user group file).

Duke3d.exe can read almost any file type from your user group file. It can’t, however, read con files from the group file. If you are using custom con files, they must be loose in the directory. Note: there are no restrictions about what kind of files can be stored in the group file, only which can be read by duke3d.exe.

If your TC features new art, sounds, music, and con files, you can shrink your entire mod into as few as three files. These are your main con file, your group file, and a batch file to launch it.

Batch files, for this purpose, are simple to make. If you can type a line of text in DOS edit and save it, you can make a batch file. A simple batch file is like a text file that stores the text that you would type at the command line. Since duke3d.exe uses flags to load user-cons and group files, it can be tedious to make the user type it out each time. By typing the name of the batch file, it will execute the text inside as if the user had typed it out completely.

Presuming you want to make things easy on the user, you should give all of your project’s files the same name.  If your project is called “TC,” for example, name your con file tc.con, your group file tc.grp, and your batch file tc.bat.  The user will be able to immediately identify which files belong to your mod, and they will be able to start your mod simply by typing “tc” at the command prompt or double-clicking the tc.bat file in windows.

To make the batch file, go to your Duke3d directory in DOS. At the command prompt, type edit. The DOS Edit program will open. Now type duke3d /xTC.CON /gTC.GRP (substituting “TC” for your projects’ files’ names). Then select the “file” menu and choose “save as.” Type a name for your batch file, making sure it has a .bat extension (tc.bat, for example).

No. As long as you type out the full 11 character file name in the command line or in your batch file, it will load with another extension. This was done in at least 2 official Build Engine projects, the Powerslave/Exhumed/1999 game and the “Platoon Leader TC” for World War II GI.

Ken Silverman answers this question in his Build Engine Page:

“The ‘.grp’ file format is just a collection of a lot of files stored into 1 big one. I tried to make the format as simple as possible: The first 12 bytes contains my name, ‘KenSilverman’. The next 4 bytes is the number of files that were compacted into the group file. Then for each file, there is a 16 byte structure, where the first 12 bytes are the filename, and the last 4 bytes are the file's size. The rest of the group file is just the raw data packed one after the other in the same order as the list of files.”

The source for these utilities are available with the Build Engine source code, which can be downloaded at Ken Silverman’s Build Source Code Page: http://www.advsys.net/ken/buildsrc/default.htm.

Document by: Matthew S. Palmer