Readme for gamtool version 0.611, June 4, 2000
(C) 1999,2000 by Alan deLespinasse  aldel@alum.mit.edu


Contents:

1.  Overview
2.  Installation
3.  Usage
4.  Reference
5.  Known problems
6.  Revision history



============
1.  Overview
============

Gamtool is a free Windows program for editing Descent 3 table files
(.gam files).  These files contain parameters of certain resources
(textures, sounds, objects, doors, player ships, and weapons) that are
used in Descent 3 missions.  You will need to create and edit table
files in order to put custom resources in your missions.

The latest version of gamtool is always available from:

descent.aldel.com



================
2.  Installation
================

Unzip all files into a single directory (if you don't have an unzip
utility, you can get one from www.winzip.com).  If you had an older
version, replace all old files with the new ones (unless you had
customized default pages that you want to keep; see description in the
Usage section).

Run gamtool.exe.  The first time you run it, it will register itself
as the default editor of .gam files, so you can simply open them from
Windows Explorer to run the program in the future.

You may also want to create shortcuts to gamtool.exe on the Start menu
or your desktop.



=========
3.  Usage
=========

Use of the editor should be mostly self-explanatory.  See the
Reference section for information on individual fields.

A few things to be aware of:

A "page" is the part of a table file that defines a texture, door,
etc.  A "field" is a place within the page where a value can be
specified.

To edit a value, double click on it, or select it then press Enter.

Many fields can be set to illegal values.  For example, the Alpha
value for textures can be set to any real number, but should be
restricted to the range from 0.0 to 1.0 inclusive.  See the Reference
section for legal values.

Copy and paste only work on whole pages.  To copy a page, you must
select its root (top) element.  If you delete an entire page, it will
also be copied.  Pasting a page inserts it after the current page.

The Find function only searches through page names, not their fields.

When editing variable-length lists (such as the elements of a
procedural texture or the death types of a generic object), press
Insert to insert a new element into the list.  You can also delete
elements with the Delete key, but you must be at the top (root) of the
element (not a sub-tree of it).  If you can't expand the list, it's
empty.

Some types of pages can refer to other pages; for example, textures,
objects and doors may specify sounds to be played under certain
circumstances; and objects may specify other objects to spew.  In
Descent 3 version 1.1 and earlier, if page A refers to page B, B must
come before A in the table file.  If it is not, the mission will still
run, but D3 will crash as soon as it ends.  This is fixed in D3 1.2.

You can edit the default pages to be inserted by the "New->Texture",
"New->Sound" etc. menu commands.  They are stored in files in the
installation directory with logical names such as
"default_texture.gam" and "default_sound.gam".

To use a table file in a mission, put it and all of the files it
refers to in the .mn3 file.  The table file and the .mn3 should have
the same name (except for the extension).  

To make D3Edit display custom textures, you need to both (1) specify
the .gam file as the mission table file, and (2) specify a hog/mn3
file containing all of the .ogf files as the mission hog.  Both of
these are done from D3Edit's Data menu, which is only available when
no rooms or levels are open.  Gwar has said (if I understood
correctly) that you can just put the table file in the hog file, and
you won't have to specify it as the mission table file, but I haven't
gotten this to work.



=============
4.  Reference
=============

Parts of this section are lifted directly from "The Descent 3
Tablefile Format (.GAM) File Spec", published by Outrage on their web
site ( www.outrage.com ).  Many thanks to Jeff Slutter at Outrage for
writing the spec and helping me to understand it and fill in the
holes.

Thanks to Otherone for additional info.

This section still has large holes in it.  See the tablefile spec for
things that aren't covered here.

If you have any information that should be in this section but isn't,
please let me know.



Doors
-----

Model file name: name of the .oof file (with extension) for the door.

Opening time: time it takes to open the door, in seconds.

Closing time: time it takes to close the door, in seconds.

Open time: time the door stays open before closing, in seconds.

Flags:Blastable: door opens by being destroyed.

Flags:See through: door can be seen through even when closed.

Hit points: amount of damage required to destroy, if destroyable.

Opening sound: table file name of sound played while opening.

Closing sound: table file name of sound played while closing.

Script name: Filename of the OSIRIS script for this door.  This
filename doesn't need an extension since it is dependent on the
platform that Descent 3 is running for (.DLL for Win32, .so for Linux,
etc.).  If this is not set then the door will not open!  By default
this can be set to "Generic", which contains a default generic script
for any door.


Sounds
------

File name: the name of the .wav file (with extension) to use wherever
this sound is specified.  Must be a 16-bit, 22050-Hz, mono file (may
require a special nonstandard wav file with an extra chunk at the
beginning, not sure).

Flags:Looped: part of the sound is looped (repeated).

Flags:Fixed frequency: no doppler effect.

Flags:Object update: sound updates with attached object movements. (?)

Flags:Forever: Always plays in high-level, this flag should be ignored
in low-level. (?)

Flags:Plays exclusively, Plays once: ?

Flags:Use cone: sound is directional.  Can be heard at full volume
within an "inner cone", at reduced volume within an "outer cone", and
not at all outside of that.

Flags:Listener update: Sound updates with listener movements. (?)

Flags:Once per object: ?

Loop start: sample index of start of loop (for looped sounds).

Loop end: sample index of start of loop.

Outer cone volume: Fraction of full volume to use in outer cone.  0.0
to 1.0.

Inner cone angle: angle of inner cone.  0-360.

Outer cone angle: angle of outer cone.  0-360; should be greater than
or equal to inner cone angle.

Maximum distance: distance beyond which sound will be inaudible?

Minimum distance: distance within which sound will be inaudible?

Import adjust: fraction of full volume to use.  0.0 to 1.0.


Textures
--------

File name: the name of the .ogf file (with extension) to use wherever
this texture is specified.
        
Destroyed file name: name of the .ogf file to use after a face has
been shot (if the Destroyable flag is set).

Red, Green, Blue light: how much light of each color to give off.
Values as high as 100 are not uncommon for bright lights.  Set all
three to equal values for white light.  Any face that gives off any
light at all will not show scorch marks.

Alpha: translucency.  1.0=opaque, 0.0=invisible.

Speed: I don't know what this means.  Maybe the speed of animated
textures.  0.0 to 1.0.

Horizontal slide: makes the texture slide across the face repeatedly
in the direction of the texture's horizontal axis (the u axis).  The
value is approximately the number of seconds it takes to make one
complete cycle, i.e., higher is slower.  Zero means no sliding.
Positive values mean the texture moves to the left; negative means to
the right.

Vertical slide: like horizontal slide, but for vertical sliding.
Positive=up, negative=down.  Can be combined with horizontal sliding
for a diagonal sliding effect.

Reflectivity: How much light it reflects (used during radiosity
lighting in D3Edit, not for mirrors).  0.0 to 1.0.

Corona style: used only if texture gives off light and corona is
turned on in face properties.

Damage: Amount of damage per second it causes if an object collides
with it.

Flags:Volatile: ?

Flags:Water: absorbs weapon fire with a puff of steam.

Flags:Lava: makes it behave like lava.

Flags:Forcefield: Deflects energy weapons.  If this is set, it's a
good idea to also emit at least a little bit of light, so that scorch
marks won't show.

Flags:Destroyable: shooting this texture will cause it to switch to
the Destroyed file instead of the original File name, with appropriate
sound and visual effects.

Flags:Breakable: can be broken by matter weapons (as in breakable
glass).

Flags:Fly through: Lets you fly through the texture.

Flags:Pass through: Not sure, maybe lets you shoot through it (one
report from a person who tried it says it didn't do this).

Flags:Saturate: Basically makes it bright.

Flags:Force lightmap: Uses a lightmap even in situations where it
normally wouldn't, like if the texture is transparent.

Flags:Saturate lightmap: Uses the lightmap differently than usual.
Instead of the brightest parts of the map being normal brightness and
the dim parts being dimmer, the dimmest parts will be normally lit and
the bright parts will be brighter.

Flags:Ping-pong: ?

Flags:Effect: ?

Flags:Alpha: ? probably has something to do with transparency.

Flags:Don't use: ?

Flags:Smooth specular: affects specular lighting somehow.

Flags:Light: texture is a light texture.  Not sure if this has any
effect in game; used by D3Edit for finding light textures.

Flags:Animated: is an animated texture.  Not sure what happens if the
texture is an .oaf file but this flag isn't set.  Maybe just used in
D3Edit for finding animated textures.

Flags:Metal, Marble, Plastic: as far as I can tell, these have no
effect in the game, and are used only by D3Edit for filtering out
specific types of texture.  Or they may have some kind of effect on
lighting and/or the sound made when players collide with it, but I
haven't noticed.

Flags:HUD cockpit, mine, terrain, object: as far as I can tell, these
have no effect in the game, and are used only by D3Edit for filtering
out specific types of texture.

Flags:Rubble: I've been told that this makes the texture spew bits of
rubble when you shoot it.

Flags:Texture 32, Texture 64, Texture 256, TMap 2: ?

Flags:Water procedural: This should only be checked if Procedural is.
If Procedural is checked and Water Procedural isn't, it's considered a
Fire Procedural texture.

Flags:Procedural: this is a procedural texture.  The Procedural data
chunk is only present if this is checked.

Procedural data: This section only exists if the Procedural flag is
checked.

Procedural data:Palette: each of these 255 entries represents a color.
The 16 bits of the binary representation of each entry are divided up
into four fields: 1 bit for alpha (transparency) (which may not ever
be used), and 5 bits each for red, green, and blue.  The palette is
ignored by many procedural element types, I think.

Procedural data:Heat: ?

Procedural data:Light: ?

Procedural data:Thickness: ?

Procedural data:Evaluation time: ?

Procedural data:Oscillation time: ?

Procedural data:Oscillation value: ?

Procedural data:Elements: a variable-length list.  If it won't expand,
it is empty.  Select and press Insert to add a new element.

Procedural data:Elements:element[n]:Type: the type of procedural
element.  The effect of this field depends on whether the texture is a
Water procedural or not.  If it is, the names to the right of the
slashes on the selection menu are operative; otherwise, it's the names
on the left.  Each type produces a different effect on the texture.

Procedural data:Elements:element[n]:Frequency: How often the effect
happens?

Procedural data:Elements:element[n]:Speed: How quickly it happens?

Procedural data:Elements:element[n]:Size: The size of the effect?

Procedural data:Elements:element[n]:x1, y1: the coordinates of the
effect on the texture.

Procedural data:Elements:element[n]:x2,y2: depends on the element
type?

Sound name: table file name of sound to emit from this texture.

Sound volume: volume of the sound.  0.0 to 1.0.



==================
5.  Known problems
==================

No sort feature, which is necessary to prevent D3 (pre-1.2) from
crashing after the level ends when there are dependencies within the
table.

Many fields that should have range restrictions don't.

Updates in inactive windows are shown just like in the active window
(i.e., subtrees are expanded to show inserted elements).  Only occurs
when using multiple views of the same file.

Undo of certain operations does not result in expansion of subtrees to
show the result.

No multiple selections.  This isn't fixable without some major
redesign of the user interface, since tree controls don't support it.

The water procedural texture flag isn't handled right (it should
automatically check the procedural flag and change the procedural type
menu under each procedural element).

Not fault-tolerant of badly formatted files.

Cut button and menu item don't become disabled when you can't delete
the selected item.

Appending large files is very slow.  Undoing such append operations is
very slow and appears to make the program hang until it is done.

The whole window jumps when a subtree is collapsed (because the
subelements are actually being deleted to save memory-- not sure if
there's a way around this).

Palette entries should have separate ARGB fields.

No automatic installation.

Doesn't save window placement between sessions.



====================
6.  Revision history
====================

Version 0.611, 6/4/2000: Just changed the URL for gamtool's homepage;
nothing else changed.

Version 0.61, 11/17/1999: Added Ship, Weapon and Gamefile pages, so
all page types are now supported.  Added a search feature.  Added a
minor easter egg.  Fixed bug that allowed nonvisible values to be
edited, resulting in strange behavior including apparent lockups.

Version 0.42, 10/3/1999: Made editing of large files much more
efficient.  Fixed serious bug that always changed a generic object's
AI type to Flylander.  Removed broken "+" button from unsupported page
types.  Fixed field edit controls so they appear in the right place
and allow spaces.  Pressing Enter now edits the selected field (space
still works too).  Single-clicking the selected field no longer edits
it.  Double-clicking parent elements no longer expands them (must use
button or right arrow).

Version 0.4, 9/22/1999: Added generic object pages.  Added copy and
paste of pages.  Fixed saving of variable length lists.  No longer
allows editing of names of fields that shouldn't be editable.  Made
use of tree control more efficient.  Fixed memory leak when command
history was truncated.  Added an hourglass cursor to a few slow
operations.  Added names of procedural element types (but they still
don't correctly reflect fire vs. water procedurals).  Made double
clicking edit field.

Version 0.3, 9/18/1999: Complete rewrite.  MDI application with tree
viewer.  Supports texture (including procedural textures), sound, and
door pages.  Has multilevel undo and redo.  New documentation.

Version 0.01, 8/17/1999: Initial version.  SDI application with list
viewer, which popped up a dialog box for editing a page.  Supported
texture pages only.
