nvs_4_quakec_coder.txt

来自「quake1 dos源代码最新版本」· 文本 代码 · 共 154 行

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

Part IV - Documentation for QuakeC Coders

You want to use the features of the enhanced NVS 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 NVS 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 NVS version. This field is not really necessary, but it
also saves you some globals.

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

The Handshake must be done in WorldSpawn() of WORLD.QC, as it is the only time
where the cvar NVS_SSVC_VERSION is not read-only and can be modified. Just set
it to your recommended NVS version.
As the cvar is range-checked the engine may lower this value to its maximum
supported NVS 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 NVS 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 ("nvs_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 NVS
versions. No problem you can limit the engine with the command NVS_MAX_SERVER, a
negative value will set it to the possible maximum. But you can also change
easily through QuakeC.

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

	// set server to recommended NVS version...
	self.nvs_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 NVS version
	if (cvar("developer"))
	{
		self.nvs_svc = cvar("temp1");
	}
	tmpstr = ftos(self.nvs_svc);
	dprint("PROGS.DAT: SSVC will be set to ");	// remove me
	dprint(tmpstr);					// remove me
	dprint("\n");					// remove me
	cvar_set ("nvs_ssvc_version", tmpstr);		// 1 global

	// ...and read supported NVS version
	self.nvs_svc = cvar("nvs_ssvc_version");	// 1 global

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

	// Please note that .nvs_svc of clients is set properly by the engine on client connect and every single frame
// 2000-04-30 NVS 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 NVS 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
NVS_InitSVCMsg() which you habe to define in DEFS.QC like this:
void(float to, float svc_message, float sub_message, entity e) NVS_InitSVCMsg = #79;	// 2000-05-02 NVS 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 NVS version before calling this
function.

Now you only have to add the corresponding writes to the message depending on
the server's NVS 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 NVS 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 NVS SVC_TE te_explosion by Maddes  start
	if (world.nvs_svc >= 1.00)
	{
		NVS_InitSVCMsg(MSG_BROADCAST, SVC_TEMPENTITY, TE_EXPLOSION, world);
	}
// 2000-05-02 NVS 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 NVS SVC_TE te_explosion by Maddes  start
	if (world.nvs_svc >= 1.00)
	{
		WriteByte (MSG_BROADCAST, 51);	// red
		WriteByte (MSG_BROADCAST, 221);	// green
		WriteByte (MSG_BROADCAST, 238);	// blue
		if (world.nvs_svc >= 2.00)
		{
			WriteByte (MSG_BROADCAST, 255);	// alpha
		}
	}
// 2000-05-02 NVS SVC_TE te_explosion by Maddes  end