The file <res>/scripts/entities.xml is used by the BigWorld engine to determine the types of entities available for use.

Each tag in this file represents an entity type, and must have a corresponding definition file in the directory <res>/scripts/entity_defs, and at least one Python script file in either the <res>/scripts/base or <res>/scripts/cell directory. It may also have a script file in <res>/scripts/client.

The order in which the entity types are declared in this file corresponds to the final entity ID associated with each entity type.

In its simplest form, the entities file has one tag listed for each entity to be loaded.

To define an entity called NewEntityType, simply add a line like the one below:

<root>
  ...
  <NewEntityType/>
</root>

<res>/scripts/entities.xml ‐ Entity definition

The entity definition file <res>/scripts/entity_defs/<entity>.def determines how your scripts communicate in BigWorld. This allows the BigWorld system to abstract the tasks of sending and receiving messages into simply calling different script methods on your entities. In a sense, the definition file provides an interface to your entity, and the Python scripts provide the implementation.

The following diagram shows the conceptual parts of a BigWorld entity:

Conceptual parts of an entity

Each entity type has a corresponding definition file, named after the entity's type name followed by the extension '.def'. For example, a Seat entity type would have a file called Seat.def.

It is useful then, to have a 'minimal' definition file to aid in quickly defining a new entity, as well as to assist in explaining what the document's section is trying to accomplish.

The following file is a minimal entity definition file:

<root>

  <Parent> optional parent entity </Parent> 

  <Implements> 
     <!-- interface references -->
   </Implements>

  <ClientName> optional client type </ClientName> 
  
  <Volatile> 
     <!-- volatile definitions -->
   </Volatile>
  
  <AppealRadius> optional appeal radius </AppealRadius> 
  
  <DetailedPosition> 
     <SendLatestOnly> whether to only send the most recent position </SendLatestOnly>
   </DetailedPosition>

   <Properties> 
     <!-- properties -->
   </Properties>

  <ClientMethods> 
     <!-- declaration --> 
   </ClientMethods>

  <CellMethods> 
     <!-- declaration --> 
   </CellMethods>

  <BaseMethods> 
     <!-- declaration --> 
   </BaseMethods>

  <LoDLevels> 
    <!-- levels of detail -->
   </LODLevels>

  <NetworkCompression> 
    <!-- internal and external network compression -->
   </NetworkCompression>
</root>

<res>/scripts/entity_defs/<entity>.def ‐ Minimal entity definition file

By the end of this chapter, we should be able to replace all placeholders (denoted by italics) in the example file above with actual code.

BigWorld Technology divides processing of entities in a game world into three different execution contexts:

Entity Types

It is possible for some entity instances to not have one of these three parts. Furthermore, some entity types may not support ever having one of these parts. For each entity type, there is a script file for each of CellApp, BaseApp, and Client, if that type supports that execution context.

These script files are named after the entity type, followed by the extension '.py'. This file must contain a class with the name of the entity type.

For example, if you have an entity type Seat that can have cell, base and client execution contexts, there would be three script files, each with the implementation of the class:

The entity's base class defined in the script file is determined by the execution context that the file represents, as described below:

Entity's base class per execution context

For more details about the difference between the Base and Proxy classes, see Proxies and Players.

The start of the script for a Seat entity could be implemented as below:

The file <res>/scripts/services.xml is used by the BigWorld engine to determine the types of services available for use.

The file contains a list of Services as elements, as children of the root node:

<root>
    <Service1/>
    <Service2/>
</root>

The service definition file <res>/scripts/service_defs/<service>.def determines how your scripts communicate in BigWorld. This allows the BigWorld system to abstract the tasks of sending and receiving messages into simply calling different script methods on your services. In a sense, the definition file provides an interface to your service, and the Python scripts provide the implementation.

Each service type has a corresponding definition file, named after the service's type name followed by the extension '.def'. For example, a NoteStore service type would have a file called NoteStore.def.

The following file is a 'minimal' service definition file, to aid in quickly defining a new service:

<root>
  <Methods> 
     <!-- declaration --> 
   </Methods>
</root>

<res>/scripts/service_defs/<service>.def ‐ Minimal service definition file

BigWorld Technology handles the processing of all services in the Service execution context. Therefore, a script file for each service type is provided for this context.

For example, a NoteStore service will have one script file with the implementation of the class, located at <res>/scripts/service/NoteStore.py

The service's base class defined in the script file is BigWorld.Service, since the file represents the Service execution context.

The start of the script for a NoteStore service could be implemented as below:

import BigWorld

class NoteStore( BigWorld.Service ):
  def __init__( self ):
    BigWorld.Service.__init__( self )

<res>/scripts/service/NoteStore.py ‐ Service script file

The file <res>/scripts/user_data_objects.xml is used by the BigWorld engine to determine the types of user data objects available for use.

The file structure matches that of the <res>/entities/entities.xml. For further details refer to The entities.xml File

The user data object definition file <res>/scripts/user_data_object_defs/<user_data_object>.def determines the properties it will store and make accessible to BigWorld user data objects. The user data object definition file also specifies if the user data object should be created in the server or in the client.

The following file is a minimal entity definition file:

<root>

  <Domain> the execution context for this user </Domain> 

  <Parent> optional parent entity </Parent> 

  <Implements> 
     <!-- interface references -->
   </Implements>

   <Properties> 
     <!-- properties -->
   </Properties>

</root>

<res>/scripts/user_data_object_defs/<user_data_object>.def — Minimal user data object definition file

BigWorld Technology divides processing of user data objects in a game world into three different execution contexts, depending on its Domain:

Most implementations of user data objects will only live either in the cell or in the client. For an example of a user data object that lives in the cell, see the PatrolNode user data object scripts and definition file in the <res>/scripts folder. For an example of a client-only user data object, look in the same place for the scripts and definition file of the CameraNode user data object.

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.

All methods in all categories have some fundamental common characteristics. They are declared in the relevant section in the file <res>/scripts/entity_defs/<entity>.def, with an XML tag per method.

The method's arguments and return values (if any) are also defined in the file, and its types are specified in the same way as property types. For more details, see Property Types.

In order to declare a method called yell on the cell, which receives a string argument named phrase, we would have the lines below:

<root>
  ...
  <CellMethods>
    <yell>
      <Args>
        <phrase> STRING </phrase> <!-- phrase to exclaim -->
      </Args>
    </yell>
  </CellMethods>
  ...
</root>

<res>/scripts/entity_defs/<entity>.def ‐ Declaration of cell method yell

Once the method is declared, it also needs to be declared in the appropriate Python implementation file. Each context of execution (cell, base, and client) has a folder containing scripts for each entity.

In our example, the method was added to the section <CellMethods>, and therefore will be executed on the cell entity.

The cell script for this entity, named <res>/scripts/cell/<entity>.py, will need to define the yell method, as illustrated below:

import BigWorld
...
class <entity>(BigWorld.Entity):

  def __init__(self):
    BigWorld.Entity.__init__(self)

  def yell(self, phrase):
    # insert code to implement yell here
    return

<res>/scripts/cell/<entity>.py ‐ Definition of cell method yell

Remote two-way method calls can be used to get return values from Python calls between processes. Return values for entity methods are declared in the same format as the method arguments in the entity definition file, except that they are listed under the ReturnValues tag instead of Args. For example, the webCreateAuction Base method for an Avatar has the following definition:

<webCreateAuction>
  <Args>
    <itemSerial>  ITEMSERIAL  </itemSerial>
    <expiry>      UINT32      </expiry>
    <startBid>    GOLDPIECES  </startBid>
    <buyout>      GOLDPIECES  </buyout>
  </Args>
  <ReturnValues>
    <auctionID>   AUCTIONID   </auctionID>
  <ReturnValues>
</webCreateAuction>

This method takes a number of arguments containing the details of the item being listed for auction, and returns the unique auction ID. However, this method makes a remote call to an entity that is potentially on another process, which prevents us from receiving a return value in the usual way. Instead, this method will return a Twisted Deferred object, that will send the return values as an argument to a callback method once they are received. This entire process is explained in Twisted Deferred Objects.

...
    <BaseMethods>
        <remoteTakeDamage>
            <Args>
                <damage>        INT32   </damage>
            </Args>
            <ReturnValues>
                <health>        INT32   </health>
            </ReturnValues>
        </remoteTakeDamage>
        ...
    </BaseMethods>

    <CellMethods>
        <takeDamage>
            <Args>
                <damage>        INT32   </damage>
            </Args>
            <ReturnValues>
                <health>        INT32   </health>
                <maxHealth>     INT32   </maxHealth>
            </ReturnValues>
        </takeDamage>
        ...
    </BaseMethods>

# base/Avatar.py

from twisted.internet import defer
...

def remoteTakeDamage( self, damage )
    deferred = self.cell.takeDamage( damage )
    deferred.addCallback( partial( self.onDamageTaken, damage ) )
    return deferred

def onDamageTaken( self, damage, healthArgs ):
    health, maxHealth = healthArgs[ 0 ], healthArgs[ 1 ]
    print "Avatar 's' took %d damage, reducing its health to %d/%d" % \
        (self.basePlayerName, damage, health, maxHealth)
    return (health,)

deferred.addErrback( onError )

# cell/Avatar.py

import CustomErrors
from twisted.internet import defer
...

def takeDamage( self, damage ):
    if (damage < 0):
        # Goes to errback which 
        return defer.fail( CustomErrors.InvalidFieldError(
                "Avatar can not take negative damage" ) )

    self.health = self.health - damage

    if (self.health < 0):
        self.health = 0

    # Goes to onDamageTaken callback
    return (self.health, self.maxHealth)

raise CustomErrors.InvalidFieldError( "Avatar can not take negative damage" ) )

return defer.fail( CustomErrors.<Error Type>( <Args> ) )

Methods for services are defined in the much same way as base, cell and client methods. However, there are some slight differences, since, unlike the other categories, services are not entities. Service methods are declared in the file <res>/scripts/service_defs/<service>.def, with an XML tag per method.

Service methods fall under the Methods tag, instead of under a specific category such as BaseMethods or CellMethods.

In order to declare a method called addNote on the service, which receives a string argument named newNote, we would have the lines below:

<root>
  ...
  <Methods>
    <addNote>
      <Args>
        <newNote> STRING </newNote>
      </Args>
      <ReturnValues>
        <noteID> NOTE_ID </newNote>
      </ReturnValues>
    </addNote>
  </CellMethods>
  ...
</root>

<res>/scripts/service_defs/<service>.def ‐ Declaration of service method addNote

Once the method is declared, it also needs to be implemented in the service Python implementation file. The service execution context has a directory containing the scripts for each service.

The script for this entity, named <res>/scripts/service/<service>.py, will need to define the addNote method, as illustrated below:

import BigWorld
...
class <service>( BigWorld.Service ):

  def addNote( self, description ):
    # insert code to implement addNote here
    return

<res>/scripts/service/<entity>.py ‐ Definition of service method addNote

Different execution contexts of an entity communicate with each other by calling methods on the other execution contexts. These are exposed as special properties of the entity.

As a quick reference, the available objects are described below:

The methods of a nearby entity can be called from the client directly on the cell part of that entity.

BigWorld automatically exposes these objects to the relevant script classes.

What this means is that it is possible for any script that is part of an entity (cell, base or client part) to call other scripts that are part of the same entity. The definition file (<res>/scripts/entity_defs/<entity>.def) describes which methods are exposed to different execution contexts.

When a method is called on Entity.otherClients (or Entity.allClients), 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^[7], 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 calls of a single method to be sent in a single update.

If the SendLatestOnly flag is set on a client method, only the latest call is kept in the event history. This avoids sending multiple calls. This can save bandwidth being sent to the client and can save some memory on CellApps if a method is called frequently and only the latest call is needed.

This value is false by default.

Properties with the OTHER_CLIENTS flag also have this flag. See Bandwidth Optimisation: Send Latest Only.

When a method is called on Entity.otherClients (or Entity.allClients), a message is sent to the appropriate client applications that have this entity in their AoI^[8]. By default, these messages are sent reliably. If the IsReliable flag is set to false on a client method, this message will be sent unreliably.

Properties with the OTHER_CLIENTS flag also have this flag. See Bandwidth Optimisation: Is Reliable.

Auxiliary data can be streamed to the client via the proxy, without affecting the normal game traffic. This data is opportunistically streamed to the client when bandwidth is available.

The bandwidth used by auxiliary data streaming can be controlled using the bw.xml options in <baseApp/downloadStreaming>. For details of this option group refer to the Server Operations Guide section BaseApp Configuration Options.

All data types in this streamed data are user-defined, since BigWorld does not have any internal uses for it.

Data is added to a proxy via method streamStringToClient:

id = Proxy.streamStringToClient( id, data )

or via method streamFileToClient:

id = Proxy.streamFileToClient( id, resource )

Where the parameters are:

Once the client has received the entire data string, the callback BWPersonality.onStreamComplete is called on the client.

Because MMOGs operate over the Internet, and in order to stop players cheating, server methods (those on the cell or the base) are not automatically allowed to be called by the client.

In order to make a server method callable from the client (so that the world can provide interactivity), its declaration has to include the tag <Exposed/>, as illustrated below:

<root>
  ...
  <CellMethods>
    <yell>
      <Exposed/>
      <Args>
        <phrase> STRING </phrase> <!-- phrase to exclaim -->
      </Args>
    </yell>
  </CellMethods>
  ...
</root>

<res>/scripts/entity_defs/<entity>.def ‐ Declaration of the exposed method

The tag <Exposed/> accomplishes two things:

Client instances actually call the method with one argument fewer than the number received by the cell entity, which prevents 'entity-faking' outside the safe server environment. The entity ID needs to be passed as an argument when calling exposed methods from the server components.

The definition of the method on the cell must be extended to take this parameter, as illustrated below:

import BigWorld
class EntityName(BigWorld.Entity):

  def __init__(self):
    BigWorld.Entity.init(self)

  def yell(self, sourceEntityID, phrase):
    # insert code to implement yell here
    # if desired, check that self.id == sourceEntityID before proceeding
    return

<res>/scripts/cell/<entity>.py ‐ Definition of cell method yell

On the client, the method yell can be called with the code below:

self.cell.yell( "BigWorld message test" )

Example of a client calling a cell method yell

If the cell method yell implements the check of sourceEntityID against self.id, only its client will be able to call it. Others clients will not be able to execute it.

There might be occasions where the method might run with a different sourceEntityID. For example, for a method called shakeHand, it is a good idea to check that the source entity is within a couple of metres away from the self entity before proceeding (and maybe that neither is dead).

The arguments of a method call made from the server to the client are optimised in the same way property updates are optimised.

See Server to Client bandwidth usage of Property updates.

When the server changes a property on the client a callback method is called on the entity to allow the client to take appropriate action.

set_<property_name> is called when a property of an entity is replaced with a new value. That is, a value in the entity's __dict__ is replaced.

If an existing property is modified, either setNested_<property_name> or setSlice_<property_name> is called.

class Seat( BigWorld.Entity ):
    ...
  def set_seatType( self, oldValue ):
    ...

class Seat( BigWorld.Entity ):
    ...
  def setNested_myFixedDict( self, path, oldValue ):
    ...

self.myFixedDict.rightHandItem.weight = 10

["rightHandItem", "weight"]

self.myArray[ 5 ][ 3 ] = 8

(5, 3)

self.myArray.append( 10 )

path = [(5,6)]
oldValues = [ ]
newValues = self.myArray[ path[-1][0] : path[-1][1] ]

del self.myFixedDict.myArray[-1]

path = ["myArray", (4,4)]
oldValues = [21]

Like properties, some methods need to be broadcast only to nearby entities.

For example, even though an entity may be visible at an AoI distance (say, 500 metres), it seems unlikely that players will be able to tell the difference between a smiling and a non-smiling entity.

To reflect his, the smile method's level of detail, can be declared as illustrated below:

<root>
  ...
  <ClientMethods>
    ...
    <smile>
      ...
      <DetailDistance> 30 </DetailDistance>
    </smile>
    ...
  </ClientMethods>
  ...
</root>

<res>/scripts/cell/<entity>.py ‐ Declaration of client method smile

The specification of the LOD for a method is far simpler than it is for a property. This is because a non-broadcast property change might have to be sent later if the LOD increases, while a non-broadcast method in the same scenario will not have to.

Consequently, the method just needs to declare a tag <DetailDistance> inline, and when it is called on exposed objects allClients or otherClients, it is broadcast only to clients within the specified distance around the entity.

Once the entities have methods assigned to them, it becomes useful to be able to call methods on other entities.

If you have an object ent as a Python script representation of another entity, then you can call ent.someMethod() to call that method on ent. This assumes that someMethod() runs on the same execution context you are in. For example, if you are on the cell, then ent.someMethod() must be defined and provided by the entity type of ent.

If you are on the cell, you can call a method on the base, with the code below:

ent.base.otherMethod()

This means that once you are able to obtain an entity object, there is a plethora of options for invoking methods on different execution contexts of different entity instances. For more details, see Intra-Entity Communication.

But to achieve this, first it is necessary to retrieve the object for another entity. The mechanism for that is described in the next sub-section

ent = BigWorld.entities[ entityID ]

serviceMailbox = BigWorld.services[ serviceName ]

BigWorld.services[ 'ExampleService' ].myTest( u"This is a test" )

Mailboxes are used to communicate with entities that are remote, i.e., not on the current process.

Entities can only access other entities that are running in the same execution context^[11]However, it is often useful to be able to send a message to entities in other execution contexts. For example, an entity may wish to send a message to all members of a chat channel, but the channel might not have all its members located on the same BaseApp as the executing entity.

Mailboxes are used to implement the following properties of an entity:

There are also a special set of mailboxes available for use from the cell which reference other entities in relation to the current entity. These mailboxes are discussed in Special Mailboxes.

These afore mentioned properties (cell, base, ownClient) allow you to reference objects located on different processes, and can be sent like any other value, using method calls, and the MAILBOX data type.

You can use the MAILBOX like a normal entity reference, and call methods declared in the entity's definition file on other entities on other processes.

Considering that an entity B (referenced in the following example as anotherEntity) has a method heyThere which takes one argument of type MAILBOX, an entity A can pass its base mailbox to entity B from the cell, as in the example below:

anotherEntity.heyThere( self.base )

<res>/scripts/cell/<original_entity>.py ‐ Passing base mailbox from cell

On the receiving entity B (referenced in the example as anotherEntity), the calling entities (entity A) base mailbox (as received via the method argument) can be used to call a method someMethod on entity A. For example:

def heyThere( self, originalEntity ):
  originalEntity.someMethod()

<res>/scripts/cell/<another_entity>.py ‐ Receiving base mailbox

It is also possible to store mailboxes in a class as properties. However this is only useful for base entity mailboxes, since they will not change address as the entity moves around the space.

Cell entity mailboxes should not be stored, because they can change as the entity moves between cells. It is possible to pass cell entity mailboxes to another entity for once-off use, since they are guaranteed to be usable for the time it takes to call a method and have it respond (i.e., up to approximately 1 second).

Using mailboxes, it is also possible to call methods within a different execution context to that of the mailbox being called. For example, using a base mailbox of an entity (baseMB in the following code), it is possible to call a cell method of the base entity as follows:

baseMB.cell.cellMethod()

Calling a cell method of another entity through its base mailbox

The call is sent to the base entity first, which then calls the cell method from where the base entity resides. Though it is more convenient than calling a base method that in turn calls the cell method, it still takes two hops to call the cell entity.

Available usages are:

These are in fact instances of MailBoxes, and can be passed as method arguments. However, the same restriction applies to cellMB.base and cellMB.client as to cell mailboxes ‐ they can change as an entity moves around, and therefore should not be stored for later use.

Note that both baseMB.ownClient and cellMB.ownClient refer to their own client only. There are no shortcut calls to otherClients and allClients.

A convenient way to obtain other entities' mailboxes is by using the methods BigWorld.lookUpBaseByDBID and BigWorld.lookUpBaseByName on the BaseApp. For more details, see the Client Python API's entry Main Page → BigWorld (Module) → Member Functions.

6.13.1. Special Mailboxes

On top of the previously discussed mailboxes, the CellApp also offers a special set of mailboxes which can be used to communicate with entities within the AoI of the reference entity.

The available mailboxes are:

• entity.allClients

• entity.otherClients

• entity.clientEntity( EntityID )

The allClients mailbox will call a method on all client entities that exist in the AoI of the reference entity as well as on the reference entity's ownClient.

The following diagram illustrates a call to the allClients mailbox on Entity A such as A.allClients.chat(). This results in the chat() method being called on Entity A on ClientApps A, B and C.

The otherClients mailbox, is almost identical to the allClients mailbox, except that the method being called will not be executed on the reference entity's ownClient. This is useful for situations where the reference entity's client was the initiator of the action.

The following diagram illustrates a call to the otherClients mailbox on Entity A such as A.otherClients.jump(). This results in the jump() method being called on Entity A on ClientApps B and C.

The most complicated mailbox is clientEntity( EntityID ). This mailbox is used to call a method on an entity that is represented on the reference entity's ClientApp. This is useful for causing a behaviour that is specific to a single Client to only be seen by the interested client, such as a quest giver talking to the player.

The following diagram illustrates a call to the clientEntity mailbox on Entity B providing the EntityID of C such as B.clientEntity( C.id ).wave(). This results in the wave() method being called on Entity C on ClientApp B.

All entity method calls across physical machines are asynchronous. For example, if you execute self.cell.cellMethod() or self.client.clientMethod() on a base entity, the call returns immediately without any value. The actual method execution takes place on the machine where the cell or client part of the entity resides.

To inform the calling entity of the execution result you will have to call a function from within the method.

The example below describes the client entity of class Avatar initiating a sequence of actions to open a door, executing the following steps:

The same callback technique is used to return values from a called method.

The example below describes the client entity of class Avatar initiating a sequence of actions to inquire about an item's description based on its inventory index, executing the following steps:

For those entities residing in the same process, the method calls take place synchronously. However, since there is no guarantee that the calling entities and the called ones will always be in the same process, it is better to adopt the callback solution.

A special case is an entity method that is not defined in the entity's definition file (<res>/scripts/entity_defs/<entity>.def ‐ For details, see The Entity Definition File). In this case, the method is always executed synchronously, and is only executed in the process of the caller. For example, a method call on a ghosted entity normally will be delegated to the real one. However, if this method is not defined in the entity's definition file, it will be treated as a usual Python method, and run locally.

This mechanism does save a bit of network traffic between server components, and can return a result immediately to the caller, but it is also limited in that it can only access the read-only ghosted properties. Trying to access non-ghosted properties or to write read-only properties would result in unexpected errors. Unless carefully planned, one should not take advantage of this feature.

The Python language allows classes to be derived from each other.

For example, to define a class B, derived from A, and methods for each of them, you can have the code below:

class A:
  def f( self ):
    print "A.f was called"

class B( A ):
  def g( self ):
    print "B.g was called"

Declaring Python class A and its derived class B

Then suppose you have a program with the code below:

x = B()
x.f()
x.g()

Program using Python class inheritance

The output of this program will be as illustrated below:

A.f was called
B.g was called

Example program output

When used in entities, this form of inheritance allows the sharing of common implementation details between entity types. Multiple inheritance is allowed, so that you can use many Python classes to help implement disparate features in some entities.

This concept is illustrated in the diagram and code fragments below:

Python class inheritance

The code fragments below show how the Python class CommonBase could be used in an entity DerivedEntity^[12]

BigWorld also supports inheritance in a form similar to Java's interface system. There can be a folder <res>/scripts/defs/interfaces that can be used to declare common parts of entities. This allows the definition in one place of often-used declarations.

This concept is illustrated below:

Python entity interfaces

The format of entity interface definition files is similar to the format of entity definition files, except that interface definition files do not have the section <Parent>. For more details on entity definition files, see The Entity Definition File.

The outline of an interface definition file is described below (all sections are optional):

<root>

  <Implements>
    <!-- interface references -->
  </Implements>
  
  <Properties> 
    <!-- properties -->
  </Properties>

  <ClientMethods> 
    <!-- client methods -->
  </ClientMethods>

  <CellMethods> 
    <!-- cell methods -->
  </CellMethods>

  <BaseMethods> 
    <!-- base methods -->
  </BaseMethods>

  <LoDLevels> 
    <!-- levels of detail -->
  </LODLevels>

</root>

<res>/scripts/entity_defs/interfaces/<entity>.def ‐ Minimal entity definition file

Unlike entities, entity interfaces do not need to have associated Python implementation files, although this can be a good idea.

The code fragments below illustrate the result of using an interface in an entity definition file:

A property from an interface can be overridden if the description needs to be changed. In this case, the entire property description is replaced with the new one, so all appropriate fields need to be specified.

It is often possible to define an entity that provides functionality common to other entity types as a single base entity. For example, a collection of NPCs may share most of their implementation, but need some specific tuning to turn them into a guard or a shopkeeper.

This concept is illustrated below:

Python entity parents

The code fragments below demonstrate this form of inheritance.

There may be times when an entity type only needs to be specialised on the server. Using the optional section <ClientName> in a .def file allows a different (usually parent) entity type to be used for the client entity.

For example, if NPC is derived from Avatar, and NPC contains additional properties that the client does not need to access, NPC objects can be sent to clients as Avatar objects. This means that the client does not need a specific script to handle NPCs.

The inheritance of interfaces and parents described for entities also apply to User Data Objects. Due to the similarity of User Data Objects to regular Entities, for further details, please refer to sections Entity Interfaces and Entity Parents

For an example of inheritance in User Data Objects see <res>/scripts/user_data_object_defs/testItem.def and <res>/scripts/user_data_object_defs/testParent.def.

The base entity can be created in the following ways:

For more details on instantiating entities from the data stored in the database, see The Database Layer.

The method BigWorld.createBaseAnywhere can specify both the base and cell entity properties, and has the following signature:

def createBaseAnywhere( entityTypeName, *args, **kwargs ):

Method BigWorld.createBaseAnywhere's signature

The parameter entityTypeName is a string containing the name of the entity type to instantiate. For example, to instantiate an entity ExampleEntity, this parameter would be "ExampleEntity".

In its simplest form, it creates the entity with all default values, and is invoked as in the example below:

newEntity = BigWorld.createBaseAnywhere( "ExampleEntity" )

Example of method BigWorld.createBaseAnywhere

This method can optionally take a list of other parameters that are searched to create base and cell entity values. These parameters can be:

The keyword arguments are searched first, then the dictionaries, and finally the DataSection. If a value is not found for any of the entity's properties, the default value for that property / data type is assigned.

Keyword arguments and dictionary values not found in the entity's definition are set as base entity properties.

The method BigWorld.createBaseAnywhere creates only the base representation of the entity. If a cell entity is required, it is the base entity's duty to instantiate its associated cell entity.

To create the associated cell entity, the following methods are used:

These methods read the base entity's special variable Base.cellData (which is initialised with the cell entity's data when the base entity is created) to get the initialisation values for the cell entity. If the entity type does not support a cell entity, the base entity will not have cellData.

The variable cellData is behaves like a dictionary containing all cell properties defined in the entity's definition file (<res>/scripts/entity_defs/<entity>.def).

It also has three additional members:

Once the cell entity is successfully created, the following steps take place:

8.2.1. Creation Near an Existing Cell Entity

The diagram below illustrates the creation of the cell entity using the method Base.createCellEntity of the BigWorld module. This method cannot be used when the cell entity has already been created.

Creation of the cell entity using the method createCellEntity of BigWorld.Base.

The declaration of method createCellEntity in Python would look like this^[14]:

class Base:
  ...
  def createCellEntity( self, mailbox = None ):
    ...

<res>/scripts/base/Base.py ‐ Declaration of method createCellEntity

The parameter mailbox is a cell entity mailbox. The new cell entity is created in the same space and cell as the mailbox references (if mailbox is not None). Ideally, the two entities are close, as this increases the likelihood of the entity starting on the correct cell.

The diagram below shows the flow of communications if the entity is created on the correct cell:

Flow of communication when cell entity is created on correct cell.

The diagram below shows the flow of communications if the entity is created on an incorrect cell:

Flow of communication when cell entity is created on an incorrect cell.

import BigWorld

class someEntity( BigWorld.Base ):
  ...
  def onGetCell( self ):
    # this method was called, that means cell entity has been created.
  ...

8.2.3. Creation in a New Space

The method Base.createInNewSpace dispatches a request to the CellAppMgr to create a new space, and the entity on it.

The resulting message trace is illustrated below:

Flow of communication when creating cell entity on a new space.

The base entity is always created before the cell entity and is destroyed after it.

The sequence of events ensued by the destruction of a cell entity is described below:

Sequence of events during entity destruction on the cell.

The method Base.destroy has two Boolean keyword arguments:

When creating a cell entity, it can be created either with its base counterpart or not. The following sub-sections describe both approaches.

8.4.1. Instantiation With No Base Counterpart

The method BigWorld.createEntity can be called to create a cell entity with no associated base entity.

This scenario is illustrated below:

Creation of cell entity without base counterpart.

The method BigWorld.createEntity has the following signature:

def createEntity( entityTypeName, spaceID, position, direction, properties ):

Method BigWorld.createEntity's signature.

For details on the parameters for this method, see the Client Python API's entry Main Page → Cell → BigWorld → Function → createEntity.

8.4.2. Instantiation With Base Counterpart

The method BigWorld.createEntityOnBase allows the CellApp to create base entities. It has the following signature:

def createEntityOnBaseApp( entityTypeName, properties ):

Method BigWorld.createEntityOnBaseApp's signature

This function takes the following parameters:

• entityTypeName ‐ Name of the entity type to create.

• properties ‐ A dictionary of properties on the base as listed in the entity's definition file.

This function dispatches a message to a BaseApp to create a base entity, which can later call method createCellEntity to create the cell entity.

Creation of cell entity with its base counterpart

World Editor can be used to insert entity placeholders into chunks. These placeholders can be read by Python script on the server to load these entities into the game world using the BigWorld.fetchEntitiesFromChunks method on BaseApps.

The following example code is taken from fantasydemo/res/scripts/base/TeleportPoint.py:

class TeleportPoint( BigWorld.Base ):
  ...
  BigWorld.fetchEntitiesFromChunks( self.geometry, EntityLoader( self ) )
                                                                                
class EntityLoader:
  def __init__( self, dstEntity ):
    self.dstEntity = dstEntity
                                                                                
  def onSection( self, entityDataSection, matrix ):
    e = BigWorld.createEntity( 
      entityDataSection.readString( "type" ),
      entityDataSection[ "properties" ],
      createOnCell = self.dstEntity.cell,
      position = matrix.applyToOrigin(),
      direction = (matrix.roll, matrix.pitch, matrix.yaw))

fantasydemo/res/scripts/base/TeleportPoint.py

The BigWorld.fetchEntitiesFromChunks method causes all chunks in the space to be loaded in a loading thread. Each <entity> data section in the loaded chunks causes the method onSection to be called on the handler object. This method can then use the data section to create an appropriate entity.

For more details on loading data section information in a thread-safe way, see both the document How To Avoid Files Being Loaded in the Main Thread and the Client Python API's entries Main Page → Base → BigWorld → Function → BigWorld.fetchDataSection, BigWorld.fetchEntitiesFromChunks, and BigWorld.fetchFromChunks.

The first step to make an entity persistent is to edit its definition file (named <res>/scripts/entity_defs/<entity>.def) and specify the properties to be made persistent.

The persistent set of properties is often a small subset of the entity properties. For example, a role playing game typically has a set of core attributes (strength, dexterity, etc...), and a set of derived attributes that need to be modified transiently (maybe the character always gets full vitality when logging on, and so vitality points need not be persisted).

To mark an entity property as persistent, it needs the tag <Persistent> added to it, as illustrated below:

<root>
  ...
  <Properties>
    ...
    <somePersistentProperty>
      <Type>       TYPENAME </Type>
      <Flags>      FLAGS    </Flags>
      <Persistent> true     </Persistent>
    </somePersistentProperty>
    ...
  </Properties> 
  ...
</root>

<res>/scripts/entity_defs/<entity>.def ‐ Marking a property as persistent

If the type is FIXED_DICT, then the <Persistent> tag can be specified for each property of the FIXED_DICT data type.

For example:

<root>
  ...
  <Properties>
    ...
    <someFixedDictProperty>
      <Type>    FIXED_DICT
        <Properties>
          <a> <Type> TYPENAME </Type> </a>
          <b> 
            <Type> TYPENAME </Type>
            <Persistent> false </Persistent>
          </b>
        </Properties>
      </Type>
      <Flags>    FLAGS      </Flags>
      <Persistent>  true    </Persistent>  
    </somePersistentProperty>
    ...
  </Properties>
  ...
</root>

In the above example, someFixedDictProperty.a is persistent, but someFixedDictProperty.b is not. If the <Persistent> tag at the <someFixedDictProperty> level is false, then neither a nor b will be persistent. By default, the <Persistent> tag at the FIXED_DICT field level is true, so it is not necessary to specify it, except for selectively turning off the persistence of some fields.

Other parameters can be set for persistent properties for the MySQL database engine. For more details, see Mapping BigWorld Properties Into SQL.

<root>
  ...
  <Properties>
    ...
    <playerNickname>
      <Type>          STRING    </Type>
      ...
      <Persistent>    true      </Persistent>
      <Indexed>       true 
        <Unique>      true      </Unique>
      </Indexed>
    </playerNickname>
    ...
    <playerNumKills>
      <Type>          UINT16    </Type>
      ...
      <Persistent>    true      </Persistent>
      <Indexed>       true 
        <Unique>      false      </Unique>
      </Indexed>
    </playerNumKills>

  </Properties>

<root>
  ...
  <Properties>
    ...
    <playerNickname> 
      <Type>       STRING </Type>
      <Flags>      Flags  </Flags>
      <Persistent> true   </Persistent>
      <Identifier> true   </Identifier>
    </playerNickname>

    <someProperty1> 
      <Type>       UINT32 </Type>
    </someProperty1>

    <someProperty2> 
      <Type>       STRING </Type>
      <Persistent> true   </Persistent>
    <someProperty2>
    ...

The database provides the means of saving entities and bringing them back into the world at a later time. It also guarantees that each saved entity can have only one instance within the world. This assures that any writes to the database for the entity will be correctly carried out.

In order to use this functionality, you must first create a persistent entity. Such an entity must exist on a BaseApp, and could be of type BigWorld.Base or BigWorld.Proxy. You can create it with any of the normal techniques. For more details, see Entity Instantiation on the BaseApp.

The key for persisting an entity is its property databaseID, combined with its entity type. The property databaseID is a 64-bit integer that is unique among entities of the same type, and usually corresponds to an auto-increment field in a database table. When an entity is created with any of the usual techniques, its databaseID is set to 0, indicating that it has never been written to the database.

To add a newly created entity to the database, its method writeToDB has to be invoked (from either cell or base).

If invoked on the base entity, writeToDB receives an optional argument specifying the callback method. Upon completion, writeToDB will invoke the callback, passing a Boolean argument indicating if writing to the database succeeded or failed, and the base entity that invoked the method. A notification method is used, as the database write is an asynchronous operation.

The code fragments below illustrate the use of method writeToDB from the base.

Next time this entity is destroyed (by invoking method ent.destroy), it will be 'logged off' ‐ the database layer keeps track of whether the entity is in the world.

A destroyed entity can later be brought back to the world using the method BigWorld.createBaseFromDBID and the properties stored in the database, as illustrated below:

BigWorld.createBaseFromDBID( "someEntity", 376182, optionalCallbackMethod )

Since loading a destroyed entity from the database is also an asynchronous operation, if you wish to be notified of the completion of this process, you need to pass a callback function as the third argument of method BigWorld.createBaseFromDBID. The callback function receives the entity identifier as the only argument, which is the databaseID if entity was successfully loaded, or None, otherwise.

The code fragments below illustrate the request to reload entities from the database:

When designing persistent properties, it is useful to understand how the mapping from BigWorld types to SQL types is performed by the database layer. This information can be used for performance tuning, or in manually modifying the database.