Group File Studio 3.1
Help Contents

Program Authored by: Gary and Jonah Bishop
Help Contents Authored by: Jonah Bishop
Copyright © 1999. All Rights Reserved.

Getting Started in Group File Studio

Back to Top

Program Overview

Group File Studio is a utility for Windows 95 and Windows 98 that makes working with group files much simpler than ever before. The group file format was used by 3D Realms in their hit games Duke Nukem 3D and Shadow Warrior. A group file is simply a "package" of many smaller files; they act as a container in which many smaller files can live. This allows the user to deal with one and only one file, yet have access to multiple files (which happen to be embedded in that one group file). As an example, the file "duke3d.grp" (the group file that comes with the game Duke Nukem 3D) contains all of the artwork, level maps, sounds, music, etc.

Program Requirements

Group File Studio's only requirement is that it is run in either Windows 95 or 98. If you can play either Duke Nukem 3D or Shadow Warrior, you are more than able to use this program.

How Do I...?

Creating a new group file - Back to Top

1. Select the "New..." menu item in the File menu. The group file contents tree view should now be blank (there should be no entries in it).
2. Select the "Insert Files..." menu item in the File menu. The file selection dialog box should appear.
3. Select the files you wish to add to the group file. You can select more than one file by holding down the control key and clicking on the files you wish to add. Once you have selected the desired files, press the "Open" button. The files will be added to the group file.
4. Save your group file. This can be done by selecting the "Save" menu item in the File menu. The changes made to the group file do not actually take place until the file is saved by Group File Studio.

Adding files to an existing group file - Back to Top

1. Open the group file that you wish to add files to.
2. Select the "Insert Files..." menu item in the File menu. The file selection dialog box should appear.
3. Select the files you wish to add to the group file. You can select more than one file by holding down the control key and clicking on the files you wish to add. Once you have selected the desired files, press the "Open" button. The files will be added to the group file.
4. Save your group file. This can be done by selecting the "Save" menu item in the File menu. The changes made to the group file do not actually take place until the file is saved by Group File Studio.

Permanently removing files from an existing group file - Back to Top

1. Open the group file that you wish to permanently remove files from.
2. In the group file contents tree view, select the file or file type that you wish to remove from the group file. Only one file or file type can be selected at a time.
3. Select the "Remove" menu item in the File menu. The group file contents tree view should be updated, and the file (or file type) should no longer appear in the tree view.
4. Save your group file. This can be done by selecting the "Save" menu item in the File menu. The changes made to the group file do not actually take place until the file is saved by Group File Studio.

Extracting a single file - Back to Top

1. Open the group file that you wish to extract a file from.
2. In the group file contents tree view, select the file that you wish to extract.
3. Select the "Extract Selected File" menu item in the Tools menu.
4. If a default extraction directory has been provided (in the program options dialog), the file will automatically be extracted to the default directory.
5. If no default extraction directory has been provided, a directory selection dialog box will appear. Select the directory that you wish to extract the file to and press the "OK" button. The file will then be extracted to the selected directory.

Extracting files of a common type - Back to Top

1. Open the group file that you wish to extract a file type from.
2. In the group file contents tree view, select the file type that you wish to extract. The file type is selected by simply selecting the appropriate heading in the tree view. For example, if you want to extract every art file, you would select the "Art Files" heading in the tree view.
3. Select the "Extract Selected File Type" menu item in the Tools menu.
4. If a default extraction directory has been provided (in the program options dialog), all files of the selected file type will automatically be extracted to the default directory.
5. If no default extraction directory has been provided, a directory selection dialog box will appear. Select the directory that you want to extract the file type to and press the "OK" button. All files in the selected file type will then be extracted to the selected directory.

Extracting all files - Back to Top

1. Open the group file that you wish to extract all files from.
2. Select the "Extract All Files" menu item from the Tools menu.
3. A dialog box will appear, providing a warning about the possible size of the files being extracted. If you wish to proceed, press the "Yes" button. Otherwise, press the "No" button.
4. If a default extraction directory has been provided (in the program options dialog), all of the embedded files will automatically be extracted to the default directory.
5. If no default extraction directory has been provided, a directory selection dialog box will appear. Select the directory that you want to extract all files to and press the "OK" button. All of the embedded files will then be extracted to the selected directory.

Renaming an embedded file - Back to Top

1. Select the file that you wish to rename.
2. Select the "Rename Selected File" menu item from the Tools menu.
3. The name will become "active" in the group file contents tree view, and you can subsequently change the name of the file. The name cannot be longer than 8 characters, and the extension must remain the same.

Viewing the artwork from embedded art files - Back to Top

1. Open the group file that contains the artwork that you wish to view.
2. Expand the "Art Files" tree heading in the group file contents tree view.
3. Select the art file that contains the art tiles you wish to view. The art file information view should be updated, showing the currently selected art file's information.
4. In the art file information view, select the tile number that you wish to view.
5. The artwork view port should now show the selected tile, scaled appropriately.

Playing an embedded sound file (*.voc only) - Back to Top

1. Open the group file that contains the sound file that you wish to play.
2. Expand the "Sound Files" tree heading in the group file contents tree view.
3. Select the sound file that you wish to listen to. As of this release, the only file format that is supported is the .voc file format.
4. Select the "Play" menu item in the Tools menu. The sound should begin to play.

Playing an embedded music file (*.mid) - Back to Top

1. Open the group file that contains the music file that you wish to play.
2. Expand the "Music Files" tree heading in the group file contents tree view.
3. Select the music file that you wish to listen to.
4. Select the "Play" menu item in the Tools menu.
5. There will be a slight pause after selecting the "Play" menu item. The progress bar will indicate the progress being made as the music file is loaded into memory. The music should then begin to play.

Program Screen Shot (with hot spot links)

A screenshot of the main program window is shown below. Click on the object you want to know more about.

The group file contents tree view - Back to Top

This is where the contents of the currently open group file are shown. Files are organized into file types (Art Files, Map Files, etc.). The file types can be expanded by clicking the little plus box next to the file type description. Once the file type heading has been expanded, all of the embedded files are listed in alphabetical order. Currently, only one heading or file may be selected at a time.

The universal progress meter - Back to Top

This progress meter is used in several areas of Group File Studio. The main purpose of this progress meter is to show the user the progress being made during a file extraction. Some files are quite large in size, and take a few seconds to be completely extracted from the group file. The progress meter is also used in indicating the progress being made while saving a group file.

The artwork view port - Back to Top

This area of the workspace is where the artwork appears when the user selects a certain tile to look at. Artwork that is either very large or very small is scaled accordingly, allowing the user to see the artwork in a clear fashion.

The art file information view - Back to Top

This area of the workspace is where information is displayed about the currently selected art file. The information displayed covers all aspects of the currently selected art file and its embedded art tiles. The columns present in this view are as follows (from left to right):

• Tile # - The tile numbers (in order) of the embedded tiles in the currently selected art file.
• Symbolic Name - The symbolic name of the art tiles (defined in the names.h file). Not all tiles have symbolic names.
• Width - The width (in pixels) of the art tiles.
• Height - The height (in pixels) of the art tiles.
• Animation - The animation type of the art tiles (if any). Valid types are: None, Oscillating, Forward, or Backward.
• Length - The number of tiles in the animation sequence, excluding the first tile. To find out how many total tiles are in the animation sequence, simply add one to this number.
• X-Offset - The x (horizontal) offset of the current tile. This value is utilized for sprite centering purposes.
• Y-Offset - The y (vertical) offset of the current tile. This value is utilized for sprite centering purposes.
• Speed - The animation speed of the current tile. The larger the value, the slower the animation.

The Accelerator Menu - Back to Top

The accelerator menu can be accessed by right-clicking the mouse cursor inside of the group file contents tree view. This menu includes several shortcuts to common commands, making it easier than ever to work with group files. The available shortcuts are:

• Extract Selected File
• Extract Selected Type
• Extract All
• Insert Files...
• Remove
• Rename
• Save
• Save As...
• Play
• Stop

The Status Bar - Back to Top

The status bar is one of the most useful places to look in Group File Studio. Several items of interest appear here:

• Total group file size - The total size of the currently open group file is reported here, as well as the total number of files. This is updated each time a file is either added or removed from a group file, to correctly report the most recent data.
• Selected file or file type size - When a file or file type is selected, the total size of the selected object is displayed. The total number of associated files is also shown when a file type is selected.
• Menu and toolbar command information - Information on the various toolbar and menu commands is shown here, providing the user with a short description of what the selected toolbar or menu command does.
• Successful extraction reports - Each time a file or file type is successfully extracted, a success report is shown here, indicating the total size of objects successfully extracted.
• Successful saves - Each time a group file is saved successfully, a success report is shown, indicating that the group file has been properly written.

The Toolbar - Back to Top

The toolbar provides the user with a shortcut method of accessing common menu commands. By moving the mouse cursor over the various toolbar buttons, the user can see what each button does (and its associated hot key combination). For an explanation as to what each toolbar command does, view the program screenshot and click on the desired toolbar button.

Program Options - Back to Top

Several options are available for the user to change in Group File Studio. These options are as follows:

General Tab

• Open last group file on program launch - Does exactly what it says. When checked, the last open group file is opened for editing at program startup (if the last group file no longer exists, the program will supply an appropriate warning). This option is turned off by default.
• Enable sound auto-play (*.voc files only) - When this option is checked, selecting a sound file (*.voc) in the group file contents tree view will cause that sound to be automatically played (i.e. - you do not need to use the "Play" menu item in the Tools menu. This option is turned off by default.
• Show art information when art files are selected - When this option is checked and an art file is selected in the group file contents tree view, the art file information view will show the selected art file's embedded attributes. This option can be turned off, preventing the information from loading when an art file is selected. This option must be turned on in order for the user to view the embedded artwork. This option is turned on by default.
• Display warning when extracting all files - This option toggles the warning that is associated with extracting all files from the group file. This option is turned on by default.

Configuration Tab

• Use a default extraction directory - When checked, the specified directory will be used as the default file extraction directory. Any files being extracted will automatically be placed into the directory specified here (preventing the user from having to choose a directory each time a file or file type is extracted). This feature is useful when you constantly work in the same directory. If this option is left unchecked, the user is forced to supply the program with a destination directory each time a file or file type is extracted.
• Alternate Palette File to Use - This option allows a custom palette.dat file to be used for viewing the artwork. The standard palette.dat file is the default selection (as it is included with Group File Studio). The user can change this option should they wish to. Palette files are required by Group File Studio in order for artwork viewing to work properly. Should the user close the options dialog with this field blank, the default palette file will be used.
• Symbolic Name File to Use - This option allows a names.h file to be used to define symbolic names for the art tiles. These names can be viewed from the art file information view under the "Symbolic Names" heading. The default names.h file is included with Group File Studio.

Troubleshooting

Back to Top

This section lists several common problems and their solutions for Group File Studio. If you are experiencing a problem, please look through this section to see if it is already listed. If the problem is not listed here, or if you are quite sure that what you are doing should work, contact me and I will see if I can help you out. It is quite likely that there are bugs in this program that I haven't yet caught.

License Agreement

Group File Studio is a freeware program, meaning that you can freely distribute it via any media. However, I do request that the following rules be adhered to:

• All of the below files should be included with the main program executable (grpstudio.exe):
  • gfsrev.htm
  • gfsindex.htm
  • palette.dat
  • names.h
  • gfs.jpg
  • readme.txt
• The above files should not be changed, added to, or renamed in any way. The program executable actually uses some of these names (which are hard coded into the executable) and renaming (or removing) them could cause some problems.
• When distributing the program, credit is given where it is due.

Contact Information

Back to Top

Group File Studio has been written with the beginning user in mind. If you have a comment, question, suggestion, or a bug to report, please let me know about it by sending e-mail to: jonahb@3dportal.com. Your input is most valuable in the creation and fine-tuning of this program, so feel free to let us know about anything!

For the latest information on Group File Studio, and the latest versions for downloading, visit the official home for Group File Studio at Map FAQ Central. You can visit Map FAQ Central at this URL: http://mapfaq.3dportal.com

Acknowledgements

Back to Top

I would like to take the time to thank the following for all that they have done. Group File Studio would not be what it is without you!

• Gary Bishop - Co-author of the program. Wrote the majority of the code dealing with group file creation and manipulation. Has helped me tremendously in my efforts to learn programming (I'm getting there...).
• Ken Silverman - Author of the group file format and the Build engine. Sent me the specs on the group file format and on other various items of interest. Without his efforts for 3D Realms, we wouldn't even have Duke Nukem 3D or Shadow Warrior. Thanks!
• 3D Portal - The ultimate 3D Realms fan site. They host Map FAQ Central (the web site that I maintain) as well.
• 3D Realms - For creating Duke Nukem 3D and Shadow Warrior in the first place. Also, thanks for providing the standard palette.dat file as well as the default names.h file.