
 =                          =
 = Defrag 1.9 documentation =
 =                          =


v1.9 notes: The older filenaming standard for record and ghost files is no longer compatible with defrag 1.9 standards. A tool is provided in \misc\tools to perform the conversion. A record files converter is to come, check out the site at http://planetquake.com/defrag.


I - Basics
  I.1: Introduction
  I.2: Installation
II - Configuration
  II.1: General settings
  II.2: Autorecord
  II.3: Scripting
    * Events
    * Maths
  II.4: Tricks Mode / Fast Caps
    * Settings
    * Items-defined Timer
  II.5: Hud settings
    * Enabling/Disabling items
    * Hud display settings
    * Video capture mode
    * Defrag Hud Color Chart
  II.6: Savepos Console Command
  II.7: Overbounce Detection/Prediction (OBD)
  II.8: Crosshair Stats Display System (CHS)
  II.9: Ghosts
  II.10: Acceleration Meter
  II.11: Demo Camera Modes
  II.12: Online Help
III - Demos Queue
IV - Additional information
  III.1: Cheat Prevention specifications
    * CVar restrictions
    * Bsp checksum verification
    * Timer Encryption
    * Authentication
  III.2: default CVar settings
  III.3: Notes
V  - Versions history


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



============
 I - Basics
============

* I.1/ Introduction
-------------------
Defrag is a modification for Quake 3 Arena from Id Software, that features a single-player game based on movements ability and player velocity through dedicated run maps. These maps require many special movements, known as tricks, in order to be completed up to the finish line. Defrag is meant for self-training and improvement, competition, and fun, while it focuses on providing a convenient environment for any q3 tricking purposes, with various tools and cheat prevention measures.
The game supports physics from both standard quake 3 arena and the CPM mod (http://www.promode.org), and sports CTF Fast Captures and a Tricks Mode that lets players use any quake 3 map for free-style tricking.
Defrag maps and score tables can be found from the official website at http://planetquake.com/defrag.



* I.2/ Installation
-------------------
Defrag requires Quake 3 Arena point release 1.27 (or any superior version).
Unzip the files in your Quake 3 folder, with "Use folder names" on. Files will be extracted into a "defrag" subdirectory.
The mod can then be loaded from the Quake 3 menu, in the Mods pannel.

Once properly installed, Defrag can also be run from the command line with these parameters:
quake3.exe +set fs_game defrag +set sv_pure 0




====================
 II - Configuration
====================

II.1/ General Settings
----------------------
/df_unit [0-2] (default: 0)
	Sets units type for distance and velocity outputs.
	0 - quake units, units/s
	1 - meters, Km/h
	2 - miles, miles/h

/df_checkpoints [0-3] (default: 3)
	manages the checkpoints display.

	0 - off
	1 - effective time
	2 - offset time
	3 - relative time

/stats (client command)
	Outputs player stats within the console.
	Stats are reseted at timer start, and each time the player respawns. Since these are processed client-side, this command can be used during demo playback. Stats are automatically displayed at end of run, with additionnal information about cvars related to physics and Defrag settings.

/df_promode [0-1]
	Switches VQ3/CPM physics.
	This is a read-only cvar, meaning that it can't be set otherwise than from using the command line. Physics usually are set from the menu, only mappers should be concerned in manually handling this cvar.


II.2/ Demos autorecord
----------------------
Defrag sports an autorecord features for timered demos.

/df_autorecord [0-3] (default: 0)
	0 - disables autorecord
	1 - enables autorecord
	2 - no longer used, kept for config compatibility
	3 - Selective - keep only the record demos

/df_country
	Sets up your country for demo naming.

/df_name
	Sets up your name for demo naming.
	When Defrag is started for the first time, it will automatically set this cvar from the standard quake player name.

/df_competition [string]
	Set a characters string to be displayed during map load and at end of run.
	Usefull to mark a demo as performed for a particular contest, and assure no cross-posted demo is received by competition maintainers.
	Note that this CVar is not saved to q3config.cfg, and has to be set each Quake 3 session.

/df_ar_stopdelay [ TYPE: INTEGER - DEFAULT: 1800 ]
	sets the number of milliseconds after the run is complete before autorecord stops the demo.

/df_ar_speedcapture_format [ DEFAULT: 0 (off) RANGE: 0 TO 1 ]
	turns on/off the speedcapture demo name format for autorecord in Fast Caps.

/df_ar_format [ TYPE: STRING - DEFAUT: "$map.$-route[$gt.$phys.$-mode]$m.$-s.$-ms($pl.$plc)" ]
	sets the demo name format for the autorecord.

 The format string supports the following identifers :
   $map   : map name
   $gt    : gametype
   $phys  : physics type
   $route : tricks mode route
   $mode  : tricks mode / fast caps game-mode
   $m     : timer minutes
   $s     : timer seconds
   $ms    : timer milliseconds
   $pl    : player name
   $plc   : player country
   $$     : ouput a '$' character

 When the argument resulting of a token is missing, the behavior can be controlled using the identifiers + and - :
   $+i : where i is the argument identifier, cancels the  
         output of the character following the token in 
         the format string.
   $-i : cancels the output of the character preceding
         the token.
 Both can be combined using $-+i. For example, "$m[$-+mode]_$p" will result in "mapname_physics" when no Mode data is available.



II.3/  Scripting
----------------
- Events:
 /df_script_onRespawn [0-1] (default: 0)
	Executes respawn.cfg each time player respawns.
	Basically used for alternative demos recording scripts.
	
 /df_script_onMapLoad [0-1] (default: 0)
	Executes [mapname].cfg after a map is loaded.
	Basically used for specific map settings (sv_fps, com_maxFps, ...) and user defined timers.

- Maths:
 Checks the related readme files in the \docs folder for further information.

 varMath: performs math on a variable using a supplied operator and value.  Allows stuff like:
	\bind uparrow "varMath timescale + .1"

 varValueMath: performs math on a variable using a supplied operator and another variable.  Allows:
	\bind uparrow "varValueMath r_gamma + MyValue"
	where MyValue could = ".2" or whatever

 varCycle: cycles a variable with values.  Allows such things as:
	\bind uparrow "varCycle com_maxfps 125 20 60 100 111 125 142"
	note first value is your defineable default value

 varValueCycle: cycles a variable with variables.  Similar to varCycle, but cycle thru variables instead of values:
	\bind uparrow "varValueCycle sv_Fps MyDefault MyVal1 MyVal2 MyVal3"
	More useful when you have very long vstrs and wish to cycle through them.


II.4/ Tricks Mode / Fast Caps
-----------------------------
These features only apply in "Tricks Mode" and "CTF Fast Caps" game types.

 /df_ndm_weaponsPickup [0-1] (default: 1)
   turns on/off the weapons pickup in Tricks Mode / Fast Caps.

 /df_ndm_damage[0-1] (default: 1)
   turns on/off player damage in Tricks Mode / Fast Caps

 /df_ndm_powerups[0-1] (default: 0)
   allows/disallows the use of powerups in Tricks Mode / Fast Caps.

 /df_ndm_weaponsSet [ TYPE: FLAGS - DEFAULT: "510" ]
   sets the weapons given to players upon respawn in Tricks Mode / Fast Caps.

 /df_ndm_nopad [ DEFAULT: 0 (enabled) - RANGE: 0 TO 2 ] - manages the behavior of jump-pads and bounce-pads in Tricks Mode / Fast Caps.
   0 - enabled
   1 - disabled
   2 - replaced by death-trigger

 /df_ndm_noteleport [ DEFAULT: 0 (enabled) - RANGE: 0 TO 2 ] - manages the behavior of the teleporters in Tricks Mode / Fast Caps.
   0 - enabled
   1 - disabled
   2 - replaced by death-trigger

 /df_ndm_nomover [ DEFAULT: 0 (enabled) - RANGE: 0 TO 1 ] - manages the behavior of the movers in Tricks Mode / Fast Caps.
   0 - enabled
   1 - disabled

 /df_ndm_itemsSpawn [ DEFAULT: 1 (selective) - RANGE: 0 TO 2 ] - manages the spawning of the items in Tricks Mode / Fast Caps.
   0 - items never spawn
   1 - selective
   2 - items always spawn

- Items-defined Timer:
 Not available in fast caps mode.
 Items can be defined so to handle the timer. Any item can be assigned for starting/stopping the timer, or setting a checkpoint.

 /df_ndm_timer_start [item alias]
 /df_ndm_timer_stop [item alias]
 /df_ndm_timer_checkpoint [item alias]

 Possible item aliases are:
  Weapons: sg gl rl lg rg pg bfg
  Ammo: a_mg a_sg a_gl a_rl a_lg a_rg a_pg a_bfg
  Health: h5 h25 h50 mh
  Armor: as ya ra
  Powerups: quad bs haste invis regen flight
  Holdables: teleport medkit


II.5/ Hud Settings
------------------

The hud can be turned back to standard quake 3 display. However, this mode does not support the latest Defrag features.
/df_hud [0-1] (default: 1)
	0 - vq3 overused hud
	1 - Defrag shiny hud


- Enabling/Disabling items (df_draw*):

 /df_drawBesttime [0-1] (default: 1)
	Displays performed best time for the current map.

 /df_drawSpeed [0-2] (default: 1)
	0 - Disabled
	1 - Displays speed meter
	2 - Displays speed meter and uses an older quake-units conversion table (Defrag old-school)

 /df_drawJumpmeters [0-7] (default: 3)
	1 - Draw jump height
	2 - Draw jump distance
	4 - Draw only high values

	This is a flags CVar, meaning option values must be added together to be enabled.
	The default value 3 enables height and distance meters, while it disables the
	"high values only" option.
	
	The jump distance meter is assumed to display some inaccuracy, within a 5 units range.


- Hud display settings (df_hud_*):

 /df_hud_color [0-11] (default: 4)
	See Color Chart below.

 /df_hud_transparency [0.0-1.0] (default: 0.25)

 /df_hud_fontcolor [0-11] (default: 7)
	See Color Chart below.

 /df_hud_fontshadow [0-1] (default: 1)

 /df_hud_colorwarning [0-1] (default: 1)
	Marks low values in red.

 /df_hud_forceteamcolors [0-1] (default: 1, CTF Fast caps only)
	Sets hud color to match player's team.

 /df_hud_3DIcons [0-1] (default: 1)
 	A 0 value disables the use of 3D models on hud (CTF flags...) and so provides a FPS gain.

 /df_hud_colorRGB (R,G,B)
	Sets a custom hud color exprimed in the 24 bits RGB format (0,0,0 to 255,255,255).
	As an example, 0,255,0 will display a green hud.

 /df_hud_fontcolorRGB (R,G,B)
	Sets a custom font color exprimed in the 24 bits RGB format (0,0,0 to 255,255,255).
	As an example, 0,255,0 will display green fonts.


- Video capture mode (/df_hud_videocapture_*) :

 This feature disables the hud, similarly to "cg_draw2D 0" effects, but keeps displaying the timer.
 It was originally settled for video capture, think of using "cl_noprint 0" for better results in that case.

 /df_hud_videocapture_enable [0-1] (default: 0)
	Enables/Disables Video Capture Mode

 /df_hud_videocapture_x (default: 320)
 /df_hud_videocapture_y (default: 240)
	Timer position from relative screen resolution 640x480.

 /df_hud_videocapture_fontsize [4-32] (default: 16)

 /df_hud_videocapture_fontjustify [0-2] (default: 0)
	Sets the font alignment:
	0 : center justify
	1 : left justify
	2 : right justify

 /df_hud_videocapture_fontcolor [0-11] (default: 7)
	See Color Chart below.
	
 /df_hud_videocapture_fontshadow [0-1] (default: 1)


- Defrag Hud Color Chart
 * vQ3 colors
	0  : Black
	1  : Red
	2  : Green
	3  : Yellow
	4  : Blue
	5  : Cyan
	6  : Magenta
	7  : White

 * Defrag Additional Colors
	8  : Gray
	9  : Orange
	10 : Purple
	11 : Dark Green


II.6/ Savepos Console Command
-----------------------------
Cheats-protected command, intended for training. Allows player to save multiple positions, and teleport to each position.
Check the related readme files in the \docs folder for details.


II.7/ Overbounce Detection/Prediction (OBD)
-------------------------------------------
Allows display of overbounce locations within a map.
Check the related readme files in the \docs folder for details.


II.8/ Crosshair Stats Display System (CHS)
------------------------------------------
Display system that can be configured by the user to output various pieces of information, such as speed, health, timers, distances, control inputs, etc.
Check the related readme files in the \docs folder for details.


II.9/ Ghosts
------------
Ghosts can be used for many different things within the game:
- Racing one's ghost within Defrag maps.
- Racing one's ghost on fast flag capture runs, as well as non Defrag maps.
- Record a ghost from an existing demo, and race that ghost.
- Ingame trick review: watch what you just did, without leaving the game.  Many different camera modes are supplied.
- Recording DemoCam movements to a file for reuse.
- Recamming demos (different than recording DemoCam movements): Ghosts can be recorded from demos, and played during demos.  In addition, the camera view during demo playback can be switched to the ghost's view
- Camera modes: allows many different camera angles, movement, etc. - very useful for video captures. Some camera modes are: 1st person, 3rd person, missile cams, etc.

Check the related readme files in the \docs folder for details.


II.10/ Acceleration Meter
-------------------------
The AccelMeter is a strafe jumping helper/efficiency meter, check the related readme file in the docs folder for details.


II.11/ Demo Camera Modes
------------------------
The Demo Camera Modes (Demo Cams) are primarily useful for quake3arena video creation.  There are 7 different camera modes that you can use.  The camera modes range from free moving, user controlled cams, to transitioning cams that are triggered by the user.
Check the related readme files in the docs folder for details.


II.12/ Online Help
------------------
- read: reads a specified text file
- info: lists info items from the crosshair stats displays sytem

Check the related readme files in the docs folder for details.


==============================
 III - Demos Queue
==============================
\dmq_add [ TYPE: COMMAND - PARAMETERS : file or directory] - adds a demo or a directory contents to the demos queue.
\dmq_clear [ TYPE: COMMAND ] - Resets the demo queue.
\dmq_play [ TYPE: COMMAND ] - Starts the demos queue playback.
\dmq_stop [ TYPE: COMMAND ] - Stops and cancels the demos queue playback.


==============================
 IV - Additional information
==============================

IV.1/ Cheat Prevention specification
-------------------------------------
- CVar restrictions
  The following list shows CVars being locked or capped in Defrag.
  g_speed                 locked to 320
  g_gravity               locked to 800
  g_knockback             locked to 1000
  g_quadfactor            locked to 3
  g_weaponRespawn         locked to 5
  g_weaponTeamRespawn     locked to 5
  timescale               protected
  sv_fps                  clamped from 60 to 140 unless cheats are on
  com_maxFps              clamped from 60 to 140 unless cheats are on

- Bsp checksum verification
  Client-side feature, run at demo playback. Ensures that the bsp file (map file) used in the demo matches the local one. Defrag will display warnings otherwise.

- Timer Encryption
  Server-side feature, run at demo playback. Ensures that a demo has actually been recorded with Defrag, otherwise the timer will display random values.
  
- Authentication
  Server-side feature. Ensures that client module actually is Defrag and that server/client versions match, by sending authentication requests with random generated key that should result in one unique auth-reply from client, that is version dependant. Defrag will immediatly return to console if a wrong result is replied or no reply at all is received.


IV.2/ Default CVar settings
----------------------------
These CVars default values change within Defrag:
  sv_fps                   120  (forced at game startup)
  g_synchronousClients     1
  pmove_fixed              1


IV.3/ Notes
------------
- Map best times and checkpoint times are kept in .rec files, located in .\records or .\records_cpm depending on the physics in use.
- Mapping tools are included in the release, and we, at planetquake.com/defrag, may support your work by providing links to your files. We do not offer any hosting however. Please contact us at defrag@planetquake.com.
- For any question, bug report, comment, feature submission, please feel free to mail us at defrag@planetquake.com.


Enjoy,

- Defrag team -
http://planetquake.com/defrag








=======================
 V - Versions history
=======================

* version 1.9 *
> check out in the \docs folder


* version 1.8 *

- Ghosts
- DemosCams
- AccelMeter
- Weapon Overbounce Detection
- Config Helper Commands: varMath, varValueMath, varCycle, varValueCycle
- Console Commands: read, info
- Demos Screen: now supports folders, mouse double clicks
- New Crosshair Stats Info Items: savedpos distances, ghost information, real life date/time
- Many tweaks and little features added to the crosshair stats display system and keypress crosshair display
- autorecord: dm_68 compatibility
- timer on respawn for non-defrag maps now optionnal (df_ndm_timer_startOnRespawn, off by default)
- added date stamp on end of run info
- added df_competition stamp to identify a demo as performed for a particular contest
- Fast Caps: players always use the 1st spawn spot which is the closest to the flag
- Included external app by DonPichol: ConfigTool


* version 1.71 *

- Fixed any items-related problem from 1.7
- Fast Caps: Players always use first-spawn spots
- Tricks Mode: Added "no weapon" mode
- Tricks Mode: Fixed timer-assigned bfg overriding item pickup rules
- Authentication failures no longer kill server


* version 1.7 *

- Added support for standard quake3 maps (Tricks Mode)
- Added support for CTF Fast Caps
- Tricks Mode: Added item-defined timer feature (df_ndm_timer_*)
- Added Crosshair Stats display system and user inputs indicator
- Autorecord: Various enhancements and fixes
- Autorecord: Added external app for demo files cleaning and sorting (_DemosTool.exe)
- CPM: Added cpm item clipboxes
- Added external app for recorded best times output (RecordsTool.exe)
- Fixed RunBeamer missing plasmagun
- Fixed some shader problems on map textures
- Fixed CVar "defrag_version" ability to be set from command line issue
- Removed sv_fps and com_maxfps restrictions when cheats are enabled
- Removed older crosshair health/armor stats and speed display
- Stats: Added "stats" console command
- Stats: Added Longest Jump
- Stats: Added pmove_msec
- Stats: Fixed target_init meddling
- Stats: Fixed Tallest Height not being reseted
- Stats: Jump meters: Replaced df_drawDistance and df_drawHeight CVars with df_drawJumpmeters
- Cheat Prevention: Fixed timer encryption side effects
- Cheat Prevention: Strengthened timer encryption
- HUD: Added video-capture mode (df_hud_videocapture_*)
- UI: Redesigned Launch Game menu (50 maps per page)
- UI: Added Tricks Mode support
- UI: Registration limits extended for demos (2x defrag 1.61 - 4x original vq3) 
- UI: Removed CD-Key splash screen and Id logo opening cinematic
- Scripting: Added df_script_onMapLoad
- Scripting: Replaced df_respawn_cfg with df_script_onRespawn
- Mapping: Added "RemoveMachinegun" option on Target_init
- Mapping: Added "author" key in map definition files (.defi)


* version 1.61 *

- Included CPM Defrag
- CPM: Added CPM Air Control and bunny
- CPM: Added Ramp-Jump and Double Jump
- CPM: Added CPM under-water movements
- CPM: Added CPM weapon settings
- Added CPM bugs fix for Id Software code
- Stats tracked and displayed in the console at end of run
- New conversion table for the Speed Meter accuracy
- Id Software code ported from 1.27 to 1.29h
- Hud: Added height meter (/df_drawHeight)
- Hud: Added jump distance meter (/df_drawDistance)
- Hud: Added crosshair health/armor display for faster reading (/df_drawCrosshairStats)
- Hud: Added crosshair speed display for faster reading (/df_drawCrosshairSpeed)
- Hud: Added animated life icon
- Hud: Added custom colors CVars (/df_hud_colorRGB /df_hud_fontcolorRGB)
- Hud: Fixed powerups display bug
- Hud: Fixed checkpoints display possible problem
- Autorecord: /df_name contains player name, specifically used for demo naming
- Autorecord: g_synchronousClients 0 compatibility
- Autorecord: timer-reset don't restart recording until 30s have passed since last time
- Autorecord: Fixed bug occuring when /name contains spaces
- Cheat Protection: Bsp Checksum verification
- Cheat Protection: Strengthened timer encryption with in-game variable factors
- Cheat Protection: Forbidden sv_fps/com_maxFps values reported so to prevent from looped sv_fps/com_maxFps commands cheat
- Cheat Protection: Fixed bug occuring at auth process
- UI: Registration limits extended for maps(x4) and demos(x2)
- UI: 15 maps displayed per menu page
- UI: Menu got bunnies invaded
- Mapping: Added Silent option to fragsfilters (disables frags-warning messages)
- Mapping: Added Reset option to fragsfilters (resets player score to 0)
- Mapping: Removed Runonce option from fragsfilters (now set on by default)
- Checkpoints displayed while playing demos
- Removed Powerups respawn sound
- Newly performed best time and checkpoints no more kept on Hud when cheats are enabled
