FuhQuake Homepage : http://www.fuhquake.net/
FuhQuake Autor    : A Nourai aka 'fuh' (#fuhquake on Quakenet irc)
FuhQuake Forum    : http://www.fuhquake.net/forum/


------------
INTRODUCTION
------------
This file documents the match tools available in FuhQuake.  A summary of the
match tools available are:
*) Auto demo recording (on compatible servers).
*) Auto console logging.
*) Auto screenshot taking of final scoreboard.
*) Customising the names of all the above.



------------------------------
SECTION 1. AUTO DEMO RECORDING
------------------------------

1A. COMPATABILE SERVERS
-----------------------
FuhQuake's auto recording only works on compatible servers. Kteams, and
ktpro server are all compatible.  OZTF (v1.45 and above) servers also work
when in clan mode.


1B. VARIABLES
-------------

match_auto_record (Default: "0")
--------------------------------
Description : When set to 1 or 2, a temp demo will automatically be recorded
              when a match starts (usually when the countdown starts).
              match_auto_record 2 automatically saves the demo after the match
              is completed. 'match_auto_record 1' requires manual saving (see
              the "match_save" command below).


match_auto_minlength (Default: "30")
----------------------------------
Description : When using 'match_auto_record 2', temp demo's auto recorded won't
              be saved automatically if they are shorter than the number of
              seconds 'match_auto_minlength' is set to.  If a temp demo is too
              short to autosave, you can still save it manually with
              "match_save" (see below).


match_auto_spectating (Default: "0")
------------------------------------
Description : When set to 1, auto recording will also occur when in spectator
              mode.


demo_dir (Default: "")
----------------------
Description: This is the default location easy recorded and saved auto recorded
             demos will be saved to.  It is relative to your basedir.  If it is
             "" then the demos will be saved to your current gamedir (default
             qw behaviour).  It's recommended setting this to something like
             "qw/demos/recording" to have your demos put into
             c:\quake\qw\demos\recording .  Note that this only affects easy
             recorded demos and saved auto recorded demos.  It does not affect
             demos recorded with "record" (these go into your gamedir).



1C. COMMANDS
------------

match_save
----------
Description : If you are using 'match_auto_record 1' then a temp demo will
              be recorded to c:\quake\fuhquake\temp\_!_temp_!_.qwd each time
              a map starts.  This temp demo will be overwritten when the next
              match starts.  If you want to keep the temp demo, use
              the "match_save" command.  This will move the demo to the same
              folder and filename that easyrecord would have used.


match_forcestart
----------------
Description : Simulates the start of a match (so that auto recording etc is
              triggered).  Useful if you join a ktpro server after countdown
              has started, or you are playing a mode that doesn't have a
              proper countdown (eg race mode).

              Most importantly this is useful for tf servers, since you can use
              a msg_trigger to execute match_forcestart on "MATCH BEGINS NOW".


1E.  COMMAND LINE PARAMETERS
----------------------------

-democache <size in KB>
-----------------------
Description : If you specify a democache size on the command line, then
              FuhQuake will record demos to memory instead of to disl.  When
              the demo is completed, FuhQuake will then copy the demo from
              memory to disk.  This can reduce hard disk activity and result
              in more smooth gameplay when recording for many people, but not
              everyone.  Don't use it if it gives you problems.

              You should specify a -democache size slightly bigger than than
              the size of demos you usually record.  Ex, if most of your qwd
              recorded demos are 15mb in size, "-democache 20000" is good.
              Don't make the democache too big unless you have the RAM for it.

              Important: If the democache space runs out (because your demo is
              too big for it), you will get a big lag while FuhQuake empties
              some of the democache to disk.

              Important: When using -democache and demo recording finishes,
              there can be a long pause while the demo is copied from memory to
              disk.  The bigger the demo, the longer the pause.


1E. IMPORTANT NOTES
-------------------
Demo recording starts whenever the "status" serverinfo key changes from
"standby" to something other than "standby".  On KT servers this happens
when the countdown begins.

Auto recording stops in the following situations:
*) The "status" serverinfo key changes from something other than "standby" to
"standby" (eg. people vote to break during countdown).
*) 4 seconds after the final match scoreboard is displayed.
*) You type "stop" to stop recording.
*) You "disconnect" from the server (includes connecting to another server,
starting demo playback, etc).
*) A new map starts on the server.

If you are using "match_auto_record 1" then after an auto recorded demo has
completed (it will tell you), you can use "match_save" to save the demo.
The demo will be saved to the same name easyrecord would use (you can
customise this name...see the MATCH NAME section below).

If you are using "match_auto_record 2", auto recorded demos will automatically
be saved unless the length of the demo is less than the number of seconds in
the match_auto_minlength variable. If they are too short to be auto saved, the
client will say "Autorecording cancelled." but you can still manually save the
demo with "match_save".


-------------------------------
SECTION 2. AUTO CONSOLE LOGGING
-------------------------------

2A. VARIABLES
-------------

match_auto_logconsole (Default: "0")
------------------------------------
Description : When set to 1 or 2, a temp console log will automatically be
              created when a match starts (usually when the countdown starts).
              match_auto_logconsole 2 automatically saves the console log after
              the match is completed. 'match_auto_logconsole 1' requires manual
              saving (see the "match_save" command above).


1B. IMPORTANT NOTES
-------------------

FuhQuake can log your console to a .log file automatically when a match begins.
This is useful if you have a stats program that generates stats from logs.
It works exactly the same as auto demo recording except "match_auto_logconsole"
is used instead of "match_auto_record" and "log_dir" is used instead of
"demo_dir". "match_save", "match_auto_minlength" and "match_auto_spectating"
still apply.

If you use 'match_auto_logconsole 1' and 'match_auto_record 1' then "match_save" will
save both the log and the demo for the match.

If you use 'match_auto_logconsole 1' and 'match_auto_record 2' then "match_save" will
only save the log for the match, and the demo should be saved automatically.

It's all common sense.

Note, the "log_readable" variable may be useful here.  Setting it to 1 will
make the console logging convert all non-printable characters to printable
equivalents.


---------------------------------------
SECTION 3. SCOREBOARD SCREENSHOT TAKING
---------------------------------------

3A. VARIABLES
-------------

match_auto_sshot (Default: "0")
-------------------------------
Description : Set to 1 to automatically take a screenshot of the final
              scoreboard when a match ends.  If your console is down or you
              are in the menus, then FuhQuake will remove the console/menu
              for a split second so it can take a screenshot of the scoreboard
              without any interference.

sshot_dir (Default: "")
-----------------------
Description: This is the default location screenshots will be saved to.  It is
             relative to your basedir.  If it is "" then the demos will be
             saved to your current gamedir (default qw behaviour).  It's
             recommended setting this to something like "qw/sshots" to have
             your screenshots put into c:\quake\qw\sshots .  Note that this
             affects all screenshots, those taken with the "screenshot"
             command, and those automatically taken with 'match_auto_sshot 1'.

sshot_format (Default: "tga" for GL, "pcx" for software)
--------------------------------------------------------
Description: This defines the image format of screenshots.  Software FuhQuake
             can only use "pcx" and "png". OpenGL FuhQuake can use "tga", "png"
             or "jpg" (recommended).  Note that if you specify an extension in
             the fiilename given to the 'screenshot' command, that image type
             is used regardless of 'sshot_format'. Ex. "screenshot blah.jpg"
             will take a screenshot in jpg format (GL only) regardless of
             sshot_format.  But "screenshot blah" would use the format set by
             'sshot_format'.

sshot_applyGamma (Default: "1")
-------------------------------
Description: If set to 1, your gamma/contrast settings will be applied to all
             screenshots taken.


3B. IMPORTANT NOTES
-------------------

FuhQuake can automatically take a screenshot of your scoreboard if you set
'match_auto_sshot' to 1.  Unlike auto recording and auto console logging,
there is no way to take a 'temp' screenshot of the final scoreboard and
manually save it.  In essence, the screenshot taken with 'match_auto_sshot 1'
is automatically saved.

The name of the screenshot taken by 'match_auto_sshot 1' is the same name
easyrecord would use (with the proper extension, eg ".tga", ".pcx", etc). You
can customise this name (see the matchname section below).

Ex. If you have "sshot_dir qw/sshots" then a 4on4 screenshot would be put into
"c:/quake/qw/sshots/4on4/[clan]quaker - [4on4_myclan_vs_someclan] - [dm3].tga"
assuming your base quake dir is c:/quake and you haven't customised the
'match_format_4on4' variable (see section 4 below).


-------------------------
SECTION 4. THE MATCH NAME
-------------------------

Each match has a customisable name that is used for easyrecord, saved auto
recordings, saved auto screenshots, saved auto logging and so on. There is also
a macro called $matchname which you can use to get the name of the match
manually (echo $matchname).

For example, a matchname might be
"[clan]quaker - [4on4_myclan_vs_someclan] - [dm3]" or whatever.


4A. MATCH TYPES
---------------
Matches are sorted into different categories.  The following lists the
categories FuhQuake supports.  If you think there should be more, please
let me know.

The criteria for each category is roughly summarised in brackets.

*) duel : (gamedir = "qw", 2 players)
*) ffa  : (gamedir = "qw", more than 2 players, teamplay off)
*) race : (gamedir = qw, serverinfo "race" key present and equal to mapname)

*) 2on2 : (gamedir = "qw", 2 teams with at least 1 team having 2 people)
*) 3on3 : (gamedir = "qw", 2 teams with at least 1 team having 3 people)
*) 4on4 : (gamedir = "qw", 2 teams with at least 1 team having 4 people)
*) tdm  : (gamedir = "qw", 2 teams, 1 team having at least 5 people)
*) multiteam  : (gamedir = "qw", 3 or more teams)

*) arena : (gamedir = "arena")
*) carena : (gamedir = "carena")

*) tf_duel : (gamedir = "fortress", 2 players)
*) tf_clanwar : (gamedir = "fortress", at least 2 teams)

*) solo : (any gamedir, 1 player on a server, not in race mode)
*) coop : (gamedir = "qw", at least 2 people, deathmatch is off)

Notes:
*) The race category is basically for ktpro race mode.


4B. CUSTOMISING MATCH NAMES
---------------------------
Each match category has a name format variable associated with it. This
variable is called match_format_<category> .

For example, there is match_format_duel, match_format_2on2, etc, etc.

All these variables can contain macro's that are expanded according to the
macro list given below.  You can also use the "match_format_macrolist" command
inside FuhQuake to display a list of the macros and their meaning.


4C. MACROS
----------
The square brackets apply when spectating.

Note that your nick is the same as your name unless you set a nick with
match_name_nick.  This is useful if you use lots of different names, but
only want a certain name to be used in %n.

You can use the "match_format_macrolist" in a game to see this list of macros.

%n - your nick [your nick followed by "(SPEC)"]

%p - your name [player1's name]
%t - your team [team1's name]
%e - enemy nick in duels, enemy team in tp [player2/team2]

%k - names of players on your team [team1] (separated by match_name_and)
%l - names of players on enemy team [team2] (separated by match_name_and)

%O - number of teammates [number on team1]
%E - number of enemies [number on team2]
%C - number of players on the server

%a - team counts separated by match_name_on (eg 4on3on4)
%b - team names separated by match_name_versus (eg sr _vs_ cmf _vs_ fs)

%v - shortcut for whatever is in match_name_versus

%T - timelimit on the server
%F - fraglimit n the server
%N - teamplay setting on the server
%D - deathmatch mode on the server

%M - mapname
%G - gamedir (eg. qw, fortress, arena, etc)

%d - day
%m - month
%y - year without century (Ex. 03)
%Y - year with century (Ex. 2003)


4D. COMMANDS
------------

match_format_macrolist
----------------------
Description: Prints list of match format macros and their use. Useful if you
             forget a certain macro in game, and can't be bothered opening this
             doc.


4E. VARIABLES
-------------

match_name_and (Default: "_&_")
-------------------------------
Description: Used for separating names in %k and %l

match_name_versus (Default: "_vs_")
-----------------------------------
Description: Used for separating names in %b

match_name_on (Default: "on")
-----------------------------
Description: Used for separating numbers in %a

match_name_nick (Default: "")
-------------------------------
Description: %n uses this if its not "", otherwise it uses your in game name.

match_name_spec (Default: "(SPEC)")
-----------------------------------
Description: This is placed after your nick when using %n and are in spec mode.
             Eg. if you use "match_name_nick fuh" and leave match_name_spec
             default, then %n will be "fuh(SPEC)" in spec mode and "fuh"
             when not in spec mode.


match_format_solo       (Default: "solo/%n - [%M]")
match_format_coop       (Default: "coop/%n - [%C_player_coop] - [%M]")

match_format_duel       (Default: "duel/%n - %p%v%e - [dmm%D] - [%M]")
match_format_ffa        (Default: "ffa/%n - [%C_player_ffa] - [%M]")
match_format_race       (Default: "race/%n - [race] - [%M]")

match_format_2on2       (Default: "2on2/%n - [%k%v%l] - [%M]")
match_format_3on3       (Default: "tdm/%n - [%Oon%E_%t%v%e] - [%M]")
match_format_4on4       (Default: "tdm/%n - [%Oon%E_%t%v%e] - [%M]")
match_format_tdm        (Default: "tdm/%n - [%Oon%E_%t%v%e] - [%M]")
match_format_multiteam  (Default: "tdm/%n - [%a_%b] - [%M]")

match_format_arena      (Default: "arena/%n - %p%v%e - [%F_frags] - [%M]")
match_format_carena     (Default: "carena/%n - [%a_%b] - [%M]")

match_format_tf_duel    (Default: "tfduel/%n - %p%v%e [%M]")
match_format_tf_clanwar (Default: "tfwar/%n - [%Oon%E_%t%v%e] - [%M]")


4F. MACROS
----------
$matchname
----------
Description: works out "match_format_<bleh>" with all macros etc expanded.
<bleh> is the match category.


--------------
SECTION 5. FAQ
--------------

Q1. Why are my auto recording/logging/screenshots not working in spec mode?
A1. You need "match_auto_spectating 1" for them to work when spectating.

Q2. Is it possible to auto record only 4on4's and not duels (etc) ?
A2. Not really.  The only solution here is to temp record and manually save
    the 4on4 demos with the match_save command.

Q3. How do I auto record in teamfortress ?
A3. If you are playing teamfortress 2.9 or earlier (including MTF, CuTF which
    are based on tf 2.5) then you need to use 'match_auto_record 1' and the
    following msg_trigger:

            alias tfstart "match_forcestart"
            msg_trigger tfstart "MATCH BEGINS NOW"

    The above msg_trigger will also work for all versions of OZTF.  However in
    OZTF 1.45 and above you don't *need* the msg_trigger since it will
    automatically start recording when the OZTF countdown begins (in clan
    mode). Of course you will need 'match_auto_record 1' for this.

    If you have the msg_trigger above in OZTF 1.45, a demo will begin recording
    when the countdown starts, and then restart again when the countdown ends
    and "MATCH BEGINS NOW" is printed.  This is perfectly fine.  But if you
    only play on OZTF 1.45 servers and above, you can just not use the
    msg_trigger.

Q4. How is 'match_auto_sshot 1' any different from
    "alias f_mapend screenshot $matchname" ?
A4. Well the main difference is that if your console is pulled down or you are
    in the quake menus when the match ends, 'match_auto_sshot 1' will
    automatically remove the console/menu for 1 frame so it can take a
    screenshot of the scoreboard without any interference.

    On a minor note, when using the screenshot command in the f_mapend alias
    (which is automatically executed when a match ends), it is important to
    put a wait in first, eg alias f_mapend "wait; screenshot <name>".  Without
    the wait, the screenshot probably won't contain the scoreboard when playing
    OpenGL fullscreen.  You don't need to worry about this if you are using
    'match_auto_sshot 1' .

Q5. Is it possible to automatically compress my demos?
A5. There was no time to put this feature into FuhQuake v0.30.  However future
    versions of FuhQuake will allow you to compress your demos using qizmo
    .qwz compression and/or .zip compression.  There will also be an option for
    converting demos to .mvd format.

    There will also be an option to zip demos and screenshots together into a
    single zip.  I plan a menu where you will be able to browse a list of demos
    inside these zip files, with a thumbnail of the scoreboard screenshot next
    to each demo.
   