ReMaic documentation

Contents

1. Introduction

1.1. What is ReMaic?

(Quake) ReMaic is a utility for changing the camera viewpoint in a Quake demo or movie that you have recorded. It is run from a shell; it doesn't have any fancy GUI.

The program was originally designed and written in order to take normal single-player Quake runs that had been made using the usual console command record, and to reshoot them from a perspective other than that of the player. We used it to make an entry for the QuakeLab Multimedia contest. The result was a movie based on a speed run through id Episode 4, which we called The Elder Whirled. We've since filmed the rest of our run also to make a complete movie journey through Quake, Quake done Quick.

I hope that Quake players everywhere will enjoy using ReMaic to make films of their most interesting single-player and deathmatch demos.

However, I suspect it may be useful for other purposes too. On most Quake movies I have seen, the camera-work tends to be a bit jerky. This is entirely understandable, because they are shot "live" with a human camera-person having to control every aspect of the camera-work. To reshoot a scene from a slightly different angle requires all the actors to regather and re-enact the scene with the camera-person in their new position. That's got to be a real pain. ReMaic should allow a movie originally shot with a Quake-C camera-patch to use alternative camera angles without having to re-enact the scene, and it allows pleasantly smooth camera movement.

1.2. The name

(Quake) ReMaic should be pronounced "(Quake) Remake", for obvious pun-related and rhyming reasons. "ReMaic" is an acronym for "Reshoot Existing Movie, Altering Its Camera." I apologise profusely for this. ReMaic was originally known as CamDem, and is referred to by that name in the text file for The Elder Whirled.

1.3. Availability

The most recent version of the documentation that you are now reading is that on the ReMaic web page. If you are reading a local copy, and having problems, do check the current version since some updates may have been made. You can also check the latest news on ReMaic.

ReMaic can be downloaded as a *.zip file - which contains

1.4. Installation and running

ReMaic is written as a Perl script, not a stand-alone executable. This means you must download and install a Perl interpreter from CPAN in order to use it. I am sorry for this inconvenience, but Perl is a wonderfully useful language that everybody should have on their machines anyway. No, really, it's great. You'll probably find it easiest to download an executable directly from the ports directory at CPAN. Most of you PC-users probably want win32/ActiveState/Release/Pw32i312.exe, but if things have changed at CPAN since I wrote this or you are using a different platform then you'll have to figure out what you need yourself. My honest guess is that if you can't manage to work out how to install Perl, you'll probably have problems working out how to use ReMaic.

ReMaic also makes use of Uwe Girlich's brilliant demo compiler and decompiler, LMPC. You will have to download and install the DOS version of LMPC if you do not already have it. I understand that ReMaic won't work with the Windows version of LMPC. It's the standard DOS version that runs in the shell that you want.

Uwe's server can be a bit unreliable at times, so if you have no luck there, you can download a copy from here instead. But use Uwe's page if you can, since then you can sure of getting the most recent version.

The first time you run ReMaic, it will ask you to tell it where it can find a copy of LMPC on your system if it can't find one immediately. It will remember the location for future runs. If ReMaic seems to have trouble finding LMPC even after you've told it where to look, try putting LMPC and ReMaic in the same directory and deleting any ReMaic.cfg file that has previously been written. If that doesn't work, something has gone badly wrong somewhere.

To install ReMaic, just download and unzip it.

To run ReMaic, you can either either explicitly call Perl on the ReMaic Perl script:

perl -w ReMaic.pl [optional switches] [filename arguments]
or, if you are running on a PC, you can use the very simple included batch-file:
ReMaic [optional switches] [filename arguments]
Under Unix, add the appropriate hash-bang line to the Perl script to run it without explicitly invoking Perl.

For the rest of the documentation, for the sake of consistency, I shall assume you are using one of the latter two methods so that you can invoke ReMaic without mentioning Perl explicitly.

The filename arguments you can give to ReMaic are explained in section 4, and the optional switches are explained in section 6.

1.5. Related utilities

There is another utility that you can use to shift the camera around in an existing demo. The 0.95beta of the excellent Film At 11 has a ReCamera option. If you are reshooting a demo, you may want to consider using this instead or as well as ReMaic.

What are the differences?

Well, you should note that currently ReCamera only allows you to give the camera to an entity already in the demo. This could be a player, or a monster, or a projectile - but you won't be able to move the camera as if it were a new entity altogether as you can in ReMaic. The camera aiming is also less flexible.

However, ReMaic is a reasonably complex shell utility, whilst Film At 11 has a nice GUI and is very straightforward to use. If you want to do something fairly simple with the camera in your demo, you may find it to be your best option. As always in computing, use the right tool for the right job!

Be sure to check the next release of Film At 11, which may feature interactive re-recording. Now that would be cool!

2. ReMaic basics

When you use the Quake engine to record a demo, it notes down the important events in the world surrounding you. These include the positions of other entities, the sounds that are played, and other assorted effects. The demo also notes the direction you were looking in. On playback, Quake remodels the world from the list of events that it has and displays it from the recorded perspective, using the game engine to render the scene just as if you were there for the first time.

This means that we can change the perspective from which a demo is seen quite easily, since the events themselves that make up the demo are not very dependent on your perspective when you recorded it. (But note that there is some dependency.)

ReMaic adds a new viewing entity to an existing demo. I shall call this entity the camera. It then sets the perspective from which the events in the reshot movie should be shown to be that of the camera. This perspective is determined by two main variables:

ReMaic reshoots a demo by taking a list of timed instructions that tell it how to move the camera and how to aim it (i.e. how to move its target.) This list of instructions is contained in a file *.cam which I will refer to as a screenplay.

Most instructions in a screenplay either affect the camera position, or the camera target. There are also one or two other instructions as well.

3. Screenplay instructions

Each instruction in a screenplay is labelled with a time at which it should occur. When ReMaic reshoots a movie, it checks the time that is associated with each frame of the existing movie, and it activates a new screenplay instruction as soon as the time in the movie reaches (or passes) the time that labels the instruction in the screenplay.

You can also include comments in screenplays by preceding them with a hash # character. A screenplay file is thus made from lines of the form

time instruction # optional-comment
This syntax is best understood by looking at an example.

3.1. Controlling the camera position

There are two instructions that control where the camera position is.

3.1.1. stay

This instruction tells the camera to remain at some specified position.

3.1.2. move

This instruction tells the camera to start moving smoothly towards some specified destination position.

Understanding the distinction between the stay instruction (which tells the camera to be somewhere) and the move instruction (which tells the camera to start going somewhere, arriving at a certain later time) is the key to writing screenplays that do what you want them to. There are many illustrations of the use of these instructions in the example file.

3.2. Controlling the camera target

There are three instructions that control where the camera target is. The first two are directly analagous to stay and move except that they control the camera target rather than the camera position. The third is a special effect for use when the second does not produce appropriate behaviour.

3.2.1. view

This instruction tells the camera target to remain at some specified position. In other words, the camera stays aimed at that position.

3.2.2. pan

This instruction tells the camera to start smoothly moving the target point at which it is aimed towards some destination. In other words, the camera aim will move to the new position over a period of time.

3.2.3. turn

This instruction tells the camera to start smoothly changing the angle at which it points in order to end up pointing at some target.

3.3. Positions

As should be clear from reading the above, positions in ReMaic that a camera may stay at, move to, view, pan or turn towards are quite flexible things. They can be static, or they can move relative to some other entity. I now describe the exact forms that positions may take.

Every position is made up of three co-ordinates. In ReMaic, each co-ordinate is specified by a separate expression. If only one expression is given, rather than three, then this just means the same expression should be used for all three co-ordinates. This just allows us to abbreviate long commands such as, say, move p~0.3 p~0.3 p~0.3 to the shorter but equivalent move p~0.3.

3.3.1. Absolute positions

The simplest kind of expression for a co-ordinate is an absolute value. This is a just a real number; it may be a decimal fraction. For example, 23.6 100 -30 specifies an absolute position.

To find the co-ordinates of an absolute position which you want to use, you must run Quake on the map in question and then move to the position using whichever cheats and so forth you desire. Then, type edict 1 in the console. This will give you the various statistics for entity 1 - that's you, the player. One of these will be your origin, which is where you currently are. That will give you the co-ordinates you require.

Sometimes you will want to refer to the current value of some co-ordinate, which may be calculated from a complicated expression whose value changes over time, as an absolute, unchanging, static co-ordinate. You can use the expression now for this value. So, for example, stay now will stop the camera wherever it is. (Of course, this instruction is an abbreviation for stay now now now, which specifies the current x, y and z-coordinates.)

3.3.2. Positions relative to entities

Often you will want to specify a position that is relative to some Quake entity. The most common example is the player who recorded a single-player demo, but other entities such other players, monsters and weapons can also be used. The expression en, where n is an integer, represents the appropriate co-ordinate of entity n. p is an abbreviation for e1 since entity 1 is always the player in a single-player game.

Thus to aim the camera at the player, you would say view p. This instruction (which is short for view p p p, representing the current x, y and z-coordinates of the player) will make the target of the camera be the origin (or position) of the player. Whilst this instruction remains active, the camera will now turn to point at the player wherever they may go.

Sometimes you want to talk about not where some entity is, but where it was some time ago. You can do this by adding the suffix ~t to the entity expression, where t is a time as a real number of seconds. Thus, for example, e14~0.3 is the appropriate co-ordinate of entity 14, 0.3 seconds ago.

(ReMaic won't look into the future, since it processes a movie as it reads it. Thus you can't refer to where an entity will be in a certain amount of time. Maybe one day a future version will enable this feature.)

The main use for the ~ construct is for creating the sort of shots that are associated with filming patches known as chase-cameras. If you set the camera target to be the player (with view p) and set the camera position to be where the player was, say, 0.3 seconds ago (with stay p~0.3), then the camera will chase the player and keep them in view. Many demos look pretty good with a screenplay file that simply has those two instructions at time 0 and nothing else.

This simple chase-cam will fail to behave nicely in two circumstances. One is where the player doubles-back or stands still. In this case, the camera may end up moving through the player, which can produce an ugly effect, or even coinciding with the player, which looks very strange. The second problem occurs when the position of the player changes instantaneously, for example because they have teleported. The delay until the chasing camera catches up can cause odd things to happen in the mean time. You should use other instructions to say what you want the camera to be doing during those kind of occasions.

One thing you may be wondering is how you can find out what number a particular entity in your demo has. Maybe you want the camera to look at a particular zombie at one point - how do you find out what its number is?

The easiest way to do this is to have a look at the *.ls file that LMPC produces for your demo and that ReMaic actually uses to process the movie. All entities will be spawned during the first frame with a spawnbaseline message, and LMPC annotates these with the names of the models that are used for them. So you'll want one of those entities whose model is annotated with the filename zombie.mdl.

To find out which zombie is the one you're interested in, you'll have to work a bit harder. The best way is to note where it is at a particular time, find out the co-ordinates of that point, and then see which zombie entity is closest to those co-ordinates at the time in question within the demo. This requires a little bit of technical nous, and some common sense detective work and some patience, but that's the way it is at the moment. You shouldn't be playing with individual entities unless you understand these *.ls files a little bit, basically.

3.3.3. Final displacements

Any co-ordinate expression can be modifed by a final absolute offset. Thus a x-coordinate of now-100 is 100 units behind the current co-ordinate. I find that a chase-cam that is also slightly above the player gives nicer results than one directly behind them. So I often use a position of p~0.3 p~0.3 p+30 or similar for my chase-cameras when I film things.

3.4. Other instructions

There are two other types of instruction that you can use in a ReMaic screenplay.

3.4.1. eyes

The instruction eyes sets the perspective used in the reshot movie to be the same as that in the original demo. The camera and target will continue to be updated, but they will not be used until the next instruction that controls the camera position.

On a normally recorded demo, this will return the view to the usual first-person perspective, with the weapon reappearing in front of you and the "jogging" up and down effect that you are used to.

You should probably move the camera in to catch up with the player using an instruction like move p~0.05 before using an eyes instruction so that the cut between the two perspectives is fairly smooth.

3.4.2. text

This instruction is anomalous in that it has nothing to do with altering the camera position, but it seemed an appropriate item to include in a screenplay nonetheless.

So, the text instruction provides an easy way to add text messages and other simple effects to a demo at particular times. You just provide the instruction text, the name of an LMPC-recognised message (such as centerprint or print) and a quoted string. So

text centerprint "Hello mum!\n"
would print that message in the centre of the screen.

You can run arbitrary console commands in this way by using a simple but grubby hack; just make the text command be stufftext, which is a message that can be used to pass arbitray commands to the console whilst a demo is playing. So, for example,

text stufftext "bf;\n"
would cause the familiar brief flash effect to occur.

4. Command line arguments

ReMaic can take two optional command line switches, /i and /t, that precede its regular filename arguments. Their uses are explained in section 6.

Otherwise, ReMaic can be called with up to three filename arguments. It needs an original demo as input, a file to use as a screenplay, and a name for the output, which will be made by reshooting the original demo using the screenplay. It tries to use sensible defaults if it is not given all three arguments. If you do not provide extensions in the filenames you give, it again tries to use sensible defaults.

ReMaic works with demos in *.ls format - these are text listings that are produced by LMPC as a result of decompiling the binary *.dem file format that Quake uses. ReMaic first looks for an *.ls file that matches the input you give it. If it doesn't find one, it looks for a *.dem file and calls LMPC to decompile it. Once it has produced an output file, also in the *.ls format, it calls LMPC to recompile this file into a binary *.dem. Finally on the extensions front, screenplay files have the extension *.cam by default.

Calling ReMaic with no arguments gives some immediate help on the syntax needed to invoke the program and the syntax used in screenplay files.

Calling ReMaic with one argument:

ReMaic input
means it will try to use input.cam as a screenplay file, converting an original demo input.ls to produce a reshot demo out.ls which LMPC compiles to make out.dem.

Calling ReMaic with two arguments:

ReMaic input camera
means it will try to use camera.cam as a screenplay file, converting the original demo input.ls to produce a reshot demo camera.ls which LMPC compiles to make camera.dem.

Calling ReMaic with three arguments does what you expect it to:

ReMaic input camera output
means it will try to use camera.cam as a screenplay file, converting the original demo input.ls to produce a reshot demo output.ls which LMPC compiles to make output.dem.

5. An example

All those complicated alternatives probably have you feeling a bit lost by now. But with any luck, inspecting the example screenplay provided, and running the demo it works on and the movie it produces, will make everything a lot clearer.

The original demo is a recording of Yonatan Donner completing E3M2 (The Vaults Of Zin) in the brilliant time of 0:58. (Although you should not be misled into underestimating his prowess, since he has completed it even quicker since then.)

I took a screenplay that he wrote to film this demo, fiddled with it a bit to show more of the possible effects, and added lots of commentary in order to demonstrate how you can combine all the above instructions to make a nice screenplay that produces a great movie.

The original movie is named original.dem, the camera file is named example.cam and the reshot movie is example.dem. You could produce the reshot movie from the original by calling the program as follows:

ReMaic /i original example

6. Other issues

6.1. The stage is all the world

When Quake records a demo, it does not record every event that happens anywhere in the level. The events it records are those that are visible from the VISibility leaf in which the player doing the recording can be found. It can be difficult to know for sure precisely what this will include and what it will leave out. However, a good approximation is that it includes anything that the player could see by looking in any direction from their current position, and also to some extent round the corners of any openings that are visible.

If you move the camera too far away from the viewpoint of the original demo when you use ReMaic, especially if you go around corners so that you can longer see the player who made the recording, then you may see entities appearing from and disappearing into thin air as they move into and out of the recording player's VISibility leaf, causing their positions to start or stop being recorded in the original demo.

This doesn't happen very often, because normally you will want to film the same events that were seen in the original demo! But it is something of which you should be aware. If you notice the problem occuring, the obvious and only solution is to change the camera view so that the entity that is affected is no longer in the picture.

6.2. Intermissions

If you are filming an existing normal demo (rather than a specially created movie) with ReMaic, then it may contain an intermission. The Quake engine behaves a little strangely during an intermission - it always displays the picture from the angle that is used by the standard intermission viewpoint, no matter what the demo is instructing it to do.

For this reason, it is normally a good idea to switch back to the normal demo view with the eyes command when the intermission starts. If you run ReMaic with the /i (intermission) switch, this will happen automatically. ReMaic gives a warning if it notices an intermission where this action has not been performed.

If you want, you can still move the camera around during the intermission - it's just that whatever you tell ReMaic to point it at, Quake will always use the angle used in the original demo when it plays back.

6.3. Exact timing

In order to work out the precise times after which you want screenplay instructions to be activated, you will probably want to change host_framerate from the console when you play a demo in order to slow it down and give you plenty of time to make notes. I advise setting up some of the function keys to perform various slow-motion and fast-forward effects on the speed that the Quake world runs at. The PlanetQuake demo page has a nice summary of how to set this up.

Even so, the clock on Quake only displays times in whole seconds, and one would often like to know what the time is to a greater degree of accuracy. In order to do this, run ReMaic on a movie with the /t (time) switch. This will print a running timer at the centre of the screen throughout the movie it produces, which will let you read off the exact times as you require if you then play the movie in slow-motion.

6.4. Entity 449

The camera is inserted into the demo as entity 449, since I believe that this is the last available dynamic entity in the game. However, it is plausible that some demo might want to use this entity for something else.

If this does occur, and you want to fix the problem yourself, it should be very easy: just find an unused entity number and modify the Perl script ReMaic.pl so that the constant $CAMERA is set to be this other number, rather than 449. This initialisation occurs very near the top of the script.

7. Credits / Boilerplate

ReMaic was written by Anthony Bailey, and I guess that means it's his copyright 1997 and so forth. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.