Conversion/validation tool for Quake1 demo files
================================================

BACKGROUND

Enhanced Win/GL/NehQuake can playback any standard Quake1 demo (protocol 15), but records demo
files in its own native format (protocols 10000-). A demo in this format cannot be played back in
a standard Quake1 engine. Main reasons are enlarged message sizes and support for more models.

ConvDem is a demo conversion tool that tries to fix that. It attempts to convert the demo file
into standard format. The converted demo might still not be playable in a standard engine due to
capacity problems, e.g. the actual map is too large or the demo contents might cause overflow.

ConvDem can limit max message size in any standard or Enhanced Win/GL/NehQuake demo file. This
can be useful if the engine aborts with error "Demo message > MAX_MSGLEN". Conversely, it can
convert only the protocol without limiting message size.

ConvDem can also limit max # entities in any standard or Enhanced Win/GL/NehQuake demo. This
can be useful if the engine aborts with error "CL_EntityNum: x is an invalid number".

ConvDem can convert Nehahra 3.05 or later demos (using Neh1000x protocols) into older Neh15
protocol. Nehahra 3.04 or older demos (using Neh15 protocol) can be converted into standard
protocol 15 format.

ConvDem can convert JoeQuake demos that in rare cases (e.g. Bastion, Castle Necrosis) contain some
Nehahra info into standard format. It can also convert some TomazQuake derived demos.

ConvDem can fix the often invalid view angle during intermission/finale.

ConvDem can join several demos into one if the protocols are the same.

ConvDem can also validate any standard or Enhanced Win/GL/NehQuake demo file. Only the demo
structure is validated, not all values in the demo. When validating, no conversion will be made.

==================================================================================================
QUICK START

To convert a demo named "demofile.dem", just enter the command "convdem demofile", and press 'Y'
to start processing. The output is written to a file named "demofile.out", i.e. the original demo
file is NOT changed.

==================================================================================================
COMMAND SYNTAX

The full command syntax is :

convdem [conversion options] [file selection options] demofile [demofile ...]

Conversion options :

-a  : fix intermission/finale view angle (no other change)
-eN : max entities allowed (default N = 600) (no other change)
-f  : force processing even when error found
-j  : join demos into one (no other change)
-k  : do not update date/time stamp in files
-l  : only limit message size in conversion
-m  : monitor log, will force quiet and validate mode
-n  : partial Nehahra conversion, prot 15
-o  : partial Tomaz conversion, prot 15
-p  : only convert protocol; no size limit
-q  : inhibit progress information (to speed process)
-v  : validate only; no conversion

All options in each group should be kept together (no spaces), but the order is not relevant. E.g.
to inhibit progress and also validate, the command could be "convdem -qv demofile".

If validation option is used, no conversion is made. Also, if nothing is done there is no output
file. If message/entity limit, join or Nehahra/Tomaz options are used, protocol remains unchanged.

The standard demo file extension ".dem" is automatically added to the supplied filename(s) and you
can enter multiple files and wildcards (e.g. abc*).

==================================================================================================
NOTES

ConvDem does NOT change anything in the original demo file; the output is written to a file with
the same name as the demo file but with the extension ".out" instead.

After processing, ConvDem will print out more or less information depending on the selected
options. Default it will print a summary of # processed messages, max message size, # entities,
protocol and whether data was lost in the conversion. When detecting Nehahra/Tomaz contents, it
will be indicated as a prefix, e.g. "Neh10002", "Neh15" or "Tom15". Beware that in monitor mode,
ConvDem may generate a huge amount of printouts. Use standard redirection to capture to file.

When limiting max message sizes, the limit is the standard Q1 format; 8000. When messages are
split, events may be invalidated by the engine due to timing logic.

When limiting entities and not specifying a value, the limit is the old standard; 600. When
specifying a value, it must follow immediately after the option character, e.g. "-e1000". Usage
together with other conversion options could be e.g. "-e1000fk", "-ke1000f" or "-fke1000".

Conversion/validation of Nehahra/JoeQuake protocol 15 demos is made by adding the "-n" option.
The specific Nehahra entity information will then be removed/parsed. This has been verified with
JoeQuake version 0.14b839.

Conversion/validation of TomazQuake demos is made by adding the "-o" option. The specific TQ
entity information will then be removed/parsed. This has been verified with TomazQuake version
1.48.

Using the "-p" option can be useful for playing the demo in another engine that also has high
message size limits (e.g. DarkPlaces).

When fixing the intermission/finale view angle, there is no check for already patched demo.
Patching it again usually doesn't cause any problems, but should be avoided.

ConvDem can always be aborted by hitting Ctrl-Break.

==================================================================================================
FILE SELECTION OPTIONS

There are a lot of file selection options, but maybe the most important one is "-i" that removes
the need for the confirmation for each file. E.g. to inhibit progress, validate and disable
confirmation, the command could be "convdem -qv -i demofile".

More info can be obtained by running ConvDem without any parameters.

==================================================================================================
CHANGES

The changes are as follows :

ConvDem 1.4 (May 12 2007)

1. Added possibility to join demos via option "-j" if the protocols are the same. The output file
   will have the same name as the first demo, but with extension ".out".


ConvDem 1.3 (Mar 12 2006)

1. Added possibility to limit # entities in demo via option "-eN". Without the option, there's no
   limit and adding just the option "-e" will set the limit 600. Adding the option with a number
   (e.g. "-e1000") will set that limit.


ConvDem 1.2 (Jan 21 2006)

1. Added support for protocols 10001/10002 (Win/GLQuake 1.30, NehQuake 3.05). Conversion of
   Neh1000x demos into Neh15 is made with the normal conversion. Neh15 can then be converted to
   standard protocol 15 as before using the "-n" option.
2. Improved handling when converting protocol 1000x demos with excessive models (> 256).
3. Fixed bug when using "-a" in a demo where the player isn't entity 1 (e.g. coop/dm). Now it will
   use the entity that is specified in the first setview service found in the demo.


ConvDem 1.1 (Jul 3 2005)

1. Changed so finale screen will also get its view angle fixed when using "-a".


ConvDem 1.0 (Jun 7 2005)

1. First version.

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