BigWorld also has ARRAY and TUPLE types, which can create an array of values of any of the BigWorld primitive types.

Properties of ARRAY type have a byte size calculated by the formula below:

The components of the formula are described below:

The BigWorld TUPLE type is represented in script by the Python tuple type, while the BigWorld ARRAY type is represented in script by Python list type.

Tuples are specified as follows:

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

<res>/scripts/entity_defs/<entity>.def — TUPLE declaration syntax

Arrays are specified as follows:

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

<res>/scripts/entity_defs/<entity>.def — ARRAY declaration syntax

In case the size of an ARRAY or TUPLE is specified, then it must have the declared n elements. Adding or deleting elements to fixed-sized ARRAY or TUPLE is not allowed. If the default value is not specified, then a fixed-sized ARRAY or TUPLE will contain n default values of the element type.

Arrays can not only contain aliased data types, but may also be aliased themselves. For more details, see Alias of Data Types.

The FIXED_DICT data type allows you to define dictionary-like attributes with a fixed set of string keys. The keys and the types of the keyed values are predefined.

The declaration of a FIXED_DICT is illustrated below:

<Type> FIXED_DICT

  <Parent> ParentFixedDictTypeDeclaration </Parent>
   <Properties>

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

   </Properties>

  <AllowNone> true|false </AllowNone> 

</Type>

FIXED_DICT data type declaration

Default is false. If set to true, then None may be used as the value of the whole dictionary.

This data type may be declared anywhere a type declaration may appear, e.g., in <res>/scripts/entity_defs/alias.xml ^[1], in <res>/scripts/entity_defs/<entity>.def, as method call arguments, etc.

The code excerpt below shows the declaration of a FIXED_DICT attribute:

<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>

fantasydemo/res/scripts/entity_defs/alias.xml

Instances of FIXED_DICT can be accessed and modified like a Python dictionary, with the following exceptions:

For example:

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

Example of FIXED_DICT usage in script

Alternatively, it also supports the following:

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

Example of FIXED_DICT usage as struct in script

A FIXED_DICT instance can be set using a Python dictionary that has a superset of the keys required. Any unnecessary keys in the dictionary are ignored.

For example:

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

Example of FIXED_DICT instance being set using a Python dictionary

When setting a FIXED_DICT instance using a Python dictionary, the values of the Python dictionary are referenced by the FIXED_DICT instance.

Changes to FIXED_DICT values are propagated efficiently wherever a change to the whole property would be propagated, i.e., to ghosts and to clients — including ownClients.

The default value of a FIXED_DICT data type can be specified at the entity property level. For example:

<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>

Example of specifying default value of a FIXED_DICT data type in an entity definition file

If the <Default> section is not specified, then the default value of a FIXED_DICT data type will depend on the value of the <allowNone> tag, as described below:

Changes to properties of PYTHON and custom user types are not automatically propagated, unless the property is reassigned.

This behaviour mainly affects composite Python types like dictionaries, arrays, and classes, because modifications to the object do not cause data propagation unless the property is reassigned to itself.

For example, if entity e has the property as illustrated below:

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

Assigning a new value to pythonProp will cause data propagation:

e.pythonProp = { 'gold': 100 }

However, modifying the value will not cause data propagation:

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

Different parts of the entity will see different values for pythonProp, unless data propagation is manually triggered by reassigning the property back to itself:

e.pythonProp = e.pythonProp

It is often desirable to wrap a FIXED_DICT data type with a class to facilitate object-oriented programming.

import cPickle

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

class MyCustomTypeConverter:    // 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

<res>/scripts/common/MyCustomTypeImpl.py — Wrapper type and type converter object

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

Excerpt of a wrapped FIXED_DICT type declaration

The above example makes a FIXED_DICT type behave as a class with members a and b, instead of as a dictionary with the same keys.

The drawback with the above example is that member updates are not automatically propagated to other components. For example, if the above data type is used in an entity attribute called custType, the following script code would only set the value of the attribute for the local copy of the entity:

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

To ensure that all copies of the entity e have the updated values, the attribute must be set to a different instance of MyCustomType with the updated values:

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

Alternatively, MyCustomType can be implemented using descriptors that reference the original FIXED_DICT instance:

class MemberProxy:              // descriptor class
  def __init__( self, memberName ):
    self.member = memberName

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

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

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

class MyCustomClass:            // wrapper class
  a = MemberProxy( "a" )
  b = MemberProxy( "b" )

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

class MyCustomTypeConverter:      // 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

<res>/scripts/common/MyCustomTypeImpl.py — Wrapper type and type converter object using descriptors

In the above example, MyCustomClass references the original FIXED_DICT instance in its fixedDict member. Access to members a or b will be redirected via the descriptor class to the fixedDict member. As updates to FIXED_DICT instances are automatically propagated to other components, updates to members a and b are also automatically propagated.

The drawback with this approach is that custom streaming is not possible. If the addToStream and createFromStream methods are implemented, then the custom object is created directly from the stream. Since it is not possible to instantiate a FIXED_DICT object in Python script, it will not be possible for the custom object to reference a FIXED_DICT object that will propagate partial changes.

The USER_TYPE data type predates the FIXED_DICT data type, and much of its functionality can be achieved by wrapping a FIXED_DICT data type. However, USER_TYPE data type additionally allows customising its representation as a <DataSection>.

A USER_TYPE data type consists of the following pieces:

The custom data type might also declare a Python class that represents the type at runtime. A Python list, a dictionary, or some other native Python data type might also represent it.

The class we implement provides methods to serialise whatever Python type we use to represent a concept. This means that we can transmit the class over the network and serialise it to a database, simply by writing the appropriate methods in this class.

These methods are described in the list below:

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

We place a class implementing these methods into a module in the directory <res>/scripts/common, and create an instance variable as an instance of this class.

For example, we may define a module called MyCustDataType.py, as illustrated below:

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()

<res>/scripts/common/MyCustDataType.py — Serialisation methods

If the property is persistent, and stored in a MySQL database, then an additional method has to be implemented. This method will declare the binding of the data into the database. For more details, see The Database Layer.

The variable instance is the object that performs the manipulation of this data type by BigWorld. In the aliases file <res>/defs/alias.xml, we would include the following definition:

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

<res>/defs/alias.xml — Definition of MY_CUST_DATA_TYPE