QSG Network Versioning System
=============================

Part IV - Documentation for QuakeC Coders

You want to use the features of the enhanced QSG SVC messages to give your
customers a better experience of your AddOn? But you don't know how to do it?
Ok, here we go...

At first you have to know which QSG network version you want to support with
your AddOn, as you have to change all enhanced messages of this and previous
versions, no matter if you really want the features or not, but have no fear you
only have to add a couple of lines to each send message.



Step 1:
-------
Let the engine know which version your AddOn supports, and check if the engine
really can support this and react in any form you like if it doesn't.

But before I give you the description and an example code of this handshake, I
would like you to add a new entity field, which gives you the opportunity to
even check new client's QSG version. This field is not really necessary, but it
also saves you some globals.

Add the following line to DEFS.QC:
.float	qsg_svc;			// 2000-04-30 QSG COMMON by Maddes

The Handshake must be done in WorldSpawn() of WORLD.QC, as it is the only time
where the cvar QSG_SSVC_VERSION is not read-only and can be modified. Just set
it to your recommended QSG version.
As the cvar is range-checked the engine may lower this value to its maximum
supported QSG version, so read the cvar again afterwards. This is also the value
you have to care when creating SVC messages.
You may check if the supported QSG version is sufficient for your needs, and
stop the AddOn if it's not.


Simple Example:
Where you don't care about anything and work without the optional new entity
field defined in DEFS.QC.
	cvar_set ("qsg_ssvc_version", "1.00");		// 2 globals

This really is all what's necessary in WorldSpawn(), but every time you create a
possible enhanced message you have to check the cvar again, which sucks
performance and always needs a new global for the cvar name (ok, some QCC
versions can reduce this).
So it is better to use the optional entity field to save a lot of globals, also
this entity field is automatically filled by the engine in every frame for the
server (world) and the clients, so you can check new clients in ClientConnect()
and/or PutClientInServer() of CLIENT.QC.


Another example:
During your development you may wish to check your AddOn on different QSG
versions. No problem you can limit the engine with the command QSG_MAX_SERVER, a
negative value will set it to the possible maximum. But you can also change
easily through QuakeC.

// 2000-04-30 QSG HANDSHAKE by Maddes  start
	local string	tmpstr;				// 1 global

	// set server to recommended QSG version...
	self.qsg_svc = 1.20;				// 1 global
	// --> Warning!!! This if-clause and should be removed in the public release of your PROGS.DAT
	//     check for testing PROGS.DAT with different QSG version
	if (cvar("developer"))
	{
		self.qsg_svc = cvar("temp1");
	}
	tmpstr = ftos(self.qsg_svc);
	dprint("PROGS.DAT: SSVC will be set to ");	// remove me
	dprint(tmpstr);					// remove me
	dprint("\n");					// remove me
	cvar_set ("qsg_ssvc_version", tmpstr);		// 1 global

	// ...and read supported QSG version
	self.qsg_svc = cvar("qsg_ssvc_version");	// 1 global

	if (self.qsg_svc < 1.00)			// 1 global
	{
		error("Server doesn't support required QSG version 1.00\nQSG version 1.50 is recommended\nPlease visit http://qsg.telefragged.com/\n");		// global #6/6
	}

	// Please note that .qsg_svc of clients is set properly by the engine on client connect and every single frame
// 2000-04-30 QSG HANDSHAKE by Maddes  end

Ok, now you how to tell the engine what you want, and there's even an example
how to stop your AddOn not to work on older QSG versions (but who wants this,
this system's purpose is backwards compatibility).



Steps 2 ... n:
--------------
Now comes the more important part: creating messages.

In front of every possible enhanced message you have to put a call to
QSG_InitSVCMsg() which you habe to define in DEFS.QC like this:
void(float to, float svc_message, float sub_message, entity e) QSG_InitSVCMsg = #79;	// 2000-05-02 QSG SVC by Maddes

The parameter "to" is the same as for the Write functions: MSG_INIT, MSG_ONE,
MSG_ALL or MSG_BROADCAST.
Then comes the SVC message byte and its sub message byte. The sub message byte
is for messages like SVC_TEMPENTITY/TE_EXPLOSION, where the message structure is
defined through a second byte, if the SVC message has no sub bytes just set it
to zero.
At last you have to specify to which client the message is send, use world for
all clients.

This function will let the engine determine the SVC structure you will create
now, plus the converting rules for all the connected clients and MSG_INIT
messages.
You can call this function even before non-enhanced messages, but this is non-
sense. Hence you should even check the server's QSG version before calling this
function.

Now you only have to add the corresponding writes to the message depending on
the server's QSG version, the engine will handle all the conversions for the
clients.

Example:
--------
This is a fictional enhancement of SVC_TEMPENTITY/TE_EXPLOSION, where a RGB
color was added in 1.00 and later an alpha value in 2.00. You see it is very
simple to support the QSG network versioning.
Don't forget to process all occassions of a message (here
SVC_TEMPENTITY/TE_EXPLOSION), this is really the hard part.

// 2000-05-02 QSG SVC_TE te_explosion by Maddes  start
	if (world.qsg_svc >= 1.00)
	{
		QSG_InitSVCMsg(MSG_BROADCAST, SVC_TEMPENTITY, TE_EXPLOSION, world);
	}
// 2000-05-02 QSG SVC_TE te_explosion by Maddes  end
	WriteByte (MSG_BROADCAST, SVC_TEMPENTITY);
	WriteByte (MSG_BROADCAST, TE_EXPLOSION);
	WriteCoord (MSG_BROADCAST, self.origin_x);
	WriteCoord (MSG_BROADCAST, self.origin_y);
	WriteCoord (MSG_BROADCAST, self.origin_z);
// 2000-05-02 QSG SVC_TE te_explosion by Maddes  start
	if (world.qsg_svc >= 1.00)
	{
		WriteByte (MSG_BROADCAST, 51);	// red
		WriteByte (MSG_BROADCAST, 221);	// green
		WriteByte (MSG_BROADCAST, 238);	// blue
		if (world.qsg_svc >= 2.00)
		{
			WriteByte (MSG_BROADCAST, 255);	// alpha
		}
	}
// 2000-05-02 QSG SVC_TE te_explosion by Maddes  end
