================================================================
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.

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: 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. For normal Quake levels, it sets
    some console variables; e.g., use "demtool -i e1m1.dem > foo.cfg", then
    start Quake with QdQStats v1.3, "exec foo.cfg", start e1m2 and you'll begin
    with the correct statistics.
    For Hipnotic and Beyond Belief levels and their respective QdQStats equi-
    valents, things are slightly different since impulse lists will be generated
    instead. You'll need to bind some key (e.g., 'bind x "exec foo.cfg"'), then
    start the level and press that key.

-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 prolonged
    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).

-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.

-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.

-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.

-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.

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

* 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 latest version of this patch can be obtained from cdrom.com or a mirror,
or at <http://www.uni-hildesheim.de/~ssch0098/demtool.zip>.

* Related material *

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

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>.

Demcmp, the demo compression utility, is at Yonatan Donner's homepage
<http://www.geocities.com/Hollywood/4704>.

The DEM specs and lmpc have their home at Uwe Girlich's page, on
<http://www.physik.uni-leipzig.de/~girlich/games>.

