Difference between revisions of "Networking Entities"

From Valve Developer Community
Jump to: navigation, search
(An Example)
Line 319: Line 319:
If a server is upgraded with a class table change, any connecting client will recieve a "Server uses different class tables" error message and be immediately dumped out.  It is not currently known whether there is any way to tell the HL2.exe core to display some other message, or in any way make a server upgrade more seemless for a novice player.
If a server is upgraded with a class table change, any connecting client will recieve a "Server uses different class tables" error message and be immediately dumped out.  It is not currently known whether there is any way to tell the HL2.exe core to display some other message, or in any way make a server upgrade more seemless for a novice player.
=Other References=
[http://developer.valvesoftware.com/wiki/Source_Multiplayer_Networking|Source Multiplayer Networking]

Revision as of 04:09, 9 August 2005


The Valve Source engine allows up to 255 players to play at the same time in a shared, virtual, real-time world. To synchronize the user input and world changes between players, Source uses a server-client architecture that communicates via UDP/IP network packets. The server as central authority processes player input and updates the world according to the game & physics rules. The server frequently broadcasts world updates to all connected clients. Logical and physical objects in the game world are called 'entities' and represented in the source code as classes derived from a shared base entity class. Some objects live only on the server (server-side only entities) and some objects live only on the client (client-side only entities), but most objects live on the server and as a corresponding copy on the client. The base entity networking code makes sure that these objects stay synchronized for all players.

Therefore the networking code has to detect changes in the server-side object, then serialize (transforming into a bit-stream) changed member variables, sending it as a data packet via the network and unserialize the data on the client (updating corresponding member variables in the client-side object). Data packets are not sent with every single change is made in some object; rather frequent snapshots (usually 20/sec) are made that contain all entity changes since the last update. Also not all entity changes are sent to all clients all the time. Only entities that are of possible interest for a client (visible, audible etc) are updated frequently to keep the network bandwidth as low as possible.

An Example

This all sounds quite complex and difficult to handle, but most of the work is done in the background by the Source engine. For a mod author it is pretty simple to create a new networked entity class.

For an example in the SDK, search for m_iPing. This illustrates networking an array, and the m_iPing variable appears in the code only a dozen times, so it's easy to find all the parts.

The next example should give an idea of how easy it can be. Still it can become very complex once you start optimizing the network bit-stream to reduce the network bandwidth.

Server-side entity (server.dll):

class CMyEntity : public CBaseEntity
	DECLARE_CLASS(CMyEntity, CBaseEntity );	// setup some macros
	DECLARE_SERVERCLASS();  // make this entity networkable

	int UpdateTransmitState()	// set transmit filter to transmit always
		return SetTransmitState( FL_EDICT_ALWAYS );

	// public networked member variables:
	CNetworkVar( int, m_nMyInteger ); // int values from 0..255
	CNetworkVar( float, m_fMyFloat ); // any float value

//Link a global entity name to this class (name used in Hammer etc.)
LINK_ENTITY_TO_CLASS( myentity, CMyEntity );

//server data table describing networked member variables (SendProps)
	SendPropInt(	SENDINFO( m_nMyInteger ), 8, SPROP_UNSIGNED ),
	SendPropFloat( SENDINFO( m_fMyFloat ), 0, SPROP_NOSCALE),

void SomewhereInYourGameCode( void )
	CreateEntityByName( "myentity" ); // create an object of this entity class

Client-side entity (client.dll):

class C_MyEntity : public C_BaseEntity
	DECLARE_CLASS( C_MyEntity, C_BaseEntity ); // setup class macros
	DECLARE_CLIENTCLASS(); // this is a client represtation for a server class 

	// networked variables as defined in server class
	int	m_nMyInteger;
	float	m_fMyFloat;

// link data table DT_Myentity to client class and map variables (RecvProps)
	RecvPropInt( RECVINFO( m_nMyInteger ) ),
	RecvPropFloat( RECVINFO( m_fMyFloat )),

Networking entities

As stated above each game object is an entity, an instance of an entity class. An entity class has, beside a unique class name, a global name that is linked with that entity class. The linkage is done by a macro:

LINK_ENTITY_TO_CLASS( globalname, CEntityClass );

The entity factory that creates world entities placed in a map uses these global names to find the matching entity class. Server-side implementations of an entity class are usually named like CName, while client-side implementations are named C_Name with an additional underscore.

A Source engine server can handle up to 2048 entities at the same time (see MAX_EDICT_BITS in \public\const.h), where each entity may have 1024 different member variables that are networked to clients (MAX_PACKEDENTITY_PROPS). (A CNetworkArray consisting of X items counts as X properties towards the 1024 limit.) Also, each entity can only send 2K of encoded data at a time. See SDK Known Issues List for more information.

A common way to address a specific entity is by its entity index ( CBaseEntity::entindex() ). Each time a new entity is instantiated, the engine looks up an unused entity index and assigns it to the new entity. Once the entity object is destroyed, its entity index becomes available again and may be reused for a different entity. Therefore the entity index is not a good way to reference a specific entity over longer times. A better and safer way is to use EHANDLEs (or CBaseHandle) to keep track of entity instances. EHANDLEs encapsulate a 32-bit ID that is unique for an entity instance during the whole game and can be used on both server and client to refer to entity objects (EHANDLEs are a combination of entity index and an increasing serial number). An EHANDLE can be transformed to CBaseEntity and vice versa just by using its overloaded operators. If an EHANDLE resolves to NULL, the entity object is not valid anymore.

// find a player, if no player is available pPlayer and hPlayer are NULL
EHANDLE hPlayer = gEntList.FindEntityByClassname( NULL, "player" );
CBaseEnity *pPlayer = hPlayer; // convert EHANDLE into entity pointer
m_hPlayer = pPlayer; // convert entity pointer to EHANDLE

To tell the server engine that an entity class should be networked and a corresponding client class exists, the DECLARE_SERVERCLASS macro must be placed in the entity's definition. This macro will register the class in a global server class list and reserve a unique class ID. The macro DECLARE_SERVERCLASS has to be added for each derived networkable entity class again. Also the macro IMPLEMENT_SERVERCLASS must be placed in the class implementation to register the server class and its data send table. This is usually done when declaring the server send table (see below).

On the client side a corresponding class has to be created which needs to place the macro DECLARE_CLIENTCLASS in its class definition and implement the macro IMPLEMENT_CLIENTCLASS_DT. This macro links the client class to a given server class name. When a client connects to a server, they exchange a list of known classes and if the client doesn't implement all server classes the connection is stopped with a message "Client missing DT class CName".

Network Variables

Entity classes have member variables just like any other classes. Some of these member variables may be server-side only, meaning they are not replicated on clients. More interesting are the member variables, which need to be replicated for the client copy of this entity. Networked variables are essential entity properties like position, angle or health. Anything that is needed to display an entity in its current state on the client must be networked.

Whenever a networked member variable changes, the Source engine must know about it to include an update message for this entity in the next snapshot broadcast. To signal a change of a networked variable, the function NetworkStateChanged() of this entity must be called to set the internal flag FL_EDICT_CHANGED. Once the engine has sent the next update, this flag will be cleared again. Now it wouldn't be very convenient to call NetworkStateChanged() every time you change a member variable, therefore networked variables use a special helper macro CNetworkVar that will replace the original variable type (int, float, bool etc) with a modified type that automatically signals a state change to its parent entity. There exits special macros for the Vector and QAngle class, as well as for arrays and EHANDLES. The practical usage of these CNetworkVars doesn't change, so you can use them just like the original data types (except networked arrays, you have to use Set() or GetForModify() when changing elements). The following example shows how the different CNetwork* macros are used when defining member variables (the comments show the non-networked version):

CNetworkVar( int, m_iMyInt );		// int m_iMyInt;
CNetworkVar( float, m_fMyFloat );		// float m_fMyFloat;
CNetworkVector( m_vecMyVector );  		// Vector m_vecMyVector;
CNetworkQAngle( m_angMyAngle );  		// QAngle m_angMyAngle;
CNetworkArray( int, m_iMyArray, 64 ); 	// int m_iMyArray[64];
CNetworkHandle( CBaseEntity, m_hMyEntity );	// EHANDLE m_hMyEntity;

Network Data Tables

When an entity signals a change and the engine is building the snapshot update, the engine needs to know how to convert a variable value into a bit stream. Of course it could just transfer the memory footprint of the member variable but that would be way too much data in most cases and not very efficient in terms of bandwidth usage. Therefore each entity class keeps a data table that describes how to encode each of its member variables. These tables are called SendTables and must have a unique name, usually like DT_EntityClassName.

Entries of this table are SendProps, objects that keep the encoding description for a member variable. The Source engine provides various different data encoders for the commonly used data types like integer, float, vector and text string. SendProps also store information on how many bits should be used, minimum and maximum values, special encoding flags and send proxy functions (explained later).

Usually you don't create and fill SendProps by yourself but rather use one of the SendProp* helper functions ( SendPropInt(…),SendPropFloat(…) etc). These functions help to set up all important encoding properties in a single line. The SENDINFO macro helps to calculate the member variable size and relative offset to the entity address. Here's an example of a SendTable for the network variables defined earlier.

   SendPropInt( SENDINFO(m_iMyInt), 4, SPROP_UNSIGNED ),
   SendPropFloat( SENDINFO(m_fMyFloat), -1, SPROP_COORD),
   SendPropVector( SENDINFO(m_vecMyVector), -1, SPROP_COORD ),		
   SendPropQAngles( SENDINFO(m_angMyAngle), 13, SPROP_CHANGES_OFTEN ),
   SendPropArray3( SENDINFO_ARRAY3(m_iMyArray), SendPropInt( SENDINFO_ARRAY(m_iMyArray), 10, SPROP_UNSIGNED ) ),
   SendPropEHandle( SENDINFO(m_hMyEntity)),

The macro IMPLEMENT_SERVERCLASS_ST automatically links the SendTable of the base class the entity it is derived from, so all inherited properties are already included. If you for some reason don't want to include base class properties, use the IMPLEMENT_SERVERCLASS_ST_NOBASE macro. Otherwise single properties of the base class can be excluded by using the SendPropExclude(…) helper function. Instead of adding a new SendProp, it removes an existing one from an inherited SendTable.

The first place to start optomizing the bit-stream size is of course the number of bits that should be used for transmission (-1=default). When you know that an integer value can only be a number between 0 and 15, you just need 4 bits instead of 32 (set also flag SPROP_UNSIGNED). Other optimizations can be archived by using proper SendProps flags:

SPROP_UNSIGNED Encodes an integer as an unsigned integer, don't send a sign bit.
SPROP_COORD Encodes float or Vector components as a world coordinate. The data is compressed, a 0.0 just needs 2 bits and other values may use up to 21 bits.
SPROP_NOSCALE Write float or Vector components as full 32-bit value to make sure no data loss occurs because of compression.
SPROP_ROUNDDOWN Limit high float value to range minus one bit unit.
SPROP_ROUNDUP Limit low float value to range minus one bit unit.
SPROP_NORMAL Float value is a normal in range between -1 to +1, uses 12 bits to encode.
SPROP_EXCLUDE Exclude a SendProp again that was added by a base class SendTable. Don't set this flag manually, use the SendPropExclude(…) function instead.
SPROP_CHANGES_OFTEN Some properties change very often like player position and view angle (almost with every snapshot). Add this flag for frequently changing SendProps, so the engine can optimize the SendTables indices to reduce networking overhead.

On the client side you must declare a ReceiveTable similar to the SendTable, so the client knows where to store the transmitted entity properties. If the variables names remain the same in the client-side class, ReceiveTables are just a simple list of received properties (property order doesn't have to match SendTable order). The macro IMPLEMENT_CLIENTCLASS_DT is used to define the ReceiveTable and also links client to the server classes and their SendTable names.

	RecvPropInt( RECVINFO ( m_iMyInt ) ),
	RecvPropFloat( RECVINFO ( m_fMyFloat ) ),
	RecvPropVector( RECVINFO ( m_vecMyVector ) ),		
	RecvPropQAngles( RECVINFO ( m_angMyAngle ) ),
	RecvPropArray3( RECVINFO_ARRAY(m_iMyArray), RecvPropInt( RECVINFO(m_iMyArray [0]))),
	RecvPropEHandle( RECVINFO (m_hMyEntity) ),

The relative offset and size of a member variable is calculated by the RECVINFO macro. If the server and client variable name is different, the RECVINFO_NAME must be used.

Transmission Filters

Transmitting all entity updates to all clients would be an unnecessary waste of bandwidth assuming that a player usually sees only a small subset of all objects in the world. In general a server needs to update only entities that are in the local vicinity of a player. Areas or rooms visible from a player's position are called the "Potential Visible Set" (PVS) of a player. A player's PVS is usually used to filter physical entities before transmitted to the client, though entities can define more complex filter rules in their virtual functions UpdateTransmitState() and ShouldTransmit(…). Specifically, logical entities use these filters since they have no 'position' and are often interesting only for players in a certain team or players of a certain game class. An entity sets its global transmission state in UpdateTransmitState() where it can choose one of the following states:

FL_EDICT_ALWAYS Always transmit this entity.
FL_EDICT_DONTSEND Don't ever transmit this entity.
FL_EDICT_PVSCHECK Always transmit entity, but check against the PVS.
FL_EDICT_FULLCHECK Call ShouldTransmit() to decide whether or not to transmit the entity. This is expensive, so only use it when needed.

If an entity changes its state so the transmission state would change too (e.g. becomes invisible etc), UpdateTransmitState() has to be called. In general you could mark all entities as FL_EDICT_FULLCHECK and place all transmission rules in ShouldTransmit(…), but that would be very expensive since the engine whould have to call ShouldTransmit(…) for every entity for every client about 30 times a second (see CServerGameEnts::CheckTransmit(…)). There are better ways to waste your server's CPU power. So whenever possible choose one of the other transmission states.

Still some entities have quite complex transmission rules (player entities, weapons etc) and calling ShouldTransmit() is unavoidable. A derived implementation of CBaseEntity::ShouldTransmit(const CCheckTransmitInfo *pInfo) must return one of the transmission flags except FL_EDICT_FULLCHECK (that would be recursive). In this case the transmission flags have the following meanings:

FL_EDICT_ALWAYS Transmit the entity this time.
FL_EDICT_DONTSEND Don't transmit the entity this time.
FL_EDICT_PVSCHECK Transmit the entity if it's inside the client's PVS.

The argument structure passed to CCheckTransmitInfo gives information about the receiving client, its current PVS and what other entities are already marked for transmission.

Send & Receive Proxies

Send and receive proxies are callback functions linked to specific Send/ReceiveProps. If installed for an entity property, these callback functions are executed whenever it's being sent or received. Proxy functions are installed when declaring entity properties in SendTables or ReceiveTables. These proxy functions allow you to modify outgoing and incoming data so you can add custom encoder and decoder implementations. A receive proxy can also be used to detect changes on a entity property without changing the incoming data. But be aware that a receive proxy is not always called if the property value really changes, for example when server is sending a full, not delta, compressed snapshot update. The following example strips the lower 2 bit of an integer before transmission, which saves bandwidth but causes a loss of data precision.

Installing the server send proxy:

void SendProxy_MyProxy( const SendProp *pProp, const void *pStruct, 
	const void *pData, DVariant *pOut, int iElement, int objectID )
	// get original variable value
	int value = *(int*)pData;

	// prepare value for transmission, will lose precision
	*((unsigned int*)&pOut->m_Int) = value >> 2;

	SendPropInt( SENDINFO(m_iMyInt ), 4, SPROP_UNSIGNED, SendProxy_MyProxy ),

Installing the client receive proxy:

void RecvProxy_MyProxy( const CRecvProxyData *pData, void *pStruct, void *pOut )
	// get the transmitted value
	int value =  *((unsigned long*)&pData->m_Value.m_Int);

	// restore value and write to destination address
	*((unsigned long*)pOut) = value << 2;

	RecvPropInt( RECVINFO ( m_iMyInt ), 0, RecvProxy_MyProxy  ),

Optimizing Bandwidth

Once the network variable and data tables are set up and all entities are working properly, the fun part of network coding begins: optimization. The source engine provides a set of tools to monitor and analyze network traffic. The goal of your optimizations is to lower the average bandwidth usage and avoid network traffic spikes (single, extremely large packets).

A well-known tool is Netgraph, which can be enabled by executing "net_graph 2" in the developer console. Netgraph shows the most important networking data in a compact form in real-time. Every incoming packet is displayed as color-coded line wandering from right to left, where the line hight represents packet size. The line colors represent different data groups as shown in this diagram:

Net graph.jpg

fps Current frames per seconds the screen is refreshing.
ping Network packet travel time between server and client in milliseconds.
in Size of last received packet in bytes, average incoming kB/ second and average packets/second received.
out Size of last send packet, average outgoing kB/second and average packets/second send.

The netgraph on screen position can be customized using the console variable "net_graphheight pixels" and "net_graphpos 1|2|3".

Another visual tool to show entity networking data in real-time is "cl_entityreport startindex". When enabling this console variable, a cell will be shown for each networked entity, containing the entity index, class name and a traffic indicator. Depending on your screen resolution hundreds of entities and their activities can be displayed at the same time. The traffic indicator is a small bar showing the transferred bits arrived with the last packet. The red line above the bar shows recent peaks. The entity text is color-coded representing the current transmission status:

Cl entityreport.jpg

none Entity index never used/transmitted.
flashing Entity PVS state change.
green Entity in PVS, but not updated recently.
blue Entity in PVS generating ongoing traffic.
red Entity still exists outside PVS, but not updated anymore.

Once you've identified a single entity constantly generating traffic or peaks you can watch that entity a bit closer using the console tool "dtwatchent entityindex". This will generate console output with each received update showing all changed member variables. For each changed property the variable name, type, SendTable index, bits used for transmission and new value is listed. Here an example output for the local player entity "dtwatchent 1":

delta entity: 1
+ m_flSimulationTime, DPT_Int, index 0, bits 8, value 17
+ m_vecOrigin, DPT_Vector, index 1, bits 52, value (171.156,-83.656,0.063)
+ m_nTickBase, DPT_Int, index 7, bits 32, value 5018
+ m_vecVelocity[0], DPT_Float, index 8, bits 20, value 11.865
+ m_vecVelocity[1], DPT_Float, index 9, bits 20, value -50.936
= 146 bits (19 bytes)

An even deeper analysis of all entity classes and average bandwidth usage of their properties is possible by using the Data Table Instrumentation (DTI). To enable DTI, the Source engine (client) must be started with a special "-dti" command line parameter, e.g "hl2.exe -game mymod -dti". Then DTI runs automatically in the background collecting data about all transmission activities. To gather a good sample of data, just connect to a game server of your mod and play for a couple of minutes. Then quit the game or run the console command "dti_flush" and the engine will write all collected data to files in your mod directory. The created files contain the data in a tabulator separated text format, which can be imported by data processing tools like MS Excel for further analysis. The most interesting file here is "dti_client.txt" where each data record contains the following fields:

Entity class; Property Name; Decode Count; Total Bits; Average Bits; Total Index Bits; Average Index Bits

A good way to search for most expensive entity properties is to sort data by "Total Bits" or "Decode Count".

Mismatched Class Tables

To work, the server and client must use the same class tables, so that each knows how to send and recieve data.

If a server is upgraded with a class table change, any connecting client will recieve a "Server uses different class tables" error message and be immediately dumped out. It is not currently known whether there is any way to tell the HL2.exe core to display some other message, or in any way make a server upgrade more seemless for a novice player.

Other References

Multiplayer Networking