================================================================
Title : Demo Tool for Quake2
Filename : dm2tool - Linux binary
dm2tool.exe - Win32 binary
dm2tool.txt - This file
skel.c - demo parsing source code
Author : Stefan Schwoon
Email Address : schwoon@informatik.uni-hildesheim.de
Description : Dm2tool provides a variety of switches to perform
operations on Quake2 demos. Most of these switches
were implemented specifically for dealing with the
speed demos found on SDA (see below), but some are
probably useful to the more general public as well.
Source is included for a prototype dm2 parsing
program, intended to give those who want to write
their own demo manipulation programs a headstart.
Installation : Unzip this archive.
Additional Credits to : Nolan Pflug, Will Marsh and Anthony Bailey
for suggestions and help with compiling the Win32
binary. Various people on [q2demos] for working out
the specs (Uwe Girlich, Kekoa Proudfoot and Darrin
Cullop, to name a few).
================================================================
Instructions:
Calling Dm2tool 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:
dm2tool <switches> <file_1> ... <file_n> [-o <outfile>]
Dm2tool will run in one of two modes, depending on the switches you
give. In "print mode", invoked by switches -stats and -report, Dm2tool
will analyse its input files and print data to outfile (if no outfile
is given output will go to the console instead). If any other switches
are given, Dm2tool will be in "change mode" - it will read one demo,
make some modifications to its contents and write this modified demo
to outfile (if given) or back to the original (if no outfile is speci-
fied). You may not combine switches of both types.
Dm2tool expects Quake2 .dm2 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.
Wildcards in filenames are not yet supported. Linux users can use their
shell's filename expansion, of course.
IMPORTANT: If you used Demtool previously, note that "-o" is now required
to specify outfile. Do not omit "-o" if you do not want Dm2tool to over-
write your originals. Note that you may only specify -o if there's no more
than one input file.
The following paragraphs describe all the available switches in detail.
Non-speedrunners may find the -delta and the -fov switch to be the most
interesting, but check out the others, too. You may combine multiple
switches.
-bestdelta: Use optimal delta compression
Quake2 demos can be delta compressed. This means that, unlike for Q1,
every frame only contains those bits of the game state that have changed
in relation to some previous frame. -bestdelta rearranges the existing
delta compression in a demo in such a way that each frame is delta encoded
in the most space-efficient manner (choosing the delta reference frame
among the baseline and a number of previous frames).
Note that -bestdelta does not save a lot of space compared to -delta
while taking a lot longer to calculate.
You may need to increase the block size (see -blocksize) to -bestdelta
to work properly, but doing so will not result in an invalid demo (at
least not if the original demo was valid :-)
You cannot use -bestdelta in combination with -delta or -undelta.
-blocksize=<size>: Override maximum blocksize
Normally, blocks in Quake2 cannot exceed a size of 1400 bytes (as of
Quake2 v3.14). For this reason, Dm2tool only allocates 1400 bytes for
its internal buffers in normal operation. You can enlarge this size by
specifying -blocksize with an alternate value. (This is sometimes needed
for the operation of -bestdelta and -undelta).
Note that demos with blocksizes of more than 1400 bytes will not play
back properly in Quake2. [This was true for earlier versions of Quake2.
I haven't checked if this is still true in v3.20.]
-chain=<nextdemo.dm2>: Play another demo after this one
This simply put a stufftext "demomap <nextdemo.dm2>\n" at the end of
your demo, thus allowing you to play multiple recordings in a row.
(Quake2 does not (yet) play back single recordings of multiple
levels properly, however).
I find that this switch makes it much more convenient to watch one
week's worth of speedruns on SDA...
-computer: Clear the computer icon
Removes the stupid F1 computer icon on the bottom of the screen.
Can also be used to remove the icon depicting the current weapon
if a demo was recorded with centered handedness.
-delta: Delta compress demos
Delta compresses demos (see explanation at -bestdelta). Contrary to
-bestdelta every frame is simply encoded against its predecessor.
Interestingly, this further reduces the size of demos that were
already recorded with Quake2's native delta encoding (with a setting
of "cl_nodelta 0", to be more precise). Presumably Quake2's native
delta encoding is not efficient as it could be, then.
You cannot use -delta in conjunction with -bestdelta or -undelta
(for obvious reasons).
-fov: Remove entities in the player's back
This is analogous to Demtool's -v switch. In both Q1 and Q2 the client
always receives information about all entities in his potentially visible
set. In other words, the entities included in packets depend on his posi-
tion, but not on the direction he is facing. For that reason, entities
in the player's back are also included. -fov identifies these entities
by means of simple geometric calculus and removes them.
Use of -fov implies -delta unless -bestdelta or -undelta are also given.
Note: The save in demo size incurred by -fov is smaller than it was for
Q1 demos, presumably because delta compression already reduces the space
consumed by entity updates.
-game[=<name of the game>]: Change the demo's game setting
Got sick of having Q2 set your "game" console variable to something
else *after* playing one demo (usually because the someone who recorded
the demo used a different "game" setting)? -game allows you to change
a demo's "game" setting. Default is "q2timer".
-grenadecounter: Remove the grenade counter
Removes the traces of q2timer's grenade counter from a demo.
So now you can use it without having Gerald say you're not a real
speed runner :)
-hand[=<xx>]: Set handedness or remove hand cmds
If <xx> is not given this merely removes all commands that set your
handedness. Otherwise, the demo's handedness is additionally set
to the value of <xx>.
-range=<start:end>: Extract range of sequence numbers
Extracts the frames that have sequence numbers in between the numbers
specified by start and end (including start, excluding end), plus all
those blocks that do not contain an svc_frame message (mostly the
header blocks at the start of each demo). Implies -delta unless
-bestdelta or -undelta are also specified.
-reconnect: In multilevel demos, keep only the first level
Quake can't play back demos recorded on multiple levels correctly.
This switch allows you to extract the first part of such a demo.
-report[=<filename>]: Print statistics using file
This switch is a versatile and flexible way to print statistics
of a demo. The filename given as an argument is used as a template,
and the macros in it are replaced by the appropriate values of the
demo. If filename is omitted, a standard template is used. See below
for a list of macros.
-setfov[=<value>]: Set the player's fov value
Sets the fov used in the demo. Default value is 90.
-stats[=<string>]: Print statistics using format string
Same as -report, only the template is not read from a file but
taken from the argument (e.g. -stats="%filename: %game" tells
you what game setting each demo was recorded with). See below
for a list of macors.
-truncate: Repair demos that were not stopped properly
Sometimes, people don't stop their recordings properly but swap
out to another console or the Windows desktop instead (with Alt-Fx
or Alt-Tab respectively). The result is that the dm2 file that was
being recorded is not closed properly, leaving an incomplete block
at the end of the demo. -truncate cuts off this incomplete block,
making it possible to process this demo with other tools (for exam-
ple, lmpc does not recognize such demos properly).
-unchain: Remove stuffed demomap commands
Removes all stufftext commands that begin with "demomap ", e.g.
those introduced by previous -chain switches.
-undelta: Remove delta compression
Removes delta compression from a demo, i.e. all frames are re-encoded
against the baseline, as if "cl_nodelta 1" was used during recording.
This vastly increases a demo's size, but may make it easier to edit it.
Most likely you will have to increase the -blocksize setting for this
to work. Note that Q2 will not play back demos with block of more than
1400 bytes, so the only real use of -undelta is to make demos easier
to look at and to edit.
You cannot use -undelta together with -delta or -bestdelta.
================================================================
Macros:
The -report and -stats switches can output a number of statistics
about your demos in a flexible way. Both switches allow you to specify
text templates with macros that are replaced with data taken from the
demo. Currently, the following macros are supported (note that many
of them will only work on demos recorded with q2timer):
%filename : Will be replaced by the name of the demo file.
%playername: The nickname of the recording player.
%bspname : The name of the map the demo is playing on (e.g. base1).
%mapname : The title of the map the demo is playing on (e.g. Outer Base
for the first level).
%game : The demo's "game" cvar setting.
%skill : The skill the demo was recorded at (q2timer only).
%time : The finishing time (q2timer).
%kills : Number of enemies killed (q2timer).
%totalkills: Number of enemies on map (q2timer).
%secrets : Number of secrets visited (q2timer).
%totalsecrets: Number of secrets in map (q2timer).
%startitem : Item the player is holding at the start of recording.
%enditem : Item the player is holding at the end of recording.
%startinv : Player's inventory at start of demo (q2timer).
%endinv : Player's inventory at intermission (q2timer).
%include{filename}: Insert contents of filename.
The following macros are of a more hackish nature. They allow you to change
the layout of the output that dm2tool produces by default.
%dumpreport: Outputs the template used by the -report switch if no filename
is given. You can use this to get an idea how a template might
look like (try -stats=%dumpreport).
%dumpinv : Outputs the layout template used for printing inventories.
I'll let you figure out the format for yourselves...
%invitems{item1,item2,...}:
Gives names to the items in the player's inventory. Put this
command at the top of your template to change the default names
(which are obtained by %dumpinv). The names are used in %invformat.
Don't use this unless you know what you're doing.
%invformat{format_of_inventory}:
Put this at the top of your template to change the way inventories
will look like (the default behaviour is obtained with %dumpinv).
The parsing routine for the format is not robust at all, you ought
to know what you're doing if you play with this.
================================================================
About skel.c:
skel.c is intended to help people make their own demo manipulation
utilities. It does nothing useful on its own, but it parses through
all messages of a demo, so with skel.c as a basis and the dm2 specs
it should be easy for halfway skilled programmers to insert their
own features.
Basically, this is the dm2tool source with all the code that actually
changes the data in demos removed. For most message types, it just
skips as many bytes as necessary to get to the next message, but
playerinfo, spawnbaseline and packetentities are parsed in detail,
making it easy to manipulate the data contained within these types
of messages (especially as the code already takes care of all the
delta encoding issues). skel.c compiles correctly and without any
warnings on gcc 2.7.2.1 and lcc 2.1.
I'm not documenting this in detail, the code should be mostly self-
explanatory with the dm2 specs at hand. Use it at your leisure,
but I'll appreciate if you give me credit when doing so.
================================================================
Version history:
17.05.98: initial public release
25.05.98: added -unchain
fixed bug with -o (Win version)
14.01.98: added support for Quake2 v3.20
changed -report switch
added inventory output in -report
18.01.98: tweaks to -report function
================================================================
* Copyright information *
This file, and all accompanying files (see list at top of page) may
NOT be used for commercial purposes. Use this program at your own risk.
* Where to Get This *
The latest version of this program can be obtained from cdrom.com or a mirror,
or at <http://www.planetquake.com/qdq/dm2tool.html>.
* Related websites *
Quake done Quick, the Quake speed-running project, can be found at
<http://www.planetquake.com/qdq>.
Speed Demos Archive, QdQ's sister site featuring lots of single-level
speedruns from a great variety of levels, is at
<http://www.planetquake.com/sda>.
The source of all knowledge pertaining to demos of Quake/2 and many
other 3d action games is Uwe Girlich's page on
<http://www.planetquake.com/demospecs>.
Demtool, this program's Quake1 equivalent, is at
<http://www.planetquake.com/qdq/demtool.html>.