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.