================================================================ 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 ... [-o ] 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=: 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=: Play another demo after this one This simply put a stufftext "demomap \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[=]: 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[=]: Set handedness or remove hand cmds If is not given this merely removes all commands that set your handedness. Otherwise, the demo's handedness is additionally set to the value of . -range=: 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[=]: 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[=]: Set the player's fov value Sets the fov used in the demo. Default value is 90. -stats[=]: 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 . * Related websites * Quake done Quick, the Quake speed-running project, can be found at . Speed Demos Archive, QdQ's sister site featuring lots of single-level speedruns from a great variety of levels, is at . The source of all knowledge pertaining to demos of Quake/2 and many other 3d action games is Uwe Girlich's page on . Demtool, this program's Quake1 equivalent, is at .