Foundational Knowledge
Quake 2 Demo Editing Tutorial
11/98 by Overman

Disclaimer:   It should be stated up front that editing Quake 2 demos with Keygrip2 requires a large amount of physical RAM.  If you don't have at least 128mb of SDRAM, you are likely to experience slow performance, system crashes and extreme frustration.  If you are thinking of doing demo editing on a PC with 48 to 64 mb of RAM (or less), please do yourself a favor and add more RAM before you even get started.  

Acknowledgements:   This tutorial in particular, and the others that will follow, would not have been even remotely possible without Uwe Girlich, who provides the .dm2 specs, and David 'crt' Wright, who created Keygrip2. Thank you both immensely.

First of all, there are some programs and files that you are going to need for all of the tutorials, and for your own demo editing use.  I am also listing some programs and files that I highly recommend getting, as they directly relate to making your demo editing experience easier and more understandable.

Necessary Downloads
     Keygrip2 - Demo Editor URL:  http://www.planetquake.com/keygrip/
  The Little Movie Processing Center URL:  http://www.planetquake.com/demospecs/lmpc-stable/
NOTE: For LMPC, DOS and Win95/98 users will want the file labeled "MS-DOS Binary Archive"
          
Recommended Downloads
  The DM2 Demospecs URL:  http://www.planetquake.com/demospecs/dm2/
     Demoplay URL:  http://www.gibbed.com/demoplay/

Once these things are downloaded and installed, you are ready to proceed.

Now, make sure you have the demo that came with this tutorial, zstut1demo.dm2.  If not, download it here (92 kb).

This is a single player run through of the final level of Quake 2.  If you installed Demoplay, you should be able to simply double click on the demo file, and Quake 2 will launch and play it for you.  In fact, you can even watch a demo from within a WinZip archive by double-clicking on the .dm2 file when the archive dialog box open up.

Go ahead and watch it now, just to get familiar with the demo, since we will be using it as our "guinea pig" for the next few tutorials.

Next, copy the demo file into your LMPC directory where the lmpc.exe file is at (wherever you installed it).  If your version of the install has a \bin\ subdirectory, copy it there instead.  Open an MS-DOS prompt, and go to the directory you just copied to.

If you type "lmpc"  (no quotes) at the command prompt, you will see a list of the command line parameters available for using Uwe's program.  Note that this program will let you examine and edit other types of id demos as well, and allows a great deal of options.  For now, we are just interested in the -s option, for converting a demo to text.  Type the following at your command prompt and hit enter:

    lmpc -s zstut1.dm2 zstut1.txt

This will create a (large) text file named zstut1.txt, based on the contents of the demo file.   Now return to Windows, and open this text file with Notepad or your text editor of choice.  Windows Notepad has a very low file size limit, and will probably not be able to load this file.  In that case, download Notepad Plus (224 kb).  It's a freeware replacement for Notepad, and offers a wide variety of nice features, including the ability to handle large files.

Now that you've got the text file open, you should see the following:

Demos are divided into "blocks" of entity information, which the Quake2 engine uses to know what it should render at any given point in time. Every block in the text conversion is represented by "block {INFO}", where info is the specific entity information.

The first few blocks of a demo are special: they represent an initialization process wherein Quake 2 loads into it's workspace (i.e. your RAM) all the general information and entities it knows it will need. Info I call "general" includes map information, such as name, sky information, cd track, and other data and checksum info. Additionally, the layout for the player status bar is stored here. Entities include player models/skins, vwep models, monsters (in the case of single player), all items and weapons it will need to show for the level, all sounds it will need for the level, all light types it will need, etc. etc. etc. Quake 2 can get most of this information from the map itself, but it will also take into account any items that the player has in his/her inventory. For example, in the demo we are working with, there are not many weapons on the map itself, but because I was carrying every weapon when I began recording, Quake 2 knows to have these available to render.

This "initialization" bundle of info is known as the "precache list," because it is all cached into memory before beginning. When any demo or map loads in Quake 2, you can see the precache list fly through a list of files before depositing you on the map. You can also initiate a precache manually from the console by simply typing "precache."

With the zstut1.txt file open, do a Find search for the text "precache." Your query should point you to a line in the demo that looks like this:

The stufftext command will place text on the console command line, just as if you had typed it yourself. In later tutorials, we will talk about uses for this command when editing with Keygrip2. The \n is a carriage return, so this stufftext command is the equivalent of typing: precache[ENTER] at the console. Everything in our text file that comes before this line is the initialization sequence I described above, also called the precache list. For our purposes, we will refer to this group of blocks as the "Demo Information." When we get started in Keygrip2, you'll see why.

NOTE:   There can be instances where Quake 2 does not know to include certain entities in it's precache list, because they are introduced once the demo has begun. One example is if another player joins in a deathmatch after you have started recording; in that case, Quake 2 will have to precache that player's model/skin info at that time, and the demo will reflect this info at the appropriate block where the player entered. Sometimes modem players will notice a brief moment of lag when a new player joins a server, and sometimes this is because that player is joining with a model that is "new" to that particular game. In zstut1.dm2, I used the "give all" command so the demo could be completed at it's quickest. On most Quake 2 levels, this cheat command will give the player items and/or weapons that might not otherwise appear on that map, and must be cached at the time the cheat is used. However, in this case, I issued "give all" before I began recording, so all weapons and items that a player can have appear in the precache list (demo information) of this demo.

It is also important to note that every entity in a demo receives an index number, and likewise every player receives his own entity number. Understanding this, and how Quake 2 knows which entities to render, will be especially important as we delve into more advanced techniques in later tutorials.


Let's briefly examine the structure of blocks that occur after the precache list (demo information).

NOTE: For the purposes of this tutorial, a client side demo will be assumed. Serverrecord demos have some structural differences, which will be covered in a later tutorial.

Basic Structure: Standard Block of Client-Side Demo

1) Frame

2) Playerinfo

3) Packetentities

There may be other messages which occur, but these are the "Big Three" that MUST be there in a client recording.

1) Frame

This is basically a sequence number, or what I will refer to as a "tick." One of the purposes of the Frame message comes into play when packet loss occurs over the internet; the Frame sequence info helps a client get back in sync with the server when transmission is temporarily disrupted by packet loss.  When connection is resumed, the client can "catch up" with the time (in blocks) that have elapsed while he was gone. For playback, the Frame message also assists in keeping playback speed consistent. It is always the first message in a standard block.

2) Playerinfo

This is your info, the client. It includes your coordinates on the map at that moment in time, as well as the direction you are facing, and other important player-related data. What Keygrip2 does, essentially, is it allows the camera to be "set free" from the client's Playerinfo (position and angle) while leaving that player's movement and direction intact. This message must always immediately follow the Frame message.

3) Packetentities

I won't pretend to know the meaning of every little detail of the Packetentities messages, which always follow directly after the Playerinfo message. But the basic principle of Packetentities is as follows. In a client side demo, Quake 2 does NOT necessarily render all entities on the map. In fact, based on the player position of the client at each block, Quake 2 determines what entities are visible from that position, in a "radius" of sorts. The radius extends slightly beyond what is actually visible at the time, and follows the player as he/she moves around. As the player info changes in each block, Quake 2 updates entity information according to this "radius" of visibility. The reason the radius extends slightly beyond the actual visibility range is to give Quake2 a bit of a protective buffer while it tries to preserve continuity. The idea is that if for some reason entity updating falls slightly behind (i.e. because of lag, or a slower PC), the Quake 2 engine will (hopefully) stay just a little bit ahead of where the player might go.

This updating process in the Packetentities messages involves adding and removing entities accordingly, using a list of Spawnbaseline messages to bring the new entities into the "world" of the player. So in a client side demo, if you are on one side of a large map, and your opponent is on the other, chances are that even though you might hear him, his player model is not at that time being drawn somewhere by your machine. Instead, Quake 2 will wait until he enters your "radius" to render his model... just prior to you seeing him.  Pretty efficient, huh?

There are other messages that can appear later in a standard block. In later tutorials, we will show how to implement these and other messages in your demos.   Here are some to take note of:

sound -This message initiates the playing of a .wav file, which can be an environment sound in the map (like the noise from a fan), or it can be a sound related to an event, like when a player picks up an item. Sounds related directly to player models (i.e. pain sounds, etc.) are handled slightly differently, using a kind of wildcard to determine the path to model-specific sounds.  Player sounds will be covered in more detail at a different time.

print - This sends text to the top line of the screen, such as player death messages and player chat. The print message occurs once to initiate the text, and then that text stays displayed for an amount of time set in certain Quake 2 defaults.

centerprint - This sends text to the center of the screen, and otherwise works the same as print.

stufftext - Mentioned above, this message sends text to the console command line to be executed.  Very useful for specifying the desired viewing settings you would like for your demo, and many other uses.

configstring - These messages handle info sent from the server to all connected clients.  Configstrings are most notable in the Demo Information (precache list) section, where the map name, sky properties, max clients, and map checksum (among other things) are sent out to all clients. During normal gameplay, the server does this for all clients whenever the level changes, and keeps all clients updated whenever a new player joins. Player models/skins are just one of the types of configstring messages.

There are many other message types, but these are the ones which are the most related to future tutorials.  For complete coverage of block structure and all message types, examine Uwe's Dm2 Demospecs.


This concludes the first tutorial on demo editing.  Future tutorials will involve almost exclusively hands-on demo editing techniques with Keygrip 2, and will likely be more exciting than this one.  However, the information contained herein will make your demo editing go a lot smoother.  You have the opportunity at any time to further expand your understanding of the intricacies of the .dm2 format by studying Uwe's demospecs more closely... we've only scratched the surface here.

In the mean time, it might be interesting for you to record your own demos, and analyze them with LMPC.   It's very helpful to be able to look at a text representation of a .dm2 and know (basically) what much of the information represents.

Related to recording, there is a helpful alias available at F176, for easy recording of multiple demos back-to-back.  Click here to see it.  It's a good idea to record yourself playing whenever you can.  You never know when something will happen that you would like to recam later.

The next tutorial will cover getting familiar with some of the features of Keygrip 2, and we will perform some basic recamming steps with the same demo we analyzed here.