====================================================================
INTRO

This package contains some of the programs I've written to access
data files of Duke Nukem 3D.  You're hereby granted a nonexclusive
license to use the programs and source codes in this package for
any and all purposes.  However, this package is provided "as is", I
make no warranties, either expressed or implied, with respect to...

====================================================================
PACKAGE CONTENTS

Here's a list of programs in this package.  Note that "GRP" refers
to the GRP files of Duke Nukem 3D, not the Windows GRP files.

        readme.txt      this file
        dn3idx.exe      list index of GRP files
        dn3ext.exe      extract files from GRP files
        artidx.exe      list index of ART files, you can extract
                        ART files from GRP files using dn3ext.exe
        dn3gv.exe       view graphics inside GRP files; can also
                        save them to hard disk

The source code for the above programs are also provided:

        dn3idx.c                C code for dn3idx.exe
        dn3ext.c                C code for dn3ext.exe
        artidx.c                C code for artidx.exe
        dn3gv.c & dn3asm.asm    C & ASM code for dn3gv.exe

These codes were written in a quick-and-dirty fashion.  Development
efficiency was more important than run-time efficiency.  They should
compile OK using MASM 6.0, QuickC 2.0, and MS C/C++ 8.0c.  If you
use another C compiler, make sure it understands C++ double slash
comments (//comments to EOL).

====================================================================
HOW TO USE THE PROGRAMS

The following DOS programs were written to access DUKE3D.GRP, the main data
file of Duke Nukem 3D.  DUKE3D.GRP contains a number of smaller files, such
as sound files, palettes, level maps, and ART files.  The ART files in turn
contains many other smaller files, all of them graphics.


program:        dn3idx.exe
what it does:   list index of GRP files.
example:        dn3idx duke3d.grp
options:        [none]

program:        dn3ext.exe
what it does:   extract files from GRP file.  In the above example,
                TILES000.ART is extracted.
example:        dn3ext duke3d.grp tiles000.art
options:        [none]

program:        artidx.exe
what it does:   list index of ART files.
example:        artidx tiles000.art
options:        [none]

program:        dn3gv.exe
what it does:   view/save DN3D graphics without running DN3D
example:        dn3gv.exe duke3d.grp /g /sa2 /p1
options:        g       show graphics only, don't show sprite info
                p#      use the #-th palette, # is a number in the
                        range of 0 to 31, inclusive.
                s###    skip the first ### sprites
                sa##    skip the first ### ART files
                o       show offset of sprites

When dn3gv.exe is running, pressing the ESC key sends you back to DOS;
pressing the F10 key writes the current sprite to disk and advances to
the next sprite; pressing any other key advances to the next sprite.

Sprites are saved to disk in HSI RAW format, and filenames are in the
form of HSI#####.RAW, where ##### is the index number of the sprite
in the GRP file.  Existing files are overwritten without any warning.

What's the HSI RAW format?  Well, HSI stands for Handmade Software Inc.,
they make a very popular shareware image conversion/processing software
called "Image Alchemy", and HSI RAW format is the format used internally
by Image Alchemy.  See documentation of Image Alchemy for details.

Chances are, Image Alchemy can handle all the graphics file formats you've
ever heard of, and many others you've never heard of.  Highly recommended!


====================================================================
Please send your comment to:

        dyang@sfu.ca    or
        destiny_software@mindlink.bc.ca (put "To: Bo" at the
                                         beginning of your message)

Best Regards

Bo Yang