================================================================
Title                   : Demo Tool

Filename                : demtool.exe - MS-DOS binary
                          demtool.txt - This file

Author                  : Stefan Schwoon

Email Address           : ssch0098@rz.uni-hildesheim.de

Description             : Demtool provides a variety of switches to perform
                          operations on Quake demos. Most of the options are
                          QdQ specific but some of them may be of interest to
                          the general public, too. Demtool works directly on
                          Quake's .dem files, allowing for fast processing.
                          Many features are intended for single player demos
                          only, and have not been tested with multiplayer ones.

Installation            : Unzip this archive. Put demtool.exe wherever it suits
                          you best. That's it.

Additional Credits to   : Anthony Bailey, Yonatan Donner and Nolan Pflug for
                          suggestions and bug reports. Uwe Girlich for the
                          DEM specs and lmpc.
                          
================================================================

Instructions:

Calling Demtool without any parameters will give you a short
description of its usage. Other than that, the syntax for a
normal call will follow this scheme:

        demtool <switches> <files> <outfile>

Demtool will run in one of two modes, depending on the switches you
give. In "print mode", invoked by switches -i, -s, -w and -x, Demtool
will analyse its input files and print data to the console (you may
want to redirect this output to a file). If any other switches are
given, Demtool will be in "change mode" - it will read one demo, make
some modifications to its contents and write this modified demo to the
same file (or a new one, see below). You may not combine switches of
both types (except that if you use -d or -: together with -w, this will
cause Demtool to remain in "print mode").

If no switches are given, -s will be assumed as default.

Files is, you guessed it, the name of the file(s) that Demtool should
process. You may use wildcards - Demtool will expand these and process
any file that matches the pattern. Demtool expects Quake .dem files as
input. Be careful - if you omit outfile then all the changes made to
input files will be written directly to these files. Backup your original
demos if necessary.

If you omit files, *.dem will be assumed. If you omit a suffix, .dem
will be appended.

If you perform a "change mode" operation but do not want to have your
input files changed, tell the program which file to write the results
to by specifying outfile. Note that you may only specify outfile if
there's no more than one input file. If no suffix is given .dem will
be appended to outfile.

If you do a "print mode" operation you can also specify outfile - in
that case, all the output that normally goes to the console will be
redirected to this file instead.

The following paragraphs describe all the available switches in detail.
Non-QdQers may find -{f,n,s,t,v,w,:} to be the most interesting, but
check out the others, too. You may combine switches, e.g. "demtool -fv"
would be equivalent to "demtool -f -v".

-a: Insert footer before disconnect
    Specify a demo after -a (e.g., -aexample.dem), and example.dem will be
    appended to the demo (it will be inserted right before the block that
    contains disconnect). If no demo is given, footer.dem will be assumed.

-b: Add bleeding to player model
    This option is useful for refilmed demos (e.g., those made with ReMaic)
    and has two effects: First, throughout the demo, blood particles will be
    spawned at the player's position, making it look as if he's bleeding.
    The number of the blood particles will depend on his current health.
    Second, every time the player takes damage, additional particles are
    spawned - red for damage to health, grey for damage to armor and purple
    for pentagram-protected damage.

-c: Remove centerprinted messages
    Does exactly this: All the centerprinted messages are removed from the
    demo, along with accompanying talk.wav sounds.

-d: Add a disconnect message at the end
    Appends one single block containing a disconnect message to the end
    of the input files. If used in conjunction with -w, the disconnect
    message will be printed to the console instead.

-e: Remove entities during finale
    Once a finale message is encountered in a demo, all following updateentity
    messages will be removed except for those of entity 1 (the player, usually).
    This is useful to save space on demos of end-of-episode levels.

-f: Set framerate
    This is a compression feature analogous to that provided by Yonatan
    Donner's demcmp. You may specify a framerate (e.g., -f10 would set
    the framerate to 10); if you omit the number (just -f), 20 fps is
    used as default. This will remove as many frames as possible without
    letting the framerate sink below the one you gave. Note that you can
    only *reduce* the framerate (and hence the size) of any given demo,
    not increase it. Using a very high value (e.g., -f1000) is not likely
    to provide real compression but can be used to remove the "pause" frames
    that occur when you pull down the console while recording.

-g: Remove grenade counter messages
    Removes the centerprinted messages produced by QdQstats' grenade counter.

-h: Insert header at start of files
    Like -a, but header.dem is assumed as default and the demo will be inserted
    at the start of all input files. At QdQ, we use this to set some console
    variables at the start of each demo to ensure correct playback - maybe you
    can come up with other creative uses.

-i: Output config file for starting statistics
    Analyses the finishing statistics of a demo and prints a list of commands
    that generate the correct starting statistics, following on from that demo,
    when used in conjunction with QdQStats. It sets some console variables;
    e.g., use "demtool -i e1m1.dem > foo.cfg", then start Quake with one of the
    stats modifications, "exec foo.cfg", start e1m2 and you'll begin with the
    correct statistics.
    Both QdQStats 1.3/1.4 and SoAStats 1.3 are supported. Demtool will not
    work with previous versions of these modifications.

-j: Stop the screen from jarring when the player fires his weapon.

-m: Remove printed messages
    Removes all messages printed at the top of the screen. The "Version x.yz"
    startup info is preserved.

-n: Add a nop block at the start
    There's a bug in some versions of Quake that prevents it from playing back
    demos recorded in certain levels (e.g., single player recordings of start,
    or hip1m3). Demtool -n circumvents this bug by simply adding a single
    block containing a single nop at the start of each demo.

-o: Fade-out, cut intermission
    When used without any argument, demtool -o will insert stufftext messages
    causing the screen to fade black during the last 0.5 seconds of recording.
    If, however, an additional parameter is given (e.g., -o5) then the demo
    will be cut off that many seconds after the appearance of the intermission
    screen, and the fade-out will occur at that time. The demo will be pro-
    longed by repeating the last frame if it is shorter than required.

-p: Add playdemo before disconnect
    Append the name of a demo to this switch (e.g., -pdemo), and Demtool will
    insert the command "playdemo demo" just before the disconnect message.
    Useful for chaining demos. If you omit the name of a demo (just -p) then
    Demtool will make up a name by increasing the last character of the bsp the
    demo was recorded on (this would yield "playdemo e1m2" on demos of e1m1).

-P: Remove setpause messages
    Removes the messages occuring when you pause a game, including the printed
    "player [un]paused the game" and the setpause message. The extra frames
    that occur while the game is standing still are left untouched but can
    be removed via -f1000 (see above).

-q: Remove QdQStats message
    Removes the messages produced by QdQStats whenever you start or end a level.

-r: Add runes to player's inventory
    On playback, this will make runes appear in the status bar. Exactly which
    runes get added depends on the name of the level the demo was recorded on;
    demos of e2m? will get the rune from the first episode, demos of e3m? will
    get those of the first two episodes, and so on.

-s: Print statistics and time
    This will analyse and print the starting and finishing statistics of the
    player (health, armor, ammo etc.), along with the intermission time, the
    exact time needed to finish the level. If the level is never completed,
    the total running time is printed instead.

-t: Centerprint time on every frame
    This will be useful for speed runners. It allows you to gauge your per-
    formance exactly, and compare it with other demos of the same level.

-T: Print block number and time
    Similar to -t, but the block number will also be printed (the numbering
    scheme being compatible with that of demcut), and the time will be for-
    matted slightly differently.

-u: Change player's uniform color
    You need to supply an additional parameter here, e.g. -u4. The meaning of
    this number is the same as for arguments of _cl_color: shirt color * 16
    + pants color (e.g., 4 = 0*16+4 = white shirt, red pants). Useful for
    refilmed demos only.

-v: Remove entities outside fov
    Another demo compression feature, based on an idea by Yonatan Donner.
    If you're familiar with the way Quake records demos you'll know that
    it stores all those entities that are in direct line of sight from the
    player's position (roughly) regardless of the direction the player is
    facing. That means that approximately one half of the updateentity
    messages in a demo are useless - the corresponding items are never
    displayed. Demtool -v identifies these messages by way of simple
    geometric calculus and removes them, resulting in a decrease of 20%
    of demo size on average.

-I: Do not remove entities in intermissions
    This switch does nothing useful when used alone, but when used in
    conjunction with -v (i.e. -vI) it prevents entities from being removed
    in intermissions. This is sometimes necessary because of a bug in Quake
    with regard to playback in intermissions (you do not always face into
    the direction that you should, usually staring at blank walls, and Quake's
    behaviour seems not to be very consistent in this aspect).

-V: Scale volume of sound effects
    Multiplies the volume of all sound effects by the factor supplied
    with this switch, i.e. -V0.7 reduces the sounds to 70 percent of
    their original volume. Note that since most sounds in a demo are
    played at full volume normally, using a factor of larger than 1
    won't help you any (except if you already used the -V switch to
    scale down the volume before, of course).

-w: Produce lmpc-style output
    LMPC, the allround demo utility by Uwe Girlich, features the useful
    possibility to turn Quake's .dem files into readable (and editable)
    text. Demtool reproduces this feature, only it's faster. You'll still
    need lmpc to compile text files back into .dems, though. Be sure to
    redirect Demtool's output into a file if you use this switch.

-x: Extract centerprinted messages
    You'll need to supply an additional parameter to this option, e.g.
    -xstring. In that case, Demtool will look at all the centerprinted
    messages in a demo, and if it finds a centerprinted "<string>", it
    will output all the following centerprinted messages until "</string>"
    occurs. If you don't know what this is for don't ask.

-[from]:[to]: Restrict output to specified range
    (also referred to as -: elsewhere in this document)
    Demtool expects "from" and "to" to be (integer or fractional) numbers
    that represent times in seconds. Either "from" or "to" may be omitted;
    start or end of the demo, respectively, will be assumed in that case.
    This will cut the demo to include just the range given by "from" and
    "to". If used in conjunction with -w, output to console will be re-
    stricted instead.

-@: FilmAt11 fails to load demos from certain levels included in the
    Hipnotic mission pack. The reason for this is the inclusion of
    seemingly useless spawnbaseline messages with modelindex 0 which
    can be removed with this option.

--damage:
    Removes all damage messages from a demo

--vcshift:
    Removes all v_cshift commands from a demo (those used for fades)

--blood:
    Removes the extraneous blood in intermissions introduced by previous
    versions of Demtool (not that anyone would ever need this again...)

--faqproxy:
    Removes all blocks before the serverinfo message, for example those
    produced by option -n and by Perkele's FAQ-Proxy. Those blocks inter-
    fere with the operation of Remaic.

--setview:
    Removes setview messages that point to an entity that already has the
    view and are thus unnecessary; Remaic produces a lot of those.

--sounds:
    Removes all sound messages. Ambient sounds remain, and some sprites
    have sounds on their own.

--bf:
    Removes all the "bf" (brief flash) stuffcmds that occur when the
    player picks up items.

--powerups:
    Removes the palette changes induced by picking up powerups like
    the ring, pentagram, biosuit or quad. (Caution: these items are
    also removed from the inventory on the status bar.)

--ambient:
    Removes all spawnstaticsound messages.

--fadein:
    Adds stufftext "v_cshift 0 0 0 x" commands at the start of a
    demo that make the screen fade softly from black to normal.

================================================================

Use of Reduce:

Reduce is a small program that eliminates all unused models and
sounds from the precache list (at the same time renumbering all
sound and model indices).

To use it, just say
        reduce demo1
which will read demo1.dem and clean up its precache list.
You can use wildcards in demo1.

If you say
        reduce demo1 demo2
the result will be written to demo2.dem instead.

By the way, I made it so that at least one sound remains in the
sound list even if there are no sounds in the demo. The reason
for this was that even though Quake itself can cope with an
empty sounds list, some demo editing utilities can't.

================================================================

Version history:

14.11.97: initial public release

18.12.97: compatibility with Rogue demos
          new switches: -T, -#1, -#2
          fades now work properly (-o)
          outfile for print mode
          .dem suffix appended to outfile
          non-zero exit code to indicate errors
          various small fixes

26.01.98: fixed options -o, -b
          added options -m, -#3
          added compatibility to SoAStats 1.3
          modified -s slightly

09.02.98: added option -@

28.02.98: added option -#4

16.03.98: fixed option -f
          added options -#5, -P

09.04.98: added a few features for Gerald :)
          renamed the -# options

03.05.98: added --ambient
          wrote the reduce program

01.06.98: added --fadein
          removed a bug in -b

28.06.98: added -V

25.07.98: added -I

================================================================

* Copyright information *

This file, and all accompanying files (see list at top of page) may
NOT be used for commercial purposes. Oh yes, use this program at your
own risk, ok?

* Where to Get This *

The Demtool homepage is at <http://www.planetquake.com/qdq/demtool.html>.
The latest version of this program can be obtained from cdrom.com or a mirror,
or from <http://www.uni-hildesheim.de/~ssch0098/demtool.zip>.

* Related websites *

Quake done Quick, the project this tool was made for, can be found at
<http://www.planetquake.com/qdq>.

Visit the Speed Demos Archive <http://www.planetquake.com/sda>
for more single level speedruns.

ReMaic by Anthony Bailey, the program that was used to refilm Quake demos
from a new camera perspective, is at <http://www.planetquake.com/remaic>.

The DEM specs and lmpc have their home at Uwe Girlich's page, on
<http://www.planetquake.com/demospecs>.

