XML Network Message - Revision history

Cadillac at 18:23, 24 August 2021

2021-08-24T18:23:24Z

← Older revision		Revision as of 14:23, 24 August 2021
Line 273:		Line 273:

	== Protocol Specification ==		== Protocol Specification ==

			[[Category:Development]]

Z-man: /* Obsoleting existing fields */

2009-03-02T10:59:13Z

Obsoleting existing fields

← Older revision		Revision as of 06:59, 2 March 2009
Line 217:		Line 217:

	=== Obsoleting existing fields ===		=== Obsoleting existing fields ===
	Is always possible. Rename the field to <old field name>_obsolete for that, but leave it in place. Adapt the existing code reading the field to the new name, but prepare it for the case that the field isn't set any more (by checking has_<old field name>_obsolete()) and for the case that it is still set; if it is still set, have it processed as before.		Is always possible. Rename the field to <old field name>_obsolete for that, but leave it in place. Add a comment stating the version it was obsoleted in, so we know when it can possibly be removed and its ID recycled. Adapt the existing code reading the field to the new name, but prepare it for the case that the field isn't set any more (by checking has_<old field name>_obsolete()) and for the case that it is still set; if it is still set, have it processed as before.

	Then, you should bump the network version and add a nVersionFeature named xx_<old_field_name>_obsoleted for the new feature. On writing a message with the obsoleted field, check whether all receivers of the message support that feature. If they do, omit the field. If one doesn't, then send the field anyway, the old receivers will still depend on it. If your message goes out to several peers, don't bother looping over them to send each an optimal message; just write one larger message all receivers will understand. The saved bandwidth is not worth the added code complexity.		Then, you should bump the network version and add a nVersionFeature named xx_<old_field_name>_obsoleted for the new feature. On writing a message with the obsoleted field, check whether all receivers of the message support that feature. If they do, omit the field. If one doesn't, then send the field anyway, the old receivers will still depend on it. If your message goes out to several peers, don't bother looping over them to send each an optimal message; just write one larger message all receivers will understand. The saved bandwidth is not worth the added code complexity.

Z-man: Control Messages described

2009-03-01T14:54:18Z

Control Messages described

← Older revision		Revision as of 10:54, 1 March 2009
Line 208:		Line 208:

	=== Control Messages ===		=== Control Messages ===

			Control messages are a way for the client to send change requests to the server in case direct syncs are not allowed. Players use it to request team changes, and game objects can use it for input events. To define a new control message type, EXTEND Network::NetObjectControl defined in nNetObject.proto with your data, using the provided extension slots (don't change nNetObject.proto for that). The control message sender uses BroadcastControl() to create a control message. The return value is a reference to the contained Network::NetObjectControl that you can fill. On the other side, the member function ReceiveControlNet() of the remote copy of the object will be called with a copy of the data you filled in. The system is mainly there for legacy reasons; you may just as well define a new message type with a pointer to your object in it and do the object lookup yourself in the receiving function.

	== Changing Messages ==		== Changing Messages ==

Z-man: added Syncing Pointers

2009-03-01T14:37:01Z

added Syncing Pointers

← Older revision		Revision as of 10:37, 1 March 2009
Line 200:		Line 200:

	=== Syncing Pointers ===		=== Syncing Pointers ===

			Sadly, they can no longer be put directly into messages. Use the static member function families IDToPointer() and PointerToID() to convert them to integers and transmit those. Use regular uint32 as protobuf type.

			There is one caveat, however: if you send a pointer to an object your peer doesn't know about yet, it may get turned into a NULL pointer when it's received, or the connection may be terminated. To avoid that, use the HasBeenTransmitted member function on the pointer target to determine whether the receiver already knows about it; if not, delay sending the message until it does. If you're writing pointers in network object syncs, do the checks in the virtual ClearToTransmit() function; as long as that returns false, the object won't be synced.

			(A better way for this would be if the message itself would carry information about contained pointers and automatically delay itself while it can't be correctly received. Maybe later.)

	=== Control Messages ===		=== Control Messages ===

Z-man: Added docs on changing messages

2009-03-01T14:17:27Z

Added docs on changing messages

← Older revision		Revision as of 10:17, 1 March 2009
Line 202:		Line 202:

	=== Control Messages ===		=== Control Messages ===

			== Changing Messages ==
			Over time, needs change, and network messages need to evolve. There are three main ways to change them. Before we begin, It's important to note that the segments streamed for legacy messages must not be changed in any way. You can't add fields, and you can't change field types in those sections. The only thing you can do is declaring old fields obsolete.
			=== Change existing fields ===
			While in general a bad idea, some modifications are legal. See the [http://code.google.com/apis/protocolbuffers/docs/proto.html#updating google docs] for details. In addition, it should be safe to turn repeated fields into optional ones and vice versa; the code reading a repeated field and expecting an optional field will see the last element (or none if the array is empty), and the code reading an optional field while expecting a repeated filed should see an array containing either 0 or 1 data elements.

			=== Obsoleting existing fields ===
			Is always possible. Rename the field to <old field name>_obsolete for that, but leave it in place. Adapt the existing code reading the field to the new name, but prepare it for the case that the field isn't set any more (by checking has_<old field name>_obsolete()) and for the case that it is still set; if it is still set, have it processed as before.

			Then, you should bump the network version and add a nVersionFeature named xx_<old_field_name>_obsoleted for the new feature. On writing a message with the obsoleted field, check whether all receivers of the message support that feature. If they do, omit the field. If one doesn't, then send the field anyway, the old receivers will still depend on it. If your message goes out to several peers, don't bother looping over them to send each an optimal message; just write one larger message all receivers will understand. The saved bandwidth is not worth the added code complexity.

			=== Adding new fields ===

			Just add them :) Be sure to pick an adequate name and numeric ID (<16 for things you expect to be transmitted frequently, >= 16 for other stuff and fields you expect to be obsoleted in the near future). Your reading code should handle the case where the new field isn't sent.

			Well, and sometimes, even with all those possibilities, you reach a point where you can no longer reuse an old message type. You need to start fresh. Then, things can get a bit messy :)

			=== Replacing whole messages ===

			Well, not as messy as you may think. First, you simply keep the code and structures handling the old message type for reading. In case of network object sync messages, you may have to transplant them into a new class. That's not a problem; as long as you keep the ID of the nNetObjectDescriptor and the message type, you can switch the actual implementation class around as you wish without breaking compatibility.

			Then, you implement your new message as if the old message type never existed. At this point, your code will be compatible with receiving old and new message types, but will never send old message types and therefore confuse old peers. That's where you have to create a translator. Say your old message type is OldMessage, the new message type is NewMessage, the old descriptor is named sx_oldMessageDescriptor, the new descriptor sx_newMessageDescriptor, and you have a nVersionFeature describing support for your new messages named sx_newMessageFeature. You then write

			class xMessageTranslator: public nMessageTranslator< NewMessage >
			{
			public:
			//! constructor registering with the descriptor
			xMessageTranslator(): nMessageTranslator< NewMessage >( sx_newMessageDescriptor )
			{
			}

			//! convert current message format to format suitable for old client
			virtual nMessageBase * Translate( NewMessage const & source, int receiver ) const
			{
			if( sx_newMessageFeature.Supported( receiver ) )
			{
			// no translation required
			return NULL;
			}

			OldMessage dest;

			// convert message from source to dest

			// pack result into message
			nProtoBufMessageBase * ret = sx_oldMessageDescriptor::TransformStatic( dest );

			// this bit is only required for netobject syncs while we're still compatible with stream message clients
			if( /* source was a sync message, not a creation message */ )
			{
			// make it a sync message
			ret->SetStreamer( nNetObjectDescriptorBase::SyncStreamer() );
			}

			return ret;
			}
			};

			static xMessageTranslator sx_messageTranslator;

			A fine example of this can be found in zShape.cpp.

	== Protocol Specification ==		== Protocol Specification ==

Z-man: Network Objects written

2009-02-13T18:04:24Z

Network Objects written

@@ Line 104: / Line 104: @@
 == Network Objects ==
 === Control Messages ===
 == Protocol Specification ==

Z-man: Non-standard Stuff written

2009-02-13T17:23:27Z

Non-standard Stuff written

← Older revision		Revision as of 13:23, 13 February 2009
Line 61:		Line 61:

	== Non-standard Stuff ==		== Non-standard Stuff ==

			There are some things about our protobuf message definitions that extend the standard.

			=== Strings ===

			Usually, when you define a string element of a message, it will get filtered by the receiver. Things filtered include
			* color codes
			* incomplete color codes
			* illegal whitespace
			* illegal characters
			depending on the configuration and current state. Sometimes, that is not desired. To turn off filtering, give your string
			element a name ending in _raw:

			Message StringMessage
			{
			optional string this_gets_filtered = 1;
			optional string does_not_get_filtered_raw = 2;
			}

			This is required for strings that don't represent strings in the game to be eventually rendered by clients, but rather internal strings like protocol IDs.

			=== Legacy Stream Messages ===

			Our old network system used simple unstructured stream messages. Compatibility with that is automatically ensured; protobuf messages are converted to stream messages by simply taking all elements appearing in the message definition before certain marker elements. Marker elements are those with an ID on the far side of the range reserved for internal protobuf use (>=20000).

			In this message:
			message PlayerRemoved
			{
			// the object ID of the player
			optional uint32 player_id = 1;

			// legacy message end marker, extensions go after it
			optional bool legacy_message_end_marker = 20000;

			optional string reason = 2;
			}
			only player_id will get written to and read from old stream messages, the reason will be omitted.

			Some messages even have two markers; those are messages for object syncs, everything before the first marker is written in the creation section of the stream message, everything between the markers is written in the sync section.

			The short version? If you see messages with legacy_end_markers, don't change the part before the last end marker, neither remove nor add elements. Only add new elements after the last end marker.

	== Network Objects ==		== Network Objects ==

Z-man: typo

2009-02-06T15:52:42Z

typo

← Older revision		Revision as of 11:52, 6 February 2009
Line 60:		Line 60:
	// do whatever you need to do with *message.		// do whatever you need to do with *message.

	== ~~Nonstandart~~ Stuff ==		== Non-standard Stuff ==

	== Network Objects ==		== Network Objects ==

Z-man: Documented typical use.

2009-02-06T15:51:58Z

Documented typical use.

@@ Line 1: / Line 1: @@
 {{Blueprint|network-xml}}
-= XML Network Messages (Draft) =
+= XML-Like Network Messages using google::protobuf =
-To be written :)
+== Protocol Specification ==

Epsy: spamming the Blueprint template :)

2008-04-22T20:44:05Z

spamming the Blueprint template :)

← Older revision		Revision as of 16:44, 22 April 2008
Line 1:		Line 1:
			{{Blueprint\|network-xml}}

	= XML Network Messages (Draft) =		= XML Network Messages (Draft) =

	To be written :)		To be written :)