================================================================
Title                   : Demix

Filename                : demix.exe - MS-DOS binary
                          demix.txt - This file
                          example1.dem
                          example2.dem
                          example3.dem

Author                  : Stefan Schwoon

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

Description             : Demix is a program used to edit Quake demos (.dem
                          files). It enables you to do some sorts of entity
                          manipulation, especially transferring entities from
                          one demo into another. (Demix is a compound from
                          "demo" and "mixing", you see.) This opens the door
                          to a wide range of possibilities - you can extend
                          the lifetime of entities, produce fake multiplayer
                          demos and other things. Also, there are special
                          features to process multiplayer cooperative demos.
                          See below for detailed information and instructions.

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

Additional Credits to   : Anthony Bailey and Yonatan Donner for suggestions.
                          
================================================================

Instructions:

An important note first: Demo editing is a complicated matter,
so expect Demix to be a reasonably complicated tool. I took no
provisions to make this "user-friendly" - this is a "you asked
for it, you got it" kind of program. Please get the basics of
demo editing down first, read the DEM specs (see bottom of doc-
ument) and *please* don't ask me questions like "What's an en-
tity?" or "What's an updateentity message?" Also, always work
from backup copies of your demos in case something goes wrong.

That said, here's the instructions proper:

Demix' purpose is to add entities to (part of) a Quake demo. These
entities can be created on the fly, or be copied from other parts
of the same demo or even from a completely different demo.

Until now, there have been two kinds of uses to this (I'm sure you'll
come up with others):
- If you refilm a demo with Remaic (see below), you will sometimes run into
  trouble. When recording, Quake reduces the information stored in a demo to
  the entities (player, items, monsters, doors etc.) that are in the poten-
  tially visible set as seen from the player's position. Imagine the following
  situation in a remaid demo:

  The player (p) ran along the upper part of a U-shaped corridor. He could see
                        the upper part of the hallway and the turn, but he could
     /------p--e1--     not look into the lower part. Thus, at this time, infor-
    c                   mation about entity1 (e1) was stored in the demo while
     \---------e2--     entity2 was left out. The camera (c) introduced by Re-
                        Maic, however, sees both parts of the hallway - but
  since entity2 does not appear in the demo, it will not be displayed. Only
  when the player reaches the U-turn, both entities come into his viewable
  area - and so entity2 will suddenly appear out of nothing. This looks wrong,
  and even if you don't notice it consciously, your subconscious will. You
  should always try to fix these problems, and while previously the only way
  was to rewrite the Remaic script, with Demix you have an alternative: Add
  entity2 during the time that the player could not see it!

- Also, you can transfer stuff from one demo into another, e.g. produce
  fake multiplayer demos. If you saw QdQlite (see below) and wondered how
  the scenes with George were put into the speed-runs, Demix is the answer.
  (Of course, note that Demix was never used to create false impressions
  about the actual running!)

Lately, people have come up with a very cool variation on speed-running:
Cooperative speed-demos. (You can find examples at the Speed Demos Archive,
see below for the URL.) I have added switches to Demix that I believe will
facilitate advanced production work on demos of this kind.

----------------------------------------------------------------

In the following, I'll first explain the functionality of Demix briefly,
and then give some examples of its usage.

Demix is a command line tool. Invoke it from the DOS prompt. Demix will
work in one of several modes, depending on the arguments you give it on
the command line. The modes of operation are as follows:

Printing:       demix demo from:to
        This will cause demix to output the numbers of all entities
        that appear in the demo in the given range (from and to are
        given in seconds), along with the name of their model.

        You can use this to see which entity number belongs to which
        item. (.dem will automatically be appended to the name of
        the demo if not supplied.)

Adding:         demix demo from:to entity_1 ... entity_n
        In this mode, demix will add updateentity messages for the
        specified entity numbers (in the time between from and to)
        if they are not already there.

        Use this to add immobile objects (like health boxes, ammo
        boxes, armor) to a demo. Since the added messages look like
        this (updateentity { entity x; }) you *might* end up with
        items hanging in the air - in that case, use mixing instead
        (never happened to me so far, though).

        Entity_i can have the form x-y where x and y are entity numbers.
        In that case, all updateentity messages of entity number x will
        be renumbered to y. Additionally, spawnbaseline information of x
        will be duplicated for y.

Mixing:         demix demo1 from1:to1 demo2 from2:to2 [entity_1 ... entity_n]
        Now, demix will extract the entities in demo1 (in the associated
        range) and add them to demo2. You may omit to1, it defaults to
        from1+to2-from2; similarly, you may leave out to2, but not both
        of them at the same time. For each frame in demo2, the program
        looks at the corresponding frame in demo1 and the entities in it.
        For "static" entity numbers (those with a spawnbaseline, like
        monsters, items, doors etc.), an entity will be copied if it does
        not occur in demo2. For "dynamic" entity numbers (those without,
        like grenades, nails, gibs etc.), an entity will be copied in any
        case and it will be renumbered to the first free entity slot.
        For "static" entities, spawnbaseline information will be copied
        from demo1 to demo2 if it does not already exist in demo2.
        If you give entity_1 ... entity_n, only those entities will be
        copied. Note that demo1 and demo2 can be identical!

Copying client-related data:
                demix -c demo1 from1:to1 demo2 from2:to2
                demix -a demo1 from1:to1 demo2 from2:to2
                demix -d demo1 from1:to1 demo2 from2:to2
        You may combine as many of these switches as you wish, e.g. like
                demix -cad demo1 from1:to1 demo2 from2:to2
        Demix -c copies replaces clientdata messages of demo2 with those
        of demo1 in the given time ranges (clientdata messages contain
        information visible on the status line as well as the currently
        held weapon etc.). Demix -a does the same to the angles the player
        looks at, and Demix -d is for damage messages that occur when the
        player is hurt and cause the screen to twist and turn red from pain.

Changing the viewing entity:
                demix -v entity demo from:to
        Quake demos are always shown from the position of one particular
        entity - in single player demos, this is the player (entity #1).
        Demix -v can change this: It inserts a setview message at time
        'from' that gives the view to the 'entity' given on the command
        line and adds another message at time 'to' to restore the view
        to the old setting.

Removing:       demix -r demo from:to entity_1 ... entity_n
        In the time interval given by 'from' and 'to', remove
        all updates for the entity numbers specified by entity_1
        through entity_n.

----------------------------------------------------------------

Example:

Watch example1.dem. It's the remaid version of a simple recording of e1m5.
The camera is in the small cave near the start all the time. The player
enters the cave at 4.2s(*). Up to that moment, the items in the cave (nailbox
and megahealth) are not visible - they turn up the instant the player sticks
his head out of the water. This is because in normal Quake, water is not
transparent (unless you're blessed with GL), so the player could not see the
items, so they were not stored in the demo while he was submerged. Since items
popping out of nowhere look strange, we want to have them in the demo all the
time. How to do this? There are at least two possibilities (you may want to
backup the demo before applying the instructions below):

  Use "print mode" to look up the entity numbers of the items:
        demix example1 4.2:4.3
  This lists all the entities occuring between 4.2 and 4.3 seconds. The
  exact range is not so important, as long as it's a period where the
  player is always above water. You will get the following output:
        entity   1: player
        entity 275: b_bh100
        entity 283: b_nail1
        entity 449: eyes
  Aha. So the megahealth is entity number 275 and the nailbox is number 283
  (the others are the player and the camera in this case). Now, we'll add
  them to this demo:
        demix example1 0:4.2 275 283
  So, we added both items to the demo, from the start until the time when
  the player enters the cave. Play the demo and see the result. For a change,
  try the following:
        demix example1 0:6 275 283
  Here, we extended the period where the items should be added. The result
  is the same: Items won't be added a second time if they are already there.
  The moral out of this is: It doesn't hurt to extend the range of time when
  you're not sure. Better make the range too large rather than too small.

  The second possibility goes like this. Restore the original example1.dem
  (you did make that backup, didn't you?) and type this:
        demix example1 4.2: example1 :4.2
  This is an example of mixing: The part between 4.2s and the end is copied
  to the part between the start and 4.2s. Watch the result. Note that again
  only the nailbox and the megahealth were copied - the player and the camera
  are in the demo all the time! Thus, the above was (in this special case)
  equivalent to
        demix example1 4.2: example1 :4.2 275 283

(*) How did I get the exact time when the player surfaces (it's 4.203 to
    be even more exact)? Either inspect the demo with a more user-friendly
    demo editor like KeyGrip, or produce an .ls text listing with lmpc or
    demtool (see below where to get all these programs), but the way that
    I prefer is to use "demtool -t" on the demo which centerprints the
    current time on all frames, i.e., do
        demtool -t example1 examplet
    and then fire up Quake and playdemo examplet in slow motion (i.e.,
    change host_framerate).

Ok, this was easy after all, wasn't it? :)
Let's get on to the (seemingly) more complicated stuff.

----------------------------------------------------------------

Another example:

Consider example2.dem and example3.dem. They are both (rather dull)
demos of me running through dm4. They also have almost exactly the
same duration which will make the following examples a bit easier.
So what we're going to do is to insert the player from example2.dem
(the one doing the rocketjump) into example3.dem (the one who's just
watching from the highest ledge). Please backup both demos before
trying the following examples, you'll need them more than once.

Let's try the simple approach first:
        demix example2 : example3 :
What does this mean? Well the ':' mean both start and end time are
omitted, so start and end of the demo are assumed. So the whole command
means "copy all entities from example2 into example3, over the complete
duration of the demos". Or rather, don't copy all the entities, but only
those that are not already in example3.

Play example3.dem. That's not too great, is it? Only one new explosion
sprite and some nails, but where's the player?

Read the above description about "Mixing" carefully. It said that "static"
entities are only copied if they don't already occur in the target demo.
Since the player is entity number 1 in both example2 and example3, he simply
wasn't copied to example3!

So, this didn't work. We'll have to use renumbering instead. Restore your
backups and do the following:
        demix example2 : 1-2
This renumbers entity 1 (the player) to entity 2 (i.e., his spawnbaseline
information is copied, and all updateentity messages are changed). Example2
will not play back properly after this change since setview is not updated.
Now, we're ready:
        demix example2 : example3 :
This time, it works, since entity number 2 was not occupied in example3.

There's yet another approach to this that will not invalidate, or even
change, example2.dem. Restore your backups and type the following:
        demix example2 : example3 : 1-2
See? This copies the player (entity 1 in example2) into example3 and
at the same time renames and copies his spawnbaseline information into
entity 2. Example2.dem is not changed. Play back example3. Oh, the ex-
plosion and nails are still missing.
        demix example2 : example3 :
Now they're in!

I hope you could gain some insight from these examples.

----------------------------------------------------------------

Possibilities for multiplayer speed-runs:

Cooperative multiplayer demos are a fascinating new twist on the
speed-running genre. Multiple people join a game, and then divide
the work among each other to finish the level as fast as possible.
One or several players record the action from their point of view.

But often, watching the demo of one player does not make obvious
the amount of cooperation required to get an optimal time. I gave
some thought to the means by which multiplayer demos could be re-
presented, to the problems that stand in their way and included
some features in Demix that can cope with them.

So far I could think of three ways to represent these runs:
- Multiple first person perspective demos: the unedited demos from
  each player's perspective. Pros: No editing necessary, no infor-
  mation is lost, and it's the most important form of distribution
  for other speed runners. Cons: Requires more diskspace (several
  100k for each member of the team), need to watch the same run
  several times to understand it (this would be tedious in a QdQ-
  style episode-length run).
- First person perspective demo with switched views: Distribute one
  demo, and during the run, switch the view to the person who has the
  most interesting view in each phase of the run. Pros: easy to make,
  takes less diskspace, enables better understanding of cooperation.
  Cons: Loss of information, switching may irritate the watcher.
- Camera perspective version: Write a Remaic script and film the
  action. Some of the advantages and disadvantages of the previous
  suggestion apply here, too. Apart from that, remaid demos are gor-
  geous to look at, but they take a lot of time to make.

Here's what Demix offers to support this:
- Multiple first person perspective demos:
  No need for Demix here.
- First person perspective demo with switched views:
  Have every member of the team record a demo from his point of view.
  Let's assume the demos are named p1.dem, p2.dem and so forth. Backup
  the originals. Then, mix all entity information these demos contain
  into one demo:
        demix p2 : p1 :
        demix p3 : p1 :         (assuming a third player)
        ...
  This alone will not change the appearance of p1.dem. Now let's assume
  you want to show player 2's actions from 0:10 to 0:15, and player 3's
  actions from 0:20 to 0:32 seconds, and show player 1 the rest of the time.
  Easy: say
        demix -cad p2 10:15 p1 10:15
        demix -cad p3 20:32 p1 20:32
        demix -v 2 p1 10:15
        demix -v 3 p1 20:32
  Play p1.dem. Note how the stats of the individual players appear in the
  status bar when it's their turn (that's because we used -c).
- Camera perspective version:
  Again, mix all entity information into one demo first:
        demix p2 : p1 :
        demix p3 : p1 :
        ...
  Then, write a Remaic script for p1.dem. Due to the previous step, all
  players and their surroundings occur in the demo, even if they have been
  apart from player 1 during recording. That means that you are not limited
  to keeping the camera in the vicinity of player 1 any more!

  When you have finished your cinematic masterpiece, you will notice that
  the statistics displayed in the status bar are still those of player 1.
  If you'd rather change it so that the status bar displays the stats of
  the player currently focused on by the camera, you can go an additional
  step further. Assuming that again, the camera shows player 2 between 0:10
  and 0:15 and player 3 between 0:20 and 0:32, take the not-yet-remaid p1.dem
  and say
        demix -c p2 10:15 p1 10:15
        demix -c p3 20:32 p1 20:32
  Note that angles, damage and setview messages are left out this time because
  they are changed/removed by Remaic, anyway. Now remaic p1.dem and enjoy!

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

Version history:

26.01.98: initial public release

02.03.98: added multiplayer features

17.05.98: added -r switch

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

* 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 Demix homepage is at <http://www.planetquake.com/qdq/demix.html>.
The latest version of this program can be obtained from cdrom.com or a mirror,
or at <http://www.uni-hildesheim.de/~ssch0098/demix.zip>.

* Related websites *

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

Demtool is at <http://www.planetquake.com/qdq/demtool.html>.

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

The Speed Demos Archive, featuring a lot of single-level speedruns
for both Quake and Quake2 is at <http://www.planetquake.com/sda>.

