This is the Python API reference documentation for the BaseApp portion of BigWorld.

BigWorld Technology 2.1.0. Released 2012.
Software designed and built in Australia by BigWorld.
Level 2, Wentworth Park Grandstand, Wattle St
Glebe NSW 2037, Australia
www.bigworldtech.com
Copyright 1999-2012 BigWorld Pty Ltd. All rights reserved.
This document is proprietary commercial in confidence and access is restricted to authorised users. This document is protected by copyright laws of Australia, other countries and international treaties. Unauthorised use, reproduction or distribution of this document, or any portion of this document, may result in the imposition of civil and criminal penalties as provided by law.

Copyright 1999-2012 BigWorld Pty. Ltd. All rights reserved. Proprietary commercial in confidence.


Actualised - BigWorld base Documentation

Actualised Classes Reference

The classes listed below are created through factory function or attribute accessors, and can not be instantiated directly (and so are not bound to any module).

See the class documentation for information on accessing these classes.

Class List

BaseEntityMailBox
CellEntityMailBox
GlobalBases
PyBases
PyObjectPlus
PyOutputWriter
PySTLSequence
RemoteEntityMethod
ServerEntityMailBox
ServicesMap
SharedData


BWConfig - BigWorld base Documentation

BWConfig Module Reference

Member Functions

def readBool( configOption ):
def readFloat( configOption ):
def readInt( configOption ):
def readString( configOption ):

Member Function Documentation

def readBool( configOption ):

This method returns the given value from bw.xml.

Parameters:
configOption The path of the option to get.

def readFloat( configOption ):

This method returns the given value from bw.xml.

Parameters:
configOption The path of the option to get.

def readInt( configOption ):

This method returns the given value from bw.xml.

Parameters:
configOption The path of the option to get.

def readString( configOption ):

This method returns the given value from bw.xml.

Parameters:
configOption The path of the option to get.


BWPersonality - BigWorld base Documentation

BWPersonality Module Reference

The name of this module is actually specified by the personality option in the configuration file. This module should be implemented by the user. It should contain callback methods that will be called by the server at specific events.

It is also possible to register for these events using BigWorld.addEventListener. For example, BigWorld.addEventListener( "onInit", myFunc ).

Member Functions

def onAppReady( isBootstrap, didAutoLoad ):
def onAppShutDown( stage ):
def onAppShuttingDown( shutdownTime ):
def onBaseAppData( key, value ):
def onBaseAppReady( ):
def onBaseAppShutDown( ):
def onBaseAppShuttingDown( ):
def onCellAppDeath( addr ):
def onDelBaseAppData( key ):
def onDelGlobalData( key ):
def onFini( ):
def onGlobalData( key, value ):
def onInit( isReload ):

Member Function Documentation

def onAppReady( isBootstrap, didAutoLoad ):

If present, this method is called when the BaseApp (or ServiceApp) is ready. The isBootstrap parameter indicates whether this BaseApp is the first BaseApp (called the bootstrap BaseApp).

This method is also called with a parameter indicating whether the database has automatically loaded any entities from the database. This is useful in the case where singleton entities need to be created from script if they did not already exist in the database.

Note that entity auto-load from database is only supported when the MySQL database is used.

See Also: Base.writeToDB.

Parameters:
isBootstrap | True if this BaseApp is the bootstrap BaseApp, False otherwise.
didAutoLoad | True if entities were automatically loaded by the database, False otherwise.

def onAppShutDown( stage ):

If present, this method is called when a controlled shutdown has been scheduled.

Parameters:
stage stage is the stage of shutdown that the server is in. These are as follows: 0 - Before disconnecting clients 1 - Before writing entities to the database 2 - After writing entities to the database

def onAppShuttingDown( shutdownTime ):

If present, this method is called when a controlled shutdown has been scheduled.

Parameters:
shutdownTime shutdownTime is the game time that the server is scheduled to shut down at.

def onBaseAppData( key, value ):

If present, this method is called whenever a shared BaseApp data value is set. This may be when a value is initially set or when it is modified.

See Also: BigWorld.baseAppData, BWPersonality.onDelBaseAppData, BigWorld.globalData, BWPersonality.onGlobalData, BWPersonality.onDelGlobalData

Parameters:
key | The key associated with the value.
value | The new value.

def onBaseAppReady( ):

def onBaseAppShutDown( ):

def onBaseAppShuttingDown( ):

def onCellAppDeath( addr ):

If present, this method is called when a CellApp death has been detected.

Parameters:
addr addr is the address of CellApp that has died.

def onDelBaseAppData( key ):

If present, this method is called whenever a shared BaseApp data value is deleted.

See Also: BigWorld.baseAppData, BWPersonality.onBaseAppData, BigWorld.globalData, BWPersonality.onGlobalData, BWPersonality.onDelGlobalData

Parameters:
key The key of the value deleted.

def onDelGlobalData( key ):

If present, this method is called whenever a shared Global data value is deleted.

See Also: BigWorld.globalData, BWPersonality.onGlobalData, BigWorld.baseAppData, BWPersonality.onBaseAppData, BWPersonality.onDelBaseAppData

Parameters:
key The key of the value deleted.

def onFini( ):

If present, this method is called whenever the Python script system is about to be completely shut down. This function is called after all stages of onBaseAppShutDown have executed.

def onGlobalData( key, value ):

If present, this method is called whenever a shared Global data value is set. This may be when a value is initially set or when it is modified.

See Also: BigWorld.globalData, BWPersonality.onDelGlobalData, BigWorld.baseAppData, BWPersonality.onBaseAppData, BWPersonality.onDelBaseAppData

Parameters:
key | The key associated with the value.
value | The new value.

def onInit( isReload ):

If present, this method is called whenever the Python scripts have completed loading.

Parameters:
isReload True if the loading was caused by a call to BigWorld.reloadScript, otherwise, False


BigWorld - BigWorld base Documentation

BigWorld Module Reference

The BigWorld module provides python script access to parts of the Base. Specifically it provides timer callback function registration and removal, and Base creation.

Class List

Base
Proxy
Service

Member Functions

def addEventListener( eventName, callback, level ):
def addFrequentTask( callback, level ):
def addFunctionWatcher( path, function, argumentList, exposedHint, desc ):
def addTimer( callback, initialOffset, repeatOffset=0, userArg=0 ):
def addWatcher( path, getFunction, setFunction ):
def address( ):
def authenticateAccount( username, password ):
def createBase( ):
def createBaseAnywhere( entityType, *params, callback ):
def createBaseAnywhereFromDB( entityType, identifier, callback ):
def createBaseAnywhereFromDBID( entityType, dbID, callback ):
def createBaseFromDB( ):
def createBaseFromDBID( ):
def createBaseLocally( entityType, *params ):
def createBaseLocallyFromDB( entityType, identifier, callback ):
def createBaseLocallyFromDBID( entityType, id, callback ):
def createBaseRemotely( entityType, baseMB, *params, callback ):
def createBaseRemotelyFromDB( entityType, identifier, baseMB, callback ):
def createBaseRemotelyFromDBID( entityType, dbID, baseMB, callback ):
def createEntity( ):
def delCellAppData( key ):
def delTimer( id ):
def delWatcher( path ):
def deleteBaseByDBID( entityType, dbID, callback ):
def deregisterFileDescriptor( fileDescriptor ):
def deregisterWriteFileDescriptor( fileDescriptor ):
def executeRawDatabaseCommand( command, callback ):
def fetchDataSection( path, callback ):
def fetchEntitiesFromChunks( path, handler ):
def fetchFromChunks( matches, path, handler ):
def fetchURL( url, callback, headers, timeout, method ):
def getLoad( ):
def getWatcher( path ):
def getWatcherDir( path ):
def hasStarted( ):
def isNextTickPending( ):
def isShuttingDown( ):
def lookUpBaseByDBID( entityType, dbID, callback ):
def lookUpBaseByName( entityType, name, callback ):
def lookUpBasesByIndex( entityType, callback, filter, sortProperty, sortAscending, limit, offset ):
def lookUpDBIDByName( entityType, name, callback ):
def quantumPassedPercent( ):
def registerFileDescriptor( fileDescriptor, callback ):
def registerWriteFileDescriptor( fileDescriptor, callback ):
def reloadScript( fullReload ):
def removeEventListener( eventName, callback ):
def setCellAppData( key, value ):
def setWatcher( path, val ):
def startService( serviceName ):
def stopService( serviceName ):
def time( ):

Attributes

LOG_ON_ACCEPT |
LOG_ON_REJECT |
LOG_ON_WAIT_FOR_DESTROY |
NEXT_ONLY |
baseAppData |
component |
entities | PyBases
globalBases | GlobalBases
globalData |
isServiceApp | bool

Member Function Documentation

def addEventListener( eventName, callback, level ):

The function addEventListener associates a callback with an event. The callback will be called whenever the event is triggered.

The events that can be listened to are all of the BWPersonality callbacks that do not have a return value. For example, "onInit", "onFini" etc.

Parameters:
eventName | The name of the event to listen for.
callback | A callable object that will be called on this event.
level | An optional integer level. Listeners with a higher level are called later. The default value is 0.

def addFrequentTask( callback, level ):

The function addFrequentTask registers a callback function to be called periodically (at game tick frequency). If the callback ever returns True, it is deregistered and will not be called again.

Parameters:
callback | Specifies the callable to be used. This is a function that takes no parameters.
level | Optional argument for the level to run the task at. This higher the level, the later the task is executed. Currently the only valid levels are 0 and 1.

def addFunctionWatcher( path, function, argumentList, exposedHint, desc ):

This function interacts with the watcher debugging system, allowing the creation of watcher variables.

The addFunctionWatcher function in Python allows the creation of a watcher path that can be queried as well as set with a variable length argument list.

For example:

BigWorld.addFunctionWatcher( "command/addGuards", util.patrollingGuards, [("Number of guards to add", int)], BigWorld.EXPOSE_LEAST_LOADED, "Add an arbitrary number of patrolling guards into the world.")

Raises a TypeError if the "function" argument is not callable.

Parameters:
path | The path the watcher will be created as. Function watchers are generally placed under the "command/" path structure.
function | The function to call to with the provided argument list.
argumentList | The argument list (provided as a tuple) of types and descriptions that the function accepts. See the example for more details about its structure.
exposedHint | The default exposure hint to be used when forwarding the watcher call from Managers to Components.
desc | (Optional) A description of the function watcher behaviour and usage. While this field is optional, it is strongly recommended to provide this description in order to allow usage through WebConsole to be more intuitive.

def addTimer( callback, initialOffset, repeatOffset=0, userArg=0 ):

The function addTimer registers a function to be called after "initialOffset" seconds. Optionally it can be repeated every "repeatOffset" seconds, and have optional user data (an integer that is simply passed to the timer function) "userArg".

The callback function must accept 2 arguments; the internal id of the timer (useful to remove the timer via the "delTimer" method), and the optional user supplied integer "userArg".

Example:
import BigWorld

# Callback function that accepts 2 parameters; the id of the timer,
# and the specified user argument.

# id is the internal id of the timer, and can be used to remove the
# timer via the use of the BigWorld.delTimer function
def onTimer( self, id, userArg ):
    print "onTimer called: id %i, userArg: %i" % ( id, userArg )
    # if this is a repeating timer then call:
    #     BigWorld.delTimer( id )
    # to remove the timer when it is no longer needed

# call onTimer after 5 seconds, and then every 1 second with a userArg of 9
BigWorld.addTimer( onTimer, 5, 1, 9 )

# call onTimer after 1 second with no repeat and userArg defaulting to a
# value of 0
BigWorld.addTimer( onTimer, 1 )

Parameters:
callback | Specifies the timer handler to be used. This is a function that takes 2 integer parameters.
initialOffset | initialOffset is a float and specifies the interval (in seconds) between registration of the timer, and the time of first execution.
repeatOffset | repeatOffset is an optional float and specifies the interval (in seconds) between repeated executions after the first execution. BigWorld.delTimer must be used to remove the timer or this will repeat continuously.
userArg | userArg is an optional integer which specifies an optional user supplied value to be passed to the callback method.

Returns:
Integer. This function returns the internal id of the timer. This can be used with BigWorld.delTimer to remove the timer.

def addWatcher( path, getFunction, setFunction ):

This function interacts with the watcher debugging system, allowing the creation of watcher variables.

The addWatcher function in Python allows the creation of a particular watcher variable. For example:

>>> maxBandwidth = 20000
>>> def getMaxBps( ):
>>>     return str(maxBandwidth)
>>> def setMaxBps( bps ):
>>>     maxBandwidth = int(bps)
>>>     setBandwidthPerSecond( int(bps) )
>>>
>>> BigWorld.addWatcher( "Comms/Max bandwidth per second", getMaxBps, setMaxBps )

This adds a watcher variable under "Comms" watcher directory. The function getMaxBps is called to obtain the watcher value and setMaxBps is called when the watcher is modified.

Raises a TypeError if getFunction or setFunction is not callable.

Parameters:
path | the path to the item to create.
getFunction | the function to call when retrieving the watcher variable. This function takes no argument and returns a string representing the watcher value.
setFunction | (optional)the function to call when setting the watcher variable This function takes a string argument as the new watcher value. This function does not return a value. If this function does not exist the created watcher is a read-only watcher variable.

def address( ):

This method returns the address of the internal network interface.

def authenticateAccount( username, password ):

This method validates whether a username and password pair are valid. On success, the entity type and database id of the associated entity are returned to the Twisted Deferred.

Parameters:
username | The username to test.
password | The password to test.

Returns:
A Twisted Deferred. On success, callback will be called with a 2-tuple containing the entity type and database id of the entity associated with this account. On failure, errback is called with a Failure object indicating the reason for failure.

def createBase( ):

def createBaseAnywhere( entityType, *params, callback ):

This method should be preferred to BigWorld.createBaseLocally and BigWorld.createBaseRemotely as the server has the flexibility to create the entity on an appropriately loaded BaseApp.

The function takes the name of the entity type to be created and optionally a Python dictionary or keyword arguments to be used to provide initial values for the entity.

Any values not provided will default to the entity's default value provided by the ".def" file.

Parameters:
entityType | Specifies the type of base entity to be created. It must be a string specifying the name of the entity type. Valid entity types are those listed in scripts/entities.xml that have a base entity component.
*params | The remaining, optional arguments. These arguments can be Python dictionaries, keyword arguments, or a DataSection. If a specified key is a Base property, its value will be used to initialise the Base entity property. If the key is a Cell property, it will be added into the 'cellData' attribute on the base entity, which is a Python dictionary, and later be sent to initialise the cell entity properties.
callback | callback is an optional callable object that will be called when the entity has been created. It is called with one argument that is a mailbox to the new base entity on success and None on failure.

Returns:
A mailbox to the new Base entity.

def createBaseAnywhereFromDB( entityType, identifier, callback ):

Parameters:
entityType | This is a string specifying the type of Base entity to load. Entity types are listed in /scripts/entities.xml.
identifier | This is a string specifying the unique identifier of the entity to load. The identifier property of an entity is specified by using the tag in the entity definition file.
callback | This is an optional callable object that will be called when operation completes. The callable object will be called with three arguments: baseRef, databaseID and wasActive. If the operation was successful then baseRef will be a mailbox or direct reference to the newly created base entity, databaseID will be the database ID of the entity and wasActive will indicate whether the entity was already active. If wasActive is true then baseRef is a reference to a pre-existing entity. If the operation failed, then baseRef will be None, databaseID will be 0 and wasActive will be false. The most common reason for failure is the that entity does not exist in the database but intermittent failures like timeouts or unable to allocate IDs may also occur.

def createBaseAnywhereFromDBID( entityType, dbID, callback ):

Parameters:
entityType | This is a string specifying the type of Base entity to load. Entity types are listed in /scripts/entities.xml.
dbID | This is a number specifying the database ID of the entity to create. The database ID of an entity is stored in the databaseID property of the entity.
callback | This is an optional callable object that will be called when operation completes. The callable object will be called with three arguments: baseRef, databaseID and wasActive. If the operation was successful then baseRef will be a mailbox or direct reference to the newly created base entity, databaseID will be the database ID of the entity and wasActive will indicate whether the entity was already active. If wasActive is true then baseRef is a reference to a pre-existing entity. If the operation failed, then baseRef will be None, databaseID will be 0 and wasActive will be false. The most common reason for failure is the that entity does not exist in the database but intermittent failures like timeouts or unable to allocate IDs may also occur.

def createBaseFromDB( ):

def createBaseFromDBID( ):

def createBaseLocally( entityType, *params ):

Any values not provided will default to the entity's default value provided by the ".def" file.

BigWorld.createBaseAnywhere should be preferred to this method and BigWorld.createBaseRemotely as the server has the flexibility to create the entity on an appropriately loaded BaseApp.

Parameters:
entityType | Specifies the type of base entity to be created. It must be a string specifying the name of the entity type. Valid entity types are those listed in scripts/entities.xml that have a base entity component.
*params | The remaining, optional arguments. These arguments can be Python dictionaries, keyword arguments, or a DataSection. If a specified key is a Base property, its value will be used to initialise the Base entity property. If the key is a Cell property, it will be added into the 'cellData' attribute on the base entity, which is a Python dictionary, and later be sent to initialise the cell entity properties.

Returns:
The newly created base entity (see Base for a description of the base entity returned).

def createBaseLocallyFromDB( entityType, identifier, callback ):

Parameters:
entityType | This is a string specifying the type of Base entity to load. Entity types are listed in /scripts/entities.xml.
identifier | This is a string specifying the unique identifier of the entity to load. The identifier property of an entity is specified by using the tag in the entity definition file.
callback | This is an optional callable object that will be called when operation completes. The callable object will be called with three arguments: baseRef, databaseID and wasActive. If the operation was successful then baseRef will be a reference to the newly created Base entity, databaseID will be the database ID of the entity and wasActive will indicate whether the entity was already active. If wasExisting is true, then baseRef is referring to a pre-existing Base entity and may be a mailbox rather than a direct reference to a base entity. If the operation failed, then baseRef will be None, databaseID will be 0 and wasActive will be false. The most common reason for failure is the that entity does not exist in the database but intermittent failures like timeouts or unable to allocate IDs may also occur.

def createBaseLocallyFromDBID( entityType, id, callback ):

Parameters:
entityType | This is a string specifying the type of Base entity to load. Entity types are listed in /scripts/entities.xml.
id | This is a number specifying the database ID of the entity to create. The database ID of an entity is stored in the databaseID property of the entity.
callback | This is an optional callable object that will be called when operation completes. The callable object will be called with three arguments: baseRef, databaseID and wasActive. If the operation was successful then baseRef will be a reference to the newly created Base entity, databaseID will be the database ID of the entity and wasActive will indicate whether the entity was already active. If wasExisting is true, then baseRef is referring to a pre-existing Base entity and may be a mailbox rather than a direct reference to a base entity. If the operation failed, then baseRef will be None, databaseID will be 0 and wasActive will be false. The most common reason for failure is the that entity does not exist in the database but intermittent failures like timeouts or unable to allocate IDs may also occur.

def createBaseRemotely( entityType, baseMB, *params, callback ):

BigWorld.createBaseAnywhere should be preferred to this method and BigWorld.createBaseLocally as the server has the flexibility to create the entity on an appropriately loaded BaseApp.

Any values not provided will default to the entity's default value provided by the ".def" file.

Parameters:
entityType | Specifies the type of base entity to be created. It must be a string specifying the name of the entity type. Valid entity types are those listed in scripts/entities.xml that have a base entity component.
baseMB | This is a Base entity mailbox. The new base entity will be created on the same BaseApp as this base entity.
*params | The remaining, optional arguments. These arguments can be Python dictionaries, keyword arguments, or a DataSection. If a specified key is a Base property, its value will be used to initialise the Base entity property. If the key is a Cell property, it will be added into the 'cellData' attribute on the base entity, which is a Python dictionary, and later be sent to initialise the cell entity properties.
callback | callback is an optional callable object that will be called when the entity has been created. It is called with one argument that is a mailbox to the new base entity on success and None on failure.

Returns:
A mailbox to the new Base entity.

def createBaseRemotelyFromDB( entityType, identifier, baseMB, callback ):

Parameters:
entityType | This is a string specifying the type of Base entity to load. Entity types are listed in /scripts/entities.xml.
identifier | This is a string specifying the unique identifier of the entity to load. The identifier property of an entity is specified by using the tag in the entity definition file.
baseMB | This is a Base entity mailbox. The new base entity will be created on the same BaseApp as this base entity
callback | This is an optional callable object that will be called when operation completes. The callable object will be called with three arguments: baseRef, databaseID and wasActive. If the operation was successful then baseRef will be a mailbox or direct reference to the newly created base entity, databaseID will be the database ID of the entity and wasActive will indicate whether the entity was already active. If wasActive is true then baseRef is a reference to a pre-existing entity. If the operation failed, then baseRef will be None, databaseID will be 0 and wasActive will be false. The most common reason for failure is the that entity does not exist in the database but intermittent failures like timeouts or unable to allocate IDs may also occur.

def createBaseRemotelyFromDBID( entityType, dbID, baseMB, callback ):

Parameters:
entityType | This is a string specifying the type of Base entity to load. Entity types are listed in /scripts/entities.xml.
dbID | This is a number specifying the database ID of the entity to create. The database ID of an entity is stored in the databaseID property of the entity.
baseMB | This is a Base entity mailbox. The new base entity will be created on the same BaseApp as this base entity
callback | This is an optional callable object that will be called when operation completes. The callable object will be called with three arguments: baseRef, databaseID and wasActive. If the operation was successful then baseRef will be a mailbox or direct reference to the newly created base entity, databaseID will be the database ID of the entity and wasActive will indicate whether the entity was already active. If wasActive is true then baseRef is a reference to a pre-existing entity. If the operation failed, then baseRef will be None, databaseID will be 0 and wasActive will be false. The most common reason for failure is the that entity does not exist in the database but intermittent failures like timeouts or unable to allocate IDs may also occur.

def createEntity( ):

def delCellAppData( key ):

This function deletes a data value that is accessible from all CellApps. This can be accessed on CellApps via BigWorld.cellAppData.

The CellAppMgr is the authoritative copy of this data. If two or more components try to set the same value, the last one to reach the CellAppMgr will be the one that is kept.

Note: Care should be taken using this functionality. It does not scale well and should be used sparingly.

Parameters:
key The key of the value to be deleted.

def delTimer( id ):

See BigWorld.addTimer for an example of timer usage.

Parameters:
id id is an integer that specifies the internal id of the timer to be removed.

def delWatcher( path ):

Parameters:
path the path of the watcher to delete.

def deleteBaseByDBID( entityType, dbID, callback ):

Parameters:
entityType | entityType is a string that specifies the type of the entity to be deleted.
dbID | Specifies the database ID of the entity to delete.
callback | callback is a callable object (e.g. a function) that takes one argument. If deletion is successful, the callback is called with the value True, if it is unsuccessful because the specified entry is currently checked out, it is called with the mailbox of that base entity, and if it is unsuccessful for any other reason (e.g. specified entry does not exist) then it is called with the value False.

def deregisterFileDescriptor( fileDescriptor ):

This function deregisters a callback that has been registered with BigWorld.registerFileDescriptor.

Parameters:
fileDescriptor An object that has a fileno method such as a socket or file, or an integer representing a file descriptor.

def deregisterWriteFileDescriptor( fileDescriptor ):

This function deregisters a callback that has been registered with BigWorld.registerWriteFileDescriptor.

Parameters:
fileDescriptor An object that has a fileno method such as a socket or file, or an integer representing a file descriptor.

def executeRawDatabaseCommand( command, callback ):

Please note that the entity data in the database may not be up to date, especially when secondary databases are enabled. It is highly recommended that this function is not used to read or modify entity data.

Parameters:
command | The command string specific to the present database layer. For MySQL database it is an SQL query.
callback | The object to call back (e.g. a function) with the result of the command execution.

def fetchDataSection( path, callback ):

Parameters:
path | The path to the data section to load.
callback | callback is a callable object (e.g. a function) that takes one argument, the data section specified by path. If the data section could not be loaded, the callback is called with None as the argument.

def fetchEntitiesFromChunks( path, handler ):

The onSection method will be called for each entity section encountered in the chunks. This method is called with two arguments. The first is the entity data section and the second is a matrix corresponding to the position of the entity. If the handler wants to pause processing until the next game tick, True should be returned from this function, otherwise None or False should be returned.

The onFinish method is called with no arguments when all chunks have been traversed.

Parameters:
path | The path to the space that is to be loaded.
handler | A Python object with an onSection method and optionally an onFinish method.

def fetchFromChunks( matches, path, handler ):

The onSection method will be called for each matched section encountered in the chunks. This method is called with two arguments. The first is the matched data section and the second is a matrix corresponding to the position of the section. If the handler wants to pause processing until the next game tick, True should be returned from this function, otherwise None or False should be returned.

The onFinish method is called with no arguments when all chunks have been traversed.

Parameters:
matches | If a string is passed in, sections named this are passed to the callback. If a sequence of strings is passed, any section with a name in the sequence is passed to the callback.
path | The path to the space that is to be loaded.
handler | A Python object with an onSection method and optionally an onFinish method.

def fetchURL( url, callback, headers, timeout, method ):

Keyword arguments are supported for this function.

Parameters:
url | The URL to retrieve.
callback | The callable object that receives the response object. The response object has body and responseCode properties.
headers | An optional sequence of strings to be added to the request's HTTP headers.
timeout | Option argument for the number of seconds before this call should time out.
method | "GET" or "PUT" to indicate the HTTP method.

def getLoad( ):

def getWatcher( path ):

This function interacts with the watcher debugging system, allowing the retrieval of watcher variables.

The watcher debugging system allows various variables to be displayed and updated from within the runtime.

Watchers are specified in the C-code using the MF_WATCH macro. This takes three arguments, the first is a string specifying the path (parent groups followed by the item name, separated by forward slashes), the second is the expression to watch. The third argument specifies such things as whether it is read only or not, and has a default of read-write.

The getWatcher function in Python allows the getting of a particular value. For example:

>>>	BigWorld.getWatcher( "Client Settings/Terrain/draw" )
1

Raises a TypeError if the watcher was not found.

Parameters:
path the path to the item to modify.

Returns:
the value of that watcher variable.

def getWatcherDir( path ):

This function interacts with the watcher debugging system, allowing the inspection of a directory watcher.

Raises a TypeError if not found.

Parameters:
path the path to the item to modify.

Returns:
a list containing an entry for each child watcher. Each entry is a tuple of child type, label and value. The child type is 1 for read-only, 2 for read-write and 3 for a directory.

def hasStarted( ):

def isNextTickPending( ):

This can be controlled by the baseApp/reservedTickFraction setting in bw.xml.

Returns:
isNextTickPending returns True if the next tick is pending, False otherwise.

def isShuttingDown( ):

def lookUpBaseByDBID( entityType, dbID, callback ):

Parameters:
entityType | entityType is a string that specifies the type of the entity to look up.
dbID | Specifies the database ID of the entity to look up.
callback | callback is a callable object (e.g. a function) that takes one argument. If the lookup is successful, the callback is called with the base mailbox, if it is unsuccessful because the specified entry is not currently checked out, it is called with the value True, and if it is unsuccessful for any other reason (e.g. specified entry does not exist) then it is called with the value False.

def lookUpBaseByName( entityType, name, callback ):

Parameters:
entityType | entityType is a string that specifies the type of the entity to look up.
name | Specifies the name of the entity to look up.
callback | callback is a callable object (e.g. a function) that takes one argument. If the lookup is successful, the callback is called with the base mailbox, if it is unsuccessful because the specified entry is not currently checked out, it is called with the value True, and if it is unsuccessful for any other reason (e.g. specified entry does not exist) then it is called with the value False.

def lookUpBasesByIndex( entityType, callback, filter, sortProperty, sortAscending, limit, offset ):

Perform an asynchronous look-up of persistent base entities stored in the primary database based on matching some of its properties. For efficiency, query properties should be an indexed property as defined in the entity definitions for the given entity type. They are specified in the search as keyword arguments to this method. The property matches are combined using the AND operator.

If successful, the callback argument is called with a list of pairs for each matching persistent entity:

[ (databaseID0, baseMailBox0), (databaseID1, baseMailBox1), ... ]

If the entity is currently checked out, the base mailbox is returned as the second element of the pair. If the entity is not current checked out, the second element of the pair will be None.

If the request resulted in a database error of some kind (this does not include the case where zero entities are matched), the callback argument will be called with None instead. Examples include if the property is of an inappropriate type to compare with a string (e.g. sequence and structured data types, PYTHON types, FLOAT* types).

Note that this method queries the primary database. If secondary databases are used, the data may be out-of-date with respect to what is contained in the secondary databases.

Parameters:
entityType | The name of the entity type to query for.
callback | A callable object that is called back when matched results are received.
filter | (Optional) One of the BigWorld.LOOK_UP_ENTITIES_FILTER_constants. (default is BigWorld.LOOK_UP_ENTITIES_FILTER_ALL).
sortProperty | (Optional) The property name to sort on.
sortAscending | (Optional) If True, sort in ascending or descending order. Default True.
limit | (Optional) Limit for the number of results returned, defaults to -1, indicating no limit.
offset | (Optional) Offset for the results returned, defaults to 0.

def lookUpDBIDByName( entityType, name, callback ):

Parameters:
entityType | entityType is a string that specifies the type of the entity to look up.
name | Specifies the name of the entity to look up.
callback | callback is a callable object (e.g. a function) that takes one argument: the database ID. If the specified entity does not exist then the database ID will be 0.

def quantumPassedPercent( ):

The function quantumPassedPercent returns the percentage of execution time that the application is through the current tick. The returned value is an integer from 0 upwards, and could conceivably be larger than 100 if the current tick execution time is longer than the expected interval between ticks.

Returns:
quantumPassedPercent returns the percentage of execution time that the application is through the current tick as an integer, truncated to the nearest percent.

def registerFileDescriptor( fileDescriptor, callback ):

This function registers a callback that will be called whenever there is data for reading on the input file descriptor.

Parameters:
fileDescriptor | An object that has a fileno method such as a socket or file, or an integer representing a file descriptor.
callback | A callable object that expects the fileDescriptor object as its only argument.

def registerWriteFileDescriptor( fileDescriptor, callback ):

This function registers a callback that will be called when the input file descriptor is available for writing.

Parameters:
fileDescriptor | An object that has a fileno method such as a socket or file, or an integer representing a file descriptor.
callback | A callable object that expects the fileDescriptor object as its only argument.

def reloadScript( fullReload ):

This method reloads Python modules related to entities and custom data types. The class of current entities are set to the newly loaded classes. This method should be used for development only and is not suitable for production use. The following points should be noted:

1) Scripts are only reloaded on the component baseapp that this method is called on. The user is responsible for making sure that reloadScript is called on all server components.

2) The client doesn't have equivalent functionality in Python. Each BigWorld client needs to use CapsLock + F11 in order to reload the scripts.

3) Doesn't handle custom data types transparently. Instances of custom data types must have their __class__ reassigned to the proper class type after reloadScript() completes. For example, if we have a custom data type named "CustomClass":

for e in BigWorld.entities.values():
   if type( e ) is Avatar.Avatar:
      e.customData.__class__ = CustomClass
BWPersonality.onInit( True ) is called when this method completes (where BWPersonality is the name of the personality module specified in <root>/<personality> in bw.xml).

Parameters:
fullReload Optional boolean parameter that specifies whether to reload entity definitions as well. If this parameter is False, then entities definitions are not reloaded. Default is True.

Returns:
True if reload successful, False otherwise.

def removeEventListener( eventName, callback ):

The function removeEventListener removes an event listener associated with an event previously added using BigWorld.addEventListener.

Parameters:
eventName | The name of the event that was listened for.
callback | The callable object that should be removed.

def setCellAppData( key, value ):

This function sets a data value that is accessible from all CellApps. This can be accessed on CellApps via BigWorld.cellAppData.

The CellAppMgr is the authoritative copy of this data. If two or more components try to set the same value, the last one to reach the CellAppMgr will be the one that is kept.

Note: Care should be taken using this functionality. It does not scale well and should be used sparingly.

Parameters:
key | The key of the value to be set.
value | The new value.

def setWatcher( path, val ):

This function interacts with the watcher debugging system, allowing the setting of watcher variables.

The watcher debugging system allows various variables to be displayed and updated from within the runtime.

Watchers are specified in the C-code using the MF_WATCH macro. This takes three arguments, the first is a string specifying the path (parent groups followed by the item name, separated by forward slashes), the second is the expression to watch. The third argument specifies such things as whether it is read only or not, and has a default of read-write.

The setWatcher function in Python allows the setting of a particular read-write value. For example:

>>>	BigWorld.setWatcher( "Client Settings/Terrain/draw", 0 )

Raises a TypeError if the watcher failed to be set. Raises a TypeError if args cannot be converted into a string.

Parameters:
path | the path to the item to modify.
val | the new value for the item.

def startService( serviceName ):

This method starts a service with the given name. If the service is already running, an exception is raised.

Parameters:
serviceName The name of the service to stop.

def stopService( serviceName ):

This method stops a service with the given name. If the service is not already running, an exception is raised.

Parameters:
serviceName The name of the service to stop.

def time( ):

This method returns the current game time in seconds as a floating point number.

Game time is incremented with each game tick.

Returns:
The current game time in seconds as a float.

Attribute Documentation

LOG_ON_ACCEPT

LOG_ON_REJECT

LOG_ON_WAIT_FOR_DESTROY

NEXT_ONLY

baseAppData

For example:
BigWorld.baseAppData[ "hello" ] = "there"

Another BaseApp can access this as follows:
print BigWorld.baseAppData[ "hello" ]

The key and value can be any type that can be pickled and unpickled on all destination components.

When a value is changed or deleted, a callback function is called on all components. See: BWPersonality.onBaseAppData and BWPersonality.onDelBaseAppData.

NOTE: Only top-level values are propagated, if you have a value that is mutable (for example, a list) and it changed internally (for example, changing just one member), this information is NOT propagated.

Do NOT do the following:
BigWorld.baseAppData[ "list" ] = [1, 2, 3]
BigWorld.baseAppData[ "list" ][1] = 7
Locally, this would look like [1, 7, 3] and remotely [1, 2, 3].

component

This is the component that is executing the present python environment. Possible values are (so far) 'cell', 'base', 'client', 'database', 'bot' and 'editor'.

entities

Type:
PyBases

globalBases

Type:
GlobalBases

globalData

For example:
BigWorld.globalData[ "hello" ] = "there"

Another CellApp or BaseApp can access this as follows:
print BigWorld.globalData[ "hello" ]

The key and value can be any type that can be pickled and unpickled on all destination components.

When a value is changed or deleted, a callback function is called on all components. See: BWPersonality.onGlobalData and BWPersonality.onDelGlobalData.

NOTE: Only top-level values are propagated, if you have a value that is mutable (for example, a list) and it changed internally (for example, changing just one member), this information is NOT propagated.

Do NOT do the following:
BigWorld.globalData[ "list" ] = [1, 2, 3]
BigWorld.globalData[ "list" ][1] = 7
Locally, this would look like [1, 7, 3] and remotely [1, 2, 3].

isServiceApp

Type:
bool


Math - BigWorld base Documentation

Math Module Reference

This module contains factory methods for the various maths related BigWorld objects.

Class List

Matrix
MatrixInverse
MatrixProduct
MatrixProvider
Plane
Vector2
Vector3
Vector4
Vector4Animation
Vector4Basic
Vector4Combiner
Vector4Distance
Vector4LFO
Vector4MatrixAdaptor
Vector4Morph
Vector4Product
Vector4Provider
Vector4Shader
Vector4Swizzle
Vector4Translation

Member Functions

def Matrix( matProv ):
def MatrixInverse( ):
def MatrixProduct( ):
def Plane( ):
def Vector2( ):
def Vector3( ):
def Vector4( ):
def Vector4Animation( ):
def Vector4Combiner( ):
def Vector4Distance( ):
def Vector4LFO( ):
def Vector4MatrixAdaptor( ):
def Vector4Morph( ):
def Vector4Product( ):
def Vector4Shader( ):
def Vector4Swizzle( ):
def Vector4Translation( ):
def getRegister( register ):

Member Function Documentation

def Matrix( matProv ):

This function creates a new Matrix. It can take either none or one arguments. If it takes none, it creates a zero matrix. If it takes one argument, then that must be a MatrixProvider, at which point this matrix is set to the matrix contained in the MatrixProvider at the time of the function call.

Parameters:
matProv an optional MatrixProvider, which this matrix is set to.

Returns:
a new Matrix

def MatrixInverse( ):

def MatrixProduct( ):

def Plane( ):

This function creates a new Plane.

Returns:
a new Plane

def Vector2( ):

This function creates a Vector with 2 elements. It can either take 2 floats, or a single float which is applied to both components.

Returns:
the newly created Vector2.

def Vector3( ):

This function creates a Vector with 3 elements. It can either take 3 floats, or a single float which is applied to all components.

Returns:
the newly created Vector3.

def Vector4( ):

This function creates a Vector with 4 elements. It can either take 4 floats, or a single float which is applied to all components.

Returns:
the newly created Vector4.

def Vector4Animation( ):

Returns:
The new Vector4Animation

def Vector4Combiner( ):

def Vector4Distance( ):

Returns:
The new Vector4Distance

def Vector4LFO( ):

Returns:
The new Vector4LFO

def Vector4MatrixAdaptor( ):

def Vector4Morph( ):

Returns:
The new Vector4Morph

def Vector4Product( ):

Returns:
The new Vector4Product

def Vector4Shader( ):

def Vector4Swizzle( ):

def Vector4Translation( ):

Returns:
The new Vector4Translation

def getRegister( register ):

This method provides a python interface to retrieve references to temporary registers. The value is returned as a Vector4ProviderPtr, so the register can also be updated by changing the returned value.

Parameters:
register The temporary register to access as an int (eg, 1-16)

Returns:
A Vector4ProviderPtr containing the contents of the given register


ResMgr - BigWorld base Documentation

ResMgr Module Reference

Class List

DataSection

Member Functions

def DataSection( sectionName ):
def isDir( pathname ):
def isFile( pathname ):
def localise( string, params ):
def openSection( resourceID, newSection ):
def purge( resourceID, recurse ):
def resolveToAbsolutePath( ):
def save( resourceID ):

Attributes

root DataSection

Member Function Documentation

def DataSection( sectionName ):

This module function constructs a blank data section. It can be optionally supplied with a new name. This DataSection will not be savable using the save function, as it has no file system association.

Parameters:
sectionName Optional name for the new section

Returns:
the section that was created

def isDir( pathname ):

This function returns true if the specified path name is a directory, false otherwise.

Parameters:
pathname The path name to check.

Returns:
True (1) if it is a directory, false (0) otherwise.

def isFile( pathname ):

This function returns true if the specified path name is a file, false otherwise.

Parameters:
pathname The path name to check.

Returns:
True (1) if it is a file, false (0) otherwise.

def localise( string, params ):

This function localises a string and expand its params

Parameters:
string | The string to localise
params | The params used to expand

Returns:
localised and expanded string

def openSection( resourceID, newSection ):

This function opens the specified resource as a DataSection. If the resource is not found, then it returns None. A new section can optionally be created by specifying true in the optional second argument.

Resources live in a res tree and include directories, xml files, xml nodes, normal data files, binary section data file nodes, etc.

Parameters:
resourceID | the id of the resource to open.
newSection | Boolean value indicating whether to create this as a new section, default is False.

Returns:
the DataSection that was loaded, or None if the id was not found.

def purge( resourceID, recurse ):

This function purges the previously loaded section with the specified path from the cache and census. Optionally, all child sections can also be purged (only useful if the resource is a DirSection), by specifying true in the optional second argument.

Parameters:
resourceID | the id of the resource to purge.
recurse | Boolean value indicating whether to recursively purge any subsections. default is False.

def resolveToAbsolutePath( ):

This function resolves a path relative to the res tree to an absolute path. If the file does not exist in any of the resource paths, then it will be resolved against the first resource path.

Returns:
The absolute path

def save( resourceID ):

This function saves the previously loaded section with the specified path. If no section with that id is still in memory, then an IO error occurs, otherwise, the section is saved.

Parameters:
resourceID the filepath of the DataSection to save.

Returns:
True if successful, False otherwise.

Attribute Documentation

root

This is the root data section of the resource tree.

Type:
DataSection


Base - BigWorld base Documentation

Base Class Reference

[BigWorld Module]

Base is part of the BigWorld module. More...

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def addTimer( self, initialOffset, repeatOffset=0, userArg=0 ):
def createCellEntity( self, cellEntityMB ):
def createInDefaultSpace( self ):
def createInNewSpace( self ):
def delTimer( self, id ):
def deregisterGlobally( self, name ):
def destroy( self, deleteFromDB, writeToDB ):
def destroyCellEntity( self ):
def registerGlobally( self, key, callback ):
def teleport( self, baseEntityMB ):
def writeToDB( self, callback, shouldAutoLoad, shouldWriteToPrimary ):

Callback Methods

def onCreateCellFailure( self ):
def onDestroy( self ):
def onGetCell( self ):
def onLoseCell( self ):
def onPreArchive( self ):
def onRestore( self ):
def onTimer( self, timerHandle, userData ):
def onWindowOverflow( self ):
def onWriteToDB( self, cellData ):

Attributes

baseType | Read-only int32
cell | Read-only CellEntityMailBox
cellData | PyCellData
className | Read-only string
databaseID | Read-only int64
hasCell | Read-only bool
id | Read-only int32
isDestroyed | Boolean
shouldAutoArchive | True, False or BigWorld.NEXT_ONLY
shouldAutoBackup | True, False or BigWorld.NEXT_ONLY

Detailed Description

The class Base represents an entity residing on a base application. Base entities can be created via the BigWorld.createBase function (and functions with createBase prefix). An base entity instance can also be created from a remote cellApp BigWorld.createEntityOnBaseApp function call.

A base entity can be linked to an entity within one of the active cells, and can be used to create an associated entity on an appropriate cell. The functionality of this class allows you to create and destroy the entity on existing cells, register a timer callback function to be called on the base entity, access contact information for this object, and also access a CellEntityMailBox through which the base entity can communicate with its cell entity (the associated cell entity can move to different cells as a result of movement of the cell entity, or load balancing).

Member Function Documentation

def addTimer( self, initialOffset, repeatOffset=0, userArg=0 ):

The onTimer function must be defined in the base entity's class and accept 2 arguments; the internal id of the timer (useful to remove the timer via the "delTimer" method), and the optional user supplied integer "userArg".

Example:
# this provides an example of the usage of addTimer
import BigWorld

class MyBaseEntity( BigWorld.Base ):

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

        # add a timer that is called after 5 seconds, and then every
        # second with custom user data of 9
        self.addTimer( 5, 1, 9 )

        # add a timer that is called once after a second, with custom
        # user data defaulting to 0
        self.addTimer( 1 )

    # timers added on a Base have "onTimer" called as their timer function
    def onTimer( self, id, userArg ):
        print "MyBaseEntity.onTimer called: id %i, userArg: %i" % ( id, userArg )
        # if this is a repeating timer then call:
        #     self.delTimer( id )
        # to remove the timer when it is no longer needed

Parameters:
initialOffset | initialOffset is a float and specifies the interval (in seconds) between registration of the timer, and the time of first call.
repeatOffset | repeatOffset is an optional float and specifies the interval (in seconds) between repeated executions after the first execution. The delTimer method must be used to remove the timer or this will repeat continuously. Values less than 0 are ignored.
userArg | userArg is an optional integer which specifies an optional user supplied value to be passed to the "onTimer" method of the base entity.

Returns:
Integer. This function returns the internal id of the timer. This can be used with delTimer method to remove the timer.

def createCellEntity( self, cellEntityMB ):

The information used to create the cell entity is stored in the cellData property of this entity. This property is a dictionary corresponding to the values in the entity's .def file plus a "position", "direction" and "spaceID" entries for the entity's position and (roll, pitch, yaw) direction.

If cellEntityMB is not passed in, the "spaceID" entry in cellData is used to indicate which space to create the cell entity in.

Parameters:
cellEntityMB an optional CellEntityMailBox argument which is used to indicate which space to create the cell entity in. Ideally, the two entities are near so that it is likely that the correct cell will be found immediately.

def createInDefaultSpace( self ):

The information used to create the cell entity are stored in the cellData property of this entity. This property is a dictionary corresponding to the values in the entity's .def file plus a "position", "direction" and "spaceID" entries ("spaceID" entry is not referenced in this method) for the entity's position and (roll, pitch, yaw) direction.

This method is only available if useDefaultSpace is set to true in the server's configuration file.

def createInNewSpace( self ):

The information used to create the cell entity are stored in the cellData property of this entity. This property is a dictionary corresponding to the values in the entity's .def file plus a "position", "direction" and "spaceID" entries("spaceID" entry is not referenced in this method) for the entity's position and (roll, pitch, yaw) direction.

def delTimer( self, id ):

See Base.addTimer for an example of timer usage.

Parameters:
id id is an integer that specifies the internal id of the timer to be removed.

def deregisterGlobally( self, name ):

Parameters:
name the global name (a string) by which this base is currently known.

def destroy( self, deleteFromDB, writeToDB ):

It may be convenient to call self.destroy in the onLoseCell callback. This causes the base entity to be destroyed whenever the cell entity is destroyed.

This method has two keyword argument:

Parameters:
deleteFromDB | If True, the entry in the database associated with this entity is deleted. This defaults to False.
writeToDB | If True, the properties associated with this entity are written to the database. This only occurs if this entity was read from the database or has previously been written with Base.writeToDB. This defaults to True but is ignored if deleteFromDB is True.

def destroyCellEntity( self ):

def registerGlobally( self, key, callback ):

Parameters:
key | The global key by which this base is to be known. This key can be any Python type that can be pickled and hashed. Typically this would be a string or a tuple of basic types.
callback | A callback that is called when registration completes. The callback is called with True (succeeded) or False (failed). Failure is usually due to an existing global base with the given name. The callback argument is not optional.

def teleport( self, baseEntityMB ):

On arrival in the new space, Entity.onTeleportSuccess is called. This can be used to move the entity to the appropriate position within that space.

Parameters:
baseEntityMB The base mailbox of the entity that this entity should be moved to. The cell entity associated with this argument will be passed into Entity.onTeleportSuccess on success.

def writeToDB( self, callback, shouldAutoLoad, shouldWriteToPrimary ):

Entities can also be marked as auto-loaded, so that subsequent server start-ups will recreate this entity automatically. This auto-load data can be cleared from the database using the clear_auto_load tool. See the Server Operations Guide -> MySQL Support -> The clear_auto_load tool for more details.

Parameters:
callback | This optional argument is a callable object that will be called when the response from the database is received. It takes two arguments. The first is a boolean indicating success or failure and the second is the base entity.
shouldAutoLoad | This optional argument specifies whether this entity should be loaded from the database when the server starts up.
shouldWriteToPrimary | This optional argument specifies whether this write should be sent to the primary database instead of the secondary database (defaults to False).

Callback Method Documentation

def onCreateCellFailure( self ):

def onDestroy( self ):

def onGetCell( self ):

def onLoseCell( self ):

def onPreArchive( self ):

def onRestore( self ):

def onTimer( self, timerHandle, userData ):

Parameters:
timerHandle | The id of the timer.
userData | The integer user data passed into Base.addTimer.

def onWindowOverflow( self ):

def onWriteToDB( self, cellData ):

Note that calling writeToDB during this callback can lead to an infinite loop.

Parameters:
cellData cellData contains cell properties that are going to be stored in database. cellData is dictionary.

Attribute Documentation

baseType

Type:
Read-only int32

cell

Note that there can be a period of time when the entity has a cell mailbox but it does not yet point to the correct CellApp. This is in the time period where Base.createCellEntity() has been called but the Base.onGetCell() callback has yet to be called. In this state, the mailbox can stil be used to send from the base entity directly but cannot be used, for example, as an argument to BigWorld.createCellEntity().

Type:
Read-only CellEntityMailBox

cellData

If the cell entity is created, these values are used and the cellData property is deleted. Besides the cell entity properties specified in the entity's type's definition, it also contains position, direction and spaceID.

Type:
PyCellData

className

The class name of the Entity.

Type:
Read-only string

databaseID

Type:
Read-only int64

hasCell

This property can be used to decide whether Base.destroyCellEntity() should be called instead of Base.destroy().

Note that this property is also True when this Base entity is in the process of getting a cell entity. For example, when Base.createCellEntity has been called but the Base.onGetCell() callback has yet to be called.

Type:
Read-only bool

id

Type:
Read-only int32

isDestroyed

Type:
Boolean

shouldAutoArchive

Type:
True, False or BigWorld.NEXT_ONLY

shouldAutoBackup

Type:
True, False or BigWorld.NEXT_ONLY


BaseEntityMailBox - BigWorld base Documentation

BaseEntityMailBox Class Reference

BaseEntityMailBox is an actualised class. It is not bound to any module and cannot be directly instantiated.

Parent Classes

CommonBaseEntityMailBox → ServerEntityMailBox → PyEntityMailBox → PyObjectPlus

Attributes

cell | { mailbox }
client | { mailbox }
ownClient | { mailbox }

Detailed Description

BaseEntityMailBox inherits from ServerEntityMailBox.

On a Base, the BaseEntityMailBox can be used to communicate with other Base Entity components, even if on different machines.

For example, to befriend an entity you meet, use:

self.befriend( friendEntity )

The friend Entity will automatically be converted to a BaseEntityMailBox, so is identical to:

self.befriend( friendEntity.base )

In either case, the befriend function definition could look like:

def befriend( self, friendMailbox ): self.myFriend = friendMailbox

To communicate with the friend, you could:

def talkToFriend( self ): self.myFriend.chat( "Hi Friend..." )

where the chat method is implemented on the Base of the friend Entity. The stored BaseEntityMailBox will directly communicate with the Base Entity it represents, regardless of which machine it is on.

Unlike direct Cell entity mailboxes, these mailboxes may be stored and used later.

Attribute Documentation

cell

For example, to call the cell methods via a base mailbox 'baseMB', use:

baseMB.cell.cellMethod()

The method call will first be sent to the base this mailbox belongs to and then redirected to the cell counterpart.

Type:
{ mailbox }

client

For example, to call the client methods via a base mailbox 'baseMB', use:

baseMB.client.clientMethod()

The method call will first be sent to the base this mailbox belongs to and then redirected to the client counterpart.

Type:
{ mailbox }

ownClient

Type:
{ mailbox }


CellEntityMailBox - BigWorld base Documentation

CellEntityMailBox Class Reference

CellEntityMailBox is an actualised class. It is not bound to any module and cannot be directly instantiated.

Parent Classes

ServerEntityMailBox → PyEntityMailBox → PyObjectPlus

Attributes

base | { mailbox }
client | { mailbox }
ownClient | { mailbox }

Detailed Description

CellEntityMailBox inherits from ServerEntityMailBox.

A CellEntityMailBox is used by a Base Entity to communicate with its associated Cell Entity. This allows the Base Entity to call the methods on the Cell Entity.

For example:

self.cell.cellMethod()

where cellMethod() is described in the .def file.

These mailboxes have the same restrictions as Cell mailboxes and should not be stored, they should be used immediately then discarded.

Attribute Documentation

base

An indirect mailbox to the base representitive this cell mailbox is associated with.

For example, to call the base methods via a cell mailbox 'cellMB', use:

cellMB.base.baseMethod()

The method call will first be sent to the cell this mailbox belongs to and then redirected to the base counterpart.

Type:
{ mailbox }

client

An indirect mailbox to the client representitive this cell mailbox is associated with.

For example, to call the client methods via a cell mailbox 'cellMB', use:

cellMB.client.clientMethod()

The method call will first be sent to the cell this mailbox belongs to and then redirected to the client counterpart.

You can only call the methods on own client.

Type:
{ mailbox }

ownClient

Type:
{ mailbox }


DataSection - BigWorld base Documentation

DataSection Class Reference

[ResMgr Module]

DataSection is part of the ResMgr module. More...

import ResMgr

Member Functions

def child( self, index ):
def childName( self, index ):
def cleanName( self ):
def copy( self, source ):
def copyToZip( self ):
def createSection( self, sectionPath ):
def createSectionFromString( self, string ):
def deleteSection( self, section ):
def has_key( self, key ):
def isNameClean( self ):
def items( self ):
def keys( self ):
def readBlob( self, sectionName, defaultVal ):
def readBool( self, sectionName, defaultVal ):
def readFloat( self, sectionName, defaultVal ):
def readFloats( self, sectionName ):
def readInt( self, sectionName, defaultVal ):
def readInt64( self, sectionName, defaultVal ):
def readInts( self, sectionName ):
def readMatrix( self, sectionName, defaultVal ):
def readString( self, sectionName, defaultVal ):
def readStrings( self, sectionName ):
def readVector2( self, sectionName, defaultVal ):
def readVector2s( self, sectionName ):
def readVector3( self, sectionName, defaultVal ):
def readVector3s( self, sectionName ):
def readVector4( self, sectionName, defaultVal ):
def readVector4s( self, sectionName ):
def readWideString( self, sectionName, defaultVal ):
def readWideStrings( self, sectionName ):
def save( self ):
def values( self ):
def write( self, sectionName, value ):
def writeBlob( self, sectionName, text ):
def writeBool( self, sectionName, val ):
def writeFloat( self, sectionName, val ):
def writeFloats( self, sectionName, values ):
def writeInt( self, sectionName, val ):
def writeInt64( self, sectionName, val ):
def writeInts( self, sectionName, values ):
def writeMatrix( self, sectionName, val ):
def writeString( self, sectionName, text ):
def writeStrings( self, sectionName, values ):
def writeVector2( self, sectionName, val ):
def writeVector2s( self, sectionName, values ):
def writeVector3( self, sectionName, val ):
def writeVector3s( self, sectionName, values ):
def writeVector4( self, sectionName, val ):
def writeVector4s( self, sectionName, values ):
def writeWideString( self, sectionName, text ):
def writeWideStrings( self, sectionName, values ):

Attributes

asBinary | String
asBlob | String
asBool | Integer
asFloat | Float
asInt | Integer
asInt64 | Integer
asMatrix | Matrix
asString | String
asVector2 | Vector2
asVector3 | Vector3
asVector4 | Vector4
asWideString | Wide String
name | Read-Only String
name | Read-Only String

Detailed Description

A DataSection controls the reading and writing of xml data sections. New DataSections can be created via ResMgr.DataSection(). In this case section cannot be saved because it has no file system association. To open an existing DataSection, use ResMgr.openSection().

Member Function Documentation

def child( self, index ):

This method returns the child at the given index.

Parameters:
index the index to look up the child subsection at.

Returns:
the child at the specified index.

def childName( self, index ):

This method returns the name of the child at the given index.

Parameters:
index the index to look up the child subsection at.

Returns:
the child at the specified index.

def cleanName( self ):

This method cleans xml section names by replacing spaces with double periods and puts "id." in front of xml section names that begin with numbers.

Returns:
A boolean indicating that a change took place in the name.

def copy( self, source ):

This function makes this DataSection into a copy of the specified DataSection.

Parameters:
source the section to copy this one from.

def copyToZip( self ):

This function makes takes this DataSection and copies it into a new DataSection as well as converting it to a zip if possible.

Returns:
A 2-tuple with the new data section and a boolean to indicate if the conversion was successful.

def createSection( self, sectionPath ):

This method creates the section specified by the input path, as a subsection of the parent. It will always create a new subsection, even if a section of the same name already exists. The path can contain slashes, which will allow for the creation of subsection within subsection. The path will be evaluated through the first section that has that name, and, if the whole path already exists, only the innermost section will be duplicated.

For example, if ds represents the following piece of xml:

    <red>
        <green>
            <blue></blue>
        </green>
    </red>
    <red>
        <green>
            <blue></blue>
        </green>
    </red>

and then the following code is executed:

ds.createSection( "red/green/blue" )

then the following will be the resultant xml represented by ds:

    <red>
        <green>
            <blue></blue>
            <blue></blue>
        </green>
    </red>
    <red>
        <green>
            <blue></blue>
        </green>
    </red>

Parameters:
sectionPath the path to the section to create.

Returns:
the DataSection that was created.

def createSectionFromString( self, string ):

This method creates the section represented by the input string, as a subsection of the parent.

For example, if ds represents the following piece of xml:

    <red>
        <green>
            <blue></blue>
        </green>
    </red>

and then the following code is executed:

string = "<red><green><blue></blue></green></red>"
ds.createSectionFromString( string )

then the following will be the resultant xml represented by ds:

    <red>
        <green>
            <blue></blue>
        </green>
    </red>
    <red>
        <green>
            <blue></blue>
        </green>
    </red>

Parameters:
string the xml string to create the section from.

Returns:
the DataSection that was created.

def deleteSection( self, section ):

This method deletes a section referenced either by a PyDataSection or an input string path. in the case of input string path,if more than one section is addressed by the path, then only the first one is deleted. It returns 1 if the section was successfully deleted, 0 otherwise.

Parameters:
section can be either a PyDataSection or a string path of the section to delete

Returns:
1 if it was deleted, 0 otherwise.

def has_key( self, key ):

This method checks if one of the subsections within this data section has the specified name, and returns 1 if it does, 0 otherwise.

Parameters:
key A string containing the name of the section to check for.

Returns:
An integer: 1 if the section exists, 0 otherwise.

def isNameClean( self ):

This method returns whether the section name is valid. XML can be a little more strict about allowed names.

Returns:
A boolean indicating whether the name is clean.

def items( self ):

Returns:
The list of (name, DataSection) tuples of this section's children.

def keys( self ):

This method returns a list of all the subsection names, in the order in which they appear in the xml code.

Returns:
The list of the names (strings)

def readBlob( self, sectionName, defaultVal ):

This function returns the contents of the section with the name specified, interpreted as a Blob string. It performs a trim (drop off leading and trailing white space) on the text immediately following the opening tag, and preceding the first open tag for a subsection.

If there is more than one section with the specified name, then only the first one is used.

Parameters:
sectionName | the name of the section to get the string from.
defaultVal | the default value should an error occur.

Returns:
the string contained in the specified section, or the default value (if specified), an empty string otherwise.

def readBool( self, sectionName, defaultVal ):

This function returns the contents of the section with the name specified, parsed as a boolean.

If it contains the string "true", with any capitalisation, then it returns 1, otherwise, it returns 0.

If there is more than one section with the specified name, then only the first one is used.

Parameters:
sectionName | the name of the section to get the boolean from.
defaultVal | the default value should an error occur.

Returns:
the boolean (integer) contained in the specified section, or the default value (if specified), false otherwise.

def readFloat( self, sectionName, defaultVal ):

This function returns the contents of the section with the name specified parsed as a floating point number.

It performs a trim (drop off leading and trailing white space) on the text immediately following the opening tag, and preceding the first open tag for a subsection. It tries to parse a float at the front of the resulting string, returning the integer if the parse succeeds, 0 otherwise.

If the sectionName specified doesn't match any sections, then 0 is returned.

If there is more than one section with the specified name, then only the first one is used.

Parameters:
sectionName | the name of the section to get the float from.
defaultVal | the default value should an error occur.

Returns:
the float contained in the specified section, or the default value (if specified), 0 otherwise.

def readFloats( self, sectionName ):

This function reads the contents of any subsections of the current section with the specified name, and returns the results as tuple of floats. It tries to parse the contents of each subsection as a float, using that float if the parse is sucessful, otherwise 0.

Parameters:
sectionName the name of the subsections from which floats will be parsed.

Returns:
a tuple of the floats from the named subsections.

def readInt( self, sectionName, defaultVal ):

This function returns the contents of the section with the name specified parsed as an integer.

It performs a trim (drop off leading and trailing white space) on the text immediately following the opening tag, and preceding the first open tag for a subsection. It tries to parse an integer at the front of the resulting string, returning the integer if the parse succeeds, 0 otherwise.

If the sectionName specified doesn't match any sections, then 0 is returned.

If there is more than one section with the specified name, then only the first one is used.

Parameters:
sectionName | the name of the section to get the int from.
defaultVal | the default value should an error occur.

Returns:
the int contained in the specified section, or the default value (if specified), 0 otherwise.

def readInt64( self, sectionName, defaultVal ):

This function returns the contents of the section with the name specified parsed as an integer.

It performs a trim (drop off leading and trailing white space) on the text immediately following the opening tag, and preceding the first open tag for a subsection. It tries to parse an integer at the front of the resulting string, returning the integer if the parse succeeds, 0 otherwise.

If the sectionName specified doesn't match any sections, then 0 is returned.

If there is more than one section with the specified name, then only the first one is used.

Parameters:
sectionName | the name of the section to get the int from.
defaultVal | the default value should an error occur.

Returns:
the int contained in the specified section, or the default value (if specified), 0 otherwise.

def readInts( self, sectionName ):

This function reads the contents of any subsections of the current section with the specified name, and returns the results as tuple of integers. It tries to parse the contents of each subsection as an integer, using that integer if the parse is sucessful, otherwise 0.

Parameters:
sectionName the name of the subsections from which integers will be parsed.

Returns:
a tuple of the integers from the named subsections.

def readMatrix( self, sectionName, defaultVal ):

This function returns the contents of the section with the name specified parsed as a Matrix.

It expects there there to be four subsections, called <row0>, <row1>, <row2> and <row3>. Each of these should have three floats separated by white space. If these conditions are met, a Matrix will be read in from the four rows otherwise, a Matrix with all zeros will be created.

If there is more than one section with the specified name, then only the first one is used.

Parameters:
sectionName | the name of the section to get the Matrix from.
defaultVal | the default value should an error occur.

Returns:
the Matrix contained in the specified section, or the default value (if specified), a Null Matrix otherwise.

def readString( self, sectionName, defaultVal ):

This function returns the contents of the section with the name specified, interpreted as a string. It performs a trim (drop off leading and trailing white space) on the text immediately following the opening tag, and preceding the first open tag for a subsection.

If there is more than one section with the specified name, then only the first one is used.

Parameters:
sectionName | the name of the section to get the string from.
defaultVal | the default value should an error occur.

Returns:
the string contained in the specified section, or the default value (if specified), an empty string otherwise.

def readStrings( self, sectionName ):

This function reads the contents of any subsections of the current section with the specified name, and returns the results as tuple of strings.

Parameters:
sectionName the name of the subsections from which strings will be extracted.

Returns:
a tuple of the strings from the named subsections.

def readVector2( self, sectionName, defaultVal ):

This function returns the contents of the section with the name specified parsed as a Vector2.

It expects two floating point numbers, separated by white space, at the beginning of the text for the named section. Any trailing text is ignored. If it gets this, it returns the two floats as a Vector2, otherwise it returns (0, 0).

If there is more than one section with the specified name, then only the first one is used.

Parameters:
sectionName | the name of the section to get the Vector2 from.
defaultVal | the default value should an error occur.

Returns:
the Vector2 contained in the specified section, or the default value (if specified), (0, 0) otherwise.

def readVector2s( self, sectionName ):

This function reads the contents of any subsections of the current section with the specified name, and returns the results as tuple of Vector2s. It tries to parse the contents of each subsection as two floats, separated by whitespace. If the parse is successful, then these two floats are interepreted as a Vector2 and added to the tupple, otherwise the Vector2 (0,0) is used instead.

Parameters:
sectionName the name of the subsections from which Vector2s will be parsed.

Returns:
a tuple of the Vector2s from the named subsections.

def readVector3( self, sectionName, defaultVal ):

This function returns the contents of the section with the name specified parsed as a Vector3.

It expects three floating point numbers, separated by white space, at the beginning of the text for the named section. Any trailing text is ignored. If it gets this, it returns the three floats as a Vector3, otherwise it returns (0, 0, 0).

If there is more than one section with the specified name, then only the first one is used.

Parameters:
sectionName | the name of the section to get the Vector3 from.
defaultVal | the default value should an error occur.

Returns:
the Vector3 contained in the specified section, or the default value (if specified), (0, 0, 0) otherwise.

def readVector3s( self, sectionName ):

This function reads the contents of any subsections of the current section with the specified name, and returns the results as tuple of Vector3s. It tries to parse the contents of each subsection as three floats, separated by whitespace. If the parse is successful, then these three floats are interepreted as a Vector3 and added to the tupple, otherwise the Vector3 (0,0,0) is used instead.

Parameters:
sectionName the name of the subsections from which Vector3s will be parsed.

Returns:
a tuple of the Vector3s from the named subsections.

def readVector4( self, sectionName, defaultVal ):

This function returns the contents of the section with the name specified parsed as a Vector4.

It expects four floating point numbers, separated by white space, at the beginning of the text for the named section. Any trailing text is ignored. If it gets this, it returns the four floats as a Vector4, otherwise it returns (0, 0, 0, 0).

If there is more than one section with the specified name, then only the first one is used.

Parameters:
sectionName | the name of the section to get the Vector4 from.
defaultVal | the default value should an error occur.

Returns:
the Vector4 contained in the specified section, or the default value (if specified), (0, 0, 0, 0) otherwise.

def readVector4s( self, sectionName ):

This function reads the contents of any subsections of the current section with the specified name, and returns the results as tuple of Vector4s. It tries to parse the contents of each subsection as four floats, separated by whitespace. If the parse is successful, then these four floats are interepreted as a Vector4 and added to the tupple, otherwise the Vector4 (0,0,0,0) is used instead.

Parameters:
sectionName the name of the subsections from which Vector4s will be parsed.

Returns:
a tuple of the Vector4s from the named subsections.

def readWideString( self, sectionName, defaultVal ):

This function returns the contents of the section with the name specified, assuming that the contents are a wide string. It performs a trim (drop off leading and trailing white space) on the text immediately following the opening tag, and preceding the first open tag for a subsection.

Most wide strings in text xml files are encoded as base64. However, you can create readable wide strings in xml by hand, simply by prefixing a standard ascii string with an exclamation mark.

If there is more than one section with the specified name, then only the first one is used.

Parameters:
sectionName | the name of the section to get the wide string from.
defaultVal | the default value should an error occur.

Returns:
the string contained in the specified section, or the default value (if specified), an empty string otherwise.

def readWideStrings( self, sectionName ):

This function reads the contents of any subsections of the current section with the specified name, and returns the results as tuple of wide strings. It assumes that the contents of those subsections were in wide string format.

Most wide strings in text xml files are encoded as base64. However, you can create readable wide strings in xml by hand, simply by prefixing a standard ascii string with an exclamation mark.

Parameters:
sectionName the name of the subsections from which wide strings will be extracted.

Returns:
a tuple of the wide strings from the named subsections.

def save( self ):

This method saves the data section back to its underlying file. If called on a DataSection which does not correspond to a file, then it causes an IO error.

def values( self ):

This method returns a list of all child sections, in the order in which they appear in the XML.

Returns:
a list of DataSections

def write( self, sectionName, value ):

This function writes a subsection with the specified name. It creates the section if it does not already exist. If one or more sections of that name already exist, then it modifies the first one. It writes whatever value it was given as its second argument as the contents for the named section.

Parameters:
sectionName | the name of the subsection to write to.
value | the value to write to the named section.

Returns:
the DataSection that was written to.

def writeBlob( self, sectionName, text ):

This function writes a subsection with the specified name, writing the specified BLOB string. If one or more subsections with that name already exist, then the value of the first one is replaced with the specified string. This will not effect any subsections of the named subsection, only its actual contents.

Parameters:
sectionName | the name of the subsection to create or overwrite.
text | the text to replace the subsection contents with.

Returns:
the DataSection that was written to.

def writeBool( self, sectionName, val ):

This function writes a subsection with the specified name, writing the specified integer as a string. If the integer is zero, 'false' is written, otherwise 'true'. If one or more subsections with that name already exist, then the value of the first one is replaced with the specified boolean. This will not effect any subsections of the named subsection, only its actual contents.

Parameters:
sectionName | the name of the subsection to create or overwrite.
val | the integer to replace the subsection contents with.

Returns:
the DataSection that was written to.

def writeFloat( self, sectionName, val ):

This function writes a subsection with the specified name, writing the specified float as a string. If one or more subsections with that name already exist, then the value of the first one is replaced with the specified float. This will not effect any subsections of the named subsection, only its actual contents.

Parameters:
sectionName | the name of the subsection to create or overwrite.
val | the float to replace the subsection contents with.

Returns:
the DataSection that was written to.

def writeFloats( self, sectionName, values ):

This function creates a subsection of the specified name for each element of the supplied sequence, writing the corresponding float from the sequence as the contents of that subsection.

For example, the following statement:

ds.writeInts( "sect", ( 123.4, 456.7 ) )

would result in the generation of the following xml

    <sect> 123.4 </sect>
    <sect> 456.7 </sect>

This function has no effect on existing subsections of the same name. A new subsection is always created for each element in the sequence.

Parameters:
sectionName | the name of the subsection to create.
values | the sequence of floats to use as values for the new subsections.

def writeInt( self, sectionName, val ):

This function writes a subsection with the specified name, writing the specified integer as a string. If one or more subsections with that name already exist, then the value of the first one is replaced with the specified integer. This will not effect any subsections of the named subsection, only its actual contents.

Parameters:
sectionName | the name of the subsection to create or overwrite.
val | the integer to replace the subsection contents with.

Returns:
the DataSection that was written to.

def writeInt64( self, sectionName, val ):

This function writes a subsection with the specified name, writing the specified 64-bit integer. If one or more subsections with that name alreadycl exist, then the value of the first one is replaced with the specified value. This will not affect any subsections of the named * subsection, only its actual contents.

Parameters:
sectionName | the name of the subsection to create or overwrite.
val | the integer to replace the subsection contents with.

Returns:
the DataSection that was written to.

def writeInts( self, sectionName, values ):

This function creates a subsection of the specified name for each element of the supplied sequence, writing the corresponding integer from the sequence as the contents of that subsection.

For example, the following statement:

ds.writeInts( "sect", ( 123, 456 ) )

would result in the generation of the following xml

    <sect> 123 </sect>
    <sect> 456 </sect>

This function has no effect on existing subsections of the same name. A new subsection is always created for each element in the sequence.

Parameters:
sectionName | the name of the subsection to create.
values | the sequence of integers to use as values for the new subsections.

def writeMatrix( self, sectionName, val ):

This function writes a subsection with the specified name, writing the specified Matrix. If one or more subsections with that name already exist, then the value of the first one is replaced with the specified value. This will not effect any subsections of the named subsection, only its actual contents.

Parameters:
sectionName | the name of the subsection to create or overwrite.
val | the Matrix to replace the subsection contents with.

Returns:
the DataSection that was written to.

def writeString( self, sectionName, text ):

This function writes a subsection with the specified name, writing the specified string. If one or more subsections with that name already exist, then the value of the first one is replaced with the specified string. This will not effect any subsections of the named subsection, only its actual contents.

Parameters:
sectionName | the name of the subsection to create or overwrite.
text | the text to replace the subsection contents with.

Returns:
the DataSection that was written to.

def writeStrings( self, sectionName, values ):

This function creates a subsection of the specified name for each element of the supplied list, writing the corresponding string from the list as the contents of that subsection.

For example, the following statement:

ds.writeStrings( "sect", ( "str1", "str2" ) )

would result in the generation of the following xml:

    <sect> str1 </sect>
    <sect> str2 </sect>

This function has no effect on existing subsections of the same name. A new subsection is always created for each list element.

Parameters:
sectionName | the name of the subsection to create.
values | the list of strings to use as values for the new subsections.

def writeVector2( self, sectionName, val ):

This function writes a subsection with the specified name, writing the specified Vector2 as a string, consisting of two floats, separated by white space. If one or more subsections with that name already exist, then the value of the first one is replaced with the specified Vector2. This will not effect any subsections of the named subsection, only its actual contents.

Parameters:
sectionName | the name of the subsection to create or overwrite.
val | the Vector2 to replace the subsection contents with.

Returns:
the DataSection that was written to.

def writeVector2s( self, sectionName, values ):

This function creates a subsection of the specified name for each element of the supplied sequence, writing the corresponding Vector2 from the sequence as the contents of that subsection.

For example, the following statement:

ds.writeVector2s( "sect", ( (1.1, 2.2) , (3.3, 4.4) ) )

would result in the generation of the following xml

    <sect> 1.100000 2.200000 </sect>
    <sect> 3.300000 4.400000 </sect>

This function has no effect on existing subsections of the same name. A new subsection is always created for each element in the sequence.

Parameters:
sectionName | the name of the subsection to create.
values | the sequence of Vector2s to use as values for the new subsections.

def writeVector3( self, sectionName, val ):

This function writes a subsection with the specified name, writing the specified Vector3 as a string, consisting of three floats, separated by white space. If one or more subsections with that name already exist, then the value of the first one is replaced with the specified Vector3. This will not effect any subsections of the named subsection, only its actual contents.

Parameters:
sectionName | the name of the subsection to create or overwrite.
val | the Vector3 to replace the subsection contents with.

Returns:
the DataSection that was written to.

def writeVector3s( self, sectionName, values ):

This function creates a subsection of the specified name for each element of the supplied sequence, writing the corresponding Vector3 from the sequence as the contents of that subsection.

For example, the following statement:

ds.writeVector3s( "sect", ( (1.1, 2.2, 3.3) , (3.3, 4.4, 5.5) ) )

would result in the generation of the following xml

    <sect> 1.100000 2.200000 3.300000 </sect>
    <sect> 3.300000 4.400000 5.500000 </sect>

This function has no effect on existing subsections of the same name. A new subsection is always created for each element in the sequence.

Parameters:
sectionName | the name of the subsection to create.
values | the sequence of Vector3s to use as values for the new subsections.

def writeVector4( self, sectionName, val ):

This function writes a subsection with the specified name, writing the specified Vector4 as a string, consisting of four floats, separated by white space. If one or more subsections with that name already exist, then the value of the first one is replaced with the specified Vector4. This will not effect any subsections of the named subsection, only its actual contents.

Parameters:
sectionName | the name of the subsection to create or overwrite.
val | the Vector4 to replace the subsection contents with.

Returns:
the DataSection that was written to.

def writeVector4s( self, sectionName, values ):

This function creates a subsection of the specified name for each element of the supplied sequence, writing the corresponding Vector4 from the sequence as the contents of that subsection.

For example, the following statement:

ds.writeVector3s( "sect", ( (1.1, 2.2, 3.3, 4.4) , (3.3, 4.4, 5.5, 6.6) ) )

would result in the generation of the following xml

    <sect> 1.100000 2.200000 3.300000 4.400000 </sect>
    <sect> 3.300000 4.400000 5.500000 6.600000 </sect>

This function has no effect on existing subsections of the same name. A new subsection is always created for each element in the sequence.

Parameters:
sectionName | the name of the subsection to create.
values | the sequence of Vector4s to use as values for the new subsections.

def writeWideString( self, sectionName, text ):

This function writes a subsection with the specified name, writing the specified wide string. If one or more subsections with that name already exist, then the value of the first one is replaced with the specified wide string. This will not effect any subsections of the named subsection, only its actual contents.

Parameters:
sectionName | the name of the subsection to create or overwrite.
text | the text to replace the subsection contents with.

Returns:
the DataSection that was written to.

def writeWideStrings( self, sectionName, values ):

This function creates a subsection of the specified name for each element of the supplied list, writing the corresponding wide string from the list as the contents of that subsection.

This function has no effect on existing subsections of the same name. A new subsection is always created for each list element.

Parameters:
sectionName | the name of the subsection to create.
values | the list of wide strings to use as values for the new subsections.

Attribute Documentation

asBinary

This attribute is the underlying binary data of this DataSection, encapsulated in a string. On reading, it includes all the child sections. On writing, it may invalidate previously accessed child sections. Use with care. It is better to use the 'copy' method to copy DataSections around than to use this attribute.

Type:
String

asBlob

This attribute is the value of this DataSection, interpreted as a BASE64 string. When reading it, it doesn't include any of the child sections. Also on reading, the leading and trailing white space is trimmed off the string. On writing, it doesn't effect any of the child nodes.

Type:
String

asBool

This attribute is the value of this DataSection, interpreted as a boolean.

On reading, if the text contains "true" in any capitalisation, it returns 1, otherwise it returns 0.

On writing, if it is given a 0, it writes "false" otherwise it writes "true".

Type:
Integer

asFloat

This attribute is the value of this DataSection, interpreted as an float. On reading, it reads the string from the top level, and tries to parse a float off the front of it. If this is successful, the float is returned, otherwise zero.

On writing, it doesn't effect any of the child nodes, but replaces the top level string with the string version of the float.

Type:
Float

asInt

This attribute is the value of this DataSection, interpreted as an integer. On reading, it reads the string from the top level, and tries to parse an integer off the front of it. If this is successful, the integer is returned, otherwise zero.

On writing, it doesn't effect any of the child nodes, but replaces the top level string with the string version of the integer.

Type:
Integer

asInt64

This attribute is the value of this DataSection, interpreted as a 64 bit integer. On reading, it reads the string from the top level and tries to parse an integer off the front of it. If this is successful, the integer is returned, otherwise zero.

On writing, it doesn't effect any of the child nodes, but replaces the top level string with the string version of the integer.

Type:
Integer

asMatrix

This attribute is the value of this DataSection, interpreted as a Matrix.

On reading, it checks for four sub-sections, called , , and . If each of these exist and contain three floats separated by whitespace, then they are interpreted as the four rows of a Matrix, which is created and returned. Otherwise, the Matrix of all zeros is returned.

On Writing, it accepts a Matrix, and writes it out to the four sub-sections , , and , each of which will contain one row of the Matrix - three floats separated by white space. This will not effect any top level text stored in this DataSection.

Type:
Matrix

asString

This attribute is the value of this DataSection, interpreted as a string. When reading it, it doesn't include any of the child sections. Also on reading, the leading and trailing white space is trimmed off the string. On writing, it doesn't effect any of the child nodes.

Type:
String

asVector2

This attribute is the value of this DataSection, interpreted as a Vector2. On reading, it reads the string from the top level, and tries to parse it as two floats, separated by white space. If this is successful, the Vector2 of these floats is returned, otherwise the Vector2 (0,0).

On writing, it doesn't effect any of the child nodes, but replaces the top level string with the string version of the two components of the Vector2 as floats, separated by white space.

Type:
Vector2

asVector3

This attribute is the value of this DataSection, interpreted as a Vector3. On reading, it reads the string from the top level, and tries to parse it as three floats, separated by white space. If this is successful, the Vector3 of these floats is returned, otherwise the Vector3 (0,0,0).

On writing, it doesn't effect any of the child nodes, but replaces the top level string with the string version of the three components of the Vector3 as floats, separated by white space.

Type:
Vector3

asVector4

This attribute is the value of this DataSection, interpreted as a Vector4. On reading, it reads the string from the top level, and tries to parse it as four floats, separated by white space. If this is successful, the Vector4 of these floats is returned, otherwise the Vector4 (0,0,0,0).

On writing, it doesn't effect any of the child nodes, but replaces the top level string with the string version of the four components of the Vector4 as floats, separated by white space.

Type:
Vector4

asWideString

This attribute is the value of this DataSection, interpreted as a wide string. When reading it, it doesn't include any of the child sections. Also on reading, the leading and trailing white space is trimmed off the string. On writing, it doesn't effect any of the child nodes.

Type:
Wide String

name

This attribute is the name of the data section. It is read-only, and consists of the tag surrounding this particular section

Type:
Read-Only String

name

This attribute is the name of the data section. It is read-only, and consists of the tag surrounding this particular section

Type:
Read-Only String


GlobalBases - BigWorld base Documentation

GlobalBases Class Reference

GlobalBases is an actualised class. It is not bound to any module and cannot be directly instantiated.

Parent Classes

PyObjectPlus

Member Functions

def get( self ):
def has_key( self, key ):
def items( self ):
def keys( self ):
def values( self ):

Detailed Description

An instance of this class emulates a dictionary of bases or base mailboxes.

Code Example:
globalBases = BigWorld.globalBases
print "The main mission entity is", globalBases[ "MainMission" ]
print "There are", len( globalBases ), "global bases."

Member Function Documentation

def get( self ):

Returns:
A base (or base mailbox) or the default value if not found.

def has_key( self, key ):

Parameters:
key key is the string key to be searched for.

Returns:
A boolean. True if the key was found, false if it was not.

def items( self ):

Returns:
A list containing all of the (ID, entity) pairs, represented as tuples containing an string label and an base (or base mailbox).

def keys( self ):

Returns:
A list containing all of the keys.

def values( self ):

Returns:
A list containing all of the bases (or base mailboxes).


Matrix - BigWorld base Documentation

Matrix Class Reference

[Math Module]

Matrix is part of the Math module. More...

import Math

Member Functions

def applyPoint( self, point ):
def applyToAxis( self, axis ):
def applyToOrigin( self ):
def applyV4Point( self, point ):
def applyVector( self, vec ):
def get( self, row, col ):
def invert( self ):
def lookAt( self, pos, direction, up ):
def orthogonalProjection( self, width, height, near, far ):
def perspectiveProjection( self, fov, aspect, near, far ):
def postMultiply( self, pre ):
def preMultiply( self, pre ):
def set( self, m ):
def setElement( self, row, col, val ):
def setIdentity( self ):
def setRotateX( self, rot ):
def setRotateY( self, rot ):
def setRotateYPR( self, ypr ):
def setRotateZ( self, rot ):
def setScale( self, scales ):
def setTranslate( self, translations ):
def setZero( self ):

Attributes

determinant | Read-Only Float
isMirrored | Read-Only Integer (as boolean)
pitch | Read-Only Float
roll | Read-Only Float
translation | Vector3
yaw | Read-Only Float

Detailed Description

The Matrix class is a 4x4 matrix. It inherits from MatrixProvider.

A Matrix can be created using the Math.Matrix() function.

Member Function Documentation

def applyPoint( self, point ):

This function applies the matrix to the specified point. The point should be a Vector3, but will be treated as if it were a Vector4 with the fourth component being 1.0.

For example:
>>>	m = Math.Matrix()
>>>	m.setTranlate( (2,4,8) )
>>> v = Math.Vector3( 1,2,3 )
>>> m.applyPoint( v )
(3.000, 6.000, 11.000)
The example applies a translation matrix to the point (1,2,3)

Parameters:
point A Vector3 which is the point to be transformed.

Returns:
A Vector3 which is the transformed point.

def applyToAxis( self, axis ):

This function applies the matrix to the specified axis. The axis is specified using an integer between 0 and 2, with 0 corresponding to the x-axis, 1 to the y-axis and 2 to the z-axis. Numbers above 2 have undefined results.

For example:
>>>	m = Math.Matrix()
>>> m.setRotateY( 3.1415 / 2 )
>>>	m.applyToAxis( 2 )
(1.00, 0.00, 0.00)
This example rotates the z-axis through 90 degrees around the y-axis leaving it lined up with the old x-axis.

Parameters:
axis an Ingeger between 0 and 2, specifying the axis to transform

Returns:
a Vector3, which is the transformed axis.

def applyToOrigin( self ):

This function applies the matrix to the origin. This is exactly the same as calling the applyPoint function on the point (0,0,0), or the applyV4Point function on (0,0,0,1). It is also the same as the translation attribute.

For example:
>>>	m = Math.Matrix()
>>> m.setTranlation( (1,2,3) )
>>>	m.applyToOrigin()
(1.00, 2.00, 3.00)
This example applies a translation matrix to the origin.

Returns:
a Vector3 which is the transformed origin.

def applyV4Point( self, point ):

This function applies the matrix to the specified point. In this case a point is Vector4, with the 4th component being w.

For example:
>>>	m = Math.Matrix()
>>>	m.setTranlate( (2,4,8) )
>>> v = Math.Vector4( 1,2,3,1 )
>>> m.applyPoint( v )
(3.000, 6.000, 11.000, 1.000)
The example applies a translation matrix to the point (1,2,3,1)

Parameters:
point A Vector4 which is the point to be transformed.

Returns:
A Vector4 which is the transformed point.

def applyVector( self, vec ):

This function applies the matrix to the specified vector. The vector is a Vector3, and the last row of the matrix is ignored in the calculations.

For example:
>>>	m = Math.Matrix()
>>>	m.setTranlate( (2,4,8) )
>>> v = Math.Vector3( 1,2,3 )
>>> m.applyVector( v )
(1.000, 2.000, 3.000)
The example applies a translation matrix to the Vector3 (1,2,3)

Parameters:
vec A Vector3 which is the Vector3 to be transformed.

Returns:
A Vector3 which is the transformed Vector3.

def get( self, row, col ):

This method gets the value of a specified element of the matrix.

For example:
>>> m = Math.Matrix()
>>>	m.setTranslate( (1.0, 2.0, 3.0) )
>>> m.get( 3, 0 )
1.0
>>>	m.get( 3, 1 )
2.0
>>>	m.get( 3, 2 )
3.0
The example sets a translation matrix, and then obtains the components one by one.

Parameters:
row | An integer between 0 and 3. This is the row that is being returned.
col | An integer between 0 and 3. This is the column that is being returned.

Returns:
A float. This is the value of the specified element.

def invert( self ):

This method inverts the matrix. Inverting a matrix is only defined if the determinant is non-zero. If this method is called on a matrix with zero determinant, then the matrix is set to the identity matrix.

In terms of transformations, inverting a matrix "undoes" its transform.

For example:
>>> m = Math.Matrix()
>>> m.setTranslate( (1.0, 2.0, 3.0 ) )
>>> m.invert()
>>> m.tranlation
(-1.000, -2.000, -3.000)
>>> m1 = Math.Matrix()
>>> m1.setRotateY( 1.0 )
>>> m1.invert()
>>> m1.yaw
-1.0000
The example shows how inverting the matrix "undoes" the translation for m, and the rotation for m1. The same holds for composite transformations.

def lookAt( self, pos, direction, up ):

This method sets the matrix up to transform by a specified position, looking in a given direction with the z-axis and with the specified vertical.

For example:
modelMat = Math.Matrix()
modelMat.setTranslate( (0,0,0) )
cameraMat = Math.Matrix()
pos = Math.Vector3( 0, 0, -10 )
cameraMat.lookAt( pos, modelMat.applyToOrigin() - pos, (0,1,0) )
This example sets up the camera matrix to be positioned at (0,0,-10) and to be looking at the model which is placed at the origin. The cameras up direction will be the same as the worlds.

Parameters:
pos | The position to set the matrix translation to.
direction | The direction to orient the "look at" matrix.
up | The vertical axis for the camera.

def orthogonalProjection( self, width, height, near, far ):

This function sets the matrix to a left-handed orthogonal projection matrix. It can be used for a projection matrix on a camera to give a non-perspective (orthogonal) view on the world.

Parameters:
width | a Float, the width of the viewport.
height | a Float, the height of the viewport.
near | a Float, the distance to the near clipping plane.
far | a Float, the distance to the far clipping plane.

def perspectiveProjection( self, fov, aspect, near, far ):

This function sets the matrix to a left-handed perspective projection matrix. This can be used as the projection matrix on a camera to give a perspective view on the world.

Parameters:
fov | A Float, the field of view.
aspect | A Float, the aspect ratio (ratio of the width to the height).
near | A Float, the distance to the near clipping plane.
far | A Float, the distance to the far clipping plane.

def postMultiply( self, pre ):

This method post multiplies this matrix by the specified matrix. Post-multiplication means that the specified matrix is on the right of the multiplication operator. In transformation terms, the specified matrix is applied AFTER this matrix.

For example:
>>> tr = Math.Matrix()
>>> tr.setTranslate( (1,0,0) )
>>> ro = Math.Matrix()
>>> ro.setRotateY( 3.14159 / 2 )
>>> out = Math.Matrix()
>>> out.set(ro)
>>> out.postMultiply(tr)
>>> out.translation
(1.000, 0.000, 0.000)
>>> out.yaw
-1.5707
This example shows that post-multiplying the rotation by the translation applies the translation second, after rotation. This results in the initial frame being rotated, and then translated, resulting in an unaltered translation. Compare this to the result from pre-multiplication.

Parameters:
pre A Matrix which is the matrix to post-multiply by.

def preMultiply( self, pre ):

This method pre multiplies this matrix by the specified matrix. Pre-multiplication means that the specified matrix is on the left of the multiplication operator. In transformation terms, the specified matrix is applied BEFORE this matrix.

For example:
>>> tr = Math.Matrix()
>>> tr.setTranslate( (1,0,0) )
>>>	ro = Math.Matrix()
>>> ro.setRotateY( 3.14159 / 2 )
>>> out = Math.Matrix()
>>>	out.set(ro)
>>> out.preMultiply(tr)
>>>	out.translation
(0.000, 1.000, 0.000)
>>>	out.yaw
-1.5707
This example shows that pre-multiplying the rotation by the translation applies the translation first, and then the rotation. This results in the transformed position being rotated, resulting in it being in a different position. Compare this to the results in the example on post-multiplication.

Parameters:
pre a Matrix which is the matrix to pre-multiply by.

def set( self, m ):

This method sets the matrix to be the same as the supplied matrix. It has the same effect as assignment.

For example:
m1.set( m2 ) # sets matrix m1 equal to matrix m2.

Parameters:
m the matrix to set this matrix equal to.

def setElement( self, row, col, val ):

This method sets the specified element of the matrix to the specified value. The element is specified by the first two arguments, which are the row and the column respectively.

For example:
>>> m = Math.Matrix()
>>> m.setElement( 3, 0, 1.0 )
>>> m.setElement( 3, 1, 2.0 )
>>> m.setElement( 3, 2, 4.0 )
>>> m.translation
(1.0, 2.0, 4.0)
The example sets the translation components of the matrix, element by element.

Parameters:
row | An integer between 0 and 3. This is the row that is being set.
col | An integer between 0 and 3. This is the column that is being set.
val | A float. The value to set the element to.

def setIdentity( self ):

This method sets the matrix to the identity matrix (with 1s down the main diagonal, and zeros elsewhere).

The important property of the identity matrix is that if it is multiplied by another matrix, the product is that other matrix.

For example:
>>> matI.setIdentity() # sets the matrix mat to be the identity matrix.
>>> matNew = matOther.preMultiply( matI )
>>>	matNew == matOther
1
The example shows setting a matrix to the identity matrix and then multiplying it by another matrix, which results in the same matrix as before.

def setRotateX( self, rot ):

This method sets the matrix to rotate around the x-axis by the specified amount. Zero rotation is specified along the z-axis, with positive rotation being clockwise.

The translation and rotations around the y and z axes are cleared.

For example:
# sets the matrix to rotate by 1.0 radians clockwise about the x-axis.
mat.setRotateX( 1.0 )

Parameters:
rot The size of the rotation.

def setRotateY( self, rot ):

This method sets the matrix to rotate around the y-axis by the specified amount. Zero rotation is specified along the z-axis, with positive rotation being anti-clockwise.

The translation and rotations around the x and z axes are cleared.

For example:
# sets the matrix to rotate by 1.0 radians anti-clockwise about the y-axis.
mat.setRotateY( 1.0 )

Parameters:
rot The size of the rotation.

def setRotateYPR( self, ypr ):

This method sets the rotation about all three axes with one function call. It takes a Vector3, the components of which specify the yaw (rotation about y, with 0 along the z-axis, increasing anti-clockwise), pitch ( rotation about x, with 0 along the z-axis, increasing clockwise), and roll (rotation about z, with 0 along the x-axis, increasing clockwise).

The translation is cleared.

For example:
mat.setRotateYPR( (1.0, 2.0, 3.0) )
sets the matrix to have yaw 1.0, pitch of 2.0 and roll of 3.0, applied in that order.

Parameters:
ypr a Vector3 specifying the yaw, pitch and roll.

def setRotateZ( self, rot ):

This method sets the matrix to rotate around the z-axis by the specified amount. Zero rotation is specified along the x-axis, with positive rotation being clockwise.

The translation and rotations around the x and y axes are cleared.

For example:
# sets the matrix to rotate by 1.0 radians clockwise about the z-axis.
mat.setRotateZ( 1.0 )

Parameters:
rot The size of the rotation.

def setScale( self, scales ):

This method sets the matrix to be a scale matrix, with the specified Vector3 scaling along the x, y and z axes.

For example:
# set the matrix mat to scale 2 times along the x-axis, 3 times along
# the y-axis and 4 times along the z-axis.
mat.setScale( (2, 3, 4) )

Parameters:
scales A Vector3, with the each component being the scale along the corresponding axis.

def setTranslate( self, translations ):

This method sets the matrix to be a translation matrix, with the specified Vector3 being the translations along the x, y and z axes.

For example:
# set the matrix to translate by 4 along the x-axis, 5 along the y-axis
# and 6 along the z-axis.
mat.setTranslate( (4, 5, 6) )

Parameters:
translations A Vector3, with each component being the translation along the corresponding axis.

def setZero( self ):

This method sets the matrix to the zero matrix (with all elements equal to zero).

For example:
# sets the matrix mat to be the zero matrix.
mat.setZero()

Attribute Documentation

determinant

This attribute returns the determinant of the matrix.

The determinant of a matrix has many mathematical uses. In the context of a 3d engine the most likely use is to compare it to zero. If the determinant of a matrix is zero, then the matrix cannot be inverted.

Type:
Read-Only Float

isMirrored

This attribute is non-zero(true) if the matrix is mirrored, and zero (false) if the matrix is non mirrored. This is derived from the elements of the matrix.

If a matrix, when applied to a coordinate system, changes it from a left hand system to a right hand system, then the matrix is described as mirrored.

Type:
Read-Only Integer (as boolean)

pitch

This attribute is the rotation specified by the matrix around the x-axis. Zero pitch is along the z-axis with increase in pitch rotating clockwise when looking along the x-axis.

Type:
Read-Only Float

roll

This attribute is the rotation specified by the matrix around the z-axis. Zero pitch is along the x-axis with increase in roll rotating clockwise when looking along the z-axis.

Type:
Read-Only Float

translation

This attribute is the translation component of the matrix. Unlike the pitch, yaw and roll attributes, it is both read and write.

Type:
Vector3

yaw

This attribute is the rotation specified by the matrix around the y-axis. Zero yaw is along the z-axis, with increase in yaw rotating anti-clockwise when looking along the y-axis.

Type:
Read-Only Float


MatrixInverse - BigWorld base Documentation

MatrixInverse Class Reference

[Math Module]

MatrixInverse is part of the Math module. More...

import Math

Parent Classes

MatrixProvider → PyObjectPlus

Attributes

source Read-Write MatrixProvider

Detailed Description

A subclass of MatrixProvider. This provides the result of the expression 'invert(source)', where source is it's MatrixProvider argument. An instance of this class can be created via the factory method Math. MatrixInverse.

It is not possible to directly access many of the internal attributes of a MatrixInverse. To view this data it is necessary to construct a Matrix which is a copy of this, & read the values from it. For example:
# import Math module
import Math

# create a MatrixInverse which provides the inverse of matrix1
minv = Math.MatrixInverse(matrix1)

# create a MatrixProvider from the MatrixInverse
m = Math.Matrix( minv )

# print the yaw
print m.yaw
Note that a Matrix constructed as a copy of a MatrixInverse will only resemble the MatrixInverse at the time that it is created. It will not update to reflect changes.

Where the source attibute is not assigned, the result will be equal to the identity matrix.

Attribute Documentation

source

Type:
Read-Write MatrixProvider


MatrixProduct - BigWorld base Documentation

MatrixProduct Class Reference

[Math Module]

MatrixProduct is part of the Math module. More...

import Math

Parent Classes

MatrixProvider → PyObjectPlus

Attributes

a | Read-Write MatrixProvider
b | Read-Write MatrixProvider

Detailed Description

A subclass of MatrixProvider. This provides the result of the expression 'a x b', where a and b are it's MatrixProvider arguments. An instance of this class can be created via the factory method Math. MatrixProduct.

It is not possible to directly access many of the internal attributes of a MatrixProduct. To view this data it is necessary to construct a Matrix which is a copy of this, & read the values from it. For example:
# import Math module
import Math

# create a MatrixProduct which provides the product of matrix1 and matrix2
mprod = Math.MatrixProduct()
mprod.a = matrix1
mprod.b = matrix2

# create a MatrixProvider from the MatrixProduct
m = Math.Matrix( mprod )

# print the yaw
print m.yaw
Note that a Matrix constructed as a copy of a MatrixProduct will only resemble the MatrixProduct at the time that it is created. It will not update to reflect changes.

Where a and/or b are not assigned, they are treated as if they were the equal to the identity matrix.

Attribute Documentation

a

Type:
Read-Write MatrixProvider

b

Type:
Read-Write MatrixProvider


MatrixProvider - BigWorld base Documentation

MatrixProvider Class Reference

[Math Module]

MatrixProvider is part of the Math module. More...

import Math

Parent Classes

PyObjectPlus

Detailed Description

A matrix provider is the base class for all matrices used as transforms. In many cases when the attribute of a particular object has a MatrixProvider assigned to it, it stores a reference to the original MatrixProvider, rather than creating a copy.

For example, in the CursorCamera, its target could be an Entity's world transformation matrix. As the entity moves around and updates its matrix, the Camera, which stores a reference to this matrix, automatically follows along.

In addition, sometimes the original MatrixProvider doesn't actually store the matrix but calculates it on the fly. For example, the DiffDirProvider provides the matrix to move from a source position to a destination position.

The base class has no attributes or methods.

The easiest way to examine the actual elements of the matrix is to create a Matrix based on the MatrixProvider. This can be done with the following code:
matrix = Math.Matrix( matrixProvider )
matrix can then be interrogated using all the Matrix methods and functions. Updating matrix will not update matrixProvider, however.


Plane - BigWorld base Documentation

Plane Class Reference

[Math Module]

Plane is part of the Math module. More...

import Math

Member Functions

def init( self, p0, p1, p2 ):
def intersectRay( self, src, dst ):

Detailed Description

The Plane class is a 3d plane

A Plane can be created using the Math. Plane() function.

Member Function Documentation

def init( self, p0, p1, p2 ):

This method initialises the plane equation so that the input points lie on it. The points should be in a clockwise order when looked at from the front of the plane. The points must not be colinear.

Parameters:
p0 | A Vector3 point on the plane.
p1 | A Vector3 point on the plane.
p2 | A Vector3 point on the plane.

Returns:
The location of the intersection

def intersectRay( self, src, dst ):

This method calculates the intersection of a ray with This plane

Parameters:
src | A point of the source ray
dst | The direction of the ray

Returns:
The location of the intersection


Proxy - BigWorld base Documentation

Proxy Class Reference

[BigWorld Module]

Proxy is part of the BigWorld module. More...

import BigWorld

Parent Classes

Base → PyObjectPlus

Member Functions

def giveClientTo( self, proxy ):
def streamFileToClient( self, resourceName, desc="", id=-1 ):
def streamStringToClient( self, data, desc="", id=-1 ):

Callback Methods

def clientDead( self ):
def onClientDeath( self ):
def onClientGetCell( self ):
def onEntitiesEnabled( self ):
def onGiveClientToFailure( self ):
def onLatencyTrigger( self, latency, goneAboveThis ):
def onLogOnAttempt( self, ip, port, password ):
def onStreamComplete( self, id, success ):

Attributes

bandwidthPerSecond
client
clientAddr
entitiesEnabled
hasClient
latencyLast
latencyTriggers
roundTripTime
timeSinceHeardFromClient
wards

Detailed Description

The Proxy is a special type of Base that has an associated Client. As such, it handles all the server updates for that Client. There is no direct script call to create a Proxy specifically.

Member Function Documentation

def giveClientTo( self, proxy ):

This method transfers the client associated with this proxy to another proxy. The current proxy must have a client and the destination must not.

See:
Proxy.onGiveClientToFailure

Parameters:
proxy the proxy to transfer the client to.

def streamFileToClient( self, resourceName, desc="", id=-1 ):

This method is similar to streamStringToClient() except that the string passed as the first argument is the path to a file to be sent to the client, rather than the actual data itself. This should be used whenever data is being read off disk to be sent to the client, as all file operations are done in a separate thread and therefore the timing of the main thread is not jeopardised.

The client treats data sent with streamStringToClient() and streamFileToClient() in exactly the same way, i.e. it doesn't try to write data sent down with this method to a file.

See BWPersonality.onStreamComplete in client Python API documentation.

See:
Proxy.onStreamComplete

Parameters:
resourceName | The name of the resource to be sent.
desc | An optional string description to be sent.
id | A 16-bit id whose management is entirely up to the caller. If -1 is passed in then the next id in sequence that is not currently in use is selected.

Returns:
The id associated with this download.

def streamStringToClient( self, data, desc="", id=-1 ):

This method adds some data to send to the currently attached client. Data is cleared if the client detaches, and this method may only be called when a client is attached. The management of the 16-bit id is entirely up to the caller. If the ID is not specified by the caller then an unused id is allocated.

You can define a callback in your Proxy-derived class (onStreamComplete) that will be called when either all data has been sent to the client, or the download has failed for some reason.

See Proxy.onStreamComplete in the base Python API documentation, and BWPersonality.onStreamComplete in client Python API documentation.

Parameters:
data | The string to be sent.
desc | An optional string description to be sent.
id | A 16-bit id whose management is entirely up to the caller. If -1 is passed in then the next id in sequence that is not currently in use is selected.

Returns:
The id associated with this download.

Callback Method Documentation

def clientDead( self ):

def onClientDeath( self ):

def onClientGetCell( self ):

def onEntitiesEnabled( self ):

def onGiveClientToFailure( self ):

def onLatencyTrigger( self, latency, goneAboveThis ):

Parameters:
latency | The latency trigger value.
goneAboveThis | Indicates whether the latency has gone above or below this.

def onLogOnAttempt( self, ip, port, password ):

This callback should return one of the following: BigWorld.LOG_ON_ACCEPT, BigWorld.LOG_ON_REJECT, BigWorld.LOG_ON_WAIT_FOR_DESTROY.

If this callback returns BigWorld.LOG_ON_REJECT, the log on attempt fails.

If this callback returns BigWorld.LOG_ON_ACCEPT, the client is attached to this active entity.

If this callback returns BigWorld.LOG_ON_WAIT_FOR_DESTROY or the proxy destroys itself in this callback, the log on attempt will wait until the current entity has logged off and then log on as normal. Note: The calling code is still responsible for ensuring the current entity is destroyed via Base.destroy. If the current entity has not been destroyed within 5 seconds, the relogon attempt will be automatically rejected.

Parameters:
ip | The IP address of the client attempting to connect.
port | The port number of the client attempting to connect.
password | The password that the user attempted to log on with. This argument is only present if the entity has a property called "password". If the entity does not have a "password" property, onLogOnAttempt will be called with only two arguments.

def onStreamComplete( self, id, success ):

Parameters:
id | The id of the terminated download.
success | Boolean indicating whether or not the download completed successfully.

Attribute Documentation

bandwidthPerSecond

Set this to limit the amount of bandwidth this Client wishes to receive per second

client

This is the ClientEntityMailBox that communicates directly with the Client entity on the ClientApp associated with this Proxy.

If the entity does not have an attached client, a dummy mailbox is returned. This will consume the method call but will not cause any network data to be sent.

Use the hasClient attribute to check if a client is attached.

clientAddr

This tuple contains the ip and port of the Client machine

entitiesEnabled

This is whether or not entities have been enabled by the Client. Scripts cannot communicate with the Client until it enables entities.

hasClient

This is whether or not a client is currently attached to this Proxy.

latencyLast

This is the latency value that was used for the last check of the latency triggers. It may be useful for initialising the state of trigger call handlers when inserting their trigger value into the list.

latencyTriggers

This is a sequence of latency trigger values. Whenever the latency passes this value in either direction, the onLatencyTrigger method is called. The call is made with the relevant trigger value and the direction (1 = above, 0 = below) as arguments. The latency is checked roughly every second, but the calls occur in sorted order, as if the latency value moved smoothly through its range. The latency value used for this calculation is that of 'timeSinceHeardFromClient'.

roundTripTime

This is the average round trip time in seconds for communication to the client.

timeSinceHeardFromClient

This is the number of seconds since a packet from the client was last received.

wards

This is a list of EntityIDs that the associated Client is allowed to control. When controlEntity() is called on the Client, the newly controlled Entity should be added to this list so the updates will be propagated to the Cell, rather than the Cell updating the Client.


PyBases - BigWorld base Documentation

PyBases Class Reference

PyBases is an actualised class. It is not bound to any module and cannot be directly instantiated.

Parent Classes

PyObjectPlus

Member Functions

def get( self, id, defaultValue ):
def has_key( self, key ):
def items( self ):
def keys( self ):
def values( self ):

Detailed Description

An instance of PyBases emulates a dictionary of Base Entity objects, indexed by their id attribute. It does not support item assignment, but can be used with the subscript operator. Note that the key must be an integer, and that a key error will be thrown if the key does not exist in the dictionary. Instances of this class are used by the engine to make lists of Base Entities available to Python. They cannot be created via script, nor can they be modified.

Code Example (on baseapp machine, eg, telnet 192.168.0.3:40001):

e = BigWorld.entities # this is a PyBases object print "The entity with ID 100 is", e[ 100 ] print "There are", len( e ), "entities"

Member Function Documentation

def get( self, id, defaultValue ):

Parameters:
id | The id of the entity to find.
defaultValue | An optional argument that is the return value if the entity cannot be found. This defaults to None.

Returns:
The entity with the input id or the default value if not found.

def has_key( self, key ):

Parameters:
key key is the integer key to be searched for.

Returns:
A boolean. True if the key was found, false if it was not.

def items( self ):

Returns:
A list containing all of the (ID, Base Entity) pairs, represented as tuples containing an integer ID and a Base Entity.

def keys( self ):

Returns:
A list containing all of the keys.

def values( self ):

Returns:
A list containing all of the Base Entities.


PyObjectPlus - BigWorld base Documentation

PyObjectPlus Class Reference

PyObjectPlus is an actualised class. It is not bound to any module and cannot be directly instantiated.

Detailed Description

This is the abstract base class for all Python classes which are implemented in the engine. Every other class inherits, directly or indirectly from PyObjectPlus.


PyOutputWriter - BigWorld base Documentation

PyOutputWriter Class Reference

PyOutputWriter is an actualised class. It is not bound to any module and cannot be directly instantiated.

Parent Classes

PyObjectPlus

Member Functions

def write( self, string ):

Attributes

softspace Read-Write String

Detailed Description

This class is used by BigWorld to implement a Python object that redirects Python's stdout and stderr streams to Dev Studio's output window and a log file which defaults to Python.log. The BigWorld client actually uses an instance of a subclass of this called BWOutputWriter, which also sends stdout and stderr to the BigWorld Python colsole. This is automatically set up by the engine, and neither of these classes nor any instances of them can be accessed via script.

Member Function Documentation

def write( self, string ):

Write a string to this writer's outputs. The Python io system calls this.

Parameters:
string The string to write.

Returns:
None

Attribute Documentation

softspace

This is required for use by the Python io system so that instances of PyOutputWriter can be used as streams.

Type:
Read-Write String


PySTLSequence - BigWorld base Documentation

PySTLSequence Class Reference

PySTLSequence is an actualised class. It is not bound to any module and cannot be directly instantiated.

Parent Classes

PyObjectPlus

Attributes

length Integer

Detailed Description

This class is used to expose STL sequences from the engine to Python. It behaves in exactly the same way as a standard Python sequence, except that it has a length property. In particular, if v, x, y and z are sequences, either standard Python or PySTLSequence and i and j are integers and n is a number, then the following operations are valid:

len(x)
x + y
x * n
x[i]
x[i:j]
x[i] = v
x[i:j] = v
v in x
x += y
x *= n

Attribute Documentation

length

This attribute returns the number of elements in the sequence

Type:
Integer


RemoteEntityMethod - BigWorld base Documentation

RemoteEntityMethod Class Reference

RemoteEntityMethod is an actualised class. It is not bound to any module and cannot be directly instantiated.

Parent Classes

PyObjectPlus

Attributes

argumentTypes
returnValueTypes

Detailed Description

An instance of RemoteEntityMethod is return from an entity mailbox to allow the calling of a method on a remote machine

Attribute Documentation

argumentTypes

This attribute is a tuple that describes the type of each argument that an entity method expects. Each element in the tuple is a 2-tuple containing the argument's name and a string describing the type of that argument.

returnValueTypes

This attribute is a tuple that describes the type of each return value that an entity method expects. Each element in the tuple is a 2-tuple containing the return value's name and a string describing the type of that return value.


ServerEntityMailBox - BigWorld base Documentation

ServerEntityMailBox Class Reference

ServerEntityMailBox is an actualised class. It is not bound to any module and cannot be directly instantiated.

Parent Classes

PyEntityMailBox → PyObjectPlus

Attributes

className | string
component | string
id | int32
ip | int32

Detailed Description

This class implements a mailbox that can send to a server Entity (ie, Cell or Base Entity). It is not instantiated directly, but used by CellEntityMailBox and BaseEntityMailBox.

Attribute Documentation

className

The class name of the associated Entity.

Type:
string

component

The server component of the associated Entity.

Type:
string

id

The id of the associated Entity.

Type:
int32

ip

The IP address of the mailbox. If zero, the mailbox is invalid.

Type:
int32


Service - BigWorld base Documentation

Service Class Reference

[BigWorld Module]

Service is part of the BigWorld module. More...

import BigWorld

Parent Classes

Base → PyObjectPlus

Detailed Description

Service is a special type of Base. It is stateless and has no corresponding Cell or Client parts.


ServicesMap - BigWorld base Documentation

ServicesMap Class Reference

ServicesMap is an actualised class. It is not bound to any module and cannot be directly instantiated.

Parent Classes

PyObjectPlus

Member Functions

def get( self ):
def has_key( self, key ):
def items( self ):
def keys( self ):
def values( self ):

Detailed Description

An instance of this class emulates a dictionary of bases or base mailboxes.

Code Example:
services = BigWorld.services
print "The main mission entity is", services[ "MyService" ]
print "There are", len( services ), "services."

Member Function Documentation

def get( self ):

Returns:
A base (or base mailbox) or the default value if not found.

def has_key( self, key ):

Parameters:
key key is the string key to be searched for.

Returns:
A boolean. True if the key was found, false if it was not.

def items( self ):

Returns:
A list containing all of the (ID, entity) pairs, represented as tuples containing an string label and an base (or base mailbox).

def keys( self ):

Returns:
A list containing all of the keys.

def values( self ):

Returns:
A list containing all of the bases (or base mailboxes).


SharedData - BigWorld base Documentation

SharedData Class Reference

SharedData is an actualised class. It is not bound to any module and cannot be directly instantiated.

Parent Classes

PyObjectPlus

Member Functions

def get( self ):
def has_key( self, key ):
def items( self ):
def keys( self ):
def values( self ):

Detailed Description

An instance of this class emulates a dictionary of data shared between server components.

Code Example:
sharedData = BigWorld.globalData
print "The main mission entity is", sharedData[ "MainMission" ]
print "There are", len( sharedData ), "global data entries."

Member Function Documentation

def get( self ):

Returns:
The found value.

def has_key( self, key ):

Parameters:
key The key to be searched for.

Returns:
A boolean. True if the key was found, false if it was not.

def items( self ):

Returns:
A list containing all of the (key, value) pairs.

def keys( self ):

Returns:
A list containing all of the keys.

def values( self ):

Returns:
A list containing all of the values.


Vector2 - BigWorld base Documentation

Vector2 Class Reference

[Math Module]

Vector2 is part of the Math module. More...

import Math

Member Functions

def cross2D( self, v2 ):
def distSqrTo( self, v2 ):
def distTo( self, v2 ):
def dot( self, rhs ):
def list( self ):
def normalise( self ):
def scale( self, s ):
def set( self ):
def tuple( self ):

Attributes

length | Read-only float
lengthSquared | Read-only float

Detailed Description

The Vector2 class is a 2-element vector. It can be created using Math.Vector2() function.

The elements of Vector2 are referred as members x and y.

Vector2 supports following operations: Addtion: ex. v1 = v2 + v3 Subtraction: ex. v1 = v2 - v3 Negative: ex. v1 = -v2 Positive: ex. v1 = +v2 True-value test: ex. if v1: statements. In this case v1 is true if v1.lengthSquared > 0.f In-place addition: ex. v1 += v2 In-place subtraction: ex. v1 -= v2 Length: ex. len(v1). In this case always returns 2. Index: ex. v1[0] equals to v1.x, v1[1] equals to v1.y. Slice: ex. v1[0:1] returns a tuple contains v1.x, v1[0:2] returns a Vector2 eqauls to v1 itself. Indexed Assignment: ex. v1[0] = 3.2 equals to v1.x = 3.2

Member Function Documentation

def cross2D( self, v2 ):

This function returns the magnitude of the cross product between two Vector2s.

The formula is v1.x * v2.y - v1.y * v2.x

Parameters:
v2 The vector on the right hand side of the cross product.

Returns:
The magnitude of the cross product (a float).

def distSqrTo( self, v2 ):

This function returns the square of the distance between two vectors. This is often used for comparisons between two distances, because it saves the computational expense of calculating a square root.

Parameters:
v2 the vector to calculated the distance to, from this vector.

Returns:
the square of the distance between the two vectors, as a float.

def distTo( self, v2 ):

This function returns the distance between two vectors.

Parameters:
v2 the vector to calculated the distance to, from this vector.

Returns:
the distance between the two vectors, as a float.

def dot( self, rhs ):

This function performs a dot product between this vector and the specified vector, and returns the product as a float. It doesn't effect this vector.

Dot product is defined to be the sum of the products of the individual components, ie:

x*x + y*y

Parameters:
rhs The vector to dot this vector with.

Returns:
The float which is the dot product.

def list( self ):

This function returns the vector converted to a list of 2 elements.

Returns:
The list representation of the vector.

def normalise( self ):

This function normalises this vector (scales it so that its length is exactly 1).

Returns:
None

def scale( self, s ):

Returns the value of this vector, mutiplied by a scalar, leaving this vector unaffected.

Parameters:
s the scalar to multiply by.

Returns:
returns the Vector2 product of the scalar with the vector.

def set( self ):

This function sets the value of a Vector2 to the specified value. It can take several different styles of argument:

- It can take a Vector2, which sets this vector equal to the argument.

- It can take a tuple, with the same size as the vector, assigning the first element to x and the second to y.

- It can take a floating point number, which will be assigned to all components of the vector.

Returns:
None

def tuple( self ):

Returns the vector converted to a tuple of 2 elements.

Returns:
the tuple representing the vector.

Attribute Documentation

length

Type:
Read-only float

lengthSquared

Type:
Read-only float


Vector3 - BigWorld base Documentation

Vector3 Class Reference

[Math Module]

Vector3 is part of the Math module. More...

import Math

Member Functions

def cross2D( self, v2 ):
def distSqrTo( self, v2 ):
def distTo( self, v2 ):
def dot( self, rhs ):
def flatDistSqrTo( self, v2 ):
def flatDistTo( self, v2 ):
def list( self ):
def normalise( self ):
def scale( self, s ):
def set( self ):
def tuple( self ):

Attributes

length | Read-only float
lengthSquared | Read-only float
pitch | Read-only float
yaw | Read-only float

Detailed Description

The Vector3 class is a 3-element vector. It can be created using Math.Vector3() function.

The elements of Vector3 are referred as members x, y and z.

Vector3 supports following operations: Addtion: ex. v1 = v2 + v3 Subtraction: ex. v1 = v2 - v3 Cross product: ex. v1 = v2 * v3 Negative: ex. v1 = -v2 Positive: ex. v1 = +v2 True-value test: ex. if v1: statements. In this case v1 is true if v1.lengthSquared > 0.f In-place Addition: ex. v1 += v2 In-place subtraction: ex. v1 -= v2 In-place cross product: ex. v1 *= v2 Length: ex. len(v1). In this case always returns 3. Index: ex. v1[0] equals to v1.x, v1[1] equals to v1.y, etc. Slice: ex. v1[0:1] returns a tuple contains v1.x, v1[0:2] returns a Vector2 consists of x and y. Indexed Assignment: ex. v1[0] = 3.2 equals to v1.x = 3.2

Member Function Documentation

def cross2D( self, v2 ):

This function returns the magnitude of the cross product between two Vector3.

The formula is v1.x * v2.z - v1.z * v2.x

Parameters:
v2 The vector on the right hand side of the cross product.

Returns:
The magnitude of the cross product (a float).

def distSqrTo( self, v2 ):

This function returns the square of the distance between two vectors. This is often used for comparisons between two distances, because it saves the computational expense of calculating a square root.

Parameters:
v2 the vector to calculated the distance to, from this vector.

Returns:
the square of the distance between the two vectors, as a float.

def distTo( self, v2 ):

This function returns the distance between two vectors.

Parameters:
v2 the vector to calculated the distance to, from this vector.

Returns:
the distance between the two vectors, as a float.

def dot( self, rhs ):

This function performs a dot product between this vector and the specified vector, and returns the product as a float. It doesn't effect this vector.

Dot product is defined to be the sum of the products of the individual components, ie:

x*x + y*y + z*z

Parameters:
rhs The vector to dot this vector with.

Returns:
The float which is the dot product.

def flatDistSqrTo( self, v2 ):

This function calculates the distance squared between the points in the XZ plane. This is often used for comparisons between two distances, because it saves the computational expense of calculating a square root.

Parameters:
v2 the vector to calculated the distance to, from this vector.

Returns:
the distance squared between the two vectors, as a float.

def flatDistTo( self, v2 ):

This function calculates the distance between the points in the XZ plane.

Parameters:
v2 the vector to calculated the distance to, from this vector.

Returns:
the distance between the two vectors, as a float.

def list( self ):

This function returns the vector converted to a list of 3 elements.

Returns:
The list representation of the vector.

def normalise( self ):

This function normalises this vector (scales it so that its length is exactly 1).

Returns:
None

def scale( self, s ):

Returns the value of this vector, mutiplied by a scalar, leaving this vector unaffected.

Parameters:
s the scalar to multiply by.

Returns:
returns the Vector3 product of the scalar with the vector.

def set( self ):

This function sets the value of a Vector3 to the specified value. It can take several different styles of argument:

- It can take a Vector3, which sets this vector equal to the argument.

- It can take a tuple, with the same size as the vector, assigning the first element to x, the second to y and the third to z.

- It can take a floating point number, which will be assigned to all components of the vector.

Returns:
None

def tuple( self ):

Returns the vector converted to a tuple of 3 elements.

Returns:
the tuple representing the vector.

Attribute Documentation

length

Type:
Read-only float

lengthSquared

Type:
Read-only float

pitch

Type:
Read-only float

yaw

Type:
Read-only float


Vector4 - BigWorld base Documentation

Vector4 Class Reference

[Math Module]

Vector4 is part of the Math module. More...

import Math

Member Functions

def distSqrTo( self, v2 ):
def distTo( self, v2 ):
def dot( self, rhs ):
def list( self ):
def normalise( self ):
def scale( self, s ):
def set( self ):
def tuple( self ):

Attributes

length | Read-only float
lengthSquared | Read-only float

Detailed Description

The Vector4 class is a 4-element vector. It can be created using Math.Vector4() function.

The elements of Vector4 are referred as members x, y, z and w.

Vector4 supports following operations: Addtion: ex. v1 = v2 + v3 Subtraction: ex. v1 = v2 - v3 Negative: ex. v1 = -v2 Positive: ex. v1 = +v2 True-value test: ex. if v1: statements. In this case v1 is true if v1.lengthSquared > 0.f In-place Addition: ex. v1 += v2 In-place subtraction: ex. v1 -= v2 Length: ex. len(v1). In this case always returns 4. Index: ex. v1[0] equals to v1.x, v1[1] equals to v1.y, etc. Slice: ex. v1[0:1] returns a tuple contains v1.x, v1[0:3] returns a Vector3 consists of x, y and z. Indexed Assignment: ex. v1[3] = 3.2 equals to v1.w = 3.2

Member Function Documentation

def distSqrTo( self, v2 ):

This function returns the square of the distance between two vectors. This is often used for comparisons between two distances, because it saves the computational expense of calculating a square root.

Parameters:
v2 the vector to calculated the distance to, from this vector.

Returns:
the square of the distance between the two vectors, as a float.

def distTo( self, v2 ):

This function returns the distance between two vectors.

Parameters:
v2 the vector to calculated the distance to, from this vector.

Returns:
the distance between the two vectors, as a float.

def dot( self, rhs ):

This function performs a dot product between this vector and the specified vector, and returns the product as a float. It doesn't effect this vector.

Dot product is defined to be the sum of the products of the individual components, ie:

x*x + y*y + z*z + w*w

Parameters:
rhs The vector to dot this vector with.

Returns:
The float which is the dot product.

def list( self ):

This function returns the vector converted to a list of 4 elements.

Returns:
The list representation of the vector.

def normalise( self ):

This function normalises this vector (scales it so that its length is exactly 1).

Returns:
None

def scale( self, s ):

Returns the value of this vector, mutiplied by a scalar, leaving this vector unaffected.

Parameters:
s the scalar to multiply by.

Returns:
returns the Vector4 product of the scalar with the vector.

def set( self ):

This function sets the value of a Vector4 to the specified value. It can take several different styles of argument:

- It can take a Vector4, which sets this vector equal to the argument.

- It can take a tuple, with the same size as the vector, assigning the first element to x, the second to y, the third to z and the last to w.

- It can take a floating point number, which will be assigned to all components of the vector.

Returns:
None

def tuple( self ):

Returns the vector converted to a tuple of 4 elements.

Returns:
the tuple representing the vector.

Attribute Documentation

length

Type:
Read-only float

lengthSquared

Type:
Read-only float


Vector4Animation - BigWorld base Documentation

Vector4Animation Class Reference

[Math Module]

Vector4Animation is part of the Math module. More...

import Math

Parent Classes

Vector4Provider → PyObjectPlus

Attributes

duration | Read-Write float
keyframes | Read-Write list of tuples containing a float and a Vector4Provider
time | Read-Write float

Detailed Description

This is a subclass of Vector4Provider. This animates between the values provided by a number of Vector4Provider objects.

Keyframe values are specified as a list of tuples containing a time and a Vector4Provider. These are assumed to be in ascending order, so if a keyframe has a time which is before that of the previous keyframe, the Vector4 which is provided will insantly snap to the new value, rather than transitioning smoothly. Also, the Vector4Animation object will have a value equal to that of the first keyframe from the start of each cycle until the first keyframe has been hit. Similarly, a Vector4Animation object's value will be equal to that of the last keyframe, between the time of the last keyframe, and the end of the cycle.

Code Example:
# This example creates four PyChunkLight objects which demonstrate the
# use of Vector4Animation objects by using them to supply colour
# information to the lights.

# Import Math module
import Math

# Create the lights at positions ( 0, 10, 0 ), ( 20, 10, 0 ),
# ( 40, 10, 0 ), ( 60, 10, 0 ).
lights = []
for i in range( 4 ):
    newLight = BigWorld.PyChunkLight()
    newLight.position = ( i * 20, 10, 0 )
    newLight.outerRadius = 10
    newLight.visible = 1
    lights.append( newLight )

# Set up the first Vector4Animation, & apply it to the first light.
# This simply demonstrates how to set up a Vector4Animation which
# smoothly transitions across keyframes and loops without snapping.
# The light should start red, fade to green, fade to blue, then fade
# back to red again.
fadeV4 = Math.Vector4Animation()
fadeV4.duration = 1.5
fadeV4.keyframes = [ ( 0.0, ( 200, 0, 0, 0 ) ),    # red at 0.0s
                     ( 0.5, ( 0, 200, 0, 0 ) ),    # green at 0.5s
                     ( 1.0, ( 0, 0, 200, 0 ) ),    # blue at 1.0s
                     ( 1.5, ( 200, 0, 0, 0 ) ) ]   # red at 1.5s
lights[0].shader = fadeV4

# Set up the second Vector4Animation, & apply it to the second light.
# This shows how keyframes are treated when they're not listed in ascending
# order. The light should flash red, green, and blue, without transitioning
# smoothly.
flashV4 = Math.Vector4Animation()
flashV4.duration = 1.5
flashV4.keyframes = [ ( 0.5, ( 200, 0, 0, 0 ) ),    # red at 0.5s
                      ( 0.1, ( 0, 200, 0, 0 ) ),    # green at 0.1s
                      ( 1.0, ( 0, 200, 0, 0 ) ),    # green at 1.0s
                      ( 0.1, ( 0, 0, 200, 0 ) ) ]   # blue at 0.1s
lights[1].shader = flashV4

# Set up the third Vector4Animation, & apply it to the third light.
# This shows how the value provided by a Vector4Animation remains static
# between the start of a cycle and the first keyframe, and between the last
# keyframe and the end of a cycle. The light should hold red, smoothly
# transition to blue, hold blue, then snap instantly back to red at the
# beginning of the next cycle.
endSnapV4 = Math.Vector4Animation()
endSnapV4.duration = 1.5
endSnapV4.keyframes = [ ( 0.5, ( 200, 0, 0, 0 ) ),    # red at 0.5s
                        ( 1.0, ( 0, 0, 200, 0 ) ) ]   # blue at 1.0s
lights[2].shader = endSnapV4

# Set up the fourth Vector4Animation, & apply it to the fourth light.
# This shows how dynamic Vector4Provider objects can be used to provide the
# keyframes used by a Vector4Animation. The light should transition between
# off, flashing white, and solid white.
offV4 = ( 0, 0, 0, 0 )           # off keyframe
flashWhiteV4 = Math.Vector4LFO() # flashing white keyframe
flashWhiteV4.period = 0.2
flashWhiteV4.waveform = "SINE"
flashWhiteV4.phase = 0
flashWhiteV4.amplitude = 200
onV4 = ( 200, 200, 200, 200 )    # on keyframe
flashFadeV4 = Math.Vector4Animation()
flashFadeV4.duration = 6.0
flashFadeV4.keyframes = [ ( 0.0, offV4 ),        # off at 0.0s
                          ( 2.0, flashWhiteV4 ), # flashing white at 2.0s
                          ( 4.0, onV4 ),         # on 4.0s
                          ( 6.0, offV4 ) ]       # off 6.0s
lights[3].shader = flashFadeV4

Attribute Documentation

duration

Type:
Read-Write float

keyframes

Type:
Read-Write list of tuples containing a float and a Vector4Provider

time

Type:
Read-Write float


Vector4Basic - BigWorld base Documentation

Vector4Basic Class Reference

[Math Module]

Vector4Basic is part of the Math module. More...

import Math

Parent Classes

Vector4Provider → PyObjectPlus

Attributes

value Vector4

Detailed Description

This is a subclass of Vector4Provider. This is a static provider, and is therefore useful when a Vector4Provider which supplies a constant is required. No factory method exists to create an instance of this class, however one is automatically created whenever a tuple of 4 floats or a Vector4 is cast to a Vector4Provider. The following example shows this in action.

Code Example:
>>> # This shows how Vector4Basic objects are used by BigWorld to cast
>>> # tuples of four floats and Vector4 objects to Vector4Provider instances.
>>>
>>> # import Math module
>>> import Math
>>>
>>> # create a tuple of four floats
>>> tuple4 = ( 1.0, 2.0, 3.0, 4.5 )
>>>
>>> # create a Vector4
>>> vector4 = Math.Vector4( 2.0, 3.0, 4.0, 5.5 )
>>>
>>> # use both the Vector4 and the tuple of four floats as Vector4Provider
>>> # objects by setting them to the source attributes of a Vector4Product
>>> v4p = Math.Vector4Product()
>>> v4p.a = tuple4
>>> v4p.b = vector4
>>>
>>> # show that the Vector4 and the tuple of four floats have both been cast
>>> # to Vector4Basic objects
>>> print v4p.a, v4p.a.value
Vector4Basic at 0x0AB298B0 (1.000000, 2.000000, 3.000000, 4.500000)
>>> print v4p.b, v4p.b.value
Vector4Basic at 0x09EE75E8 (2.000000, 3.000000, 4.000000, 5.500000)

Attribute Documentation

value

Type:
Vector4


Vector4Combiner - BigWorld base Documentation

Vector4Combiner Class Reference

[Math Module]

Vector4Combiner is part of the Math module. More...

import Math

Parent Classes

Vector4Provider → PyObjectPlus

Attributes

a | Read-Write Vector4Provider
b | Read-Write Vector4Provider
fn | string

Detailed Description

Combines two Vector4Providers based on given function

A new Vector4Combiner is created using Math. Vector4Combiner method.

Attribute Documentation

a

Type:
Read-Write Vector4Provider

b

Type:
Read-Write Vector4Provider

fn

Type:
string


Vector4Distance - BigWorld base Documentation

Vector4Distance Class Reference

[Math Module]

Vector4Distance is part of the Math module. More...

import Math

Parent Classes

Vector4Provider → PyObjectPlus

Attributes

a | Read-Write Vector4
b | Read-Write Vector4

Detailed Description

This is a subclass of Vector4Provider. This provides a Vector4 value that returns the distance in metres between the two given Matrix providers. The distance is returned in all 4 components

Code Example:
# This creates a Vector4 that returns the distance from the camera
# to the player's head

# import the Math module
import Math

v = Math.Vector4Distance()
v.a = BigWorld.player().model.node("biped Head")
v.b = BigWorld.camera().invViewMatrix()

Attribute Documentation

a

Type:
Read-Write Vector4

b

Type:
Read-Write Vector4


Vector4LFO - BigWorld base Documentation

Vector4LFO Class Reference

[Math Module]

Vector4LFO is part of the Math module. More...

import Math

Parent Classes

Vector4Provider → PyObjectPlus

Attributes

amplitude | Read-Write float
period | Read-Write float
phase | Read-Write float
time | Read-Write float
waveform | Read-Write string

Detailed Description

This is a subclass of Vector4Provider. This provides Vector4 values using a Low Frequency Oscillator. Instances of this class can provide vectors which follow square, triangle, sine or sawtooth waveforms. Each component of the Vector4 provided by a Vector4LFO will be equal to the output of the Vector4LFO object's single oscillator. Consequently, all four components will have the same value. Note also that the waveform produced by a Vector4LFO will occupy the range between 0 and it's amplitude attribute. This means that the centre of a waveform produced by a Vector4LFO with an amplitude of 2 would be 1.

Code Example:
# This creates a flashing light whose brightness follows a sine wave.

# import the Math module
import Math

# create the light at ( 0, 0, 0 )
light = BigWorld.PyChunkLight()
light.position = ( 0, 0, 0 )
light.outerRadius = 10
light.visible = 1

# create the Vector4LFO, & use it to provide the light's colour
# The Vector4LFO provides a sine wave between the values 0 and 200,
# with a period of 2.0 seconds.
v = Math.Vector4LFO()
v.period = 2.0
v.waveform = "SINE"
v.phase = 0
v.amplitude = 200
light.shader = v

Attribute Documentation

amplitude

Type:
Read-Write float

period

Type:
Read-Write float

phase

Type:
Read-Write float

time

Type:
Read-Write float

waveform

Type:
Read-Write string


Vector4MatrixAdaptor - BigWorld base Documentation

Vector4MatrixAdaptor Class Reference

[Math Module]

Vector4MatrixAdaptor is part of the Math module. More...

import Math

Parent Classes

MatrixProvider → PyObjectPlus

Attributes

position | Vector4Provider
source | Vector4Provider
style | Vector4Provider

Detailed Description

As a matrix adaptor, this class produces a MatrixProvider representation based upon a source Vector4Provider and it's rotational or scalable style.

A new Vector4MatrixAdaptor is created using Math. Vector4MatrixAdaptor method.

Attribute Documentation

position

Type:
Vector4Provider

source

Type:
Vector4Provider

style

Type:
Vector4Provider


Vector4Morph - BigWorld base Documentation

Vector4Morph Class Reference

[Math Module]

Vector4Morph is part of the Math module. More...

import Math

Parent Classes

Vector4Provider → PyObjectPlus

Attributes

duration | Read-Write float
target | Read-Write Vector4
time | Read-Write float

Detailed Description

This is a subclass of Vector4Provider. This provides a Vector4 value that morphs from the current value to the target value, over the specified duration. You can query its current value using the value attribute.

Code Example:
# This creates a Vector4 that smoothly changes from value to value.

# import the Math module
import Math

v = Math.Vector4Morph()
v.duration = 2.0

print Math.Vector4(v)
# '0, 0, 0, 0'

v.target = (4,4,4,4)
BigWorld.callback( 1.0, partial( checkValue, v ) )

def checkValue( v ):
    print Math.Vector4(v)
    # '2, 2, 2, 2'

    v.target = (2,3,1,9)
    v.time = v.duration
    print v.current
    # '2, 3, 1, 9'

Attribute Documentation

duration

Type:
Read-Write float

target

Type:
Read-Write Vector4

time

Type:
Read-Write float


Vector4Product - BigWorld base Documentation

Vector4Product Class Reference

[Math Module]

Vector4Product is part of the Math module. More...

import Math

Parent Classes

Vector4Provider → PyObjectPlus

Attributes

a | Read-Write Vector4Provider
b | Read-Write Vector4Provider

Detailed Description

This is a subclass of Vector4Provider. This provides the componentwise product of the outputs of two Vector4Provider objects, which means that each component of the output Vector4 is equal to the product of the equivalent components of the two source Vector4 objects. For example, the componentwise product of ( 1, 2, 0.5, 0 ) and ( 2, 2, 2, 2 ) is ( 2, 4, 1, 0 ).

If a Vector4Product instance has only one source Vector4Provider objects is specified, then the source's value is provided. If no source is specified then it provides ( 0, 0, 0, 0 ).

Code Example:
# This creates a flashing yellow light.
# It demonstrates the use of a Vector4Product by multiplying a Vector4LFO,
# which is used to provide the flash, with a Vector4Basic, which is used to
# provide the colour.

# import Math module
import Math

# create the light at ( 0, 10, 0 )
light = BigWorld.PyChunkLight()
light.outerRadius = 10
light.position = ( 0, 10, 0 )
light.visible = 1

# create the flashing Vector4LFO
flash = Math.Vector4LFO()
flash.period = 0.5
flash.waveform = "SAWTOOTH"
flash.phase = 0
flash.amplitude = 1

# create the yellow Vector4Basic
yellow = ( 200, 150, 0, 0 )

# create the Vector4Product and apply to the light
yellowFlash = Math.Vector4Product()
yellowFlash.a = flash
yellowFlash.b = yellow
light.shader = yellowFlash

Attribute Documentation

a

Type:
Read-Write Vector4Provider

b

Type:
Read-Write Vector4Provider


Vector4Provider - BigWorld base Documentation

Vector4Provider Class Reference

[Math Module]

Vector4Provider is part of the Math module. More...

import Math

Parent Classes

PyObjectPlus

Attributes

value Read-Only Vector4

Detailed Description

Vector4Provider is the abstract base class for all objects which supply a dynamic Vector4. In many cases when the attribute of a particular object has a Vector4Provider assigned to it, it stores a reference to the original Vector4Provider rather than creating a copy.

Code Example:
# This example creates a flashing light at ( 0, 10, 0 ).
# The light flashes because the Vector4Provider assigned to its shader
# attribute provides a dynamic Vector4, and the light uses this to
# determine its colour.

# Import Math module
import Math

# Create a light at positions ( 0, 10, 0 )
newLight = BigWorld.PyChunkLight()
newLight.position = ( i * 20, 10, 0 )
newLight.outerRadius = 10
newLight.visible = 1

# Set up a Vector4Animation, & apply it to the light.
fadeV4 = Math.Vector4Animation()
fadeV4.duration = 1.5
fadeV4.keyframes = [ ( 0.0, ( 200, 0, 0, 0 ) ),    # red at 0.0s
                     ( 0.5, ( 0, 200, 0, 0 ) ),    # green at 0.5s
                     ( 1.0, ( 0, 0, 200, 0 ) ),    # blue at 1.0s
                     ( 1.5, ( 200, 0, 0, 0 ) ) ]   # red at 1.5s
newLight.shader = fadeV4

When a tuple of four floats or a Vector4 is used in place of a Vector4Provider it is cast to a Vector4Basic, which is a simple static subclass of Vector4Provider. See the documentation for Vector4Basic for an example.

Vector4Providers can be used to provide dynamic input to PyChunkLight objects, GUI shaders, TintShaderPSA objects, and the PyModel dye system.

This base class provides no methods, and only one attribute, which is the Vector4 currently being provided.

Attribute Documentation

value

Type:
Read-Only Vector4


Vector4Shader - BigWorld base Documentation

Vector4Shader Class Reference

[Math Module]

Vector4Shader is part of the Math module. More...

import Math

Parent Classes

Vector4Provider → PyObjectPlus

Member Functions

def addOp( self, opcode, outreg, param1, param2 ):

Detailed Description

The Vector4Shader implements a Vector4Provider that can be used to emulate a pixel shader implementation for 2D GUI components.

The following code example show how to create a flickering light, for example when a spot fire occurs for "duration" and fades out gracefully.

code:
import BigWorld
from Math import Vector4Shader
from Math import Vector4LFO
from Math import Vector4Animation
from V4ShaderConsts import _mul
from V4ShaderConsts import _r0
from V4ShaderConsts import _r1

#and in class FlickeringLight...

self.light = BigWorld.PyChunkLight()
self.light.innerRadius = self.innerRadius
self.light.outerRadius = self.outerRadius

self.lightFaderAnim = Vector4Animation()
self.lightFaderAnim.time = 0
self.lightFaderAnim.duration = duration
col = Vector4(self.colour)
self.lightFaderAnim.keyframes = [(0.0,(0,0,0,0)),(0.25,col),
    (duration*0.5,col),(duration,(0,0,0,0))]

lfo1 = Vector4LFO()
lfo1.period = 0.4
lfo2 = Vector4LFO()
lfo2.period = 0.149
self.lightFader = Vector4Shader()

#First we multiply lfo1 by lfo2, and place the result in
#the temporary register _r1
self.lightFader.addOp( _mul, _r1, lfo1, lfo2 )

#Then we multiply the light fader animation to _r1, placing
#the result in _r0 ( the final output register )
self.lightFader.addOp( _mul, _r0, self.lightFaderAnim, _r1 )

self.light.source = source.model.root
self.light.visible = 1
self.light.shader = self.lightFader

Member Function Documentation

def addOp( self, opcode, outreg, param1, param2 ):

One parameter: 0 - MOVE 1 - RECIPROCAL 2 - BIAS 3 - COMPLEMENT

Two parameters: 4 - MULTIPLY 5 - DIVIDE 6 - ADD 6 - SUBTRACT 7 - DOT 8 - MIN 9 - MAX 10 - SGE 11 - SLT

Parameters:
opcode | One of the above values as an uint8
outreg | Temporary output register as Vector4ProviderPtr to store result
param1 | First parameter as Vector4ProviderPtr
param2 | Optional second parameter as Vector4ProviderPtr, used as required


Vector4Swizzle - BigWorld base Documentation

Vector4Swizzle Class Reference

[Math Module]

Vector4Swizzle is part of the Math module. More...

import Math

Parent Classes

Vector4Provider → PyObjectPlus

Attributes

w | Read-Write Vector4Provider
x | Read-Write Vector4Provider
y | Read-Write Vector4Provider
z | Read-Write Vector4Provider

Detailed Description

The Vector4Swizzle class takes four Vector4Providers and combines the x component of each into a single Vector4Provider.

A new Vector4Swizzle is created using Math. Vector4Swizzle method.

Attribute Documentation

w

Type:
Read-Write Vector4Provider

x

Type:
Read-Write Vector4Provider

y

Type:
Read-Write Vector4Provider

z

Type:
Read-Write Vector4Provider


Vector4Translation - BigWorld base Documentation

Vector4Translation Class Reference

[Math Module]

Vector4Translation is part of the Math module. More...

import Math

Parent Classes

Vector4Provider → PyObjectPlus

Attributes

source Read-Write Vector4

Detailed Description

This is a subclass of Vector4Provider. This provides a Vector4 value that returns the translation part of the source Matrix.

Code Example:
# This creates a Vector4 that returns the position of the players
# head node.

# import the Math module
import Math

v = Math.Vector4Translation()
v.source = BigWorld.player().model.node("biped Head")

Attribute Documentation

source

Type:
Read-Write Vector4


 BigWorld BaseApp

Actualised Classes

Modules
BWConfig
BWPersonality
BigWorld
Math
ResMgr
Class List
Base
BaseEntityMailBox
CellEntityMailBox
DataSection
GlobalBases
Matrix
MatrixInverse
MatrixProduct
MatrixProvider
Plane
Proxy
PyBases
PyObjectPlus
PyOutputWriter
PySTLSequence
RemoteEntityMethod
ServerEntityMailBox
Service
ServicesMap
SharedData
Vector2
Vector3
Vector4
Vector4Animation
Vector4Basic
Vector4Combiner
Vector4Distance
Vector4LFO
Vector4MatrixAdaptor
Vector4Morph
Vector4Product
Vector4Provider
Vector4Shader
Vector4Swizzle
Vector4Translation