Q2PRO HOWTO

SF.net page of this project is here.
Nightly built Win32 binaries may be found here.

Abstract

Q2PRO is a Quake2 engine modification. Client and server sides are both compatible with original Quake2 v3.20 network architecture, as well as with modern R1Q2 network architecture. Q2PRO is designed to be secure, fast and doesn't provide any graphical enhancements that are contrary to the classic Quake2 look and feel. It provides some features yet unique to Quake2, notably server side Multi View Demos. Q2PRO has it's own software and OpenGL refresh libraries and runs under Win32 and GNU/Linux natively. Q2PRO also runs under Windows Mobile, although this port is not currently playable.

Q2PRO supports the following network protocols:

34, original Quake2 protocol.
35, enhanced R1Q2 protocol.
36, enhanced Q2PRO protocol, extension of R1Q2 protocol.
37, special broadband MVD protocol.

Key features of Q2PRO protocol from client's perspective:

Decoupled outgoing client packet rate (cl_maxpackets) and rendering frame rate (cl_maxfps).
Client still generates usercmds each frame but sends them in batches every few frames. This should result in exactly the same physics as in stock Quake2 and allows you to take advantage of high FPS while keeping outgoing bandwidth adequate.
Adjustable number of backup usercmds in each packet (cl_packetdup). May be turned off completely for extra bandwidth savings on reliable connections.
Server doesn't send player entity coordinates every frame. Client regenerates them from playerstate.
Server is able to filter gibs/footsteps on per-client basis.
Netchan level packet fragmentation support with possible asynchronous delivery. No more frame overflows in mods with extremly high activity.
Instant delivery of messages while client is in connecting state (still takes rate limit in respect and doesn't flood your modem).
Per-key delta userinfo updates. If you update your FOV setting for example, only a few bytes will be transmitted instead of the whole userinfo string. (Thanks to Berserker for the idea.)

Some terminology:

Multi View Demo (or MVD) is essentialy a server side recording of the game with all player states and all entity states stored. It is somewhat similar to the original serverrecord demo format that was built into Quake2 since the very beginning, but is much more compact thanks to delta compression and other bandwidth optimizations.
MVD broadcasting is a transmission of the game (either live or pre-recorded) using special MVD protocol.
MVD server is a Q2PRO server capable of MVD broadcasting.
MVD client is a Q2PRO server listening to MVD broadcast or playing back locally some pre-recorded MVD. Yes, Q2PRO allows UDP connections between servers.

Q2PRO has the following MVD facilities:

Local MVD recording. This is an easy and resource-friendly way to record MVD directly on the game server.
Live MVD broadcasting a-la QTV/GTV. The game server in this scheme becomes a MVD server. This server is typically private and allows single external MVD connection. A publically accessible MVD client connects to this game server and waits for normal Quake2 clients connect and watch live MVD stream from any POV they choose.
"Spectator proxy" feature. MVD client is able to connect to non-Q2PRO servers and broadcast single POV selected by the administrator.
Server side MVD playback with pause and smooth reverse functions. Any Quake2 client may watch MVDs on external Q2PRO server. Of course one may download a MVD and watch it locally just as normal Quake2 demo on a listen Q2PRO server.

Other features:

OpenGL refresh library supports *.jpg textures and *.md3 models.
Enhanced, configurable command completion (completes arguments for such commands as gamemap, demo, kick, etc).
Filesystem support for compressed *.pk2 files (these are essentially ZIP archives).
Some more, yet to be documented.

Getting source code

You will need to install Subversion (SVN) client specific to your OS to accomplish this task. Use the following command to checkout the lastest working copy into the "q2pro" subdirectory:

svn co https://svn.sourceforge.net/svnroot/q2pro/q2pro q2pro

Remember, Q2PRO is in development and source code in the repository may be broken at any given point in time. If you are not a developer, only proceed with downloading if you wish to participate in Q2PRO testing and don't mind building the whole thing yourself.

You may also browse Q2PRO source code online.

Building (Windows)

On Windows, Q2PRO is buildable using MinGW (Cygwin distribution is recommended, but MSYS should also work), Visual Studio 2003 and Visual Studio 2005. All needed external libraries are precompiled and included in the source tree (libz/1.2.3 and libjpeg/6b).

Visual Studio

Required solution and project files may be found in vc7/ and vc8/ subdirectories. Visual Studio 2005 seems to come without DirectX headers, so you will need to install MS DirectX SDK first.

MinGW/MSYS

Download MinGW packages from http://mingw.org/download.shtml. Required packages are: mingw-runtime, w32api, binutils, gcc and MSYS graphical installer. It is recommended to install MSYS using graphical installer first, then uncomress each MinGW package into the mingw/ subdirectory of your MSYS main directory. You also need to get ddraw.h, dsound.h and dinput.h files from MS DirectX SDK and place them into win32-libs-mgw/include subdirectory, unless they are in your include path already.

Open MSYS shell, cd to the root of q2pro source tree and type make:

cd /c/source/q2pro #change the path accordingly
make

This should build the following files in ./build/releasex86/ directory:
q2pro.exe - client executable
q2proded.exe - dedicated server
ref_newgl.dll - OpenGL refresh library
ref_soft.dll - software refresh library

Building (GNU/Linux)

Q2PRO is being developed and tested on Debian Sarge. Q2PRO currently uses SDL framework for video and OSS for sound output. You should compile Q2PRO using GCC version 3.x. libz is required by both client and dedicated server and libsdl is required by the client. libjpeg is optional for OpenGL refresh library and may be disabled by editing corresponding makefile. Make sure that X Server development packages are installed so there are OpenGL headers available. I don't use pkg-config yet, so you may need to tweak makefiles if some libraries or headers are in non-standard location.

cd to the root of q2pro source tree and type make:

cd ~/q2pro #change the path accordingly
make

This should build the following files in ./build/releasei386/ directory:
q2pro - client executable
q2proded - dedicated server
ref_newgl.so - OpenGL refresh library
ref_soft.so - software refresh library

About ref_newgl on linux: it should show acceptable performance with open source r300-dri drivers for ATI Radeon series video cards. I basically started writing ref_newgl so I could play Quake2 on my notebook equipped with ATI Mobility Radeon.

Running

Q2PRO first adds baseq2pro subdirectory of the base directory to the VFS search path. This is also the directory Q2PRO loads refresh libraries from. Note that refresh libaries are not compatible with original Quake2 refresh API and should not be mixed with libraries from other Quake2 clients.

To launch Q2PRO directly from the build directory on Windows, use a command line like this:
./build/releasex86/q2pro.exe +set sys_debugdir ./build/releasex86 +set basedir c:/quake2 +set game action

To record a local MVD:
q2pro +set mvd_enable 1 +map q2dm1 +mvdrecord test
To play it back enter in console: mvdstop; mvdplay test

To setup a game server for MVD broadcasting:
q2pro +set port 27910 +set mvd_enable 2 +map q2dm1

To setup a QTV-like server listening to MVD broadcast:
q2pro +set port 27911 +mvdconnect 127.0.0.1:27910
Then connect your normal Quake2 clients to 127.0.0.1:27911 and they will watch live MVD stream (cross your fingers).

Real documentation is to be written...

Setting up spectator proxy

In spectator proxy mode, MVD client connects to arbitrary game server just as a regular Quake2 client, using non-MVD protocol. MVD client does not need any Quake2 media files in order to run in spectator proxy mode, and may run outside Quake2 virtual filesystem tree. All you need is just dedicated server executable and (optionally) a config.

Start up dedicated MVD client: q2proded +set mvd_admin_password PASSWORD +set maxclients 32 +set hostname Q2PRO_TV +mvdconnect server:port
Connect to the newly created proxy using any Quake2 client.
Enter administrator mode by entering the following command in console: !mvdadmin PASSWORD. In administrator mode you have the full control over MVD client: all your movement and console input is forwarded to the game server.
Perform any actions needed to select the desired POV and make sure scoreboard is visible on your screeen.
Leave administrator mode by typing !mvdadmin again.

Some server cvars

sv_oldgame_hack	0	On GNU/Linux, enables "compatibility mode" so game libraries built using old GCC versions may be loaded without recompilation. If your server segfaults while loading a map, try toggling this variable.
sv_bodyque_hack	0	Attempts to prevent "flying bodies" effect present in some buggy mods. This hack assumes the mod allocates some certain range of entity slots for "body queue" and disables client side interpolation of those entities. Use this hack with caution bacuse it may not be compatible with all mods.
sv_strafejump_hack	0	Enables FPS-independent strafejumping for R1Q2 and Q2PRO clients.
sv_iplimit	3	Maximum number of simultaneous connections from single IP address. Setting this variable to 0 disables the limit.
sv_status_show	2	Specifies whether server should respond to status queries. 0 - do not respond 1 - respond with server info only 2 - respond with server info and player list
sv_status_limit	15	Maximum number of status queries server should respond to, per one second.
sv_badauth_time	1	Time, in seconds, for server to be unresponsive after invalid authentication attempt. This applies to rcon commands, as well as authenticated connection requests.
sv_password	""	If not empty, allows only authenticated clients to connect. Clients set their passwords using password userinfo variable.
sv_mvd_password	""	If not empty, allows only authenticated MVD clients to connect. If sv_mvd_password is empty, but sv_password is not, MVD client's password is checked against the latter. MVD clients set their passwords using password userinfo variable.

Some MVD-related cvars

mvd_enable	0	0 - disable MVD facilities (MVD playback is still available) 1 - enable local MVD recording 2 - enable MVD broadcasting
mvd_maxclients	1	Number of client slots reserved for MVD clients. Memory for these clients is allocated only if MVD broadcasting is enabled.
mvd_wait_clients	1	When recording a local MVD, skip server frames with no active clients present. 0 - do not skip any frames 1 - count active client entities (may include bots in some implementations and does not include observers) 2 - count only physically connected clients (does not include bots and includes observers)
mvd_buffer_size	16	Size (in frames) of the internal MVD buffer. Set on the MVD client. This buffer is used for the following distinct purposes: delaying live MVD stream playing MVDs backwards Each frame is 100ms long, thus to allocate the buffer that is one minute long set this value to 600. Higher values are not recommended since large delay buffers eat memory extensively. Note that buffer size in bytes is actually O(maxclients*mvd_buffer_size). Try to keep your maxclients value adequate.
mvd_pause	0	When playing back a MVD, stops running it forward in time. You may still run MVD backwards using +mvdback command.
mvd_noblend	0	Filter out playerstate color blend effects when recording and broadcasting MVDs. Used for optional bandwidth savings.
mvd_nogun	1	Filter out playerstate gun updates when recording and broadcasting MVDs. Used for optional bandwidth savings.
mvd_nodelta	0	Disable delta compression when recording local MVDs. Used for debugging purposes.
mvd_motd	"..."	This string is macro expanded and centerprinted to each MVD spectator on initial connection. Line feed escape sequences are allowed.
mvd_timeout	120	Specifies maximum time, in seconds, for MVD client to wait for incoming network packets before disconnecting.
mvd_custom_fov	1	Optionally enforces FOV settings for non-Q2PRO spectators. 0 - FOV setting of the player being followed is used. 1 - FOV setting of MVD spectator is used. For Q2PRO clients their cl_demo_local_fov setting is taken into account and mvd_custom_fov is ignored.
mvd_nextserver	1	Specifies what action should be taken when MVD playback finishes. 0 - close demofile and pause playback. 1 - attempt to execute contents of nextserver variable, kill the server if it is empty.
mvd_admin_password	""	Password required for clients to enter administrator mode and control the camera. If empty, administrator mode is disabled for non-local clients.

MVD client shares userinfo cvars with regular client. Keep this in mind when you run MVD client in listen mode.

Some MVD-related commands

mvdrecord [/]<filename>	Starts local MVD recording on the game server or MVD client. Records in demos/ subdirectory unless slash is prepended to the filename.
mvdstop	Stops local MVD recording.
mvdstreamrecord [/]<filename>	On a MVD client, starts MVD recording directly from live MVD stream, ahead current delay buffer position. Records in demos/ subdirectory unless slash is prepended to the filename.
mvdstreamstop	Stops streamed MVD recording.
mvdplay [/]<filename>	Starts MVD playback. Loads file from demos/ subdirectory unless slash is prepended to the filename.
mvdconnect <address:port> [protocol]	Connects MVD client to the specified server. Available protocols: 34 - use original Quake2 v3.20 network protocol 35 - use R1Q2 protocol 36 - use Q2PRO protocol 37 - use MVD protocol If protocol argument is omitted, automatically selects the "best" protocol supported by server.
mvdisconnect	Disconnects MVD client from MVD server. Note the spelling.
mvdautorecord [/]<filename>	Has the same functionality as mvdrecord command, plus puts the demo into the MVD cache. This command is intended to be issued by triggers.
+mvdback	When bound to a key, play MVD backwards until the key is released. The amount of time you may run MVD backwards is depends on the mvd_buffer_size value and the current position inside demofile. When end of buffer is reached, reverse playback stops. This command is available for listen servers only.
mvdjump <0-100>	Jump to the specified position (in percents) in the delay buffer (NOT in the whole demo).

Some MVD-related client commands

These commands may be issued on any Quake2 client connected to a MVD server.

follow [playerNum]	Starts following the specified player. Player number may be obtained from the output of skins command, for instance. If player number is omitted, switches to the most recently followed player, if none, switches to the first active player found.
observe	Goes into freefloat mode.
playernext	Cycles to the next active player.
playerprev	Cycles to the previous active player.
playertoggle	Toggles between the two most recently followed players, if any.
help	Toggles the display of scoreboard.
inven	Toggles the display of client list.
!mvdadmin [password]	Toggles administrator mode. For non-local clients to enter administrator mode, password is required and should match mvd_admin_password set on the MVD client.

Some client cvars

cl_protocol	0	Specifies preferred network protocol when connecting to servers. 0 - automatically select the "best" protocol available 34 - use original Quake2 v3.20 network protocol 35 - use R1Q2 protocol 36 - use Q2PRO protocol
cl_maxpackets	60	Number of packets client should send per second, directly impacts outgoing bandwidth. If set to 0, disables outgoing packet limit completely and sends packets every frame. When connected using Q2PRO protocol, client uses special usercmd batching code which ensures that physics are bound to cl_maxfps only and there is proper number of backup usercmds sent in each packet (see cl_packetdup). Otherwise, client falls back to oldschool FuzzQuake2 hack where some usercmds are dropped (up to 2 usercmds in a row). This hack exploits original Quake2 usercmd backup code and if your outgoing connection tends to drop packets on it's own, you will likely experience prediction misses and other issues.
cl_packetdup	1	Number of backup usercmds client should include in each packet, directly impacts outgoing bandwidth. Server runs these backup usercmds when it encounters dropped client packets. This variable is relevant only when connected using Q2PRO protocol.
cl_disable_particles	0	A bitmask. Disables rendering of particles for certain types of client effects. 1 - grenade explosions 2 - grenade trails 4 - rocket explosions 8 - rocket trails
cl_disable_explosions	0	A bitmask. Disables rendering of animated models for certain types of client effects. 1 - grenade explosions 2 - rocket explosions
cl_gibs	1	If set to 0, disables rendering of entities with EF_GIB flag set. When connected using Q2PRO protocol, enables considerable bandwith savings since the server stops sending these entities at all.
cl_gun	1	0 - do not render the gun model. When connected using R1Q2 or Q2PRO protocol, enables considerable bandwith savings since the server stops sending gun updates at all. The side effect is that cl_weapon macro no longer works. 1 - render the gun model. -1 - do not render the gun model. When connected using R1Q2 protocol, has the same effect as if set to 0. When connected using Q2PRO protocol, the server stops gun position updates but still sends current gun index. Needed for cl_weapon macro to work properly.
cl_footsteps	1	If set to 0, disables footsteps sounds. When connected using Q2PRO protocol, enables certain bandwith savings since the server stops sending footstep events at all.
cl_railtrail_type	0	0 - use original rail trail effect 1 - use alternative rail trail effect (draw rail core only) 2 - use alternative rail trail effect (draw rail rings) Alternative rail trail effect is available when using OpenGL refresh library only. Remaining cl_rail* variables are relevant only for alternative rail trail effect.
cl_railtrail_time	1.0	Time, in seconds, for the rail trail to be visible.
cl_railtrail_alpha	1.0	Initial transparency of the rail trail (it linearly fades to zero in cl_railtrail_time seconds).
cl_railcore_color	0xFF0000	Color of the core rail trail beam in the hexadecimal 0xRRGGBB format.
cl_railcore_width	3	Width of the core rail trail beam.
cl_railrings_color	0x0000FF	Color of the rail trail rings in the hexadecimal 0xRRGGBB format.
cl_railrings_width	3	Width of the rail trail rings.
in_driver	""	Specifies which non-keyboard (typically mouse) input driver to use. When set to "" or "video", default input facilities provided by the current window system are used. On Windows, there is "dinput" driver available (DirectInput version 7 and higher). On GNU/Linux, there is "evdev" driver available (Kernel input event interface).
con_clock	0	Toggles presence of clock in the right corner of console. Clock format is specified by com_time_format variable.
con_height	0.5	Fraction of the screen in-game console occupies.
con_chat	0	If enabled, all text entered into in-game console not explictly prepended by a slash or backslash is treated as chat.
con_alpha	1	Transparency of the in-game console background. Only relevant to OpenGL video modes.
con_scale	1	Scale factor of the console text. Only relevant to OpenGL video modes.
con_font	"conchars"	Font image of the console text.
con_background	"conback"	Background image of the console.
scr_demobar	1	A bitmask, specifies whether graphical status bars are drawn at the bottom of the screen when client demo or local MVD is being played back. 1 - draw current position in demo file 2 - draw current position in MVD history buffer
scr_scale	1	Scale factor of the HUD. Only relevant to OpenGL video modes.
scr_font	"conchars"	Font image of the HUD text.

Misc cvars

fs_restrict_mask	4	A bitmask of filesystem restrictions. May be set from command line only. 1 - do not load any files outside pakfiles 2 - do not load .pak files 4 - do not load .pk2 files It is an error to specify all these flags at once.
com_completion_mode	1	Specifies what action should be taken when you press TAB in a graphical or system console. 0 - print solid, alphabetically sorted list of possible matches 1 - print list of matches in multiple coloumns 2 - print separate lists of matches (cvars, commands, aliases)

Known bugs/limitations

There may be sound spatalization issues when watching MVDs using non-q2pro client.
It is not possible to display current scores or similar mod-specific info during MVD playback.
Some mods don't broadcast obituary messages and instead send them to each client with different highlighting.
MVD spectators are unable to receive such messages in freefloat mode.
Q2PRO may not be 64-bit safe.

Author

Author (SkulleR) may be contacted using this email address.

$Id: index.htm 111 2006-11-25 02:04:14Z sku11er $