BigWorld needs to efficiently transmit data over a network between its various components. For this purpose, BigWorld definition file describes the type of each property of an entity (despite the fact that BigWorld is scripted using Python — an untyped language).

Because bandwidth conservation is important in implementing an MMOG, property types should be selected such that they are the smallest type (in terms of number of bits) that can represent the data.

<Type> TUPLE <of> [TYPE_NAME|TYPE_ALIAS] </of> [<size> n </size>] </Type>

<Type> ARRAY <of> [TYPE_NAME|TYPE_ALIAS] </of> [<size> n </size>] </Type>

self.myList = [1,2,3]
self.myList.equals_seq( [1,2,3] )
# should return True
self.myList.equals_seq( (1,2,3) )
# should return True

self.myList = [1, 2, 3, 4, 5]
self.myList[ 3 ] = 8
self.myList.append( 6 )
self.myList.extend( [7, 8] )
self.myList += [9, 10]
self.myList.pop()
self.myList.remove( 7 )
self.myList[ 2 : 5 ] = [11, 12]
del self.myList[ 2 ]
del self.myList[ 1 : 4 ]

<Type> FIXED_DICT

  <Parent> ParentFixedDictTypeDeclaration </Parent>
   <Properties>

    <field>
      <Type> FieldTypeDeclaration </Type>
     </field>

   </Properties>

  <AllowNone> true|false </AllowNone> 

</Type>

<root>
  <TradeLog> FIXED_DICT
    <Properties>
      <dbIDA>
        <Type>      INT64                 </Type>
      </dbIDA>
      <itemsTypesA>
        <Type>      ARRAY <of> ITEM </of> </Type>      
      </itemsTypesA>
      <goldPiecesA>
        <Type>      GOLDPIECES            </Type>
      </goldPiecesA>
    </Properties>
  </TradeLog>
</root>

if entity.TradeLog[ "dbIDA" ] == 0:
  entity.TradeLog[ "dbIDA" ] = 100

if entity.TradeLog.dbIDA == 0:
  entity.TradeLog.dbIDA = 100

entity.TradeLog = { "dbIDA" : 100, "itemsTypesA" : [ 1, 2, 3 ], 
     "goldPiecesA" : 1000, "redundantKey" : 12345 }

<root>
  <Properties> FIXED_DICT
    <someProperty>
      <Type>  TradeLog    </Type>    <!-- From last example -->
      <Default>
        <dbIDA>  0  </dbIDA>
        <itemsTypesA>
          <item>  101  </item>
          <item>  102  </item>
        </itemsTypesA>
        <goldPiecesA>  100  </goldPiecesA>
      </Default>
    </someProperty>
  </Properties>
</root>

<root>
  ... other alias definitions ...
  <ALIAS_NAME> TYPE_TO_ALIAS [<Default> Value </Default> ] </ALIAS_NAME>
</root>

<root>

  <!-- Aliased data types --> 
  <OBJECT_ID>  INT32   </OBJECT_ID>
  <BOOL>       INT8    </BOOL>
  <ANGLE>      FLOAT32 </ANGLE>
  <INFO>       UINT16  </INFO>

  <!-- Aliased arrays ?
  <MISSION_STATS>  ARRAY <of> INFO           </of> </MISSION_STATS>
  <STATS_MATRIX>   ARRAY <of> MISSION_STATS  </of>  </STATS_MATRIX>

</root>

<root>
  <ALIAS_NAME> 
    USER_TYPE 
    <implementedBy> UserDataType.instance </implementedBy>
  </ALIAS_NAME>
</root>

When the server sends a property update to the client, it generally includes a byte representing the length of the data being streamed. However, if the server is able to determine that the size of a particular property is always the same when streamed to the client, that byte can be eliminated.

The server will consider a property to be a fixed-size type if it is any combination of:

Slice assignment of ARRAY elements and updates to individual ARRAY or TUPLE elements or FIXED_DICT values do not benefit from this optimisation for fixed-size types.

You can optimise your server to client bandwidth usage by ensuring that values which are updated together are fixed-size, and bundled into FIXED_DICT structures. If the entire FIXED_DICT is updated at once, then only a single message needs to be sent, without a byte indicating the length of the message.

Properties that are generally updated individually are better off not being bundled into FIXED_DICTs, as updating an individual element of a FIXED_DICT uses more bandwidth than updating a top-level property.

Where possible, avoid propagating variable-sized properties to the client. The cost of a variable-sized property is only one byte though, so for example an ARRAY should have its size specified only if it is always that long, rather than to indicate the maximum interesting length.

One other thing to note is that there is a limited number of identifiers for properties to propagate to the client, and if you have more properties for a given entity type than this, the excess properties will be sent slightly less efficiently (generally one byte more per value update) and as if they were variably-sized. The server prefers to send large fixed-size or variably-sized properties using this 'overflow' mechanism.

The dumpEntityDescription DBMgr Configuration Option can be used to examine the client to server bandwidth requirements of your entity properties and methods. See the document Server Operations Guide's section DBMgr Configuration Options.

When an entity is created, its properties are initialised to their default values. Default values can be overridden at the property level (in the entity definition file^[2]) or at the type level (in alias.xml^[3]).

The default value for each type and the syntax for overriding it are described below:

Properties represent the state of an entity. Some states are only relevant to the cell, others only to the base, and yet others only to the client. Some states, however, are relevant to more than one of these.

Each property then has a distribution type that specifies to BigWorld which execution context (cell, base, or client) is responsible for updating the property, and where to propagate its value within the system.

Data distribution is set up by specifying the sub-section <Flags> of the section <Properties> in the file <res>/scripts/entity_defs/<entity>.def.

The bit flags available are defined in bigworld/src/lib/entitydef/data_description.hpp, and are described in the list below:

<pythonProp>
  <Type> PYTHON </Type>
  ...
</pythonProp>

e.pythonProp = { 'gold': 100 }

e.pythonProp[ 'gold' ] = 50
e.pythonProp[ 'arrows' ] = 200

e.pythonProp = e.pythonProp

Custom data types are useful for the implementation of data structures with complex behaviour that is shared between different components, or that must be attached to cell entities (in which case they must be able to be transferred from one cell to another).

<Type> 
  FIXED_DICT
  <implementedBy> CustomTypeConverterInstance  </implementedBy>
  <Properties> ... </Properties>
  ...
</Type>

import cPickle

class MyCustomType( object ):          # wrapper type
  def __init__( self, dict ):
    self.a = dict[ "a" ]
    self.b = dict[ "b" ]
  ...                    # other MyCustomType methods

class MyCustomTypeConverter( object ):    # type converter class
  def getDictFromObj( self, obj ):
    return { "a": obj.a, "b": obj.b }
  
  def createObjFromDict( self, dict ):
    return MyCustomType( dict )

  def isSameType( self, obj ):
    return isinstance( obj, MyCustomType )

  def addToStream( self, obj ):          # optional
    return cPickle.dumps( obj )

  def createFromStream( self, stream ):    # optional
    return cPickle.loads( stream )

instance = MyCustomTypeConverter()    # type converter object

<Type> 
  FIXED_DICT
  <implementedBy> MyCustomTypeImpl.instance  </implementedBy>
  <Properties>
    <a> ... </a>
    <b> ... </b>
  </Properties>
  ...
</Type>

e.custType.a = 100
e.custType.b = 200

e.custType = MyCustomType( { "a": 100, "b": 200 } )

class MemberProxy( object ):              # descriptor class
  def __init__( self, memberName ):
    self.memberName = memberName

  def __get__( self, instance, owner ):
    return instance.fixedDict[ self.memberName ]

  def __set__( self, instance, value ):
    instance.fixedDict[ self.memberName ] = value

  def __delete__( self, instance ):
    raise NotImplementedError( self.memberName )

class MyCustomType( object ):            # wrapper class
  a = MemberProxy( "a" )
  b = MemberProxy( "b" )

  def __init__( self, dict ):
    self.fixedDict = dict
  ...                      # other MyCustomType methods

class MyCustomTypeConverter( object ):      # type converter class
  def getDictFromObj( self, obj ):
    return obj.fixedDict        # must return original instance
  
  def createObjFromDict( self, dict ):
    return MyCustomType( dict )

  def isSameType( self, obj ):
    return isinstance( obj, MyCustomType )

  # addToStream and createFromStream cannot be implemented

def addToStream( self, obj ):
	return struct.pack( "i", obj )

def createFromStream( self, stream ):
  if len(stream) != 4: # one integer
    raise "Error: string has wrong length"
  else:
    return struct.unpack( "I", stream )

def fromStreamToSection( self, stream, section ):
  o = self.createFromStream( stream )
  self.addToSection( o, section ) 

section.asBlob = stream

def fromSectionToStream( self, section ):
  o = self.createFromSection( section )
  return self.addToStream( o ) 

return section.asBlob

class MyCustDataType:
  def addToStream( self, obj ):
    ...
  def createFromStream( self, stream ):
    ...
  def addToSection( self, obj, section ):
    ...
  def createFromSection( self, section ):
    ...
  def fromStreamToSection( self, stream, section ):
    ...
  def fromSectionToStream( self, section ):
    ...
  def defaultValue( self ):
    ...
instance = MyCustDataType()

<root>
  ...
  <MY_CUSTOM_DATA_TYPE> 
    USER_TYPE
    <implementedBy> MyCustDataType.instance </implementedBy>
  </MY_CUSTOM_DATA_TYPE>

Some properties are updated more often than others, and almost all entities have a set of properties that need to be handled specially due to this. These properties are called volatile properties, and are pre-defined by the BigWorld engine.

Typically, properties flagged with OTHER_CLIENTS (or ALL_CLIENTS) are only sent to the appropriate client applications when the property changes. These changes are sent reliably. Properties that are deemed to be volatile are sent to the client each time that entity is considered by an AoI (via its priority queue mechanism). These are sent unreliably as a newer value will be sent the next time that entity is considered. For more details on how the AoI priority queue works, see Player AoI Updates.

The default volatile properties defined by BigWorld are outlined below:

These properties are updated with an optimised protocol used between the client and the server, in order to minimise bandwidth.

The volatile properties are listed separately to the normal properties in the file <res>/scripts/entity_defs/<entity>.def.

Each entity can decide which of these volatile properties are automatically updated. Additionally, they can have a priority attached to them. This priority determines a distance from the entity above which the property is no longer sent.

The syntax is as follows:

<root>
  ...
  <Volatile>
    <position/> | <position>  float  </position> 
    <yaw/>      | <yaw>       float  </yaw> 
    <pitch/>    | <pitch>     float  </pitch> 
    <roll/>     | <roll>      float  </roll> 
  </Volatile>
  ...

<res>/scripts/entity_defs/<entity>.def — Declaration of volatile properties

This is how the volatility status and priority of a property are interpreted:

Supposing an entity the volatile properties as defined below:

<root>
  ...
  <Volatile>
    <position/>   
    <yaw>    30.0  </yaw> 
    <pitch>  25.0  </pitch> 
  </Volatile>
  ...
</root>

<res>/scripts/entity_defs/<entity>.def — Example definition

For the above example, we have the following for each property:

Sometimes bandwidth usage can be optimised by not distributing information to clients that are distant. We can do this by attaching a <DetailLevel> tag to a property. This tag determines the distance after which property changes will not be sent to the client.

Note that this is purely an optimisation for the property. This option should only be used if bandwidth usage is proven to be too high. If this feature is enabled for the property, then you must test it very carefully to check if the result achieved in terms of game play is what you expected.

The definition of the LOD (level of detail) of a property in the file <res>/scripts/entity_defs/<entity>.def is described below:

<root>
  ...
  <Properties>
    ...
    <modelNumber>
      ...
      <DetailLevel> NEAR </DetailLevel>
    </modelNumber>
    ...

<res>/scripts/entity_defs/<entity>.def — Declaration of LOD for property

The example above declared a LOD labelled NEAR for the property. The actual value of NEAR is defined in the sub-section <level> of the section <LodLevels> in the entity's file.

For example, to subdivide the AoI into the ranges labelled NEAR, MEDIUM, and FAR (with everything further than FAR being transmitted whenever entities are within each other's AoI), the entity's definition file will include the lines below:

<root>
  ...
  <LODLevels>
    <level>  20  <label> NEAR    </label> </level>
    <level> 100  <label> MEDIUM  </label> </level>
    <level> 250  <label> FAR     </label> </level>
  </LODLevels>
  ...
</root>

<res>/scripts/entity_defs/<entity>.def — Definition of labels for LODs

The LODs specified for the entity in the example file above are illustrated below:

Location of LOD boundaries relative to the entity

Detail levels are inherited from parent definition files. Any level with the same label as a parent will modify that level, and any new levels will be added.

There is currently a limit of six levels of detail for each entity type

5.7.1. LOD and Hysteresis

In addition to its parameter <label>, the sub-section <level> can also have <hyst> parameter.

It is defined as illustrated in the example below:

<root>
  ...
  <LODLevels>
    <level>  20 <label> NEAR   </label> <hyst>  4 </hyst> </level>
    <level> 100 <label> MEDIUM </label> <hyst> 10 </hyst> </level>
    <level> 250 <label> FAR    </label> <hyst> 20 </hyst> </level>
  </LODLevels>
  ...

<res>/scripts/entity_defs/<entity>.def — Definition of hysteresis regions

This parameter defines a hysteresis region starting from the LOD's outer boundary and moving outwards. It prevents frequent changes in the LOD of a property, which saves significant processing time on the cell, as properties do not have to change their priorities often. In order to do this, the <hyst> specifies a buffer region around the boundary of a LOD level, which an entity must pass through completely before changing to a lower LOD.

The declaration of the <hyst> parameter is optional, and if not declared, it will default to 10 metres.

As an example, consider a stationary entity, and another entity travelling through points A, B, C, D, E, and finally back to A, as illustrated in the diagram below:

Entity moving around LODs of another entity

We consider the minimum LOD of properties that will be propagated from the moving entity to the stationary entity, as listed in the table below:

Table 5.6. Entity moving around LODs of another entity.

Point	LOD	Reason
A	NEAR	Unaffected by hysteresis.
B	NEAR	Entity has moved from NEAR to MEDIUM, but not yet completely through the hysteresis.
C	MEDIUM	Entity has moved from NEAR to MEDIUM, and completely through the hysteresis.
D	MEDIUM	Entity is still in MEDIUM.
E	MEDIUM	Entity is still in MEDIUM.
A	NEAR	Entity has moved from MEDIUM to NEAR.

In the example above, we have the following regarding the change of LOD for the moving entity:

• The change of LOD for the moving entity from NEAR to MEDIUM occurs at a distance of 24 metres from the stationary entity (20 metres as defined for the NEAR LOD, plus 4 metres for its hysteresis). If no <hyst> parameter were specified, the change would happen at 30 metres (since hysteresis would then default to 10 metres).

• The change of LOD for the moving entity from MEDIUM to NEAR occurs at 20 metres from the stationary entity (since hysteresis does not affect moving to a higher LOD).

When an OTHER_CLIENTS property of an entity changes, an event object is created and added to the event history. This event history is used when updating client applications that have this entity in their AoI. When this entity is considered, any events that have been added since the last time this entity was considered are sent to the client. There is the potential for multiple changes to a single property to be sent in a single update. For more details on how the AoI priority queue works, see Player AoI Updates.

If the SendLatestOnly flag is set on a property, only the latest change is kept in the event history. This avoids sending multiple changes. This can save bandwidth being sent to the client and can save some memory on CellApps if a property is changed frequently.

This value is false by default.

Client methods also have this flag. See Bandwidth Optimisation: Send Latest Only.

Note that changing the contents of ARRAY and FIXED_DICT data type instances should be avoided if the property is SendLatestOnly since this requires the entire property to be resent.

When an OTHER_CLIENTS property of an entity changes, a message is sent to appropriate client applications to update their view of this entity. By default, this message is sent reliably so that the change will be received even when there is packet loss. There may be rare situations where sending these unreliably is preferred. This is typically only used with the SendLatestOnly option and with a property that is changed continuously.

Setting SendLatestOnly to true and IsReliable to false and changing a value every game tick causes behaviour similar to volatile position and direction values.

Client methods also have this flag. See Bandwidth Optimisation: Is Reliable.

Note that changing the contents of ARRAY and FIXED_DICT data type instances should be avoided if the property has IsReliable set to false since this requires the entire property to be resent.

Entity position updates sent to the client are usually relative to the client position. These values are limited in magnitude to maxAoIRadius, which allows them to be compressed to conserve bandwidth.

However, if an entity does not have any volatile properties, it will implicitly send its detailed position to the clients interested in it. The detailed position is made up of absolute coordinates on the space. Since the position is not classified as volatile, it will be sent to all clients interested in the entity every time its value changes.

For entity types with volatile properties, a detailed position can be sent to interested clients by using the DetailedPosition option. This option is useful if higher precision is required for an entity's position updates than is provided by the usual, compressed values. However, it should be used sparingly, as it uses much larger types, and thus uses more bandwidth.

The DetailedPosition option can have a SendLatestOnly flag, which defaults to false if not specified. See Bandwidth Optimisation: Send Latest Only for more details. Using this flag will help reduce bandwidth usage for entity types whose positions change frequently.

The grammar for the DetailedPosition option is displayed below:

<root>
   ...
   <DetailedPosition>
      <SendLatestOnly> value </SendLatestOnly>
   </DetailedPosition>
   ...
</root>

It is sometimes desirable to have properties sent to the client from entities outside the client's AoI. For example, it could be that a large dragon should be visible from many kilometres away. Increasing the AoI radius to a significantly larger value is far from ideal, since it would drastically increase bandwidth usage due to unnecessary updates from many more entities.

A non-zero AppealRadius value specifies an area around the entity. If this area intersects with the client's AoI, property updates will be sent to the client as if the entity were in its AoI. For example, if the client's aoiRadius is 500m, and an entity's AppealRadius is set to 1500m, then the player will be able to see the entity from up to 2000m away. Specifically, the client will receive property updates from the entity if the distance between the avatar and the entity is less than the sum of the aoiRadius and the entity's AppealRadius, on both the X and Z axes.

In the diagram below, three clients, A, B and C, are near a large entity. The entity is within the AoI of Client C only. Client B, however, is close enough to the entity that its AoI intersects with the entity's area of appeal. For this reason, Client B will receive property updates as if the entity were in its AoI.

Clients approaching an entity's area of appeal

Entity types that set an AppealRadius will implicitly set the DetailedPosition/SendLatestOnly option. The relative position updates usually sent for an entity are restricted to values in the client's AoI, making entities outside this area too far away to have their positions represented. DetailedPosition is used because it allows values outside this range. See Detailed Position for more details.

Temporary properties can be used for properties that do not need to be backed up or offloaded with an entity.

The grammar for temporary property definition is displayed below:

<root>
   ...
   <TempProperties>
      <tempPropertyName1/>
      <tempPropertyName2/>
      ...
   </TempProperties>
   ...
</root>

These should generally be rare but are useful for properties that cannot be streamed such as sockets or properties that are recreated on restoring. These apply to both cell and base entities.

Typically, there is at least one database table associated with each entity type in the game's entity database. This is where entities of this type can be persisted. Frequently, there are entity types that never need to be persisted.

You can avoid having a table created in the database by setting its Persistent property to false.

<root>
   ...
   <Persistent>false</Persistent>
   ...
</root>

This defaults to true. The only real advantage in setting this to false is to reduce the number of tables created. There is no real performance impact.

There is a special property type, UDO_REF, that can be used in both entities and user data objects. This property type makes it possible to create a connection between an entity and a user data object, or between two user data objects. This property type is a key feature of user data objects, as it allows the creation of complex graphs made up of different types of user data objects and entities that can be used by the entity scripts as desired. A UDO_REF property is nothing more than a reference to a user data object. When an entity or a user data object with a UDO_REF property is loaded, the user data object referenced by the UDO_REF property could exist in an unloaded state if the user data object referenced hasn't been loaded yet. In this case, the script will only be able to get the user data object's unique identification number through the guid attribute. Once the referenced user data object is loaded, all it's attributes and properties can be accessed.

The most important example of this property type is in the PatrolNode user data object. The old patrol path system, including the old PATROL_PATH property type, have been deprecated. Patrol functionality is now achieved with the PatrolNode user data object, which can be linked to other PatrolNode objects through an array of UDO_REF properties. Entities that wish to patrol through a graph of PatrolNode objects just need have a UDO_REF property that links to a PatrolNode.