
 =                          =
 = Defrag 1.7 documentation =
 =                          =


I - Basics
  I.1: Introduction
  I.2: Installation
II - Configuration
  II.1: General settings
  II.2: Autorecord
  II.3: Scripts
  II.4: Non-Defrag Maps support
    * 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)
III - Additional information
  III.1: Cheat Prevention specifications
    * CVar restrictions
    * Bsp checksum verification
    * Timer Encryption
    * Authentication
  III.2: default CVar settings
  III.3: Notes
  III.4: Credits
IV  - 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 (default: 11)
	Many Defrag maps feature checkpoints, this cvar handles the way these are displayed.
	
	1 - displays time offset when a checkpoint is triggered (screen center)
        2 - displays checkpoints stats (screen bottom right corner)
	Display modes for checkpoints stats:
	. - displays time difference with previous checkpoint (ON if no other display mode is set)
        4 - displays overall time (overrides the previous mode)
	8 - displays time offset (overrides the previous modes, ON only if a best time is set,
				otherwise Defrag will use the next available Display mode)

	This is a flags CVar, meaning option values must be added together to be enabled.
	As an example, 7 will display both time offset (1) AND checkpoints stats (2), AND will use overall time to display checkpoints stats (4).

/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 features an autorecord option for demos, that starts a new demo each run, and overwrites the same demo file until the finish line is reached.
An external application is provided, _DemosTool.exe, that will properly rename files with the performed time, delete demos from unfinished runs, and keep only the n best demos per map for the selected player with n ranged from 1 to 16.

/df_autorecord [0-2] (default: 0)
	0 - disables autorecord
	1 - enables autorecord
	2 - no longer used, kept for config compatibility
	3 - overwrites the same demo file until a best time is performed.

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

- Notes:
 An online and permanent competition is settled at http://planetquake.com/defrag, and the web site provides scripts to upload your demos so the admins can check your performance and update the score tables. Valid demo names format for competition is "mapname_time_playername_playercountry.dm_67". 


II.3/  Scripts
--------------
/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.


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

- Settings:
 /df_ndm_allWeapons[0-2] (default: 1)
   0 - normal weapon handling.
   1 - gives player all weapons, with the exception of the BFG.
   2 - gives player all weapons, BFG included.

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

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

- 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_startOnItem [item alias]
 /df_ndm_timer_stopOnItem [item alias]
 /df_ndm_timer_checkpointOnItem [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
-----------------------------
Allows player to save multiple positions, and teleport to each position. This only works when cheats are enabled, as a modified version of the "setviewpos" console command is ultimately what is called.  This is great for practicing maps,  as it allows the player to return to a position in a map instantly.  It uses a modified version of setviewpos, but does not teleport the player - it places the player (it does not create teleport visuals, does not create any velocity, and does not delay (the q3 version of setviewpos does).  It also observers your pitch as well, unless you turn this off using "savepos 1"

- usage:
 The command is used either through the console, or (better solution) through config binds.

- example binds:
 set posempty ""
 bind 0 "savepos 0"
 bind 1 "vstr pos1; set saveposname pos1"
 bind 2 "vstr pos2; set saveposname pos2"
 bind 3 "vstr pos3; set saveposname pos3"
 bind 9 "set pos1 vstr posempty; set pos2 vstr posempty; set pos3 vstr posempty; echo saved positions cleared"

 NOTE: if you don't want the pitch to be saved (ignore pitch option), use:
       bind 0 "savepos 1"


- how it works:
 pressing 1, then 0, will save your position (in pos1)
 pressing 1 will teleport you to the saved position (pos1)
 pressing 9 will clear all the saved positions, especially useful when switching to a new map

- additional information:
 The player must first supply a "saveposname", so when "savepos" is called, it has a name for the vstr string it will create.  Usage is as follows:
	
 /set posempty ""		// creates an empty string used to reset positions
 /set saveposname MyPositionName	// sets the saveposname to "MyPositionName"
 /savepos			// saves position (now the vstr "MyPositionName" contains "setviewpos x y z yaw")
 /vstr MyPositionName		// teleport player (executes the vstr "MyPositionName")

 Essentially what happens, is when savepos is called, q3 will create a vstr (string) that the player may execute.  The name of this vstr is whatever is assigned to it through the /set saveposname command.  The player may then execute that vstr.  This allows as many position saves as desired.



II.7/ Overbounce Detection/Prediction (OBD)
-------------------------------------------
Allows display of overbounce locations within a map.
See "readme [Overbounce Detection].txt" separate document for further information.

- usage:
 Overbounce detection occurs internally, and is it's results are displayed through the Crosshair Stats (CHS) display system (see that section for more info.)  Note that if the CHS is not displaying any overbounce detections, than the overbounce predictions are not run.  Turning on overbounce detection is accomplished by assigning one or more detection types to one or more Crosshair Stats information positions.

- to quickly turn on all overbounce prediction types (JGB):
 /df_chs1_draw 1
 /df_chs1_info1 54

- config variables:
 /df_ob_fast [ default: 0 (off) range: 0 (off) to 1 (on) ]

 Turns OB fast prediction on or off.  OB fast prediction uses a different algorithm internally to detect OBs.  This algorithm is much faster, and is not dependant on the distance/height to the floor the player is looking at, and therefore has absolutely minimal effects on display framerates.  It is, however, very slightly inaccurate (due to floating point rounding errors, etc.).  General players may wish to enable fast detection.  Map makers should not use this feature if they are looking to find new OB heights for usage in a new map.  Using noclip to move up and down while using OB detection should definately use df_ob_fast off, as it is much more accurate.

- overbounce detection types:
 There are 3 types of overbounce detection that the system will do: (GO, JUMP, BELOW)

 - GO (G): OB detection for the floor the player is looking at.  GO indicates that for a player to OB, the player must go to this location.

 - JUMP (J): OB detection for the floor the player is looking at.  JUMP indicates that for the player to OB, the player must jump from the current position and then fall towards that location. JUMP predictions only occur when the player is on the ground.

 - BELOW (B): OB detection for the floor below the player.  If the player is currently falling, B indicates that an overbounce will occur if the player hits the floor directly below.  If the player is currently standing on the ground, B indicates that an overbounce will occur if the player jumps and lands on the same floor.  This detection type is useful in that it allows the player to see overbounce locations without looking at the floor below - a nice mode to keep on even when the player is not out actively seeking new OB locations.






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

** NOTE: see Crosshair Stats separate document for all the info types and examples **

The CHS is comprised of 3 crosshair stat sets.  One absolute center set (display is inside the crosshair), and two user sets. The 2 user sets each have 8 assignable information slots, giving a total of 16 info slots.

-------------------
Center Set (set 0):
-------------------
The center set is used to display user control input inside the crosshair.  Any demos recorded using this pk3 will be able to display the user control input information, even if the demo itself was not displaying this information during the recording process.  Useful mostly as a training tool, to see how a particular trick was accomplished from an input point of view.

config vars (for CHS set 0):
---------------------------
 /df_chs0_Draw [ default: 0 (off), range: 0 to 3 ] - turns display on/off
	0 = off
	1 = always on
	2 = on for demos only
	3 = on for non-demos only (off for demos)

 /df_chs0_FontColor	   [ default: 0 (white), range: 0 to 9 ] - changes font color
 /df_chs0_FontTransparency [ default: 1 (no transparency), range: 0 to 1 (.xx) ] - changes font transparency

--------------------------------
User Sets (CHS set 1 and 2):
--------------------------------
The user sets are capable of displaying a lot of different types of information.  They are also very configurable from a display point of view. It is possible to have one set be displayed around the crosshair, and have the other set displayed elsewhere on the screen, in more of a vertical list of stats.  In addition, the user sets are highly configurable in regards to the font, the size, the position, the display type, etc.

config vars (for CHS set 1):
----------------------------
Note that set 1 and set 2 are essentially identical in their configuration (with the exception of some of the default values), but each set has it's own group of config vars.

df_chs1_Draw
df_chs1_FontSize, df_chs1_FontColor, df_chs1_FontTransparency, df_chs1_FontShadow
df_chs1_LabelColor, df_chs1_LabelType
df_chs1_DisplayType
df_chs1_OffsetX, df_chs1_OffsetY 


 /df_chs1_Draw [ default: 0 (off), range: 0 to 3 ] - turns display on/off
	0 = off
	1 = always on
	2 = on for demos only
	3 = on for non-demos only (off for demos)

 /df_chs1_FontSize	   [ default: 7, range: 4 to 15 ] - changes font size
 /df_chs1_FontColor	   [ default: 0 (white), range: 0 to 9 ] - changes font color (for data)
 /df_chs1_FontTransparency [ default: 1 (no transparency), range: 0 to 1 (.xx) ] - changes font transparency
 /df_chs1_FontShadow	   [ default: 1 (on), range: 0 to 1 ] - toggles font shadows
 /df_chs1_LabelColor	   [ default: 0 (white), range: 0 to 9 ] - changes font color (for label)

 /df_chs1_OffsetX [ default: 0*, range: -320 to 320 ] - changes the horizontal position of the CHS set relative to the center of the screen
 /df_chs1_OffsetY [ default: 0*, range: -240 to 240 ] - changes the vertical position of the CHS set relative to the center of the screen
 /df_chs1_DisplayType [ default: 0* (crosshair style), range: 0 to 4 ] - changes the display type of the CHS set
	0 = crosshair
	1 = 1 column, left aligned
	2 = 1 column, center aligned
	3 = 1 column, right aligned
	4 = 2 column, split

* use DisplayType along with LabelType to create a display/label set to your liking

 /df_chs1_LabelType [ default: 0 (off), range: 0 to 4 ] - changes the lable type of the CHS set
	0 = off (no label displayed)
	1 = left (label appears to the left of the data)
	2 = center (style 1) (use with displaytype 4)
	3 = center (style 2) (use with displaytype 4)
	4 = right (label appears to the right of the data)

* use DisplayType along with LabelType to create a display/label set to your liking

each CHS set has 8 positions (slots) available for information.
 /df_chs1_Info1 [ default: 0 (empty), range: 0 to 71 ] - assigns an information type to the stat info slot1
 /df_chs1_Info2 [ default: 0 (empty), range: 0 to 71 ] - assigns an information type to the stat info slot2
 /df_chs1_Info3 [ default: 0 (empty), range: 0 to 71 ] - assigns an information type to the stat info slot3
 /df_chs1_Info4 [ default: 0 (empty), range: 0 to 71 ] - assigns an information type to the stat info slot4
 /df_chs1_Info5 [ default: 0 (empty), range: 0 to 71 ] - assigns an information type to the stat info slot5
 /df_chs1_Info6 [ default: 0 (empty), range: 0 to 71 ] - assigns an information type to the stat info slot6
 /df_chs1_Info7 [ default: 0 (empty), range: 0 to 71 ] - assigns an information type to the stat info slot7
 /df_chs1_Info8 [ default: 0 (empty), range: 0 to 71 ] - assigns an information type to the stat info slot8

example 1: /df_chs1_info4 1	(assigns "CH_INFO_SPEED" to CHS set 1, position 4)
example 2: /df_chs2_info1 54	(assigns "CH_INFO_OVERBOUNCE_ALL" to CHS set 2, position 1)

see list below for info values

config vars (for CHS set 2):
----------------------------
config vars for CHS set 2 are identical to CHS set 1, but are referenced as:
 /df_chs2_*

floating point display:
-----------------------
Many of the information types allow display of information after the decimal place (.xxx).  The default is that no information is display after the decimal place.  Display of data after . is accomplished when and information type is assigned to an info slot.  Essentially, use x000, and the value for x will be the number of decimals display after the decimal place.

example 1: /df_chs1_info1 23	// displays horizontal speed as: x	(   23/1000 = 0 decimals )
example 2: /df_chs1_info1 1023	// displays horizontal speed as: x.x	( 1023/1000 = 1 decimal  )
example 3: /df_chs1_info1 3023	// displays horizontal speed as: x.xxx	( 3023/1000 = 3 decimals )

** NOTE: see Crosshair Stats separate document for all the info types and examples **




==============================
 III - Additional information
==============================

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


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


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


III.4/ Credits
--------------
- Thanks to arQon and the promode team for providing CPM physics code.
  http://www.promode.org

- 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








=======================
 IV - Versions history
=======================

* 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
