This is the Python API reference documentation for the Client 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 client 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

GroundNormalProvider
PyMozillaEvent
PyObjectPlus
PyOutputWriter
PySTLSequence


BWPersonality - BigWorld client 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 when specific events occur.

Member Functions

def expandMacros( ):
def fini( ):
def handleIMEEvent( event ):
def handleKeyEvent( event ):
def handleLangChangeEvent( ):
def handleMouseEvent( event ):
def init( scriptConfig, engineConfig, preferences, loadingScreenGUI ):
def onChangeEnvironments( isInside ):
def onRecreateDevice( ):
def onStreamComplete( id, desc, data ):
def onTimeOfDayLocalChange( gameTime, secondsPerGameHour ):
def start( ):

Member Function Documentation

def expandMacros( ):

If present, this method is used to process input on the Python console before it is fed to the Python interpreter. It should accept a string and return a string formed by processing macros in whatever manner you desire. In FantasyDemo, this function is used to expand single character $ expressions like '$p' into 'BigWorld.player()'.

See the implementation of expandMacros() in fantasydemo/res/scripts/client/FantasyDemo.py for a sample implementation.

def fini( ):

If present, this method is called when the client engine shuts down. Usually, this function does any cleanup required before the client exits e.g. log out of the server.

def handleIMEEvent( event ):

If present, this method is called whenever the IME system changes state internally. The event object can be inspected to determine what part actually changed so that the scripts can update the IME interface that is currently being shown to the user.

Parameters:
event A PyIMEEvent object.

Returns:
This function should return False if the event was not handled and True if the key event was handled.

def handleKeyEvent( event ):

If present, this method is called whenever a key is pressed, released, or repeated due to operating system auto-repeat settings.

Parameters:
event A PyKeyEvent object.

Returns:
This function should return False if the key event was not handled and True if the key event was handled.

def handleLangChangeEvent( ):

If present, this method is called whenever the user changes the input language for the client (e.g. via the language bar).

Returns:
This function should return False if the event was not handled and True if the event was handled.

def handleMouseEvent( event ):

If present, this method is called whenever the mouse moves.

Parameters:
event A PyMouseEvent object.

Returns:
This function should return False if the mouse event was not handled and True if the mouse event was handled.

def init( scriptConfig, engineConfig, preferences, loadingScreenGUI ):

If present, this method is called when the engine initialises. Usually, this function initialises script objects from the configuration data.

Parameters:
scriptConfig | Is a PyDataSection object refering to the root section of script_config.xml.
engineConfig | Is a PyDataSection object refering to the root section of engine_config.xml.
preferences | Is a PyDataSection object refering to the scriptsPreference section of the preferences fils (defined in engine_config.xml).
loadingScreenGUI | (optional) a GUI.SimpleGUIComponent refering to loading screen GUI component shown during the startup procees, if one was defined in resources.xml.

def onChangeEnvironments( isInside ):

If present, this method is called when the type of environment that the player is in changes. Currently there are only two types of environments: inside and outside.

Parameters:
isInside This boolean indicates whether the player is in an inside environment.

def onRecreateDevice( ):

If present, this method is called when the Direct3D device is recreated e.g. when the screen resolution changes. Usually, this function re-layouts the GUI components and recreates any static PyModelRenderer textures.

def onStreamComplete( id, desc, data ):

If present, this method is called when a download from the proxy triggered with either streamStringToClient() or streamFileToClient() has completed.

See Proxy.streamStringToClient in BaseApp Python API documentation See Proxy.streamFileToClient in BaseApp Python API documentation

Parameters:
id | A unique ID associated with the download.
desc | A short string description of the download.
data | The downloaded data, as a string.

def onTimeOfDayLocalChange( gameTime, secondsPerGameHour ):

If present, this method is called when: a) the game time is changed manually i.e. not due to the natural progression of time; or b) The ratio of game time to real time is changed.

Parameters:
gameTime | The new game time.
secondsPerGameHour | The new number of real time seconds per game time hour.

def start( ):

If present, this method is called when the engine has initialised. Usually, this function starts the game e.g. by bringing up a menu or log-in screen.


BigWorld - BigWorld client Documentation

BigWorld Module Reference

The BigWorld Module is a Python module that provides the world related interfaces to the client. It is used to find out application specific information, such as unique, special-case Entities, connecting Entities and other game objects by their respective IDs. It is used to provide information on game world state from the server.

Class List

ActionMatcher
ActionQueuer
ArmTrackerNodeInfo
AutoAim
AvatarDropFilter
AvatarFilter
BaseCamera
BaseNodeInfo
BlendNodeInfo
BoidsFilter
Bouncer
BoxAttachment
CameraSpeed
CursorCamera
DiffDirProvider
DirectionCursor
DumbFilter
Entity
EntityDirProvider
EntityMProv
Filter
FlexiCam
FootTrigger
FreeCamera
Homer
LatencyGUIComponent
LatencyInfo
LinearHomer
Motor
Orbitor
OrthogonalNodeInfo
Oscillator
Oscillator2
Physics
PlayerAvatarFilter
PlayerMProv
ProjectionAccess
Propellor
PyAttachment
PyAxisEvent
PyChunkLight
PyChunkModel
PyChunkSpotLight
PyDye
PyEntities
PyFashion
PyFont
PyGraphicsSetting
PyIME
PyIMEEvent
PyKeyEvent
PyLoft
PyModel
PyModelNode
PyModelObstacle
PyModelRenderer
PyMorphControl
PyMouseEvent
PyResourceRefs
PySceneRenderer
PyServer
PyShimmerCountProvider
PySplodge
PyTarget
PyTextureProvider
PyWaterVolume
PythonServer
ScanDirProvider
ServerCaller
ServerDiscovery
ServerDiscoveryDetails
Servo
SkeletonCollider
Targeting
Tracker
TrackerNodeInfo
UnresolvedUDORefException
VectorGenerator
Weather
WebPageProvider

Member Functions

def ActionMatcher( ):
def ArmTrackerNodeInfo( model, pUpperArmNode, pForeArmNode, minShoulderPitch, maxShoulderPitch, minShoulderYaw, maxShoulderYaw, minShoulderRoll, maxShoulderRoll, minElbowPitch, maxElbowPitch, minPitch, maxPitch, minYaw, maxYaw, pointingAxis, angularVelocity, angularThreshold, angularHalflife ):
def AvatarDropFilter( an ):
def AvatarFilter( an ):
def AxisEvent( axis, value, dTime ):
def BoidsFilter( ):
def Bouncer( ):
def BoxAttachment( ):
def CursorCamera( ):
def DiffDirProvider( source, target ):
def DumbFilter( ):
def EntityDirProvider( entity, pitchIndex, yawIndex ):
def FlexiCam( ):
def Font( name ):
def FootTrigger( Boolean, string ):
def FreeCamera( ):
def GraphicsSetting( String, String, Int, Boolean, Boolean, PyObject ):
def Homer( ):
def InvViewMatrix( ):
def KeyEvent( key, state, modifiers, character, cursorPos ):
def LatencyInfo( ):
def LinearHomer( ):
def Loft( ):
def Material( effectName, diffuseMap, DataSection ):
def Model( *modelPath ):
def MouseEvent( dx, dy, dz, cursorPos ):
def MouseTargettingMatrix( ):
def Orbitor( ):
def OrthogonalNodeInfo( model, pitchNode, yawNode, directionNode, minPitch, maxPitch, minYaw, maxYaw, yawAxis, pitchAxis, angularVelocity, angularThreshold, angularHalflife ):
def Oscillator( yaw, period, amplitude, offset ):
def Oscillator2( yaw, period, amplitude, offset ):
def PlayerAvatarFilter( ):
def PlayerMatrix( ):
def Propellor( ):
def PyChunkLight( ):
def PyChunkModel( modelName, spaceID, matrix ):
def PyChunkSpotLight( ):
def PyModelObstacle( modelNames, matrix, dynamic ):
def PyModelRenderer( width, height ):
def PyMorphControl( ):
def PySceneRenderer( width, height ):
def PyShimmerCountProvider( ):
def PyTextureProvider( resourceId ):
def PyWaterVolume( ):
def RenderTarget( name, width, height, reuseZ, format ):
def ScanDirProvider( amplitude, period, offset, callback ):
def Servo( signal ):
def Splodge( ):
def ThirdPersonTargettingMatrix( source ):
def Tracker( ):
def TrackerNodeInfo( model, primaryNodeName, secondaryNodesList, pointingNodeName, minPitch, maxPitch, minYaw, maxYaw, angularVelocity, angularThreshold, angularHalflife ):
def VOIP.command( data ):
def VOIP.createChannel( channelName, password, data ):
def VOIP.disableActiveChannel( channelName, data ):
def VOIP.disableMicrophone( data ):
def VOIP.disablePositional( data ):
def VOIP.enableActiveChannel( channelName, data ):
def VOIP.enableMicrophone( data ):
def VOIP.enablePositional( data ):
def VOIP.finalise( data ):
def VOIP.getStatistics( ):
def VOIP.initialise( data ):
def VOIP.inviteUser( userName, channelName, data ):
def VOIP.joinChannel( channelName, password, data ):
def VOIP.kickUser( userName, channelName, data ):
def VOIP.leaveChannel( channelName, data ):
def VOIP.login( username, password, data ):
def VOIP.logout( data ):
def VOIP.queryChannels( ):
def VOIP.setChannelVolume( attenuation, data ):
def VOIP.setHandler( callback ):
def VOIP.setMasterVolume( attenuation, data ):
def VOIP.setMicrophoneVolume( attenuation, data ):
def addAlwaysUpdateModel( pModel ):
def addDecal( start, end, size, type ):
def addFogEmitter( position, density, innerRadius, outerRadius, colour, localised ):
def addFunctionWatcher( path, function, argumentList, exposedHint, desc ):
def addMat( source, callback, target ):
def addModel( pModel, spaceID ):
def addPot( centre, radius, callback ):
def addShadowEntity( Entity ):
def addSkyBox( a, p ):
def addSpaceGeometryMapping( spaceID, matrix, filepath ):
def addTextureFeed( identifier, texture ):
def addWatcher( path, getFunction, setFunction ):
def addWaterVolumeListener( dynamicSource, callback ):
def ambientController( p ):
def autoDetectGraphicsSettings( ):
def axisDirection( axis ):
def callback( time, function ):
def camera( cam ):
def cameraSpaceID( spaceID ):
def cancelCallback( int ):
def changeFullScreenAspectRatio( ratio ):
def changeVideoMode( new, windowed ):
def chunkTransform( chunkNMapping, spaceID ):
def clearAllSpaces( keepClientOnlySpaces ):
def clearDecals( ):
def clearEntitiesAndSpaces( ):
def clearSpace( spaceID ):
def collide( spaceID, src, dst ):
def commandLineLoginInfo( ):
def commitPendingGraphicsSettings( ):
def connect( server, loginParams, progressFn ):
def connectedEntity( ):
def consumerBuild( ):
def controlEntity( entity, beControlled ):
def createEntity( className, spaceID, vehicleID, position, direction, state ):
def createSpace( ):
def createTranslationOverrideAnim( baseAnim, translationReferenceAnim, noOverrideChannels, outputAnim ):
def darkenConsoleBackground( enable ):
def dcursor( ):
def debugAQ( ):
def debugModel( ):
def decalTextureIndex( textureName ):
def delAlwaysUpdateModel( pModel ):
def delFogEmitter( id ):
def delMat( matID ):
def delModel( pModel ):
def delPot( handle ):
def delShadowEntity( Entity ):
def delSkyBox( m, p ):
def delSpaceGeometryMapping( spaceID, handle ):
def delStaticSkyBoxes( ):
def delTextureFeed( identifier ):
def delWatcher( path ):
def delWaterVolumeListener( id ):
def destroyEntity( id ):
def disconnect( ):
def dumpMemCounters( ):
def dumpRefs( ):
def entity( id, lookInCache ):
def fetchModel( *modelPath, onLoadCompleted ):
def findChunkFromPoint( point, spaceID ):
def findDropPoint( spaceID, vector3 ):
def flashBangAnimation( p ):
def floraReset( ):
def floraVBSize( Number ):
def flyThroughRunning( ):
def fogController( p ):
def getFullScreenAspectRatio( ):
def getGraphicsSetting( label ):
def getMaterialKinds( ):
def getTextureFeed( identifier ):
def getWatcher( path ):
def getWatcherDir( path ):
def graphicsSettings( ):
def graphicsSettingsNeedRestart( ):
def hasPendingGraphicsSettings( ):
def isKeyDown( key ):
def isTripleBuffered( ):
def isVideoVSync( ):
def isVideoWindowed( ):
def keyToString( key ):
def listVideoModes( ):
def loadResourceListBG( resourceList, callbackFn, priority ):
def localeInfo( ):
def memUsed( ):
def models( Any ):
def noPartialLocks( ):
def playMovie( ):
def player( entity ):
def playerDead( isDead ):
def probe( server, progressFn ):
def projection( ):
def quit( ):
def releaseSpace( spaceID ):
def reloadChunks( ):
def reloadTextures( ):
def removeFlashBangAnimation( p ):
def resetEntityManager( keepPlayerAround, keepClientOnly ):
def resizeWindow( width, height ):
def restartGame( ):
def rollBackPendingGraphicsSettings( ):
def saveAllocationsToFile( filename ):
def saveFontCacheMap( identifier ):
def savePreferences( ):
def screenHeight( ):
def screenShot( format, name ):
def screenSize( ):
def screenWidth( ):
def server( ):
def serverTime( ):
def setCursor( cursor ):
def setGraphicsSetting( label, optionIndex ):
def setTripleBuffering( doTripleBuffering ):
def setVideoVSync( doVSync ):
def setWatcher( path, val ):
def sinkKeyEvents( key, [optional] ):
def spaceLoadStatus( (optional) ):
def spaceTimeOfDay( spaceID, time ):
def stime( ):
def stringToKey( string ):
def sunlightController( p ):
def target( ):
def time( ):
def timeOfDay( time ):
def totalPhysicalMemory( ):
def totalVirtualMemory( ):
def videoModeIndex( ):
def weather( spaceID ):
def weatherController( p ):
def windowSize( ):
def worldDrawEnabled( newValue ):

Attributes

allEntities | Read-Only PyEntities.
cachedEntities | Read-Only PyEntities.
cameraSpeed | CameraSpeed.
component |
entities | Read-Only PyEntities.
isEmbedded |
platform |
serverDiscovery | ServerDiscovery
target | PyTarget.
targeting |

Member Function Documentation

def ActionMatcher( ):

This function returns a new ActionMatcher Motor object, which is used to match the movements and orientation of an entity to the actions defined on its primary model. Note that the primary Model will be assigned an ActionMatcher Motor by default.

Returns:
new ActionMatcher object

def ArmTrackerNodeInfo( model, pUpperArmNode, pForeArmNode, minShoulderPitch, maxShoulderPitch, minShoulderYaw, maxShoulderYaw, minShoulderRoll, maxShoulderRoll, minElbowPitch, maxElbowPitch, minPitch, maxPitch, minYaw, maxYaw, pointingAxis, angularVelocity, angularThreshold, angularHalflife ):

Creates a new instance of the ArmTrackerNodeInfo class. This describes how PyModelNode instances are affected by a two bone IK Tracker.

Parameters:
model | The PyModel that owns the nodes which trackers using this will affect.
pUpperArmNode | A string containing the name of the upper arm node.
pForeArmNode | A string containing the name of the forearm node.
minShoulderPitch | A float describing the maximum pitch variation in the negative direction (downwards) that a tracker can apply, in degrees.
maxShoulderPitch | A float describing the maximum pitch variation in the positive direction (upwards) that a tracker can apply, in degrees.
minShoulderYaw | A float describing the maximum yaw variation in the negative direction (to the left) that a tracker can apply, in degrees.
maxShoulderYaw | A float describing the maximum yaw variation in the positive direction (to the right) that a tracker can apply, in degrees.
minShoulderRoll | A float describing the maximum roll variation in the negative direction (clockwise) that a tracker can apply, in degrees.
maxShoulderRoll | A float describing the maximum roll variation in the positive direction (anticlockwise) that a tracker can apply, in degrees.
minElbowPitch | A float describing the maximum pitch variation in the negative direction (downwards) that a tracker can apply, in degrees.
maxElbowPitch | A float describing the maximum pitch variation in the positive direction (upwards) that a tracker can apply, in degrees.
minPitch | A float describing the maximum pitch variation in the negative direction (downwards) that a tracker can apply, in degrees.
maxPitch | A float describing the maximum pitch variation in the positive direction (upwards) that a tracker can apply, in degrees.
minYaw | A float describing the maximum yaw variation in the negative direction (to the left) that a tracker can apply, in degrees.
maxYaw | A float describing the maximum yaw variation in the positive direction (to the right) that a tracker can apply, in degrees.
pointingAxis | An int specifying the pointing axis of node (Xaxis, Yaxis or Zaxis).
angularVelocity | A float describing the speed at which a tracker will turn the PyModelNode instances that it influences, in degrees per second.
angularThreshold | A float describing the angle to check if a decay or simple interpolation is used to blend the tracker node into the correct angle, specified in degrees. For more information check BaseNodeInfo.
angularHalflife | A float describing the angular rate of decay to blend the tracker node, specified in seconds. For more information check BaseNodeInfo.

Returns:
The new ArmTrackerNodeInfo.

def AvatarDropFilter( an ):

This function creates a new AvatarDropFilter, which is used to move avatars around the same as an AvatarFilter does, but also to keep them on the ground beneath their specified positions.

Parameters:
an optional AvatarFilter to initialise the filter with

Returns:
a new AvatarDropFilter

def AvatarFilter( an ):

This function creates a new AvatarFilter, which is used to interpolate between the position and yaw updates from the server for its owning entity.

Parameters:
an optional AvatarFilter to initialise the filter with

Returns:
a new AvatarFilter

def AxisEvent( axis, value, dTime ):

This function creates a new PyAxisEvent object. This can be used to create artificial events which did not originate from the engine's input system itself.

Parameters:
axis | The axis index, as defined in Keys.py
value | A float value between -1.0 and +1.0.
dTime | A value representing the time since the last time the axis was processed.

Returns:
the newly created axis event.

def BoidsFilter( ):

This function creates a new BoidsFilter. This is used to filter the movement of an Entity which consists of several models (boids) for which flocking behaviour is desired.

Returns:
a new BoidsFilter

def Bouncer( ):

Bouncer is a factory function to create a Bouncer Motor. A Bouncer is a Motor that starts with an initial velocity, and bounces according to the laws of physics, finally coming to rest. This Motor could be used for thrown objects, such as grenades.

Returns:
A new Bouncer object.

def BoxAttachment( ):

This method creates a BoxAttachment and returns it.

Returns:
Returns a new BoxAttachment object.

def CursorCamera( ):

This function creates a new CursorCamera. A CursorCamera looks at a specified target, in the direction of a specified source.

Returns:
a new CursorCamera object.

def DiffDirProvider( source, target ):

Creates a DiffDirProvider. This provides a matrix representing the direction between the points specified by two matrices.

Code Example:
# returns a new DiffDirProvider which provides a matrix which points from
# matrix e1 to matrix e2
BigWorld.DiffDirProvider( e1.matrix, e2.matrix )

Parameters:
source | The MatrixProvider that gives the position from which the matrix this provides points.
target | The MatrixProvider that gives the position towards which the matrix this provides points.

Returns:
The new DiffDirProvider

def DumbFilter( ):

This function creates a new DumbFilter, which is the simplest filter, which just sets the position of the owning entity to the most recently received position from the server.

Returns:
A new DumbFilter object

def EntityDirProvider( entity, pitchIndex, yawIndex ):

Create a new EntityDirProvider. This is a MatrixProvider with the direction of a specified entity.

Code Example:
# return a new EntityDirProvider which provides the direction
# faced by the entity ent.
BigWorld.EntityDirProvider( ent )

Parameters:
entity | The entity whose facing direction this provides.
pitchIndex | An integer which describes which of the entity's axis are to be interpreted as pitch (0:yaw, 1:pitch, 2:roll).
yawIndex | An integer which describes which of the entity's axis are to be interpreted as yaw (0:yaw, 1:pitch, 2:roll).

Returns:
The new EntityDirProvider.

def FlexiCam( ):

This function creates a new FlexiCam, which can be used to look at a target from a specified point relative to the target.

Returns:
a new FlexiCam

def Font( name ):

Parameters:
name the resource id.

Returns:
A new PyFont object.

def FootTrigger( Boolean, string ):

This function creates a new FootTrigger object. This can be attached to PyModelNodes to test for them hitting the ground, and calling a function when they do.

Parameters:
Boolean | left [False] foot or right [True] foot
string | [optional] sound trigger prefix

Returns:
a new FootTrigger object.

def FreeCamera( ):

This function creates a new FreeCamera. This is a camera that is controlled by the mouse and arrow keys, and moves around independently of entities and geometry, making it useful for debugging and exploring the world.

Returns:
a new FreeCamera object.

def GraphicsSetting( String, String, Int, Boolean, Boolean, PyObject ):

This function creates a PyGraphicsSetting.

For example:
def onOptionSelected( idx ):
    print "graphics setting option %d selected" % (idx,)

gs = BigWorld.GraphicsSetting( "label", "description", -1, False, False, onOptionSelected )
gs.addOption( "High", "High Quality", True )
gs.addOption( "Low", "Low Quality", True )
gs.registerSetting()	#always add after the options have been added.

Parameters:
String | Short label to display in the UI.
String | Longer description to display in the UI.
Int | Active option index. When this setting is added to the registry, the active option will be either reset to the first supported option or to the one restored from the options file, if the provided active option index is -1. If, instead, the provided activeOption is a non negative value, it will either be reset to the one restored from the options file (if this happens to be different from the value passed as parameter) or not be reset at all.
Boolean | Delayed - apply immediately on select, or batched up.
Boolean | Requires Restart - game needs a restart to take effect.
PyObject | Callback function.

Returns:
a new PyGraphicsSetting

def Homer( ):

Homer is a factory function to create a Homer Motor. A Homer is a Motor that moves a model towards a target (MatrixProvider).

Returns:
A new Homer object.

def InvViewMatrix( ):

This function returns a new InvViewMatrixProvider which is a MatrixProvider that can be used to access the rendering engine's inverse view matrix.

def KeyEvent( key, state, modifiers, character, cursorPos ):

This function creates a new PyKeyEvent object. This can be used to create artificial events which did not originate from the engine's input system itself.

Parameters:
key | The key code.
state | The state of the key, where -1 indicates up and >= 0 indicates the repeat count (so 0 means the key has just been pressed).
modifiers | The state of the modifier keys (ALT, CONTROL, SHIFT).
character | A unicode string or None.
cursorPos | The clip-space position of the mouse cursor.

Returns:
the newly created key event.

def LatencyInfo( ):

The function LatencyInfo is a factory function to create and return a LatencyInfo object. A LatencyInfo object is a Vector4Provider with an overloaded value attribute. This attribute (for a LatencyInfo object) is overloaded to return a 4 float sequence consisting of ( 1, minimum latency, maximum latency, average latency ) if the client is connected to a server. If the client is not connected to the server then the value attribute returns ( 0, 0, 0, 0 ).

Returns:
A new LatencyInfo object (see also Vector4Provider).

def LinearHomer( ):

This function returns a new LinearHomer object, which is Motor designed to drive a Model towards it's target in a straight line. It has a different set of features to the Homer Motor.

Returns:
A new LinearHomer object

def Loft( ):

This function creates and returns a new PyLoft object.

def Material( effectName, diffuseMap, DataSection ):

Note that the parameter list is complicated, so although three parameters are listed below, the PyMaterial constructor takes : Either the name of an .fx file, (and optionally the name of a diffuse map.) Or a PyDataSection containing a material section.

There are no listed attributes for a PyMaterial, however on creation, the attribute dictionary will be filled with all the "artist editable" variables contained in the effect file.

Parameters:
effectName | Name of the effect file (*.fx)
diffuseMap | Name of the diffuse map for the .fx file
DataSection | DataSection for a material section.

Returns:
A new PyMaterial object.

def Model( *modelPath ):

Model is a factory function that creates and returns a new PyModel object (None if there are problems loading any of the requested resources). PyModels are renderable objects which can be moved around the world, animated, dyed (have materials programatically assigned) and contain points to which objects can be attached.

The parameters for the function are one or more model resources. Each of these individual models is loaded, and combined into a "supermodel".

This function will block the main thread to load models in the event that they were not specified as prerequisites. To load models asynchronously from script use the method BigWorld.loadResourceListBG().

For example, to load a body and a head model into one supermodel:

model = BigWorld.Model( "models/body.model", "models/head.model" )

Parameters:
*modelPath String argument(s) for the model.

Returns:
A reference to the PyModel specified.

def MouseEvent( dx, dy, dz, cursorPos ):

This function creates a new PyMouseEvent object. This can be used to create artificial events which did not originate from the engine's input system itself.

Parameters:
dx | A signed integer representing the delta movement on the X-axis.
dy | A signed integer representing the delta movement on the Y-axis.
dz | A signed integer representing the mouse wheel.
cursorPos | The clip-space position of the mouse cursor.

Returns:
the newly created mouse event.

def MouseTargettingMatrix( ):

Creates and returns a new MouseTargettingMatrix provider. This matrix provider produces a world-space transform (position and direction) from the unprojected mouse position. The translation component is positioned on the near plane of the camera.

While this provider is intended to be used with the BigWorld targeting system, you can also use it to produce world position and direction vectors from Python. For example, these vectors could be used as parameters to BigWorld.collide:

mtm = Math.Matrix( BigWorld.MouseTargetting() )
src = mtm.applyToOrigin()
dir = mtm.applyToAxis(2)

def Orbitor( ):

Orbitor is a factory function to create a Orbitor Motor. A Orbitor is a Motor that moves a model towards a target (MatrixProvider) and orbits.

Returns:
A new Orbitor object.

def OrthogonalNodeInfo( model, pitchNode, yawNode, directionNode, minPitch, maxPitch, minYaw, maxYaw, yawAxis, pitchAxis, angularVelocity, angularThreshold, angularHalflife ):

This creates a new instance of the OrthogonalNodeInfo class which describes how PyModelNode instances can be affected by a Tracker. Note that the attributes specified by this function are not made accessable by script in the object it creates. Instances of this particular NodeInfo class can be used by a Tracker to apply pitch changes to one model node, and yaw changes to another. This can be used very effectively with models which represent machinery that turns on swivel joints.

Parameters:
model | The PyModel owning the nodes that will be affected by any Tracker which makes use of the returned OrthogonalNodeInfo.
pitchNode | A string containing the name of the pitch node. This is the node to which a Tracker applies pitch changes. If this does not match the name of a node of the model specified by the model argument then a ValueError is thrown.
yawNode | A string containing the name of the yaw node. This is the node to which yaw changes are applied. If this does not match the name of a node in the model specified by the model argument then a ValueError is thrown.
directionNode | A string containing the name of a node that can be assumed to have undergone both the pitch and yaw translations after they've been applied. This should be a descendent of both the pitchNode and the yawNode. If this does not match the name of a node in the model specified by the model argument then a ValueError is thrown.
minPitch | A float describing the maximum pitch variation (in degrees) in the negative direction (downwards) that can be applied by a Tracker.
maxPitch | A float describing the maximum pitch variation (in degrees) in the positive direction (upwards) that can be applied by a Tracker.
minYaw | A float describing the maximum yaw variation (in degrees) in the negative direction (to the left) that can be applied by a Tracker.
maxYaw | A float describing the maximum yaw variation (in degrees) in the positive direction (to the right) that can be applied by a Tracker.
yawAxis | An int describing which axis to rotate along to change yaw 1=x-axis, 2=y-axis, 3=z-axis, negative values means invert the axis.
pitchAxis | An int describing which axis to rotate along to change pitch 1=x-axis, 2=y-axis, 3=z-axis, negative values means invert the axis.
angularVelocity | A float describing the speed (in degrees per second) that a Tracker will rotate any PyModelNode instances that it influences.
angularThreshold | A float describing the angle to check if a decay or simple interpolation is used to blend the tracker node into the correct angle, specified in degrees. For more information check BaseNodeInfo.
angularHalflife | A float describing the angular rate of decay to blend the tracker node, specified in seconds. For more information check BaseNodeInfo.

Returns:
The new OrthogonalNodeInfo.

def Oscillator( yaw, period, amplitude, offset ):

Oscillator is a factory function that creates and returns a new Oscillator object. An Oscillator is a Motor that applies an oscillating rotational component to an objects world transform.

See the Oscillator class for more information on the parameters below.

Parameters:
yaw | Float. Specifies the initial yaw (in radians) of the rotation.
period | Float. Specifies the period (in seconds) of rotation.
amplitude | Float. Specifies the maximum angle (in radians) of rotation.
offset | Float. Specifies the offset (in seconds) to the start of the period of oscillation.

Returns:
A new Oscillator object.

def Oscillator2( yaw, period, amplitude, offset ):

Oscillator2 is a factory function that creates and returns a new Oscillator2 object. An Oscillator2 extends Oscillator (Motor) and applies an oscillating rotational component around the origin to a model's world transform, instead of rotating it around its own centre.

See the Oscillator class for more information on the parameters below.

Parameters:
yaw | Float. Specifies the initial yaw (in radians) of the rotation.
period | Float. Specifies the period (in seconds) of rotation.
amplitude | Float. Specifies the maximum angle (in radians) of rotation.
offset | Float. Specifies the offset to the start of the period of oscillation.

Returns:
A new Oscillator2 object.

def PlayerAvatarFilter( ):

This function creates a new PlayerAvatarFilter. This updates the position and yaw of the entity to those specified by the most recent server update.

Returns:
a new PlayerAvatarFilter

def PlayerMatrix( ):

This function returns a new PlayerMProv which is a MatrixProvider that can be used to access the player entity's position.

def Propellor( ):

Creates and returns a new Propellor Motor, which is used to move a model by applying a point source of force.

def PyChunkLight( ):

Creates a new PyChunkLight. This is a script controlled chunk omni light which can be used as a diffuse and/or specular light source for models and shells.

def PyChunkModel( modelName, spaceID, matrix ):

NOTE: This function has been deprecated - Use a static PyModelObstacle instead

Creates an instance of PyChunkModel using a given model, with a given transform. A PyChunkModel is a PyObjectPlus wrapper around a simple model which is treated by BigWorld as a part of the level geometry.

Code Example:
# Import Math library
import Math

# Place a PyChunkModel in the world at ( 0, 10, 0 )
modelName = "objects\models\items\Trees & Plants\oak4.model"
matrix = Math.Matrix()
matrix.setTranslate( ( 0, 10, 0 ) )
newPyChunkModel = BigWorld.PyChunkModel( modelName, $p.spaceID, matrix )

Parameters:
modelName | A string containing the name of the model to use.
spaceID | The ID of the space in which to place the PyChunkModel.
matrix | The MatrixProvider which gives the PyChunkModel's transform. Note that the PyChunkModel's transform is static. It does does not dynamically change with this MatrixProvider.

Returns:
The new PyChunkModel.

def PyChunkSpotLight( ):

Creates a new PyChunkSpotLight. This is a script controlled chunk spot light which can be used as a diffuse and/or specular light source for models and shells.

def PyModelObstacle( modelNames, matrix, dynamic ):

Creates and returns a new PyModelObstacle object, which is used to integrate a model into the collision scene.

Example:
    self.model = BigWorld.PyModelObstacle("models/body.model", "models/head.model", self.matrix, 1)

Once created and assigned (self.model = PyModelObstacle), the PyObstacleModel becomes attached, hence its dynamic nature cannot be changed. If left as static, the position of the PyObstacleModel will not be updated as the MatrixProvider changes. PyModelObstacles are reasonably expensive, hence should only be used when truly required.

Parameters:
modelNames | Any number of ModelNames can be used to build a SuperModel, which is a PyModel made of other PyModels ( see BigWorld.Model() ). Each modelName should be a complete .model filename, including resource path.
matrix | (optional) The transform Matrix for the resultant PyModelObstacle, used to update (if dynamic) or set (if static) the SuperModel's position.
dynamic | (optional) If true, PyModelObstacle will be treated as dynamic, otherwise static. Defaults to false (static).

def PyModelRenderer( width, height ):

This function creates a new PyModelRenderer, which can be used to render models into a PyTextureProvider which can supply a texture to other things, such as a SimpleGUIComponent, which need a texture to render.

Parameters:
width | the width of the texture to render to
height | the height of the texture to render to

def PyMorphControl( ):

This function creates a new PyMorphControl. This can be applied to a model, and used to blend between a specified list of morph targets using weights supplied in a MatrixProvider.

Returns:
a new PyMorphControl

def PySceneRenderer( width, height ):

This function creates a new PySceneRenderer. The function takes two arguments, which are the width and height of the texture to render to. PySceneRenderers render one or more cameras to a texture, which can then be applied to anything which can use a PyTextureProvider.

Parameters:
width | an Integer. The width of the texture to render to (in Pixels).
height | an Integer. The height of the texture to render to (in Pixels).

Returns:
a new PySceneRenderer.

def PyShimmerCountProvider( ):

This function creates a PyShimmerCountProvider. It records the number of shimmer objects currently visible. It can be used to optimise Post-Processing effects that use the shimmer channel (alpha of the back buffer).

Returns:
a new PyShimmerCountProvider.

def PyTextureProvider( resourceId ):

This function creates a PyTextureProvider. It takes a texture filename as an argument. A PyTextureProvider is used to supply a texture to classes which need a texture, such as SimpleGUIComponent.

For example:
tex = BigWorld.PyTextureProvider( "maps/fx/picture.bmp" )
In the example, tex is set to be a PyTextureProvider which exposes the picture.bmp texture.

Parameters:
resourceId the filename of the texture to load.

Returns:
a new PyTextureProvider.

def PyWaterVolume( ):

Factory function to create and return a new PyWaterVolume object.

Returns:
A new PyWaterVolume object.

def RenderTarget( name, width, height, reuseZ, format ):

Note that width and height can be specified either in absolute pixels, or they can represents multipliers of the screen size. These dimensions automatically adjust when the screen size changes.

w,h = 0 : use the screen size w,h = -1 : screen size / 2 w,h = -2 : screen size / 4 w,h = -n : screen size / pow(2,n)

Parameters:
name | Name of the render target
width | Desired Width. 0, ... -n have special meaning (see above)
height | Desired Height. 0, ... -n have special meaning (see above)
reuseZ | (optional)Re-use the back-buffer's Z-buffer, or False to create a unique z-buffer for this render target.
format | (optional)D3DFORMAT enum value.

Returns:
A new PyRenderTarget object.

def ScanDirProvider( amplitude, period, offset, callback ):

Creates a new ScanDirProvider. This is a MatrixProvider whose direction oscillates around the y axis, and may be instructed to call a function when it hits it's leftmost and rightmost limits.

Code Example:
# return a new ScanDirProvider which swings left and right by pi/2 radians
# every 10 seconds, offset by 0 percent of its period from time 0. It calls
# limitFunct( 4 ) when it hits it's leftmost limit, and limitFunct( 5 )
# when it hits it's rightmost limit.
BigWorld.ScanDirProvider( math.pi/2, 10, 0, limitFunct )

Parameters:
amplitude | A float representing the angle about 0 to which this should swing around the y axis, in radians.
period | A float giving the time in seconds for a full sweep left & right.
offset | An optional float giving the offset of the sweep cycle from time 0, as a proportion of the period.
callback | An optional function with a single argument. This function is called with value 4 when this hits it's leftmost limit, and 5 when it hits it's rightmost limit.

Returns:
The new ScanDirProvider

def Servo( signal ):

Creates and returns a new Servo Motor, which sets the transform of a model to the given MatrixProvider. As the MatrixProvider is updated, the model will move.

Parameters:
signal MatrixProvider that model will follow

def Splodge( ):

Creates a new PySplodge object which is ready to be attached to a node on a model. This draws a "splodge" shadow on the ground below the point where it is attached.

Returns:
A new PySplodge.

def ThirdPersonTargettingMatrix( source ):

Creates and returns a new ThirdPersonTargettingMatrix provider. This matrix provider implements a special-case matrix designed for targetting while using a 3rd person camera. It takes camera matrix and moves it forward along its z-axis until it lines up with the position given by the user-specified source matrix (for example, the player entity matrix).

Parameters:
source MatrixProvider to help calculate the look from matrix.

def Tracker( ):

Creates a new instance of the Tracker class. This is a subclass of PyFashion which manipulates yaw and pitch of the PyModelNode instances in a PyModel so as to make them face towards (or "track") a target.

Returns:
The new Tracker object.

def TrackerNodeInfo( model, primaryNodeName, secondaryNodesList, pointingNodeName, minPitch, maxPitch, minYaw, maxYaw, angularVelocity, angularThreshold, angularHalflife ):

Creates a new instance of the TrackerNodeInfo class. This describes how PyModelNode instances are affected by a Tracker. Note that the attributes specified by this function are not made accessable by script in the object it creates.

Parameters:
model | The PyModel that owns the nodes which trackers using this will affect.
primaryNodeName | A string containing the name of the primary node. The direction change applied to the primary node is not weighted.
secondaryNodesList | A list of tuples of the form ( nodeName, weight ), where nodeName is a string containing the name of a node to be affected by a tracker, and weight is a float describing the influence a tracker has over it.
pointingNodeName | A string containing the name of a node provides the frame of reference used for tracker manipulations. If the node specified is not present, the model's scene root is used instead.
minPitch | A float describing the maximum pitch variation in the negative direction (upwards) that a tracker can apply, in degrees.
maxPitch | A float describing the maximum pitch variation in the positive direction (downwards) that a tracker can apply, in degrees.
minYaw | A float describing the maximum yaw variation in the negative direction (to the left) that a tracker can apply, in degrees.
maxYaw | A float describing the maximum yaw variation in the positive direction (to the right) that a tracker can apply, in degrees.
angularVelocity | A float describing the speed at which a tracker will turn the PyModelNode instances that it influences, in degrees per second.
angularThreshold | (optional) A float describing the angle to check if a decay or simple interpolation is used to blend the tracker node into the correct angle, specified in degrees. For more information check BaseNodeInfo. Defaults to -1.
angularHalflife | (optional) A float describing the angular rate of decay to blend the tracker node, specified in seconds. For more information check BaseNodeInfo. Defaults to 0.

Returns:
The new TrackerNodeInfo.

def VOIP.command( data ):

This is a generic function for handling implementation specific commands not exposed in the general VoIP interface.

Parameters:
data (dictionary) Additional information in the form of string value pairs

def VOIP.createChannel( channelName, password, data ):

Creates a new channel with the given name. The creating user automatically joins the newly created channel. The channel will be destroyed when all users leave the channel. Default password is "".

Parameters:
channelName | (string) The string that uniquely identifies the new channel
password | (string) Optional: The password that will be needed to access the channel
data | (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.disableActiveChannel( channelName, data ):

Disables voice transmission on the specified channel.

Parameters:
channelName | (string) The string identifying the channel
data | (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.disableMicrophone( data ):

Disables microphone input.

Parameters:
data (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.disablePositional( data ):

Disables positional audio filtering

Parameters:
data (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.enableActiveChannel( channelName, data ):

Enables voice transmission on the specified channel.

Parameters:
channelName | (string) The string identifying the channel
data | (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.enableMicrophone( data ):

Enables microphone input.

Parameters:
data (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.enablePositional( data ):

Enables positional audio filtering

Parameters:
data (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.finalise( data ):

This function instructs the VoIP client to clean up all its connections and resources.

Parameters:
data (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.getStatistics( ):

Requests an implementation specific a statistics report that will be sent back to the application via the response callback mechanism.

def VOIP.initialise( data ):

This function initialises the VoIP client.

Parameters:
data (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.inviteUser( userName, channelName, data ):

Sends an invite to another VoIP user to join a channel.

Parameters:
userName | (string) The string identifying the user's VoIP account
channelName | (string) The string identifying the channel
data | (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.joinChannel( channelName, password, data ):

Joins an existing channel. Default password is "".

Parameters:
channelName | (string) The string identifying the channel
password | (string) Optional: The password that will be needed to access the channel
data | (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.kickUser( userName, channelName, data ):

Kicks a user from a channel

Parameters:
userName | (string) The string identifying the user's VoIP account
channelName | (string) The string identifying the channel
data | (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.leaveChannel( channelName, data ):

Leaves a channel that the client is already connected to.

Parameters:
channelName | (string) The string identifying the channel
data | (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.login( username, password, data ):

This function logs the client into the VoIP service.

Parameters:
username | (string) The string that uniquely identifies the user's account
password | (string) The corresponding password to access the account
data | (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.logout( data ):

This function logs the client out of the VoIP service.

Parameters:
data (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.queryChannels( ):

Returns the list of channels the client is connected to.

Returns:
[(string),...] The list of channel names

def VOIP.setChannelVolume( attenuation, data ):

Sets the volume at which voice communications on the given channel play. This attenuation is in addition to that applied by the master volume.

Parameters:
attenuation | (float) The new speaker volume attenuation in decibels(dB)
data | (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.setHandler( callback ):

Sets a callback function that can be used by the VOIPClient implementation. The function augments will be of the form (int, dictionary).

Parameters:
callback (callable) A callable object that can handle arguments of the form (int, dictionary)

def VOIP.setMasterVolume( attenuation, data ):

Sets the overall volume at which voice communications will be played.

Parameters:
attenuation | (float) The new speaker volume attenuation in decibels(dB)
data | (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def VOIP.setMicrophoneVolume( attenuation, data ):

Sets the attenuation applied to microphone capture.

Parameters:
attenuation | (float) The new microphone attenuation in decibels(dB)
data | (dictionary) Optional: Additional information in the form of string value pairs

Returns:
(none)

def addAlwaysUpdateModel( pModel ):

This function adds a PyModel to a list of models that have their nodes updated even when they are not visible.

Parameters:
pModel the model to always update

def addDecal( start, end, size, type ):

This function attempts to add a decal to the scene, given a world ray. If the world ray collides with scene geometry, a decal is placed over the intersecting region (clipped against the underlying collision geometry). Try not to have too large an extent for the decal collision ray, for reasons of performance.

Parameters:
start | The start of the collision ray.
end | The end of the collision ray.
size | The size of the resultant decal.
type | The index of the decal texture.

def addFogEmitter( position, density, innerRadius, outerRadius, colour, localised ):

This function adds a fog emitter to the world at the specified location, with the specified density, radii and colour.

There are two types of emitters, non-localised and localised. A non-localised fog emitter adds fog to the entire world, causing all cameras to render their views with fog of the specified density. The emitters position, innerRadius and outerRadius values are ignored.

A localised fog emitter causes a camera to add fog to a scene if it is within the outer radius of the fog emitter. The density of the fog (try numbers between 2 and 10, with 10 being denser) tapers off linearly between the specified density at the inner radius to zero at the outer radius. Note that a localised fog emitter does not actually appear in the camera as a patch of fog, if the camera is outside it. It merely applies a uniform fog to any cameras which are within it.

Fog emitters are identified by an integer id, which is returned by this function. This can be passed to the delFogEmitter function to remove that emitter.

Parameters:
position | a Vector3. This is the position for the fogEmitter. Ignored if localised is zero (false).
density | a float. This is how dense to make the fog. Try numbers between 2 and 10, with 10 being denser.
innerRadius | a float. This is the inner radius for the fog emitter. Ignored if localised is zero (false). If the camera is within this radius of the emitter, then this emitter will apply fog of the specified density.
outerRadius | a float. This is the outer radius for the fog emitter. Ignored if localised is zero (false). If the camera is between the inner radius and the outer radius then the density of the fog applied to the camera will be linearly interpolated between the specified density and zero.
colour | an integer. This is the colour of the fog to apply. It is in packed rgb format.
localised | An integer, treated as a boolean. If this is true, then the fogEmitter will be localised, otherwise it will be non-localised.

Returns:
an integer. This is the id of this fog emitter.

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 addMat( source, callback, target ):

This method adds a matrix trap to the active list. Rather than having a Player Entity trigger the trap, as in a pot (Player-Only Trap) it uses a MatrixProvider to trigger the trap. It could use the Player's matrix to perform the exact same task as a pot, however a mat has the added flexibility of being able to use any point in the world as the triggering element (be it an Entity or otherwise). If the target matrix is not provided, the MatrixProvider of the current Camera will be used. The scale of the source MatrixProvider represents the size of the mat.

When the matrix trap is triggered, it will notfiy the given callback function, defined as;

def callback( self, in, matID ):

where in will be 1 if the target MatrixProvider has entered the mat and 0 if it has left. The ID of the mat that was triggered is also provided

Parameters:
source | The centre and size of the mat, as given by a MatrixProvider (size = scale of matrix)
callback | The script function to be called when the mat is triggered (to receive in flag and mat ID)
target | The optional MatrixProvider that will trigger the mat (uses current Camera if not provided)

Returns:
integer ID of the created and active matrix trap

def addModel( pModel, spaceID ):

This function adds a model to the global model list. It allows models to be drawn and ticked without being attached to either an entity or another model. This function actually allows any PyAttachment to be added, however it is called addModel to be consistent with the Entity method addModel. That method also allows any PyAttachment to be added.

Parameters:
pModel | A PyAttachment to be added to the global models list.
spaceID | [optional] space ID. If not set, the current camera space is used.

def addPot( centre, radius, callback ):

This function adds a player-only trap to the active list of traps. This trap will trigger if the player entity moves either into or out of the sphere of specified radius and centre. When it triggers, it will call the specified callable object, with two arguments, the first of which is 0 if the player moved out of the sphere, and 1 if the player moved into the sphere. The second is the handle of the trap, which is the number returned by the addPot function. See Entity.addTrap for a trap that works on all entities.

For example:
# the callback function
def hitPot( enteredTrap, handle ):
    if enteredTrap:
        print "The player entered the sphere for trap number ", handle
    else:
        print "The player left the sphere for trap number ", handle

# Note: player.matrix is the players current position
BigWorld.addPot( BigWorld.player().matrix, 5.0, hitPot )
In this example, the hitPot function will get called whenever the player enters or leaves a stationary sphere with a radius of 5 metres (the position of the sphere is centred around where the player was when the addPot function was called).

Parameters:
centre | a MatrixProvider. This is the centre of the sphere.
radius | a float. This is the radius of the sphere to trap.
callback | a callable object. This is the function that gets called when the trap is triggered.

Returns:
an integer. The handle of the trap.

def addShadowEntity( Entity ):

Adds the given entity to the dynamic shadow manager. The manager holds onto a weak reference to the entity.

Parameters:
Entity entity to be added to the shadow manager.

def addSkyBox( a, p ):

This function registers a PyAttachment and Vector4Provider pair. The output of the provider sets various values on the sky box, in particular the alpha value controls the blend in/out amount.

The Vector4Provider is set onto the sky box's effect file using the SkyBoxController semantic.

Parameters:
a | the PyAttchment to use as a python sky box
p | the Vector4Provider to set on the sky box

def addSpaceGeometryMapping( spaceID, matrix, filepath ):

This function maps geometry into the given client space ID. It cannot be used with spaces created by the server since the server controls the geometry mappings in those spaces.

The given transform must be aligned to the chunk grid. That is, it should be a translation matrix whose position is in multiples of 100 on the X and Z axis. Any other transform will result in undefined behaviour.

Any extra space mapped in must use the same terrain system as the first, with the same settings, the behaviour of anything else is undefined.

Raises a ValueError if the space for the given spaceID is not found.

Parameters:
spaceID | The ID of the space
matrix | The transform to apply to the geometry. None may be passed in if no transform is required (the identity matrix).
filepath | The path to the directory containing the space data

Returns:
(integer) handle that is used when removing mappings using BigWorld.delSpaceGeometryMapping().

def addTextureFeed( identifier, texture ):

This adds a new TextureProvider to BigWorld, identified by a given label. This label can then be used to refer to the TextureProvider in other parts of BigWorld.

Parameters:
identifier | A string label to identify this TextureProvider
texture | A PyTextureProviderPtr that is the TextureProvider to link to this label

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 addWaterVolumeListener( dynamicSource, callback ):

Parameters:
dynamicSource | A MatrixProvider providing the listener's location.
callback | A callback fn that takes one boolean argument and one PyWaterVolume argument.

def ambientController( p ):

This function registers a vector4 provider to provide further control over the ambient lighting. It is interpreted as an (r,g,b,reserved) multiplier on the existing time-of-day ambient colour.

Parameters:
p the Vector4Provider to set

def autoDetectGraphicsSettings( ):

Automatically detect the graphics settings based on the client's system properties.

def axisDirection( axis ):

This function returns the direction the specified joystick is pointing in.

The return value indicates which direction the joystick is facing, as follows:

- 0 down and left
- 1 down
- 2 down and right
- 3 left
- 4 centred
- 5 right
- 6 up and left
- 7 up
- 8 up and right

Parameters:
axis This is one of AXIS_LX, AXIS_LY, AXIS_RX, AXIS_RY, with the first letter being L or R meaning left thumbstick or right thumbstick, the second, X or Y being the direction.

Returns:
An integer representing the direction of the specified thumbstick, as listed above.

def callback( time, function ):

Registers a callback function to be called after a certain time, but not before the next tick. The callback is executed once and is not automatically repeated, so reset the callback again if regular updates are needed. If multiple callbacks are due to be executed within a single frame, the chronological order in which they were added is maintained.

Parameters:
time | A float describing the delay in seconds before function is called. If a time of 0 is given, then it is guaranteed to be called on the next frame.
function | Function to call. This function must take 0 arguments.

Returns:
int A handle that can be used to cancel the callback.

def camera( cam ):

This function is used to get and set the camera that is used by BigWorld to render the world. It can be called with either none or one arguments. If it has no arguments, then it returns the camera currently in use. If it is called with one argument, then that argument should be a camera and it is set to be the active camera. In this case the function returns None.

Parameters:
cam a Camera object, which is set to be the current camera. If this is not specified, the current camera will be returned.

Returns:
A Camera object or None

def cameraSpaceID( spaceID ):

Parameters:
spaceID (optional) Sets the space that the camera exists in.

Returns:
spaceID The spaceID that the camera currently exists in. If the camera is not in any space then 0 is returned.

def cancelCallback( int ):

Cancels a previously registered callback.

Parameters:
int An integer handle identifying the callback to cancel.

Returns:
None.

def changeFullScreenAspectRatio( ratio ):

Changes screen aspect ratio for full screen mode.

Parameters:
ratio the desired aspect ratio: float (width/height).

def changeVideoMode( new, windowed ):

This function allows you to change between fullscreen and windowed mode. If switching to fullscreen mode, the video mode index is used to determine the new resolution. If switching to windowed mode, this parameter is ignored.

The exception to the above is if you set the modeIndex to -1, then both parameters are ignored, and the device will simply be reset and remain with its current settings.

The video mode index is reported via the listVideoModes function.

Parameters:
new | int - fullscreen video mode to use.
windowed | bool - True windowed mode is desired.

Returns:
bool - True on success. False otherwise.

def chunkTransform( chunkNMapping, spaceID ):

Parameters:
chunkNMapping | chunkNMapping is a string containing the name of the chunk whose transform is to be returned.
spaceID | spaceID is the id of the space in which the chunk resides.

Returns:
A Matrix which describes the chunk's transform.

def clearAllSpaces( keepClientOnlySpaces ):

As the name implies, clears all currently loaded spaces. If the optional Boolean parameter is True client only spaces will not be cleared. Default is False.

Parameters:
keepClientOnlySpaces If true this function will leave spaces created locally intact.

def clearDecals( ):

This function clears the current list of decals. Only the decals on the space currently being viewed by the camera will be cleared.

@note Before version 1.9, this needed to be called when changing spaces, so that decals from another space didn't draw in the current one. From 1.9 onwards, decals are stored per space and calling this function is no longer a requirement.

def clearEntitiesAndSpaces( ):

As the name implies, removes all entities (including the player) and clear all currently loaded spaces. Equivalent to calling BigWorld.resetEntityManager followed by BigWorld.clearAllSpaces.

def clearSpace( spaceID ):

This function clears out the given client space ID, including unmapping all geometry in it. Naturally there should be no entities inside the space when this is called or else they will be stranded without chunks. It cannot be used with spaces created by the server since the server controls the geometry mappings in those spaces.

Raises a ValueError if the space for the given spaceID is not found.

Parameters:
spaceID The ID of the space

def collide( spaceID, src, dst ):

This function performs a collision test along a line segment from one point to another through the collision scene. If the line intersects nothing then the function returns None. Otherwise, it returns a tuple consisting of the point the first collision occurred at, the triangle that was hit (specified by its three points, as Vector3s), and the material type of the poly that was hit (an integer between 0 and 255). This material type corresponds to the material or object Kind specified in ModelViewer (see Object->Properties and Material->Material Properties panes).

For example:
    >>> BigWorld.collide( spaceID, (0, 10, 0), (0,-10,0) )
    ((0.0000, 0.0000, 0.0000), ( (0.0000, 0.0000, 0.0000),
    (4.0000, 0.0000, 0.0000), (4.0000, 0.0000, 4.0000)), 0)
In this example the line goes from 10 units above the origin to 10 units below it. It intersects with a triangle at the origin, where the triangles three points are (0,0,0), (4,0,0) and (4,0,4). The material is of type 0.

Parameters:
spaceID | The space in which to perform the collision.
src | The point to project from.
dst | The point to project to.

Returns:
A 3-tuple of the hit point, the triangle it hit, and the material type or None if nothing was hit.

def commandLineLoginInfo( ):

This function returns the username and password that where specified on the command line as a tuple. If none were specified, None is returned.

The command line flags are --username and --password. (-u and -p can also be used).

def commitPendingGraphicsSettings( ):

This function commits any pending graphics settings. Some graphics settings, because they may block the game for up to a few minutes when coming into effect, are not committed immediately. Instead, they are flagged as pending and require commitPendingGraphicsSettings to be called to actually apply them.

def connect( server, loginParams, progressFn ):

This function initiates a connection between the client and a specified server. If the client is not already connected to a server and is able to reach the network then all entities which reside on the client are destroyed in preparation for entering the server's game. This function can be used to tell the client to run offline, or to pass username, password, and other login data to the server. The client can later be disconnected from the server by calling BigWorld.disconnect.

Parameters:
server | This is a string representation of the name of the server which the client is to attempt to connect. This can be in the form of an IP address (eg: "11.12.123.42"), a domain address (eg: "server.coolgame.company.com"), or an empty string (ie: "" ). If an empty string is passed in then the client will run in offline mode. If a connection is successfully established then subsequent calls to BigWorld.server will return this value.
loginParams | This is a Python object that may contain members which provide login data. If a member is not present in this object then a default value is used instead. These members are:
progressFn | This is a Python function which is called by BigWorld to report on the status of the connection. This function must take three arguments, where the first is interpreted as an integer indicating where in the connection process the report indicated, the second is interpreted as a string indicating the status at that point and the third is a string message that the server may have sent.

Returns:
None

def connectedEntity( ):

This method returns the entity that this application is connected to. The connected entity is the server entity that is responsible for collecting and sending data to this client application. It is also the only client entity that has an Entity.base property.

def consumerBuild( ):

Check if this is a consumer build.

Returns:
true if this is a consumer build.

def controlEntity( entity, beControlled ):

Sets whether the movement of an entity should be controlled locally by physics.

When shouldBeControlled is set to True, the entity's physics attribute becomes accessible. Each time this is called with its shouldBeControlled attribute as True, the entity's physics attribute is set to None. As this is also made accessible, it can then be set to a different value.

When shouldBeControlled is set to False, attempts to access the entity's physics object raise an AttributeError.

This function only works for client-side entities. The server decides who controls server-side entities. A TypeError is raised if the given entity is not a client-side entity.

Parameters:
entity | The entity to control/uncontrol.
beControlled | Whether the entity should be controlled.

def createEntity( className, spaceID, vehicleID, position, direction, state ):

Creates a new entity on the client and places it in the world. The resulting entity will have no base or cell part.

Parameters:
className | The string name of the entity to instantiate.
spaceID | The id of the space in which to place the entity.
vehicleID | The id of the vehicle on which to place the entity (0 for no vehicle).
position | A Vector3 containing the position at which the new entity is to be spawned.
direction | A Vector3 containing the initial orientation of the new entity (roll, pitch, yaw).
state | A dictionary describing the initial states of the entity's properties (as described in the entity's .def file). A property will take on it's default value if it is not listed here.

Returns:
The ID of the new entity, as an integer.

def createSpace( ):

The space is held in a collection of client spaces for safe keeping, so that it is not prematurely disposed.

Returns:
spaceID The ID of the client-only space that has been created

def createTranslationOverrideAnim( baseAnim, translationReferenceAnim, noOverrideChannels, outputAnim ):

This function is a tool which can be used to alter skeletal animations so that they can be used with models which have skeletons of different proportions. This is achieved by creating a new animation which is based on a given animation, but replaces the translation component for each node with that of the beginning of the same node in a reference animation. As the translation should not change in a skeletal system (bones do not change size or shape), this effectively re-fits the animation on to a differently proportioned model. This operates by creating a new animation file, and is not intended for in-game use.

Parameters:
baseAnim | A string containing the name (including path) of the animation file on which the new file is to be based.
translationReferenceAnim | A string containing the name (including path) of the animation file whose first frame contains the translation which will be used for the new animation. This should have the same proportions as are desired for the new animation.
noOverrideChannels | A list of strings containing the names of the nodes that shouldn't have their translation overridden. These nodes will not be scaled to the proportions provided by translationReferenceAnim in the new animation.
outputAnim | A string containing the name (including path) of the animation file to which the new animation will be saved.

Returns:
None

def darkenConsoleBackground( enable ):

Sets the dark-console-background flag. When true, a dark background will be rendered underneat the current active console (if any), making the console text easier to read. If false, console text will be rendered directly over the current contents of the color buffer. Some console may inhibit the renderting of the dark background (e.g. the histogram console).

Parameters:
enable (optional) new value to be assigned to the dark-console-background flag.

Returns:
the current value (before the call is processed).

def dcursor( ):

This function returns the direction cursor which is used to control which way the user is looking with the mouse.

Returns:
the current direction cursor.

def debugAQ( ):

This function controls the Action Queue debugging graph. It takes one argument which is either a PyModel, or None. None switches the debugging graph off. If the argument is a model, then a graph is displayed on the screen. It is a line graph, which shows what actions are currently playing on that model, and what blend weight each action has.

Each line represents one currently playing action. It will have an arbitrary colour assigned to it, and have the Actions name printed below it in the same colour. The height of the line represents what percentage of the total blended Actions this Action makes up.

If one model is currently being graphed, and this function is called again with another model, the graph for the first model stops, and the new model takes over.

def debugModel( ):

This function is used to turn on/off the drawing of the models * skeleton. This can also be done through the watcher located in * Render/Draw Skeletons

def decalTextureIndex( textureName ):

This function returns the texture index that is needed to pass into addDecal. It takes the name of the texture, and returns the index, or -1 if none was found.

Parameters:
textureName The name of the texture to look up.

Returns:
The index of the texture

def delAlwaysUpdateModel( pModel ):

This function removes a model from the update list.

Parameters:
pModel the model to remove from the update list

def delFogEmitter( id ):

This function removes a fog emitter which was previously created by addFogEmitter.

Parameters:
id An integer. The id of the fog emitter to delete. This is returned by addFogEmitter when a fog emitter is created.

def delMat( matID ):

Removes the mat from active duty as described by the given mat handle.

Parameters:
matID The integer ID of the mat to remove. Corresponds to the handle returned by BigWorld.addMat()

def delModel( pModel ):

This function deletes a model from the global model list.

This function actually works with any PyAttachment, however it is called delModel to be consistent with the Entity method delModel. That method also allows any PyAttachment to be deleted.

Parameters:
pModel A PyAttachment to be added to the global models list.

def delPot( handle ):

This method deletes a trap from the active list. This stops it responding to the player entity entering or leaving its sphere.

The trap is specified by its handle, which was returned by addPot when the trap was created.

Parameters:
handle an integer. The handle of the trap to remove.

def delShadowEntity( Entity ):

Removes the given entity from the dynamic shadow manager. Does nothing if the entity was not previously added.

Parameters:
Entity entity to be removed from the shadow manager.

def delSkyBox( m, p ):

This function registers a PyAttachment and Vector4Provider pair. The output of the provider sets various values on the sky box, in particular the alpha value controls the blend in/out amount.

The Vector4Provider is set onto the sky box's effect file using the SkyBoxController semantic.

Parameters:
m | the PyAttachment to use as a python sky box
p | the Vector4Provider to set on the sky box

def delSpaceGeometryMapping( spaceID, handle ):

This function unmaps geometry from the given client space ID.

It cannot be used with spaces created by the server since the server controls the geometry mappings in those spaces.

Raises a ValueError if the space for the given spaceID is not found, or if the handle does not refer to a mapped space geometry.

Parameters:
spaceID | The ID of the space
handle | An integer handle to the space that was returned when created

def delStaticSkyBoxes( ):

This function removes the static sky boxes added via Worldeditor. This is usually used when you want script control and dynamic sky boxes, in which case you'd use this method as well as addSkyBox / delSkyBox.

def delTextureFeed( identifier ):

This function removes a previously added TextureProvider. The TextureProvider can still be used in script, but cannot be referred to by its previously associated label anymore.

Parameters:
identifier A string label to identity the TextureProvider to remove

def delWatcher( path ):

Parameters:
path the path of the watcher to delete.

def delWaterVolumeListener( id ):

Parameters:
id id formerly returned by addWaterVolumeListener

def destroyEntity( id ):

Destroys an exiting client-side entity.

Parameters:
id The id of the entity to destroy.

def disconnect( ):

If the client is connected to a server then this will terminate the connection. Otherwise it does nothing. This function does not delete any entities, however it does stop the flow of data regarding entity status to and from the server.

The client can be connected to a server via the BigWorld.connect function.

Returns:
None

def dumpMemCounters( ):

This debugging function prints out the current value of memory watchers found in "Memory/" watcher directory.

def dumpRefs( ):

Dumps references to each object visible from the entity tree. This does not include all objects, and may not include all references.

def entity( id, lookInCache ):

Returns the entity with the given id, or None if not found. This function can search all entities known to the client, or only entities which are not cached. An entity only becomes cached if in an online game the server indicates to the client that the entity has left the player's area of interest.

Parameters:
id | An integer representing the id of the entity to return.
lookInCache | An optional boolean which instructs the function to search for the entity amongst the entities which are cached. Otherwise, this function will only search amongst non-chached entities. This argument defaults to false.

Returns:
The entity corresponding to the id given, or None if no such entity is found.

def fetchModel( *modelPath, onLoadCompleted ):

Deprecated: It is recommended to use BigWorld.loadResourceListBG in the following manner instead:
# load list of models in background
myList = [ "a.model", "b.model" ]
BigWorld.loadResourceListBG( myList, self.callbackFn )
def callbackFn( self, resourceRefs ):
    if resourceRefs.failedIDs:
        ERROR_MSG( "Failed to load %s" % ( resourceRefs.failedIDs, ) )
    else:
        # construct supermodel
        myModel = BigWorld.Model( *resourceRefs.keys() )

fetchModel is a function that creates and returns a new PyModel object through the callback function provided (None if there are problems loading any of the requested resources). PyModels are renderable objects which can be moved around the world, animated, dyed (have materials programatically assigned) and contain points to which objects can be attached.

The parameters for the function are one or more model resources. Each of these individual models is loaded, and combined into a "supermodel".

This function is similar to the BigWorld.Model function. However, it schedules the model loading as a background task so that main game script execution would not be affected. After model loading is completed, callback function will be triggered with the valid PyModel.

For example, to load a body and a head model into one supermodel:

BigWorld.fetchModel( "models/body.model", "models/head.model", onLoadCompleted )

Parameters:
*modelPath | String argument(s) for the model.
onLoadCompleted | The function to be called when the model resource loading is completed. An valid PyModel will be returned. When the model loading fails. A None is passed back.

Returns:
No return values.

def findChunkFromPoint( point, spaceID ):

Parameters:
point | point is a Vector3 describing the location to search for a chunk, in world space.
spaceID | spaceID is the id of the space to search in.

Returns:
The name of the chunk found, as a string.

def findDropPoint( spaceID, vector3 ):

Finds the point directly beneath the start point that collides with the collision scene and terrain (if present in that location)

Parameters:
spaceID | The ID of the space you want to do the raycast in
vector3 | Start point for the collision test

Returns:
A pair of the drop point, and the triangle it hit, or None if nothing was hit.

def flashBangAnimation( p ):

This function adds a vector4 provider for the flash bang animation. The output of the flashbanganimation is modulated with the previous frame of the game to create a saturated frame buffer. There can be any number of flash bang animations running at the same time.

Parameters:
p the Vector4Provider to add

def floraReset( ):

This method will re-initialise the flora vertex buffer, i.e. repopulating all flora objects in the vicinity of the camera. This needs to be called if for example you have changed the height map and need the flora to be re-seeded onto the new terrain mesh.

def floraVBSize( Number ):

This method sets the vertex buffer size for the Flora.

Parameters:
Number of bytes as an integer.

def flyThroughRunning( ):

This function returns true if a fly through is currently running

Returns:
True if a fly through is currently running

def fogController( p ):

This function registers a vector4 provider to provide further control over the fogging. (x,y,z) is a multiplier on the existing fog colour. (w) is a multiplier on the fog density.

Parameters:
p the Vector4Provider to set

def getFullScreenAspectRatio( ):

This function returns an estimate of the amount of memory the application is currently using.

def getGraphicsSetting( label ):

Gets graphics setting option.

Raises a ValueError if the given label does not name a graphics setting, if the option index is out of range, or if the option is not supported.

Parameters:
label string - label of setting to be retrieved.

Returns:
optionIndex int - index of option.

def getMaterialKinds( ):

This method returns a list of id and section tuples of the material kind list, in the order in which they appear in the XML file

Returns:
The list of (id, DataSection) tuples of material kinds

def getTextureFeed( identifier ):

This function returns a previously added TextureProvider.

Parameters:
identifier A string label to identity the TextureProvider to return

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

Returns list of registered graphics settings

Returns:
list of 4-tuples in the form (label : string, index to active option in options list: int, options : list, desc : string). Each option entry is a 3-tuple in the form (option label : string, support flag : boolean, desc : string).

def graphicsSettingsNeedRestart( ):

This function returns true if any recent graphics setting change requires the client to be restarted to take effect. If that's the case, restartGame can be used to restart the client. The need restart flag is reset when this method is called.

def hasPendingGraphicsSettings( ):

This function returns true if there are any pending graphics settings. Some graphics settings, because they may block the game for up to a few minutes when coming into effect, are not committed immediately. Instead, they are flagged as pending and require commitPendingGraphicsSettings to be called to actually apply them.

def isKeyDown( key ):

The 'isKeyDown' method allows the script to check if a particular key has been pressed and is currently still down. The term key is used here to refer to any control with an up/down status; it can refer to the keys of a keyboard, the buttons of a mouse or even that of a joystick. The complete list of keys recognised by the client can be found in the Keys module, defined in Keys.py.

The return value is zero if the key is not being held down, and a non-zero value is it is being held down.

Parameters:
key An integer value indexing the key of interest.

Returns:
True (1) if the key is down, false (0) otherwise.

def isTripleBuffered( ):

Returns current display's triple buffering status.

Returns:
bool - True if triple buffering is on. False if it is off.

def isVideoVSync( ):

Returns current display's vertical sync status.

Returns:
bool - True if vertical sync is on. False if it is off.

def isVideoWindowed( ):

Queries current video windowed state.

Returns:
bool True is video is windowed. False if fullscreen.

def keyToString( key ):

The 'keyToString' method converts from a key index to its corresponding string name. The string names returned by the integer index can be found in the keys.py file. If the index supplied is out of bounds, an empty string will be returned.

Parameters:
key An integer representing a key index value.

Returns:
A string containing the name of the key supplied.

def listVideoModes( ):

Lists video modes available on current display device.

Returns:
list of 5-tuples (int, int, int, int, string). (mode index, width, height, BPP, description)

def loadResourceListBG( resourceList, callbackFn, priority ):

This function loads a list of resources in the background thread and is designed to be use as an extension to the Entity prerequisites mechanism, for times when you don't know ahead if time what resources an entity requires, or if the entity changes in such a way that requires new resources to load.

The function takes a tuple of resource IDs, a callback function and an optional priority number as arguments. The resource list is loaded in the background thread and then the callback function is called with a new ResourceRefs instance as the argument. You can use the resources immediately, or you can hold onto the ResourceRefs object; the loaded objects are tied to its lifetime. Nothing is returned from this function call immediately. The priority number defines which resources are need to be loaded before others where a higher number indicates a higher priority.

For example:
# In the example, a new item is obtained; the item is one of many available
# and thus there is no way to know before-hand what resources will be
# required.  When the item is obtained, a ResourceRefs object is
# constructed; it loads the resources in the background, and calls back the
# function when done.  While the resourceRefs object is in existence, it
# will hold onto the resources making sure they aren't unloaded.  In this
# case a model is immediately constructed and a gui texture is immediately
# set - thus it is unnecessary to hold onto the extra resource refs at all.
# There is an alternative example not being called, onLoad2, which does not
# use the resources immediately, it uses the ResourceRefs object to hold
# onto them until needed later.

self.obtainItem( "maps/items/icon_item4.tga","models/items/item4.model" )

def obtainItem( self, iconName, modelName ):
    resName = (iconName, modelName)
    BigWorld.loadResourceListBG(resources, partial(self.onLoad, resName))

# In this case we will construct the objects we needed, so we don't
# have to keep a hold of the resource refs object.  Note we check
# isDestroyed, as in this example self is an entity, and the entity
# may have left the world during our resource loading.
def onLoad( self, resName, resourceRefs ):
    assert isinstance( self, BigWorld.Entity )
    if self.inWorld:
        failed = resourceRefs.failedIDs
        guiName = resourceRefs[ resName[0] ]
        modelName = resourceRefs[ resName[1] ]

        #now you can construct models or set gui textures or whatever
        #without causing resource loads in the main thread.

        if guiName not in failed:
            self.itemGUI.textureName = guiName
        else:
            ERROR_MSG( "Could not load gui texture %s" % (guiName,) )

        if modelName not in failed:
            self.newItemModel = resourceRefs[modelName]
        else:
            ERROR_MSG( "Could not load model %s" % (modelName,) )

# In this case we won't use the resources straight away, so
# we keep a hold of the resource refs until we need them.
def onLoad2( self, resourceRefs ):
    if not self.inWorld:
        self.resourcesHolder = resourceRefs

def discardItem( self ):
    #release the ResourceRefs object, freeing the references
    #to all associated resources.  If nobody else is using these
    #resources they will be freed.
    del self.resourcesHolder

Parameters:
resourceList | a list of resources to load. This is similar to the list returned by entity prerequisites.
callbackFn | a function to be called back when the load of all resources is complete. The callback function takes no arguments.
priority | [optional] integer to indicate the priority number (defaults to 64).

Returns:
None

def localeInfo( ):

Returns a tuple containing information about the currently activated input. locale. The locale changes when the user selects a new language from the language bar in the operating system. Use the BWPersonality.handleInputLangChange event handler to determine when this happens.

The tuple returned is of the form:

(country, abbreviatedCountry, language, abbreviatedLanguage)

Returns:
A 4-tuple of unicode strings that contain containing locale information..

def memUsed( ):

This function returns an estimate of the amount of memory the application is currently using.

def models( Any ):

This function sets or gets the global model list.

Parameters:
Any sequence of PyAttachments, or None.

Returns:
The global models list, if no arguments were passed in, or None.

def noPartialLocks( ):

This function is deprecated. Use BigWorld.target.noPartial attribute instead.

def playMovie( ):

Placeholder for deprecated functionality.

def player( entity ):

This sets the player entity, or returns the current player entity if the entity argument is not provided. The BigWorld engine assumes that there is no more than one player entity at any time. Changing whether an entity is the current player entity involves changing whether it is an instance of its normal class, or its player class. This is a class whose name equals the entity's current class name, prefixed with the word "Player". As an example, the player class for Biped would be PlayerBiped.

The following occurs if a new entity is specified:

The onBecomeNonPlayer function is called on the old player entity.

The old player entity becomes an instance of its original class, rather than its player class.

The reference to the current player entity is set to None.

A player class for the new player entity is sought out. If the player class for the new player entity is found, then the entity becomes an instance of this class. Otherwise, the function immediately returns None.

The onBecomePlayer function is called on the new player entity.

The reference to the current player entity is set the new player entity.

Parameters:
entity An optional entity. If supplied, this entity becomes the current player.

Returns:
If the entity argument is supplied then this is None, otherwise it's the current player entity.

def playerDead( isDead ):

This method sets whether or not the player is dead. This information is used by the snow system to stop snow falling if the player is dead.

Parameters:
isDead an integer as boolean. This is 0 if the player is alive, otherwise it is non-zero.

def probe( server, progressFn ):

The function probe is used to determine the status of a particular server. This has not yet been implemented.

Parameters:
server | String. Specifies the name or address of server.
progressFn | Callback Function (python function object, or an instance of a python class that implements the __call__ interface). The function to be called when information on the status for a particular server is available.

def projection( ):

This function retrieves the ProjectionAccess object for the current camera, allowing access to such things as the fov and the clip planes.

Returns:
ProjectionAccess

def quit( ):

Ask the application to quit.

def releaseSpace( spaceID ):

This function releases the given client space ID.

Note that the space will not necessarily be immediately deleted - that must wait until it is no longer referenced (including by chunk dir mappings).

Raises a ValueError if the space for the given spaceID is not found.

Parameters:
spaceID The ID of the space to release.

def reloadChunks( ):

Unload all chunks, purge all ".chunk" data sections and begin reloading the space.

def reloadTextures( ):

This function recompresses all textures to their .dds equivalents, without restarting the game. The procedures may take a while, depending on how many textures are currently loaded by the engine. This is especially useful if you have updated the texture_detail_levels.xml file, for example to change normal maps from 32 bit to 16 bits per pixel.

def removeFlashBangAnimation( p ):

This function removes a Vector4Provider from the list of flash bang animations

Parameters:
p the Vector4Provider to remove

def resetEntityManager( keepPlayerAround, keepClientOnly ):

Resets the entity manager's state. After disconnecting, the entity will retain all of it's state. Allowing the world to still be explored offline, even with entity no longer being updated by the server. Calling this function resets the entity manager, removing all entities from the space.

Parameters:
keepPlayerAround | (type bool) True if player should be spared. False if player should also be removed together with all entities.
keepClientOnly | (type bool) True to clear all server entities and keep client only entities.

def resizeWindow( width, height ):

Sets the size of the application window (client area) when running in windowed mode. Does nothing when running in fullscreen mode.

Parameters:
width | The desired width of the window's client area.
height | The desired height of the window's client area.

def restartGame( ):

This function restarts the game. It can be used to restart the game after certain graphics options have been changed that require a restart.

def rollBackPendingGraphicsSettings( ):

This function rolls back any pending graphics settings.

def saveAllocationsToFile( filename ):

Save all recorded memory allocations into the text file for further analysis File format description:

number_of_callstack_hashes 64bit hash;callstack 64bit hash;callstack .... 64bit hash;callstack slotId;64bit callstack hash;allocation size ... slotId;64bit callstack hash;allocation size

Use condense_mem_allocs.py script to convert saved file into the following format: slot id;allocationSize;number of allocations;callstack ...

Parameters:
filename The name of file to save data

def saveFontCacheMap( identifier ):

This saves the current cache texture map for the given font out to disk as a .dds file with the same name as the font file.

Additionally it saves out a .generated file of the same name, which is a binary file with the dimensions and positions of each glyph in that map (note that the font will continue to operate dynamically until it is next loaded).

Finally it saves another DDS file that has colour-coded blocks representing glyph dimensions, the effect margin and texture margin to aid artists with generating their own font texture maps.

Please see the client programming guide for more information.

Parameters:
identifier A string label to identify the font

def savePreferences( ):

Saves the current preferences (video, graphics and script) into a XML file. The name of the file to the writen is defined in the field in engine_config.xml.

Returns:
bool True on success. False on error.

def screenHeight( ):

Returns the height of the current game window.

Returns:
float

def screenShot( format, name ):

This method takes a screenshot and writes the image to disk. The output folder is configured by the 'screenShot/path' section in engine_config.xml.

Parameters:
format | Optional string. The format of the screenshot to be outputed, can be on of "bmp", "jpg", "tga", "png" or "dds". The default comes from resources.xml.
name | Optional string. This is the root name of the screenshot to generate. A unique number will be postpended to this string. The default comes from resources.xml.

def screenSize( ):

Returns the width and height of the current game window as a tuple.

Returns:
(float, float)

def screenWidth( ):

Returns the width of the current game window.

Returns:
float

def server( ):

This function returns the name of the server to which the client is currently connected. The name is identical to the string which would have been passed in as the first argument to the BigWorld.connect function to establish the connection. Usually this is a string representation of an IP address. If the client is running in offline mode, then this is an empty string. Otherwise, if the client is neither connected to a server nor running in offline mode, then this returns None.

Returns:
The name of the server to which the client is connected, an empty string if the client is running in offline mode, or None if the client is not connected.

def serverTime( ):

This function returns the server time. This is the time that all entities are at, as far as the server itself is concerned. This is different from the value returned by the BigWorld.time() function, which is the on the client.

Returns:
a float. This is the current time on the server.

def setCursor( cursor ):

Sets the active cursor. The active cursor will get all mouse, keyboard and axis events forwarded to it. Only one cursor can be active at a time.

Parameters:
cursor the new active cursor, or None to simply deactivate the current one.

def setGraphicsSetting( label, optionIndex ):

Sets graphics setting option.

Raises a ValueError if the given label does not name a graphics setting, if the option index is out of range, or if the option is not supported.

Parameters:
label | string - label of setting to be adjusted.
optionIndex | int - index of option to set.

def setTripleBuffering( doTripleBuffering ):

Turns triple buffering on/off.

Parameters:
doTripleBuffering bool - True to turn triple buffering on. False to turn if off.

def setVideoVSync( doVSync ):

Turns vertical sync on/off.

Parameters:
doVSync bool - True to turn vertical sync on. False to turn if off.

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 sinkKeyEvents( key, [optional] ):

Adds a global event handler for the given key. The handler will exist up to and including the next "key up" event for the given key. This is useful if you process the key down event and want to stop all subsequent key events for a particular key from occuring. For example, it is useful when the GUI state is changed in the GUI component's handleKeyDown and you don't want the new GUI state to receive the subsequent char or key up events (i.e. the user would have to fully let go of the key and press it again before anything receives more events from that key).

The handler should be a class instance with methods "handleKeyEvent" and "handleCharEvent". The handler methods should return True to override the event and stop it from being passed to any other handleres, or False to allow the event to continue as per normal.

If no event handler is specified, then it will sink all events up to and including the next key-up event.

When the

Parameters:
key | The key code to be routed to the sink.
[optional] | sink The class instance that will process the key events. If not specified, it will sink all events for the given key up to and including the next key up.

def spaceLoadStatus( (optional) ):

This function queries the chunk loader to see how much of the current camera * space has been loaded. It queries the chunk loader to see the distance * to the currently loading chunk ( the chunk loader loads the closest chunks * first ). A percentage is returned so that scripts can use the information * to create for example a teleportation progress bar.

Parameters:
(optional) distance The distance to check for. By default this is * set to the current far plane.

Returns:
float Rough percentage of the loading status

def spaceTimeOfDay( spaceID, time ):

Gets and sets the time of day in 24 hour time, as used by the environment system.

Parameters:
spaceID | The spaceID of the space to set/get the time.
time | Optional string. If provided, the time of day is set to this. This can be in the format "hour:minute" (eg "01:00", "1:00", "1:0", "1:" ), or as a string representation of a float (eg "1", "1.0"). Note that an incorrectly formatted string will not throw an exception, nor will it change the time of day.

Returns:
A string representing the time of day at the end of the function call in the form "hh:mm" (eg "01:00" ).

def stime( ):

def stringToKey( string ):

The 'stringToKey' method converts from the name of a key to its corresponding key index as used by the 'isKeyDown' method. The string names for a key can be found in the keys.py file. If the name supplied is not on the list defined, the value returned is zero, indicating an error. This method has a inverse method, 'keyToString' which does the exact opposite.

Parameters:
string A string argument containing the name of the key.

Returns:
An integer value for the key with the supplied name.

def sunlightController( p ):

This function registers a vector4 provider to provide further control over the sunlight. It is interpreted as an (r,g,b,reserved) multiplier on the existing time-of-day sunlight colour.

Parameters:
p the Vector4Provider to set

def target( ):

BigWorld.target is actually an attribute that is callable. See PyTarget.__call__ for more information.

def time( ):

This function returns the client time. This is the time that the player's entity is currently ticking at. Other entities are further back in time, the further they are from the player entity.

Returns:
a float. The time on the client.

def timeOfDay( time ):

Gets and sets the time of day in 24 hour time, as used by the environment system. If the camera is not currently in a space, then this function will not do anything, and will return an empty string.

This can also be changed manually via the following key combinations:

DEBUG + "[": Rewind time of day by 10 minutes

DEBUG + Shift + "[": Rewind time of day by 1 hour

DEBUG + "]": Advance time of day by 10 minutes

DEBUG + Shift + "]": Advance time of day by 1 hour

Parameters:
time Optional string. If provided, the time of day is set to this. This can be in the format "hour:minute" (eg "01:00", "1:00", "1:0", "1:" ), or as a string representation of a float (eg "1", "1.0"). Note that an incorrectly formatted string will not throw an exception, nor will it change the time of day.

Returns:
A string representing the time of day at the end of the function call in the form "hh:mm" (eg "01:00" ). Returns an empty string if the camera is not currently in a space.

def totalPhysicalMemory( ):

Return the amount of physical RAM in the machine. This can help when a game automatically chooses graphics settings for a user. There are a few graphics settings that affect the amount of system RAM used. Two examples are: - texture detail (managed textures are used, and they are mirrored in RAM) - the far plane distance directly affects how many chunks are loaded and thus how many unique assets will be loaded at any time.

Returns:
Integer The amount of physical RAM, in bytes.

def totalVirtualMemory( ):

Return the amount of virtual memory, a.k.a the amount of address space available to the process. Used in conjunction with the totalPhysicalMemory function, you should be able to determine whether or not the user running a 64 bit client and therefore whether or not your game has access to the full amount of physical RAM installed.

This can help a game automatically choose graphics settings for a user. There are a few graphics settings that affect the amount of system RAM used. Two examples are: - texture detail (managed textures are used, and they are mirrored in RAM) - the far plane distance directly affects how many chunks are loaded and thus how many unique assets will be loaded at any time.

Returns:
Integer The amount of virtual RAM, in bytes.

def videoModeIndex( ):

Retrieves index of current video mode.

Returns:
int Index of current video mode or zero if render context has not yet been initialised.

def weather( spaceID ):

This function returns the unique Weather object which is used to control the weather on the client.

Parameters:
spaceID [optional] The id of the space to retrieve the weather object from, or the current camera space if no argument is passed in.

Returns:
the unique Weather object.

def weatherController( p ):

This function registers a vector4 provider to provide further control over the weather. It is interpreted as (extraRain, reserved, reserved, reserved) The output of the provider sets various values on the weather.

Parameters:
p the Vector4Provider to set

def windowSize( ):

Returns size of application window when running in windowed mode. This is different to the screen resolution when running in fullscreen mode (use listVideoModes and videoModeIndex functions to get the screen resolution in fullscreen mode).

This function is deprecated. Use screenSize, instead.

Returns:
2-tuple of floats (width, height)

def worldDrawEnabled( newValue ):

Sets and gets the value of a flag used to control if the world is drawn. Note: the value of this flag will also be used to turn the watching of files being loaded in the main thread on or off. That is, if enabled, warnings will be issued into the debug output whenever a file is accessed from the main thread.

Parameters:
newValue (optional) True enables the drawing of the world, False disables.

Returns:
Bool If the no parameters are passed the current value of the flag is returned.

Attribute Documentation

allEntities

This lists all of the entities instantiated on the client.

Type:
Read-Only PyEntities.

cachedEntities

This lists all of the entities currently cached. Entities are cached when they are known by the client but exist outside the player's area of interest. This only occurs for entities which are provided by a server.

This variable is not supported in client-only licenses of BigWorld.

Type:
Read-Only PyEntities.

cameraSpeed

Stores the CameraSpeed object which is used to describe how a camera can move.

Type:
CameraSpeed.

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

This lists all of the entities currently in the world, which includes all entities that have not been cached. Entities are cached when they are known by the client but exist outside the player's area of interest. This only occurs for entities which are provided by a server.

Type:
Read-Only PyEntities.

isEmbedded

This is a boolean that represents if the client is running embedded

platform

This is a string that represents which platform the client is running on, for example, "windows".

serverDiscovery

This is an instance of the ServerDiscovery class. It can be used to locate BigWorld servers on a local area network and obtain information regarding their current status. This is the only instance of ServerDiscovery which can be accessed via Python script.

Type:
ServerDiscovery

target

A PyTarget instance created automatically by the BigWorld engine. Most targeting operations can be handled through this object.

Type:
PyTarget.

targeting

Stores a Targeting object, which is used to configure the BigWorld Targeting System.


FMOD - BigWorld client Documentation

FMOD Module Reference

The FMOD module provides access to the FMOD Ex integration, if it is enabled.

Class List

EventCategory
EventGroup
EventProject
EventReverb
MusicSystem
Sound
SoundParameter

Member Functions

def getMusicSystem( ):
def getSound( path ):
def getSoundBanks( ):
def loadEventProject( filename ):
def loadSoundBankIntoMemory( soundbank ):
def loadSoundGroup( path ):
def playSound( path ):
def reloadEventProject( name ):
def setDefaultSoundProject( name ):
def setMasterVolume( vol ):
def unloadEventProject( name ):
def unloadSoundBankFromMemory( soundbank ):
def unloadSoundGroup( path ):

Member Function Documentation

def getMusicSystem( ):

Returns the music system object associated with the FMOD EventSystem.

def getSound( path ):

Returns a sound handle.

Parameters:
path The path to the sound event you want to trigger (see FMOD.playSound() for syntax)

Returns:
The PySound for the sound event.

def getSoundBanks( ):

Returns a list of sound banks that are referenced by FMod.

Returns:
list of sound bank names

def loadEventProject( filename ):

Load the specified event project file. Note that the argument to this function is the name of the project, *not* its filename. So basically you are passing in the filename minus the .fev extension.

Parameters:
filename The name of the soundbank.

def loadSoundBankIntoMemory( soundbank ):

Loads a sound bank into memory.

Parameters:
soundbank name of soundbank

def loadSoundGroup( path ):

Loads the wave data for the specified event group (and all descendant groups) into memory, so that the sounds will play instantly when triggered.

If called with just a project name as the argument, all sound groups in that project will be loaded.

Parameters:
path The path to the event group

def playSound( path ):

Plays a sound.

The semantics for sound naming are similar to filesystem paths, in that there is support for both 'relative' and 'absolute' paths. If a path is passed without a leading '/', the sound is considered to be part of the default project (see FMOD.setDefaultProject), for example 'guns/fire' would refer to the 'guns/fire' event from the default project. If your game uses only a single FMOD project, you should refer to events using relative paths, as it is (slightly) more efficient than the absolute method.

If your game uses multiple projects and you want to refer to a sample in a project other than the default, you can say '/project2/guns/fire' instead.

Parameters:
path The path to the sound event you want to trigger.

Returns:
The PySound for the sound event.

def reloadEventProject( name ):

Reload the named event project. Use this if you have created or deleted events in a project using the FMOD Designer tool and you want to get the changes in your app. If you are just tweaking properties on existing sound events you can audition them using the network audition mode of the FMOD Designer tool without needing to call this function.

Parameters:
name The name of the project

def setDefaultSoundProject( name ):

Sets the default sound project that relatively-named events will be read from.

See FMOD.playSound() for more information about sound event naming conventions.

See the 'soundMgr' section of engine_config.xml for how to load sound projects into your game.

Parameters:
name The name of the project to be set as the default.

def setMasterVolume( vol ):

Sets the master volume applied to all sounds.

Parameters:
vol A float in the range [0.0, 1.0].

def unloadEventProject( name ):

Unload the named event project.

Parameters:
name The name of the project

def unloadSoundBankFromMemory( soundbank ):

Unloads a sound bank from memory.

Parameters:
soundbank name of soundbank

def unloadSoundGroup( path ):

Unloads the wave data for the specified event group (and all descendant groups) from memory. Note that sounds can still be played from this group later on, however the first playback for each event will block whilst the wave data is loaded from disk.

Parameters:
path The path to the event group


GUI - BigWorld client Documentation

GUI Module Reference

The GUI module contains all the functions which are used to create GUI components and shaders, to display them on the screen, and to handle input events.

Class List

AlphaGUIShader
BoundingBoxGUIComponent
ClipGUIShader
ColourGUIShader
ConsoleGUIComponent
FlashGUIComponent
FlashTextGUIComponent
FrameGUIComponent
FrameGUIComponent2
GUIShader
GoboComponent
GraphGUIComponent
GuiAttachment
MatrixGUIShader
MeshGUIAdaptor
Minimap
MouseCursor
SimpleGUIComponent
TextGUIComponent
WindowGUIComponent
WorldToClipMP

Member Functions

def AlphaShader( ):
def Attachment( ):
def BoundingBox( textureName ):
def ClipShader( ):
def ColourShader( ):
def Console( ):
def Flash( movie ):
def FlashText( text ):
def Frame( backgroundTextureName, cornerTextureName, edgeTextureName, tiledWidth, tiledHeight ):
def Frame2( ):
def Gobo( textureName ):
def Graph( ):
def Latency( ):
def MatrixShader( target ):
def MeshAdaptor( ):
def Minimap( ):
def Simple( textureName ):
def Text( text ):
def Window( ):
def WorldToClipMP( ):
def addRoot( component ):
def delRoot( component ):
def draw( ):
def handleAxisEvent( event ):
def handleAxisEvent( event ):
def handleKeyEvent( event ):
def handleMouseEvent( event ):
def load( section ):
def mcursor( ):
def printRoots( ):
def reSort( ):
def roots( ):
def screenResolution( ):
def setDragDistance( distance ):
def setResolutionOverride( resolution ):
def update( dTime ):

Member Function Documentation

def AlphaShader( ):

This function creates a new AlphaGUIShader. An AlphaGUIShader is used to control the alpha on a GUI component and its children.

Returns:
a newly created AlphaGUIShader.

def Attachment( ):

Creates and returns a new GUIAttachment, which is used to display gui elements in the 3D scene.

Returns:
The new GUIAttachment object

def BoundingBox( textureName ):

Parameters:
textureName The full resource path of the texture to be used.

Returns:
The newly created BoundingBoxGUIComponent

def ClipShader( ):

This function creates a new ClipGUIShader. This is used to clip the specified portion off one side of the component.

Returns:
a new ClipGUIShader.

def ColourShader( ):

This function creates a new ColourGUIShader. This is used to apply colours to gui components.

Returns:
a new ColourGUIShader.

def Console( ):

Creates and returns a new ConsoleGUIComponent, which displays an editable console on the screen.

Returns:
The new ConsoleGUIComponent.

def Flash( movie ):

This function creates a new FlashGUIComponent which allows a flash movie to be inserted into the GUI hierarchy. If this component has an attached script, then the script must take responsibility for passing mouse and key events into the PyMovieView object.

Parameters:
movie A PyMovieView object containing the movie to associate with the component.

Returns:
the newly created component.

def FlashText( text ):

This function creates a new FlashTextGUIComponent. This component renders a line of text.

Parameters:
text A string containing the line of text to be rendered. This can be changed once the component is created.

Returns:
the newly created component.

def Frame( backgroundTextureName, cornerTextureName, edgeTextureName, tiledWidth, tiledHeight ):

This function creates a new FrameGUIComponent. This is basically a tiled simpleGUIComponent with a frame around it. The frame is specified by and edge texture and a corner texture. The size of the frame is specified by the tiledWidth and tiledHeight, which are also used to specify the tiling of the background.

Parameters:
backgroundTextureName | The filename of the background texture. This needs to be a valid texture file.
cornerTextureName | The filename of the corner texture. This needs to be a valid texture file.
edgeTextureName | The filename of the edge texture. This needs to be a valid texture file.
tiledWidth | The width to make the frame, and to tile the background at.
tiledHeight | The height to make the frame, and to tile the background at.

def Frame2( ):

This function creates a new FrameGUIComponent2. This is a resizable frame created from a single texture and a single draw call. The frame requires specific artwork, please see the content creation guide for details.

def Gobo( textureName ):

This function creates a new Gobo component. The GoboComponent acts like other gui components, but blends the gui component texture with another specified PyTextureProvider, using the alpha channel of the component's texture.

If you associate a render target with the gobo component, you can also freeze and unfreeze the secondary PyTextureProvider.

A recommended use of the gobo component is to create a post-processing effect, and use the output of that effect as the second texture stage in the gobo component.

This is for example perfect for binoculars and sniper scopes.

For example, in the following code:

comp = GUI.Gobo( "gui/maps/gobo_binoculars.dds" )
comp.materialFX="SOLID"
comp.secondTexture=myBlurredRenderTarget.texture
GUI.addRoot( comp )

This example will display a binocular gobo, and where the alpha channel is relatively opaque in the binocular texture map, a blurred version of the scene is drawn.

Parameters:
textureName The filename of the gobo texture. The alpha channel determines how much of the blurred screen should be blended in.

def Graph( ):

Creates and returns a new GraphGUIComponent, which is used to graph a Vector4Provider on the screen.

Returns:
The new GraphGUIComponent.

def Latency( ):

This function creates a new LatencyGUIComponent. This will display the word "Offline" on the screen if the client is not connected to the server, and nothing otherwise.

Returns:
a new LatencyGUIComponent.

def MatrixShader( target ):

This function creates a new MatrixGUIShader. This can be used to transform the position of one or more GUI Components within clipping space.

Parameters:
target (optional) The initial target MatrixProvider.

Returns:
a new MatrixGUIShader.

def MeshAdaptor( ):

Creates and returns a new MeshGUIAdaptor object, which is used to display 3D objects in the GUI scene.

Returns:
The new MeshGUIAdaptor

def Minimap( ):

Factory function to create and return a new Minimap object. Minimap is a GUI component that can display a scrolling map, with entries displayed on the map.

Returns:
A new Minimap object.

def Simple( textureName ):

This function creates a SimpleGUIComponent, which renders the specified texture in the centre of the screen. It can be customised once it has been created.

Example:
myGui = GUI.Simple( "gui/maps/myGui.dds" )

Parameters:
textureName the string resourceId of the texture to display in the gui component.

Returns:
the SimpleGUIComponent that got created

def Text( text ):

This function creates a new TextGUIComponent. This component renders a line of text.

Parameters:
text A string containing the line of text to be rendered. This can be changed once the component is created.

Returns:
the newly created component.

def Window( ):

This function creates a new WindowGUIComponent, which is used to apply scroll functionality to its children.

Returns:
a new WindowGUIComponent.

def WorldToClipMP( ):

Used primarily with the MatrixGUIShader, this returns a new WorldToClip MatrixProider object.

def addRoot( component ):

This function adds a GUI component to the gui root. GUI elements exist in a treelike structure, with every element having a parent. The top level parent is the root of the whole tree. This root exists internal to the GUI module. In order for a gui component to be processed, for both rendering and event handling, it, or one of its parents, must be added to the root.

Parameters:
component the gui component to add to the root

def delRoot( component ):

This function removes a Gui component from the root gui's list of children.

Parameters:
component the component to remove

def draw( ):

This method causes the GUI and all components which have been added as roots to be redrawn.

It is called automatically by the system each tick. It would not normally be necessary to call this function.

def handleAxisEvent( event ):

This function gets the GUI to handle the given axis event. It hands the event to each of its child components which have the focus attribute set, until one of them returns non zero, at which point it returns non-zero. Otherwise, it returns zero.

This needs to be called from the personality script, otherwise the GUI will not process axis events.

Parameters:
event A PyAxisEvent object.

Returns:
non-zero means the event was handled, zero means it wasn't.

def handleAxisEvent( event ):

If present, this method is called whenever a joystick axis event occurs.

* This needs to be called from the personality script, otherwise the GUI will * not process axis events.

Parameters:
event A PyAxisEvent object.

Returns:
This function should return False if the axis event was not handled * and True if the axis event was handled.

def handleKeyEvent( event ):

This functions gets the GUI to handle the given key event. It hands the event to each of its child components which have the focus attribute set, until one of them returns non zero, at which point it returns non-zero. Otherwise, it returns zero.

This needs to be called from the personality script, otherwise the GUI will not process key events.

Parameters:
event A PyKeyEvent containing information about this key event.

Returns:
non-zero means the event was handled, zero means it wasn't.

def handleMouseEvent( event ):

This function gets the GUI to handle the given mouse event. It hands the event to each of its child components which have the focus attribute set, until one of them returns non zero, at which point it returns non-zero. Otherwise, it returns zero.

This needs to be called from the personality script, otherwise the GUI will not process mouse events.

Parameters:
event A PyMouseEvent object.

Returns:
non-zero means the event was handled, zero means it wasn't.

def load( section ):

This module function loads a gui component from a data section. The data section can either be specified as a string resourceID (filename), or as a PyDataSection. Normally, the data section would have been created previously by calling the save method on the gui component.

Parameters:
section either a resourceId or a PyDataSection

def mcursor( ):

This function returns the MouseCursor object.

Use it, in conjunction with BigWorld.setCursor function to activate the mouse cursor. The mouse cursor object should be activated whenever is desirable to have the user interacting with GUI components by using the mouse. No mouse events will be propagated to the components if the mouse cursor is not active. To activate the mouse cursor, use:

    BigWorld.setCursor( GUI.mcursor() )

Also, use it to access and modify all mouse cursor properties, like position, visible, shape and active:

    mouseStatus = GUI.mcursor().active
    mousePosition = GUI.mcursor().position
    GUI.mcursor().visible = True
    GUI.mcursor().shape = 'arrow'

def printRoots( ):

Prints the GUI structure (as info msgs) this is useful for debugging GUI structures.

def reSort( ):

This function resorts the gui components at the root of the GUI tree. This function sorts according to the third (depth) component of the children's position attributes. Changing this depth value in a child doesn't automatically reorder the children, so an explicit call to this function is required.

Returns:
Read-Only list of GUI components.

def roots( ):

This function returns a list of the current root components. It is not editable. Instead, use the GUI.addRoot and GUI.delRoot to add and remove components from the list.

Returns:
Read-Only list of GUI components.

def screenResolution( ):

This function simply returns the current (width, height) in pixels of the screen. If a resolution override has been set, then this returns the override. Use BigWorld.screenSize if you need the physical resolution regardless of whether the GUI resolution has been overridden.

Returns:
A 2-tuple representing the width and height of the screen, in pixels.

def setDragDistance( distance ):

Sets the minimum distance the mouse pointer has to travel after the left mouse button has been pressed before the movement is considered a drag.

Once the movement is classified as dragging, a click event will no longer be generated if the mouse is released over the dragged component.

Parameters:
distance the minimum drag distance (float, in clip space). The default value is 0.002.

def setResolutionOverride( resolution ):

This method overrides the resolution that the GUI system uses for calculations. This allows components setup in pixel space to be automatically scaled. For example, if the resolution override is set to 1024x768, then the GUI will take up the same area of the screen no matter what the actual screen resolution is.

Parameters:
resolution A Vector2 of the new override. If it is a zero vector then the override is disabled.

def update( dTime ):

This function causes the GUI to be updated as if the specified amount of time had passed. This updates all of the components and shaders which have been added to the GUI root.

The system automatically updates the gui each tick with dTime on each update being the actual time since the last update. This call would not normally need to be used.

Parameters:
dTime The amount of time assumed to have passed since the last update.


Math - BigWorld client Documentation

Math Module Reference

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

Class List

Matrix
MatrixAnimation
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 MatrixAnimation( ):
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 MatrixAnimation( ):

Returns:
The new MatrixAnimation

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


Pixie - BigWorld client Documentation

Pixie Module Reference

Pixie provides an interface to the BigWorld client's particle systems. It exposes factory functions that provide instances of the client's base particle system and instances of modifier classes that affect the manner in which the particle system evolves over time.

The modifiers that affect the ParticleSystem are all derived from the ParticleSystemAction abstract base class.

Class List

PyAmpParticleRenderer
PyBarrierPSA
PyBlurParticleRenderer
PyCollidePSA
PyFlarePSA
PyForcePSA
PyJitterPSA
PyMagnetPSA
PyMatrixSwarmPSA
PyMeshParticleRenderer
PyMetaParticleSystem
PyNodeClampPSA
PyOrbitorPSA
PyParticleSystem
PyParticleSystemAction
PyParticleSystemRenderer
PyPointSpriteParticleRenderer
PyScalerPSA
PySinkPSA
PySourcePSA
PySplatPSA
PySpriteParticleRenderer
PyStreamPSA
PyTintShaderPSA
PyTrailParticleRenderer
PyVisualParticleRenderer

Member Functions

def AmpParticleRenderer( ):
def BarrierPSA( ):
def BlurParticleRenderer( ):
def CollidePSA( elasticity ):
def FlarePSA( filename ):
def ForcePSA( ):
def JitterPSA( ):
def MagnetPSA( ):
def MatrixSwarmPSA( ):
def MeshParticleRenderer( ):
def MetaParticleSystem( ):
def NodeClampPSA( ):
def OrbitorPSA( ):
def ParticleSystem( ):
def PointSpriteRenderer( spritename ):
def ScalerPSA( ):
def SinkPSA( ):
def SourcePSA( position_source, velocity_source ):
def SplatPSA( ):
def SpriteRenderer( spritename ):
def StreamPSA( ):
def TintShaderPSA( ):
def TrailParticleRenderer( ):
def VisualParticleRenderer( ):
def create( name ):
def createBG( name, callback ):
def prerequisites( pSection ):

Member Function Documentation

def AmpParticleRenderer( ):

Factory function to create and return a new PyAmpParticleRenderer object. An AmpParticleRenderer is a ParticleRenderer that renders segmented lines from the particle position back to the origin of the particle system.

Returns:
A new PyAmpParticleRenderer object.

def BarrierPSA( ):

Factory function to create and return a new PyBarrierPSA object. BarrierPSA is a ParticleSystemAction that acts as an invisible barrier to particles.

Returns:
A new PyBarrierPSA object.

def BlurParticleRenderer( ):

This function creates and returns a new PyBlurParticleRenderer object.

def CollidePSA( elasticity ):

Factory function to create and return a new PyCollidePSA object. CollidePSA is a ParticleSystemAction that collides particles with the collision scene.

Parameters:
elasticity Elasticity of the collisions.

Returns:
A new PyCollidePSA object.

def FlarePSA( filename ):

Factory function to create and return a new PyFlarePSA object. FlarePSA is a ParticleSystemAction that draws a lens flare at the location of the oldest particle.

Parameters:
filename Name of the flare resource to use.

Returns:
A new PyFlarePSA object.

def ForcePSA( ):

Factory function to create and return a new PyForcePSA object. ForcePSA is a ParticleSystemAction that applies a constant acceleration to particles in a particular direction.

Returns:
A new PyForcePSA object.

def JitterPSA( ):

Factory function to create and return a new PyJitterPSA object. JitterPSA is a ParticleSystemAction that adds random motion to the particles.

Returns:
A new PyJitterPSA object.

def MagnetPSA( ):

Factory function to create and return a new PyMagnetPSA object.

Returns:
A new PyMagnetPSA object.

def MatrixSwarmPSA( ):

Factory function to create and return a new PyMatrixSwarmPSA object. MatrixSwarmPSA takes a list of target matrix providers, and for each particle, assigns the position of one of the targets to it.

Returns:
A new PyMatrixSwarmPSA object.

def MeshParticleRenderer( ):

Factory function to create and return a new PyMeshParticleRenderer object. A MeshParticleRenderer is a ParticleSystemRenderer which renders each particle as mesh object.

Returns:
A new PyMeshParticleRenderer object.

def MetaParticleSystem( ):

Factory function to create and return a PyMetaParticleSystem object.

Returns:
A new PyMetaParticleSystem object.

def NodeClampPSA( ):

Factory function to create and return a new PyNodeClampPSA object. NodeClampPSA is a ParticleSystemAction that locks a particle to a Node.

Returns:
A new PyNodeClampPSA object.

def OrbitorPSA( ):

Factory function to create and return a new PyOrbitorPSA object. OrbitorPSA is a ParticleSystemAction that causes particles to orbit around a point.

Returns:
A new PyOrbitorPSA object.

def ParticleSystem( ):

Factory function to create and return a PyParticleSystem object. The PyParticleSystem class provides a base particle system to manage particles.

Returns:
A new ParticleSystem object.

def PointSpriteRenderer( spritename ):

Factory function to create and return a new PyPointSpriteParticleRenderer object. A PointSpriteParticleRenderer is a ParticleSystemRenderer which renders each particle as a point sprite.

Parameters:
spritename Name of sprite to use for particles.

Returns:
A new PyPointSpriteParticleRenderer object.

def ScalerPSA( ):

Factory function to create and return a new PyScalerPSA object. ScalarPSA is a ParticleSystemAction that scales particle size over time.

Returns:
A new PyScalerPSA object.

def SinkPSA( ):

Factory function to create and return a new PySinkPSA object. SinkPSA is a ParticleSystemAction that destroys particles within a ParticleSystem.

Returns:
A new PySinkPSA object.

def SourcePSA( position_source, velocity_source ):

Factory function to create and return a new PySourcePSA object. SourcePSA is a ParticleSystemAction that creates particles within a ParticleSystem.

Parameters:
position_source | VectorGenerator as a position source for the particles.
velocity_source | VectorGenerator as a velocity source for the particles.

Returns:
A new PySourcePSA object.

def SplatPSA( ):

Factory function to create and return a new PySplatPSA object. SplatPSA is a ParticleSystemAction that splats particles onto the collision scene.

Returns:
A new PySplatPSA object.

def SpriteRenderer( spritename ):

Factory function to create and return a new PySpriteParticleRenderer object. A SpriteParticleRenderer is a ParticleSystemRenderer which renders each particle as a facing polygon.

Parameters:
spritename Name of sprite to use for particles.

Returns:
A new PySpriteParticleRenderer object.

def StreamPSA( ):

Factory function to create and return a new PyStreamPSA object. StreamPSA is a ParticleSystemAction the converges particles to the velocity of the stream.

Returns:
A new PyStreamPSA object.

def TintShaderPSA( ):

Factory function to create and return a new PyTintShaderPSA object. TintShaderPSA is a ParticleSystemAction that alters a particles tint according to its age.

Returns:
A new PyTintShaderPSA object.

def TrailParticleRenderer( ):

This function creates and returns a new PyTrailParticleRenderer object.

def VisualParticleRenderer( ):

Factory function to create and return a new PyVisualParticleRenderer object. A VisualParticleRenderer is a ParticleSystemRenderer which renders each particle as a visual. Note that it is quicker to use MeshParticle objects exported specifically for use with the MeshParticleRenderer, as they can be drawn 15-at-a-time; however the MeshParticle objects have more limited material functionality. The VisualParticleRenderer can render any material.

Returns:
A new PyVisualParticleRenderer object.

def create( name ):

This function creates either a PyParticleSystem or PyMetaParticleSystem by loading an definition for the particle system from an XML file.

If the XML file defines a ParticleSystem then the returned object is a PyParticleSystem, and if it defines a MetaParticleSystem then the returned object is a PyMetaParticleSystem.

Parameters:
name Name of the XML file to load.

def createBG( name, callback ):

This function creates a MetaParticleSystem in the background thread by loading an definition for the particle system from an XML file.

Unlike the create function, it always return a MetaParticleSystem. If the XML file defines a ParticleSystem, this will be returned as the only system in the new MetaParticleSystem create.

The callable object provided as the second argument will be called after the particle system has been created. This call will always occur in the same thread as the original call (the main thread).

Parameters:
name | Name of the XML file to load.
callback | Callable object to be invoked when the new system is ready.

def prerequisites( pSection ):

This function returns a tuple of all the resources required to load a MetaParticleSystem.

The XML passed in should be either a ParticleSystem or a Meta- ParticleSystem.

Parameters:
pSection Data Section of the particle system.


PostProcessing - BigWorld client Documentation

PostProcessing Module Reference

The PostProcessing module provides access to the Post Processing framework in the BigWorld client and tools.

Class List

Debug
Effect
PyCopyBackBuffer
PyFilterQuad
PyPhase
PyPointSpriteTransferMesh
PyTransferQuad
PyVisualTransferMesh

Member Functions

def CopyBackBuffer( ):
def Debug( ):
def Effect( ):
def FilterQuad( ):
def Phase( ):
def Phase( ):
def PointSpriteTransferMesh( ):
def TransferQuad( ):
def VisualTransferMesh( ):
def chain( Any ):
def debug( A ):
def load( DataSection ):
def profile( N ):
def save( DataSection ):

Member Function Documentation

def CopyBackBuffer( ):

Returns:
A new PostProcessing PyCopyBackBuffer object.

def Debug( ):

Returns:
A new PostProcessing Debug object.

def Effect( ):

Returns:
A new PostProcessing Effect object.

def FilterQuad( ):

Returns:
A new PostProcessing PyFilterQuad object.

def Phase( ):

Returns:
A new PostProcessing PyPhase object.

def Phase( ):

Factory function to create and return a PostProcessing PyPhase object.

Returns:
A new PostProcessing PyPhase object.

def PointSpriteTransferMesh( ):

Returns:
A new PostProcessing PyPointSpriteTransferMesh object.

def TransferQuad( ):

Returns:
A new PostProcessing PyTransferQuad object.

def VisualTransferMesh( ):

Returns:
A new PostProcessing PyVisualTransferMesh object.

def chain( Any ):

This function sets or gets the entire post-processing chain of effects.

Parameters:
Any sequence of PyEffects, or None.

Returns:
The global PyEffects list, if no arguments were passed in, or None.

def debug( A ):

This function sets or gets the debug object for the PostProcessing chain.

Parameters:
A PostProcessing.Debug object, or None.

Returns:
A PostProcessing.Debug object, or None.

def load( DataSection ):

This function load a post-processing chain. Note that the resulting chain is not automatically set as the global chain.

Parameters:
DataSection

Returns:
PyEffects list.

def profile( N ):

This function profiles the post-processing chain, returning the average GPU time incurred.

Parameters:
N (optional)number of samples to take

Returns:
float average GPU time, in seconds, taken to process the chain.

def save( DataSection ):

This function saves the post-processing chain.

Parameters:
DataSection

Returns:
None


ResMgr - BigWorld client 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


Scaleform - BigWorld client Documentation

Scaleform Module Reference

The Scaleform module provides access to the Scaleform integration, if it is enabled.

Class List

PyMovieDef
PyMovieView

Member Functions

def MovieDef( ):

Member Function Documentation

def MovieDef( ):

Factory function to create and return a Scaleform Movie Definition.

Returns:
A new Scaleform PyMovieDef object.


ActionMatcher - BigWorld client Documentation

ActionMatcher Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Motor → PyObjectPlus

Attributes

actions | Read-Only Tuple
bodyTwistSpeed | Float
boredNotifier | Function object
collisionRooted | Integer
debug |
debugWorldVelocity |
entityCollision | Integer
fallNotifier | Function object
fallSelected | Integer
footTwistSpeed | Float
fuse | Float
inheritOnRecouple | Integer
lastMatch | Read-Only String
matchCaps |
matchModelScale | Integer
matchNotifier | Function object
matcherCoupled | Integer
maxCollisionLod | Float
patience | Float
startMovingNotifier | Function object
turnModelToEntity | Integer
useEntityModel | Boolean
useEntityPitchAndRoll | Read-Write Boolean.
velocityProvider |

Detailed Description

ActionMatcher is a Motor that matches the movements and orientation of an entity to the actions defined on its primary model.

The ActionMatcher takes account of such information as:

- the speed of the Entity

- the angle between the Model and the Entity

- the angle between the Model and the Entity's velocity

- user-defined state flags

It also reads configuration information from Actions in the .model file, in order to work out which action to play and how fast to play it. The ActionMatcher starts at the top, and checks each action in order, until it finds one that matches the current criteria. The relevent parts of the action definition are within the <match> section.

- <trigger> contains the criteria for picking a particular action. For an action to be chosen, all of the following must be true:

- The speed (magnitude of the velocity) of the Enitity is betweeen <minEntitySpeed> and <maxEntitySpeed>. If <minEntitySpeed> is less than zero, then the engine assumes the entity is falling when it plays this animation. Note that minEntitySpeed should always be closer to zero, regardless of sign, eg, min = -2, max = -7, min = 2, max = 7

- The angle (entityYaw - modelYaw)is between <minEntityAux1> and <maxEntityAux1>.

- The angle (entityVelocity - modelYaw) is between <minEntityYaw> and <maxEntityYaw>. To match a model walking backward, give it a a yaw range of between, 90 and 270.

- The ActionMatcher must have all of the caps specified in <capsOn> switched on. These caps are bitpositions in a bitfield, so range between 0 and 31. The caps have no BigWorld specific meanings, so it is up to the game to assign meaning to specific numbers.

- The ActionMatcher must have all of the caps specified in <capsOff> switched off.

- <scalePlaybackSpeed>, if set to true, specifies that the rate the animation is played at will be scaled to match the movement rate. If, for example, the animation was designed in 3dsmax to be played at 30 frames a second and move at 2 m/s. If the entity is moving at 3.5 m/s, and the valid range for this particular animation is 1 m/s to 5 m/s then the animation will play 3.5/2.0 = 1.75 times faster than the animator built it to play.

- <feetFollowDirection>, if set to true, causes the model to turn to track the DirectionCursor

By default, an ActionMatcher motor is automatically created for a primary Model. To create additional ActionMatchers, use BigWorld. ActionMatcher function.

Attribute Documentation

actions

This attribute contains the name of all matchable actions in use by the action matcher

Type:
Read-Only Tuple

bodyTwistSpeed

The angular speed at which the model will turn to line up with the entity in radians per second. Defaults to 2pi.

Type:
Float

boredNotifier

The boredNotifer is the callback function to call once fuse exceeds patience. As an animation plays, fuse will increase. When a new animation is played, fuse will be reset. The patience parameter is set by script. If 0, the boredNotifier will not be triggered. The callback can be defined as follows:

    def onBored( self, actionName )

The name of the action is that described in the .model file under /. It can be set in the Action panel of ModelViewer.

Type:
Function object

collisionRooted

This attribute controls how the model responds to entity to entity collisions. The entityCollision attribute controls whether the entity will contribute towards collisions at all, collisionRooted controls whether this model will move in response to collisions. This model will move directly away from the entity it has collided with, until its bounding box no longer overlaps that of the model belonging to the collided entity. Note that it is the model that moves, rather than the entity, making this a client side effect only.

If this is non-zero, then it will NOT move in response to collisions, otherwise it will.

Type:
Integer

debug

The debug attribute allows you to view internal action matcher variables that are contributing towards matching, including information about the currently matched action, if any.

debugWorldVelocity

The debug attribute exposes the internal world velocity that was calculated and used by the action matcher to select actions.

entityCollision

Specifies whether the model responds to collisions between entities. If this is true then when the parent entity collides with another entity, then one model, or the other, or both, will be moved away from other model so that they dont overlap. Which model moves is determined by the collisionRooted flag on the ActionMatcher on both models. If collisionRooted is set on either model, then that model will NOT move away from the entity, leaving the onus for movement on the other model. If both have it set, then neither will move. If it is clear on both of them then they will both move half as far. It defaults to 0. Note that it is the model that moves, rather than than the entity, making this ta client side effect only.

Type:
Integer

fallNotifier

The callback function to call when the entity transitions between falling and not-falling. On callback the function will receive one argument, falling, which is 1 if the entity has started to fall, and 0 if it has just stopped falling. The ActionMatcher decides if the entity is falling based on the action that it chooses. If the minEntitySpeed of the trigger is less than zero, then it assumes that the entity is falling. This will be the case when the falling checkbox is selected in the model editor for an action.

Type:
Function object

fallSelected

This attribute is set to true if the ActionMatcher chose a falling action in its most recent choice. The ActionMatcher decides if the entity is falling based on the action that it chooses. If the minEntitySpeed of the trigger is less than zero, then it assumes that the entity is falling.

Type:
Integer

footTwistSpeed

The angular speed at which the model can twist to match its unitRotation in radians per second. Defaults to 3pi.

Type:
Float

fuse

Fuse is the attribute that tracks how long (in seconds) a model has been bored (playing the same action). Once it exceeds patience, the boredNotifier callback is called. This works for all animations, not just idle animations. It is up to the callback function to process different types of animation.

Type:
Float

inheritOnRecouple

This attribute is used for client controlling entities to smooth their motion when the ActionMatcher is switched on after being off (which is done by setting matcherCoupled to 1). If inheritOnRecouple is true, then the Entities position is set to the models position, otherwise the model is moved immediately to the entities position, which can cause a visual jar. It defaults to 1.

Type:
Integer

lastMatch

This attribute is set to the name of the last action chosen by the action matcher.

Type:
Read-Only String

matchCaps

This attribute specifies which user defined capabilities the ActionMatcher is matching at the moment. It is a list of numbers between 0 and 31. It is checked against the <capsOn> and <capsOff> fields (in the .model file definition of each action) for each action, and the ActionMatcher will only match those actions for which all caps in the <capsOn >field are on in matchCaps and all those in <capsOff> are NOT on.

Read-Write List of Integers (0-31)

matchModelScale

This attribute controls whether the model's scale is taken into account when choosing an action. Note: Only the Z scale is used as in the following entity.model.scale[2]

Type:
Integer

matchNotifier

The callback function to call when the entity transitions between one action-matched action and another. On callback the function will receive one argument, the name of the new action.

Type:
Function object

matcherCoupled

This attribute switches the ActionMatcher on and off. If the attribute is false (0), then the ActionMatcher is decoupled, otherwise, it is coupled. It defaults to 1.

Type:
Integer

maxCollisionLod

If the LOD (level of detail) of the model is less than this amount, then the model will be moved to respond to entity-entity collisions. If it is greater than this amount, then the model won't respond to collisions.

Type:
Float

patience

Patience is how long the model can continue playing the same action for, before it becomes bored. Fuse keeps track of how long the same animation has been playing. Once fuse exceeds patience, the boredNotifier callback is called.

Type:
Float

startMovingNotifier

The startMovingNotifier is a callback function to call when the entity changes from a stationary to a moving state. This callback's purpose is to provide the opportunity to the script programmer to clear the action queue in the even that it had been set explicitly in script. The callback can be defined as follows:

    def onStartMoving( self, actionName ):
        for actionName in self.model.queue:
            self.model.action(actionName).stop()
        pass

    self.am.startMovingNotifier = onStartMoving

The name of the action is that described in the .model file under /. It can be set in the Action panel of ModelViewer.

Type:
Function object

turnModelToEntity

This attribute controls whether or not the ActionMatcher turns the model to track direction changes in the Entity. If it is true, then the models yaw will be set to the Entities yaw. If it is false, then the action matcher doesn't control the model's yaw at all.

Type:
Integer

useEntityModel

The useEntityModel attribute makes the action matcher use the entity's model to check for movement and rotation, instead of the action matcher's owner's model.

This is particularly useful if the action matcher is constructed with and entity that is different than the owner of the model that this action matcher is used by.

Type:
Boolean

useEntityPitchAndRoll

This attribute controls whether the model should use the pitch and roll of the entity.

Type:
Read-Write Boolean.

velocityProvider

The velocityProvider attribute allows you to use any Vector4Provider to match against, instead of the entity velocity. This is particularly useful with player physics Vector4Providers, which allow you to remove the effect of collision corrections.


ActionQueuer - BigWorld client Documentation

ActionQueuer Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def Get_seek( self ):
def Get_seekInv( self ):
def __call__( self, afterTime, callBack, promoteMotion ):
def action( self, aname, errIfNotFound ):
def getSeek( self, posYaw ):
def getSeekInv( self, posYaw ):
def stop( self ):

Attributes

blendInTime | Read-Only Float
blendOutTime | Read-Only Float
blended | Read-Only Integer
displacement | Read-Only Vector3
duration | Read-Only Float
filler | Read-Only Integer
impact | Read-Only Vector3
rotation | Read-Only Vector4
seek | Read-Only Vector4
seekInv | Read-Only Vector4
track | Read-Only Integer

Detailed Description

An ActionQueuer is an action that can be queued on a model. It has many read only attributes which are defined in the .model file. An ActionQueuer can be obtained by either calling the PyModel.action function, or treating the name of the action as a property of a PyModel. The only two methods that actually effect the state of the ActionQueuer are ActionQueuer.stop and calling the actionqueuer as a function object, which makes it play.

Actions play on a track, that is specified in the .model file. Actions that are on different tracks play concurrently. Actions that are on the same track either overwrite the current action, or queue up behind it. Actions can be queued by creating subsequence ActionQueuer's via an an existing ActionQueuer that is either queued or playing.

This class inherits from PyFashion.

Example:
model = BigWorld.Model( "objects/models/characters/biped.model" )

# These two lines are equivalent.
aq = model.action( "Walk" )
aq = model.Walk

# Calling the aq object executes the action.
model.Walk()

# This gets an ActionQueuer for the "Run" action that will be queued
# up to start playing after the "Walk" action completes
model.Run().Walk()

# Here is an example of queueing up a set of actions by string names
def queueActions( model, actionNames ):
    aq = model.action( actionNames[0] )()
    for name in actionNames[1:]:
        aq = aq.action( name )()
...
queueActions( self.model, ["Walk", "Run", "Jump"] )

Member Function Documentation

def Get_seek( self ):

This attribute returns the seek position for another entity wishing to co-ordinate using this action's counterpart on its own model with this action on this model.

Returns:
A Vector4 which is the position and rotation that the corresponding action should be played at.

def Get_seekInv( self ):

This attribute returns the seek position for another entity wishing to co-ordinate using this action on its own model with this action's counterpart on this model (got that?).

Returns:
A Vector4 which is the position and rotation that this action should be played at.

def __call__( self, afterTime, callBack, promoteMotion ):

By calling the ActionQueuer itself as a function, you initiate the action that the ActionQueuer refers to.

For example:
# Start the walk action immediatly.
self.model.Walk()
# Start the climb action after a short delay, call onClimbFinished on
# completion, and apply animation transforms to the model transform.
self.model.Climb(0.5, self.onClimbFinished, 1)

Parameters:
afterTime | A float which is the time in seconds to delay before starting to play the action. Default is 0.
callBack | A script functor that will be called when the action finishes playing. Default is None.
promoteMotion | An integer specifying a boolean value (0 or 1) that determines whether the animation transforms are applied to the model's transform. Default is 0 (false).

Returns:
The ActionQueuer object on success, None on failure.

def action( self, aname, errIfNotFound ):

This function returns the specified action as an ActionQueuer object. If an action is found that matches the action name parameter then it is added into the ActionQueue.

For example:
# Start the walk action.
self.model.action("Walk")()

Parameters:
aname | The name of the action to return as an ActionQueuer object.
errIfNotFound | An optional bool value specifying whether to return an error, if no action was found. Default value is True.

Returns:
Returns an ActionQueuer object of the specified action.

def getSeek( self, posYaw ):

This method returns the seek position and yaw (in world space )for another entity wishing to co-ordinate using this action on the provided position and yaw with this action's counterpart on this model.

This method is different from the seek attribute. The seek attribute specifies the position relative to this model. This function returns the position relative to a specified postition.

Parameters:
posYaw A Vector4 which is the position and yaw that this action will be played at

Returns:
A Vector4 which is the position and rotation that the corresponding action should be played at.

def getSeekInv( self, posYaw ):

This method returns the seek position and yaw for another entity wishing to co-ordinate using this action's counterpart on this position and yaw with this action on its own model.

This method is different from the seekInv attribute. The seekInv attribute specifies the position relative to this model. This function returns the position relative to a specified postition.

Parameters:
posYaw A Vector4 which is the position and yaw that the corresponding action will be played at

Returns:
A Vector4 which is the position and rotation that this action should be played at.

def stop( self ):

This function stops all instances of the input action on the queue, by starting to blend them out (excepting matched actions)

Attribute Documentation

blendInTime

The time, in seconds, that this action will take to blend in. That is, it will start playing blendInTime before the previous action has finished, and gradually blend from the first to the second. In order for the blending to be smooth, it is important that the blendOutTime of the previous action be the same as the blend in time of this action.

This attribute is read in from the model file.

Type:
Read-Only Float

blendOutTime

The time, in seconds, that this action will take to blend out. The system will start playing the next animation blendOutTime before this animation ends. In order for the blending to be smooth, it is fairly important that the blendOutTime of the previous action be the same as the blend in time of this action.

This attribute is read in from the model file.

Type:
Read-Only Float

blended

If this is set to non-zero, then this action will be played on track -1. The track system replaces the use of the blended attribute.

Type:
Read-Only Integer

displacement

The distance and direction that the model moves between the first and last frame of this action, measured relative to the models initial frame of reference.

This attribute is read in from the model file.

Type:
Read-Only Vector3

duration

The time it takes to play the action (measured in seconds). There are a few caveats to this:

- If the <ScalePlaybackSpeed> flag is set in the .model file for this action, then it may play faster or slower, depending on how fast the model is moving. If a model moves over the duration of its animation, it has a 'natural' speed which is the distance it covers, divided by the duration. If the model's in game velocity is different from this, then the playback rate of the animation is scaled accordingly, to keep it synchronised with the movement rate. This changing of the playback rate changes the duration.

- The blend in and blend out times are part of the duration of the action. If the action is short, in particular, shorter than the blend times, the action will start to blend out from the moment it starts blending in, resulting in the action never being fully blended in.

This attribute is read in from the model file.

Type:
Read-Only Float

filler

If this is set to non-zero then this action is available for the ActionMatcher to choose. See the ActionMatcher documentation for a description of how it chooses which action to play.

This attribute is read in from the model file.

Type:
Read-Only Integer

impact

This atribute is the position that the model will end up at, in world coordinates, after playing this action. This is the current models current position in world coordinates, plus the displacement attribute of this action converted to world coordinates.

This attribute is read in from the model file.

Type:
Read-Only Vector3

rotation

The quarternion representing the rotation of the model between the first and last frames of this action.

This attribute is read in from the model file.

Type:
Read-Only Vector4

seek

This attribute is the position and yaw (in world space) that another model should be at, so that when this model plays this action, and the other model plays the coordinated action, it all synchronises properly. It is a vector4, with the 4th element being yaw.

Type:
Read-Only Vector4

seekInv

This attribute is the position and yaw (in world space)that another model should be at, so that when the other model plays this action, and this model plays the coordinated action, it all synchronises properly. It is a vector4, with the 4th element being yaw.

This attribute is read in from the model file.

Type:
Read-Only Vector4

track

Which track the action plays on. Tracks are integers from -1 up, with -1 having a special status. When an action is played on a particular track, it stops whatever action was playing on the track before (blending the other one out, and itself in). When an action is played on track -1, it doesn't interfere with the playing of any actions. Actions which are playing concurrently on different tracks are weighted together using the alpha values for each node in each animation.

This attribute is read in from the model file.

Type:
Read-Only Integer


AlphaGUIShader - BigWorld client Documentation

AlphaGUIShader Class Reference

[GUI Module]

AlphaGUIShader is part of the GUI module. More...

import GUI

Parent Classes

GUIShader → PyObjectPlus

Member Functions

def reset( self ):

Attributes

alpha | Float
currentAlpha | Float
mode | String
speed | Float
start | Float
stop | Float
value | Float

Detailed Description

An AlphaGUIShader is used to change the alpha values of the components (instances of SimpleGUIComponent or its subclasses) it is applied to. AlphaGUIShader is a subclass of GUIShader.

It can apply alpha either evenly over the component, or fading from one edge towards the opposite edge.

A new AlphaGUIShader is created using the GUI.AlphaShader function.

For example:
# create a component to apply the shader to
comp = GUI.Simple( "maps/scroll.dds" )
GUI.addRoot( comp )

# now create the shader.  It will be fully transparent on the left
# and fully opaque on the right.
shad = GUI.AlphaShader()
shad.start = -0.5
shad.stop = 0.5
shad.mode = "RIGHT"
shad.alpha = 1.0

# now add the shader to the component
comp.addShader( shad )

Member Function Documentation

def reset( self ):

This function resets the interpolation of alpha to start at the current value and go for a number of seconds specified by the speed attribute moving linearly to the value specified by the alpha attribute.

This can be useful if you want to reset the interpolation without actually changing the initial alpha value.

Attribute Documentation

alpha

The alpha attribute specifies the alpha value for the component.

If the mode attribute is anything other than "ALL", then this will be the upper limit for the gradient, which fades to zero over the width/height specified by the start and stop attributes.

If the speed attribute is non-zero, then the currentAlpha attribute will move from its current value to alpha over speed seconds, in a linear fashion. The currentAlpha attribute specifies what alpha is actually applied to the component at this moment in time.

This attribute is synonymous with the value attribute.

See:
AlphaGUIShader.mode

Type:
Float

currentAlpha

This attribute is the instantaneous value of alpha that is applied to the component. If speed is non-zero then, when a new value is assigned to the alpha or value attributes, currentValue will move linearly over speed seconds, from whatever value it had at the moment of assignment to the newly assigned value.

Type:
Float

mode

An AlphaGUIShader can apply an alpha gradient, which is where the alpha applied to the component varies linearly either horizontally or vertically.

The mode attribute specifies which direction the alpha gradient runs in. It can take two settings:

- "ALL" - There is no gradient. The entire component has the alpha specified by the alpha attribute.

- "RIGHT" - The gradient starts from the alpha attribute on the right and fades to zero on the left. The alpha gradient begins at the location specified by the start attribute or the edge of the affected GUI component(s), whichever occurs first. The gradient then linearly decreases to the point specified by the stop attribute, or the edge of the affected GUI component(s), whichever occurs last. In this mode, start should always be a higher value than stop.

Type:
String

speed

The speed attribute is the time in seconds that it takes the currentAlpha attribute to move from its current value to the new alpha value, when either the alpha attribute or the value attribute is set.

If speed is zero, then the assignment is instantaneous.

Type:
Float

start

The start attribute specifies the point on the screen (measured in clip coordinates, with (-1,-1) being the bottom left and (1,1) being the top right), at which the alpha gradient will be the value specified by the alpha attribute.

It is a float, and is interpreted as either the x or y component of a Vector2, depending on mode.

Type:
Float

stop

The stop attribute specifies the point on the screen (measured in clip coordinates, with (-1,-1) being the bottom left and (1,1) being the top right), at which the alpha gradient will be zero.

It is a float, and is interpreted as either the x or y component of a Vector2, depending on mode.

Type:
Float

value

The value attribute specifies the alpha value for the component.

If the mode attribute is anything other than "ALL", then this will be the upper limit for the gradient, which fades to zero over the width/height specified by the start and stop attributes.

If the speed attribute is non-zero, then the currentAlpha attribute will move from its current value to alpha over speed seconds, in a linear fashion. The currentAlpha attribute specifies what alpha is actually applied to the component at this moment in time.

This attribute is synonymous with the alpha attribute.

See:
AlphaGUIShader.mode

Type:
Float


ArmTrackerNodeInfo - BigWorld client Documentation

ArmTrackerNodeInfo Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

BaseNodeInfo → PyObjectPlus

Attributes

maxElbowYaw | float
maxShoulderPitch | float
maxShoulderRoll | float
maxShoulderYaw | float
minElbowYaw | float
minShoulderPitch | float
minShoulderRoll | float
minShoulderYaw | float
pointingAxis | integer

Detailed Description

This is a subclass of BaseNodeInfo. This describes a two bone arm system used to either reach a specific direction or point in a specific direction. The values are all provided to the factory method used to create this (BigWorld. ArmTrackerNodeInfo).

Refer to the Tracker class documentation for an overview of the tracker system and related code samples.

Attribute Documentation

maxElbowYaw

Describes the maximum yaw variation in the positive direction (to the right) that a tracker can apply, in degrees.

Type:
float

maxShoulderPitch

Describes the maximum pitch variation in the positive direction (upwards) that a tracker can apply, in degrees.

Type:
float

maxShoulderRoll

Describes the maximum roll variation in the positive direction (anticlockwise) that a tracker can apply, in degrees.

Type:
float

maxShoulderYaw

Describes the maximum yaw variation in the positive direction (to the right) that a tracker can apply, in degrees.

Type:
float

minElbowYaw

Describes the maximum yaw variation in the negative direction (to the left) that a tracker can apply, in degrees.

Type:
float

minShoulderPitch

Describing the maximum pitch variation in the negative direction (downwards) that a tracker can apply, in degrees.

Type:
float

minShoulderRoll

Describes the maximum roll variation in the negative direction (clockwise) that a tracker can apply, in degrees.

Type:
float

minShoulderYaw

Describes the maximum yaw variation in the negative direction (to the left) that a tracker can apply, in degrees.

Type:
float

pointingAxis

Specifies the pointing axis of node (Xaxis, Yaxis or Zaxis).

Type:
integer


AutoAim - BigWorld client Documentation

AutoAim Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

adhesionDistance | float
adhesionFalloffDistance | float
adhesionHorizontalAngle | float
adhesionHorizontalFalloffAngle | float
adhesionPitchToYawRatio | float
adhesionVerticalAngle | float
adhesionVerticalFalloffAngle | float
forwardAdhesion | float
friction | float
frictionDistance | float
frictionFalloffDistance | float
frictionHorizontalAngle | int
frictionHorizontalFalloffAngle | float
frictionMinimumDistance | float
frictionVerticalAngle | float
frictionVerticalFalloffAngle | float
reverseAdhesionStyle | int
strafeAdhesion | float
turnAdhesion | float

Detailed Description

AutoAim is made up of essentially two components. The first is friction and defines to what degree a Camera will 'stick' to its target and the second is adhesion, which describes to what degree the target reticle (eg, crosshairs, target box, etc) will follow the target. Each has a field of view where the friction and adhesion will be the maximum specified and a falloff field of view, where the values linearly blend to 0.

The object is contained within the BigWorld.Targeting object. Defaults for any number of values can be provided in engine_config.xml under <targeting>/<autoAim>, eg;

<root>
    ...
    <targeting>
        ...
        <autoAim>
            ...
            <friction> .5 </friction>
            ...
        </autoAim>
        ...
    </targeting>
    ...
</root>

AutoAim Object can be accessed through BigWorld.autoAim function.
Note that this is only valid for hand-held controllers...

Attribute Documentation

adhesionDistance

This attribute specifies the distance within which the adhesion
will be the maximum specified for the current movement.

Type:

float

adhesionFalloffDistance

This attribute specifies the distance outside which the adhesion will be 0.
The adhesion will linearly deplete from adhesionDistance to adhesionFalloffDistance.

Type:

float

adhesionHorizontalAngle

This attribute specifies the left and right field of view angles, in radians, within which the adhesion
will be the maximum specified for the current movement.

Type:

float

adhesionHorizontalFalloffAngle

This attribute specifies the left and right field of view angles, in radians, outside which the adhesion
will be 0.  The adhesion will linearly deplete from adhesionHorizontalAngle to adhesionHorizontalFalloffAngle.

Type:

float

adhesionPitchToYawRatio

This value is used in calculations to handle pitch and yaw.  Defaults to 0.5.

Type:

float

adhesionVerticalAngle

This attribute specifies the upper and lower field of view angles, in radians, within which the adhesion
will be the maximum specified for the current movement.

Type:

float

adhesionVerticalFalloffAngle

This attribute specifies the upper and lower field of view angles, in radians, outside which the adhesion
will be 0.  The adhesion will linearly deplete from adhesionVerticalAngle to adhesionVerticalFalloffAngle.

Type:

float

forwardAdhesion

This describes to what degree the target reticle will 'stick' to a target as the targeter moves forward.
The value is between 0.0 and 1.0. 0 would mean the target reticle is not affected, whereas 1 would cause
the target reticle to follow the target until it slides out of view.  Defaults to 0.05.

Type:

float

friction

This describes to what degree the Camera will 'stick' to a target.  It is on a scale from 0.0 to 1.0.
A value of 0.0 would mean there was no friction at all, so the camera would move freely when a target
is present and a value of 1.0 would mean that the camera would lock onto the target until it reaches the
friction falloff angle/distance.  Defaults to 0.5.

Type:

float

frictionDistance

This attribute specifies the distance within which the friction will be maximum specified by friction.

Type:

float

frictionFalloffDistance

This attribute specifies the distance outside which the friction will be 0.
The friction will linearly deplete from frictionDistance to frictionFalloffDistance.

Type:

float

frictionHorizontalAngle

This attribute specifies the left and right field of view angles, in radians, within which the friction
will be the maximum specified by friction.

Type:

int

frictionHorizontalFalloffAngle

This attribute specifies the left and right field of view angles, in radians, outside which the friction
will be 0.  The friction will linearly deplete from frictionHorizontalAngle to frictionHorizontalFalloffAngle.

Type:

float

frictionMinimumDistance

This attribute specifies the distance before friction will come into effect,
ie, if the target is too close, 0 friction will be used...

Type:

float

frictionVerticalAngle

This attribute specifies the upper and lower field of view angles, in radians, within which the friction
will be maximum specified by friction.

Type:

float

frictionVerticalFalloffAngle

This attribute specifies the upper and lower field of view angles, in radians, outside which the friction
will be 0.  The friction will linearly deplete from frictionVerticalAngle to frictionVerticalFalloffAngle.

Type:

float

reverseAdhesionStyle

Adjusts the forwardAdhesion for backwards movement.  The default, -1 will perform the usually desired
effect, 0 will deactivate it.  Other values will adjust it proportionally.

Type:

int

strafeAdhesion

This describes to what degree the target reticle will 'stick' to a target as the targeter moves sideways.
The value is between 0.0 and 1.0. 0 would mean the target reticle is not affected, whereas 1 would cause
the target reticle to follow the target until it slides out of view.  Defaults to 0.2.

Type:

float

turnAdhesion

This describes to what degree the target reticle will 'stick' to a target as the targeter turns.
The value is between 0.0 and 1.0. 0 would mean the target reticle is not affected, whereas 1 would cause
the target reticle to follow the target until it slides out of view.  Defaults to 0.1.

Type:

float


AvatarDropFilter - BigWorld client Documentation

AvatarDropFilter Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

AvatarFilter → Filter → PyObjectPlus

Attributes

alignToGround | bool
groundNormal | GroundNormalProvider

Detailed Description

This class inherits from AvatarFilter. It is nearly exactly the same as its parent, except that a findDropPoint is used to place each input point on the ground.

An AvatarDropFilter is created using the BigWorld. AvatarDropFilter function.

Attribute Documentation

alignToGround

This attribute controls whether the entity should also be rotated to match the slope of the ground on which they are standing.

Type:
bool

groundNormal

The attribute returns a Vector4 provider to the normalised ground normal of the drop filter in the form (x, y, z, 0).

Type:
GroundNormalProvider


AvatarFilter - BigWorld client Documentation

AvatarFilter Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Filter → PyObjectPlus

Member Functions

def callback( self, whence, fn, extra, passMissedBy ):
def debugMatrixes( self ):

Attributes

latency | float
latencyCurvePower | float
latencyFrames | float
minLatency | float
velLatency | float

Detailed Description

This class inherits from Filter. It implements a filter which tracks the last 8 entity updates from the server, and linearly interpolates between them.

Linear interpolation is done at ( time - latency ), where time is the current engine time, and latency is how far in the past the entity currently is.

Latency moves from its current value in seconds to the "ideal latency" which is the time between the two most recent updates if an update has just arrived, otherwise it is 2 * minLatency. Lantency moves at velLatency seconds per second.

An AvatarFilter is created using the BigWorld. AvatarFilter function. The constructor takes in an optional AvatarFilter to copy for example:

# create an avatar filter
filter = BigWorld.AvatarFilter()

# create an avatar filter from another avatar filter
filter = BigWorld.AvatarFilter(oldFilter)

Member Function Documentation

def callback( self, whence, fn, extra, passMissedBy ):

This method adds a callback function to the filter. This function will be called at a time after the event specified by the whence argument. The amount of time after the event is specified, in seconds, by the extra argument.

If whence is -1, then the event is when the filter's timeline reaches the penultimate update (i.e. just before the current update position starts influencing the entity). If whence is 0, then the event is when the current update is reached. If whence is 1 then the event is when the timeline reaches the time that the callback was specified.

The function will get one argument, which will be zero if the passMissedBy argumenty is zero, otherwise it will be the amount of time that passed between the time specified for the callback and the time it was actually called at.

Note: When the callback is made, the entity position will already have been set for the frame (so it'll be at some spot after the desired callback time), but the motors will not yet have been run on the model to move it. The positions of other entities may or may not yet have been updated for the frame.

Note: If a callback function returns '1', the entity position will be snapped to the position that the entity would have had at the exact time the callback should have been called.

Parameters:
whence | an integer (-1, 0, 1). Which event to base the callback on.
fn | a callable object. The function to call. It should take one integer argument.
extra | a float. The time after the event specified by whence tha the function should be called at.
passMissedBy | whether or not to pass to the function the time it missed its ideal call-time by.

def debugMatrixes( self ):

This function returns a tuple of matrix providers that when applied to a unit cube visualises the received position data being used by the filter.

Note: These matrix providers hold references to the filter that issued them.

Returns:
tuple([MatrixProvider,]) A tuple of newly created matrix providers

Attribute Documentation

latency

This attribute is the current latency applied to the entity. That is, how far in the past that entity is, relative to the current game time.

Latency always moves towards the "ideal" latency with a velocity of velLatency, measured in seconds per second.

If an update has just come in from the server, then the ideal latency is the time between the two most recent updates, otherwise it is two times minLatency.

The position and yaw of the entity are linearly interpolated between the positions and yaws in the last 8 updates using (time - latency).

Type:
float

latencyCurvePower

The power used to scale the latency velocity |latency - idealLatency|^power

Type:
float

latencyFrames

Type:
float

minLatency

This attribute is the minimum bound for latency.

Type:
float

velLatency

This attribute is the speed, in seconds per second, that the latency attribute can change at, as it moves towards its ideal latency. If an update has just come in from the server, then the ideal latency is the time between the two most recent updates, otherwise it is two times minLatency.

Type:
float


BWOpenAutomate - BigWorld client Documentation

BWOpenAutomate Class Reference

[OpenAutomateWrapper Module]

BWOpenAutomate is part of the OpenAutomateWrapper module. More...

import OpenAutomateWrapper

Detailed Description

This class is used to wrap different OpenAutomate enum values and global values.


BaseCamera - BigWorld client Documentation

BaseCamera Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def handleAxisEvent( self, event ):
def handleKeyEvent( self, event ):
def handleMouseEvent( self, event ):
def render( self ):
def set( self, matrix ):

Attributes

direction | Read-Only Vector3
invViewMatrix | Read-Only MatrixProvider
matrix | Read-Only MatrixProvider
position | Read-Only Vector3
spaceID | SpaceID (int)

Detailed Description

This class is the abstract base class for all cameras. It supplies basic functionality for setting a camera to a particular matrix, for updating and rendering the camera, and for reading the camera's position and direction.

There are three subclasses, CursorCamera, FlexiCam and FreeCamera.

Member Function Documentation

def handleAxisEvent( self, event ):

This function allows the camera to handle the given joystick axis event. If the camera handles the event it returns True, otherwise it returns False.

Parameters:
event A PyAxisEvent representing the event.

Returns:
True if the event was handled, False if it was not.

def handleKeyEvent( self, event ):

This function allows the camera to handle the given key event. If the camera handles the event it returns True, otherwise it returns False.

Parameters:
event A PyKeyEvent representing the event.

Returns:
True if the event was handled, False if it was not.

def handleMouseEvent( self, event ):

This function allows the camera to handle the given mouse movement event. If the camera handles the event it returns True, otherwise it returns False.

Parameters:
event A PyMouseEvent representing the event.

Returns:
True if the event was handled, False if it was not.

def render( self ):

This function has no effect

def set( self, matrix ):

This function sets the transformation matrix for the camera to the specified MatrixProvider. It doesn't actually use the specified MatrixProvider directly but copies it.

Parameters:
matrix The MatrixProvider which the camera is being moved to.

Attribute Documentation

direction

The current facing of the camera within the world

Type:
Read-Only Vector3

invViewMatrix

The MatrixProvider which specifies the current inverse transform of the camera within the world ( i.e. the camera's transform as a world object )

Type:
Read-Only MatrixProvider

matrix

The MatrixProvider which specifies the current transform of the camera within the world

Type:
Read-Only MatrixProvider

position

The current location of the camera within the world

Type:
Read-Only Vector3

spaceID

This is the ID of the space in which the camera resides. If zero the camera derives its space from that of the player. Default is zero.

Type:
SpaceID (int)


BaseNodeInfo - BigWorld client Documentation

BaseNodeInfo Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

angularHalflife | Read-Write float.
angularThreshold | Read-Write float.
angularVelocity | Read-Write float.
maxPitch | Read-Write float.
maxYaw | Read-Write float.
minPitch | Read-Write float.
minYaw | Read-Write float.

Detailed Description

This is the abstract base class for the TrackerNodeInfo class. It holds information about how a Tracker affects PyModel Node instances, the yaw and pitch movement ranges that it permits, and the speed at which the nodes rotate.

Refer to the Tracker class documentation for an overview of the tracker system and related code samples.

Attribute Documentation

angularHalflife

The angular halflife determines the time of angular decay, specified in seconds. This value is to be used in conjunction with angular threshold and must be non zero for it to take effect.

Type:
Read-Write float.

angularThreshold

The angular threshold is a value used when blending the node rotation to switch between decay or angular modes. The decay mode blends the node to the new angle using a decaying function by specifying the halflife. The angular mode blends the node to its new angle using the angular velocity specified. The choice of modes depends on the difference between the nodes old angle and new angle, if the difference is less than the threshold then the decaying function else the angular velocity is used. The threshold is specified in radians. e.g. threshold <= 0 : only use angular velocity (default value) threshold < a (a > 0) : use angular decay if angle diff < a else use angular velocity

Type:
Read-Write float.

angularVelocity

The angular speed at which the nodes turn, in radians per second.

Type:
Read-Write float.

maxPitch

The maximum pitch that this will allow a Tracker to apply to a Node, in radians, with its initial position as 0.

Type:
Read-Write float.

maxYaw

The maximum yaw that this will allow a Tracker to apply to a Node, in radians, with its initial position as 0.

Type:
Read-Write float.

minPitch

The minimum pitch that this will allow a Tracker to apply to a Node, in radians, with its initial position as 0.

Type:
Read-Write float.

minYaw

The minimum yaw that this will allow a Tracker to apply to a Node, in radians, with its initial position as 0.

Type:
Read-Write float.


BlendNodeInfo - BigWorld client Documentation

BlendNodeInfo Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

BaseNodeInfo → PyObjectPlus

Detailed Description

This is a subclass of BaseNodeInfo. Instances of this class are used by the Tracker system to blend between BaseNodeInfo objects over 0.3 seconds. This is automatically done whenever the nodeInfo or directionProvider properties of a Tracker are changed. Instances of this class cannot be created or accessed via script.


BoidsFilter - BigWorld client Documentation

BoidsFilter Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

AvatarFilter → Filter → PyObjectPlus

Attributes

approachRadius | float
collisionFraction | float
influenceRadius | float
speed | float
speed | float
stopRadius | float

Detailed Description

This subclass of AvatarFilter implements a filter which implements flocking behaviour for the models that make up an entity. This would normally be used for an entity such as a flock of birds or a school of fish which has many models driven by one entity.

The interpolation of the Entity position is done using the same logic as its parent AvatarFilter. However, it also updates the positions of individual models (which are known, according to flocking conventions, as boids) that are attached to the entity, using standard flocking rules.

When the flock lands, the boidsLanded method is called on the entity.

A new BoidsFilter is created using the BigWorld. BoidsFilter function.

Attribute Documentation

approachRadius

When the boids are in the process of landing, and a boid is inside the approach radius, then it will point directly at its goal, instead of smoothly turning towards it.

Type:
float

collisionFraction

The collision fraction defines the proportion of the influence radius within which neighbours will be considered colliding.

Type:
float

influenceRadius

The influence radius simply determines how close a boid must be to another to affect it at all.

Type:
float

speed

The normal speed of the boids. While boids will speed up and slow down during flocking, their speed will always be damped toward this speed.

Type:
float

speed

Controls whether the boids are flying or landing. By default they are in * the flying state which is specified with 0. The landing state will cause * the boids to land and is specified with 1. When a boid lands the method * boidsLanded is called.

Type:
float

stopRadius

When the boids are in the process of landing, and a boid is inside the stop radius, it will be positioned exactly at the goal, and its speed will be set to 0.

Type:
float


Bouncer - BigWorld client Documentation

Bouncer Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Motor → PyObjectPlus

Member Functions

def calcPath( self, clientSourcePos, serverSourcePos, destPos, elasticity, radius, maxBounces ):
def estimatePath( self, clientSourcePos, elasticity, radius, maxBounces ):
def updatePath( self, clientSourcePos, serverSourcePos, destPos ):

Attributes

destPos | Sequence of floats (x, y, z).
timeSlice | Float. Default is 0 (this must be set before calcPath is called).
tripTime | Float. Default is -1 (this must be set before calcPath is called).
vx | Float. Default is 0.
vy | Float. Default is 0.
vz | Float. Default is 0.

Detailed Description

Bouncer is a Motor that causes the model to move with an initial velocity (vx, vy, vz) in a balistic trajectory, following the laws of motion and bouncing against the collision scene until it eventually comes to rest.

It is designed to work in a lagged network environment so that the player originally activating the bouncer can get immediate feedback, being able to see the balistic projectile without having to wait for the server to return its correct final path, while still getting an end result that is consistent with that on the server and all witnessing clients.

This is achieved by allowing the original client to estimate the object's path (using estimatePath) and start animating it right away. When the final authoritative trajectory arrives from the server, the two paths are blended together over time (using updatePath), so that the final position on the client is the same as the one returned by the server.

Clients witnessing the balistic object will animate the server-computed trajectory from the begining (using calcPath).

Example:
    def throwGrenade(self):
        # when throwing the grenade
        motor = BigWorld.Bouncer()
        motor.vx = throwSpeed[0]
        motor.vy = throwSpeed[1]
        motor.vz = throwSpeed[2]
        motor.tripTime  = Grenade.FUSETIME # no point in simulating past explosion time
        motor.timeSlice = 1.0 / 30.0
        motor.estimatePath( owner.position, ELASTICITY, RADIUS, MAX_BOUNCES)

        model = BigWorld.Model(GRENADE_MODEL)
        model.motors = [motor]
        (...)

    def enterWorld(self):
        if self.ownerId == BigWorld.player().id:
            # update existing motor
            (...)
            model.motors[0].updatePath(
                self.clientSourcePos,
                self.serverSourcePos,
                self.destinationPos)
        else:
            # witnessing grenade being thrown
            (...)
            motor = BigWorld.Bouncer()
            motor.vx = self.throwSpeed[0]
            motor.vy = self.throwSpeed[1]
            motor.vz = self.throwSpeed[2]
            motor.tripTime  = self.fusetime
            motor.timeSlice = 1.0 / 30.0
            motor.calcPath(
                currentOwnerPosition, self.serverSourcePos,
                self.destPos, ELASTICITY, RADIUS, MAX_BOUNCES)

Member Function Documentation

def calcPath( self, clientSourcePos, serverSourcePos, destPos, elasticity, radius, maxBounces ):

Pre-calculates the path of the object, as determined by the Bouncer motor. The Bouncer will move the object along this path as the motor is updated over time.

The clientSourcePos is the initial position, and the model has its position interpolated over the first second of its trajectory to join on the calculated path from serverSourcePos to destPos.

This method should be used on witnessing clients.

This needs to be called before the motor is used.

The tripTime attribute must be set to an estimate before this function is called. The simulation will be carried up to tripTime. This can either be sent by the server or be a constant in the game (e.g., the fuse time of a grenade).

Velocity is taken from the vx, vy and vz attributes. These and timeSlice must also be set before calcPath can be called.

Parameters:
clientSourcePos | Sequence of floats (x, y, z): initial position on the client.
serverSourcePos | Sequence of floats (x, y, z): initial position on the server.
destPos | Sequence of floats (x, y, z): destination position.
elasticity | float: bouncing object elasticity factor.
radius | float: bouncing object radius.
maxBounces | int: maximum number of bounces before stoping the simulation.

Returns:
2-tuple: (total simulation time, time to reach destination).

def estimatePath( self, clientSourcePos, elasticity, radius, maxBounces ):

Estimates a path before the final information arrives from the server.

This method should be used on the client activating the bouncer.

This needs to be called before the motor is used.

The tripTime attribute must be set to an estimate before this function is called. The simulation will be carried up to tripTime. The lifetime of the bouncing object is usually the best guess.

Velocity is taken from the vx, vy and vz attributes. These and timeSlice must also be set before estimatePath is called.

Parameters:
clientSourcePos | Sequence of floats (x, y, z): initial position on the client.
elasticity | float: bouncing object elasticity factor.
radius | float: bouncing object radius.
maxBounces | int: maximum number of bounces before stoping the simulation.

Returns:
float: total simulation time.

def updatePath( self, clientSourcePos, serverSourcePos, destPos ):

Updates an estimated path, based on the final authoritative information received from the server. The combination of estimatePath and updatePath should end up with the same result as calcPath, but it can start earlier. The path is smoothed from the estimate to the correct result, based on what has already been played back.

This method should be used on the client that activated the bouncer, after it has received the server-computed source and destination positions.

Parameters:
clientSourcePos | Sequence of floats (x, y, z): initial position on the client.
serverSourcePos | Sequence of floats (x, y, z): initial position on the server.
destPos | Sequence of floats (x, y, z): destination position.

Returns:
float: total simulation time.

Attribute Documentation

destPos

The attribute destPos can be used to access the destination position for the path of the Bouncer. This attribute is Read Only. If called before calcPath or estimatePath are called, the return value will be the zero vector.

Type:
Sequence of floats (x, y, z).

timeSlice

The attribute timeSlice is used to specify the time interval between pre-calculated positions for the objects path. This needs to be set to a value greater than 0 before calcPath is called. A rough estimate for this would be the time interval between frames. This along with tripTime allows you to specify how many steps are precalculated by calcPath for the objects trajectory, and to control how much processor time is used by calcPath.

Type:
Float. Default is 0 (this must be set before calcPath is called).

tripTime

The attribute tripTime is used to specify in rough terms the expected time that the object will take to come to rest (reach its destination). This needs to be set to a value greater than 0 before calcPath is called. It will serve as the upper bound for the simulation time. This, along with timeSlice allows you to specify how many steps are precalculated by calcPath for the objects trajectory, and to control how much processor time is used by calcPath.

Type:
Float. Default is -1 (this must be set before calcPath is called).

vx

Initial velocity in the models x-axis direction.

Type:
Float. Default is 0.

vy

Initial velocity in the models y-axis direction.

Type:
Float. Default is 0.

vz

Initial velocity in the models z-axis direction.

Type:
Float. Default is 0.


BoundingBoxGUIComponent - BigWorld client Documentation

BoundingBoxGUIComponent Class Reference

[GUI Module]

BoundingBoxGUIComponent is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Attributes

absoluteSubspace | integer
alwaysDisplayChildren | boolean (0 or 1)
clipSpaceSource | boolean (0 or 1)
clipToBox | boolean (0 or 1)
offsetSubspace | tuple of size 3
source | MatrixProvider

Detailed Description

A BoundingBoxGUIComponent is used to render a bounding image on the hud that surounds a Model displayed in the world. It moves across the hud to stay bounding the model as either the camera or the model moves.

BoundingBoxGUIComponent inherits from SimpleGUIComponent. It is created by the GUI.BoundingBox function, which takes the filepath to the image to use to render the corner of the bounding box. The image is used unflipped in the bottom right hand corner of the bounding box. It is flipped horizontally to give the bottom left corner. It is flipped vertically to give the the top right corner. It is flipped horizontally and vertically to give the top left corner.

The outside of the corners line up with the outside of the bounding rectangle. The images can be scaled using the functionality of SimpleGUIComponent. If they are too big, then they overlap.

The bounding components are also semi-constrained by the screen. For example, if the source matrix goes gradually off the left of the screen, then the two left hand corners will remain on the left hand edge of the screen until the right hand corners have followed the source off. At this point, the left hand corners will gradually move off screen. The same logic applies to the other screen edges.

In order to make the BoundingBoxGUIComponent appear, it needs both to be added to the GUI tree, and it needs to have its source attribute assigned. This is normally set to the bounds attribute of the model the box is to surround.

The following example draws a bounding box around the player model:

bb = GUI.BoundingBox( "maps/gui/select.dds" )
model = BigWorld.player().model
bb.source = model.bounds

Attribute Documentation

absoluteSubspace

Type:
integer

alwaysDisplayChildren

Type:
boolean (0 or 1)

clipSpaceSource

Using this in conjunction with clipToBox and offsetSubspace allows the BoundingBoxGUIComponent to be used to build almost any window-based widget, eg, scrolling lists of items, drop-down combo boxes, etc...

Type:
boolean (0 or 1)

clipToBox

Using this in conjunction with clipSpaceSource and offsetSubspace allows the BoundingBoxGUIComponent to be used to build almost any window-based widget, eg, scrolling lists of items, drop-down combo boxes, etc...

Type:
boolean (0 or 1)

offsetSubspace

Using this in conjunction with clipSpaceSource and clipToBox allows the BoundingBoxGUIComponent to be used to build almost any window-based widget, eg, scrolling lists of items, drop-down combo boxes, etc...

Type:
tuple of size 3

source

The source attribute specifies the matrix provider which gives the bounding box in world space. This is normally set to the bounds attribute of the model the box is to draw a box around.

Type:
MatrixProvider


BoxAttachment - BigWorld client Documentation

BoxAttachment Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyAttachment → PyObjectPlusWithWeakReference

Attributes

hit | bool.
maxBounds | Vector3.
minBounds | Vector3.
name | String.
worldTransform | Matrix.

Detailed Description

This class implements a bounding box that can be attached to a node to perform hit testing.

Attribute Documentation

hit

Whether the box attachment was hit in the last hit test

Type:
bool.

maxBounds

The maximum bounds of the hit box

Type:
Vector3.

minBounds

The minimum bounds of the hit box

Type:
Vector3.

name

The name of the box attachment

Type:
String.

worldTransform

The world transform of the box attachment

Type:
Matrix.


CameraSpeed - BigWorld client Documentation

CameraSpeed Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

accelerateEnd | float
accelerateRate | float
accelerateStart | float
accelerateWhileTargetting | boolean (0 or 1)
cameraPitchSpeed | float
cameraYawSpeed | float
lookAxisMax | float
lookAxisMin | float
lookTable | list of tuple2
turningHalfLife | float

Detailed Description

The CameraSpeed object stores current camera movement settings. Defaults can be specified in engine_config.xml through the <camera> data section.

CameraSpeed object can be accessed through BigWorld.cameraSpeed attribute.

Attribute Documentation

accelerateEnd

This is the time in seconds at which acceleration stops, and the movement has reached it maximum speed.

Type:
float

accelerateRate

Acceleration is linear, and the maximum speed multiplier is given by this value. The speed increases linearly between the time acceleration starts and ends.

Type:
float

accelerateStart

The delay, in seconds, before acceleration can start.

Type:
float

accelerateWhileTargetting

If true, the camera speed is permitted to accelerate if targeting, otherwise it won't. Defaults to false (0).

Type:
boolean (0 or 1)

cameraPitchSpeed

This is the basic turning speed (in degrees per second) for vertical turning.

Type:
float

cameraYawSpeed

This is the basic turning speed (in degrees per second) for horizonal turning. Horizontal turning can be accelerated.

Type:
float

lookAxisMax

The maximum value used for camera control with axis oriented devices. In addition, if the position is less than the minimum, it is ignored (the deadzone). If the position is more than the maximum, it is considered "pinned", i.e. at the extreme.

Type:
float

lookAxisMin

The minimum value used for camera control with axis oriented devices. In addition, if the position is less than the minimum, it is ignored (the deadzone). If the position is more than the maximum, it is considered "pinned", i.e. at the extreme.

Type:
float

lookTable

This is a table that provides values for basic, non-linear camera movement. Rather than just have the camera speed be a multiple of the axis control, it is also multiplied by a number from this table. The table is made up of Vector2s, with the first item in the vector being an index, and the second being the value. The item in the table with the highest index less than the current value of the axis control is used. The value associated with that item is used to mulitply the camera speed.

The table defaults to:
    ( 0.00, 0.00 )
    ( 0.10, 0.05 )
    ( 0.30, 0.10 )
    ( 0.50, 0.25 )
    ( 0.70, 0.58 )
    ( 0.84, 1.00 )
For example, An axis value of 0.55 would pick the 4th item, giving a value of 0.25. The camera speed would then be:
    base camera speed * 0.55 * 0.25

Type:
list of tuple2

turningHalfLife

The time the camera should take to move half the distance required to meet its objective. If this is zero, there is no momentum, and the camera always point exactly where it's told. A value of 1.0 would mean than each second the camera would get half-way to the desired direction. A value of 0.5 would mean that each second the camera would get 70% of the wat to the desired direction. Other values would be:
    0.25  84%
    0.10  93%
    0.08  95%
    0.05  97%
    0.03  98%
    0.01  99%

Type:
float


ClipGUIShader - BigWorld client Documentation

ClipGUIShader Class Reference

[GUI Module]

ClipGUIShader is part of the GUI module. More...

import GUI

Parent Classes

GUIShader → PyObjectPlus

Member Functions

def reset( self ):

Attributes

currentValue | Read-Only Float
delay | Float
dynValue |
mode | String
slant |
speed | Float
value | Float

Detailed Description

This GUIShader clips the components that it is applied to. It clips a component to a rectangle that has one dimension the same as the component's rectangle, and the other dimension having one side that lines up with the corresponding component edge, and the other side having been scaled in from the component edge by the value attribute. Which edge is scaled is determined by the mode attribute.

This can be useful for things like health bars, which need to be dynamically clipped.

For example, in the following code:

comp = GUI.Simple( "maps/gui/scroll.dds" )
GUI.addRoot( comp )
shad = GUI.ClipShader()
comp.addShader( shad )

shad.mode	= "RIGHT"
shad.value	= 0.75
shad.speed  = 10.0
shad.value	= 0.25

This example will start with the leftmost three quarters of the component visible and the rightmost quarter clipped off. Over 10 seconds it will linearly clip more and more until only the leftmost quarter is visible.

A ClipGUIShader is created using the GUI.ClipShader function.

Member Function Documentation

def reset( self ):

This function forces current size of the clip rectangle to move instantly to the size specified by the value attribute

Attribute Documentation

currentValue

The currentValue attribute gives read access to the current size (in clip coordinates, with (-1,-1) in the bottom left of the screen and (1,1) in the top right) of the cliprect while it is linearly interpolating from its initial value to the newly assigned value attribute. It interpolates over a number of seconds specified by the speed attribute.

Type:
Read-Only Float

delay

The delay attribute is the time it takes, when the attribute value is assigned to, before the clipper is adjust from its current value to the newly assigned value.

Type:
Float

dynValue

This attribute is unsupported.

mode

The mode attribute determines which edge moves to clip the component. It can have a value of "LEFT" or "RIGHT". If mode is "LEFT", then the value attribute determines the rightmost fraction of the component to be shown. If mode is "RIGHT", then the value attribute determines the leftmost fraction of the component to be shown.

Type:
String

slant

The slant value offers support for clipping gui components where the cut needs to be on a slant ( for example a slanted health bar ). It only works on simple gui components ( i.e. not text nor mesh components ).

The slant is a percentage of the component's width , and represents the x-offset between the top and the bottom of the component. If your component's texture has a backwards slope ( like a backslash ) then set the slant to a negative value.

speed

The speed attribute is the time it takes, when the attribute value is assigned to, to adjust from its current value to the newly assigned value. The clip rectangle size is linearly interpolated over this time period.

The currentValue attribute gives the current size of the clip rectangle during the interpolation.

Type:
Float

value

This attribute determines the proportion of the component to reveal. Values less than zero are treated the same as zero, values above one are treated as one. How to align the revealed rectangle with the underlying component is determined by the mode attribute.

If the speed attribute is non-zero, then, when a new value is assigned, the actual size of the clip rect will take speed seconds to move from its initial value to the newly assigned value. The currentValue attribute will give read access to actual size of the clip rect as it is moving.

Type:
Float


ColourGUIShader - BigWorld client Documentation

ColourGUIShader Class Reference

[GUI Module]

ColourGUIShader is part of the GUI module. More...

import GUI

Parent Classes

GUIShader → PyObjectPlus

Member Functions

def reset( self ):

Attributes

colourProvider | ColourProvider
end | Vector4
middle | Vector4
speed | Float
start | Vector4
value | Float

Detailed Description

This class modifies the colours of the GUI components it is applied to. It is a subclass of GUIShader.

There are two ways it can specify which colour to shade the components. The first is to have a ColourProvider (which is a Vector4Provider, with its components interpreted as ( red, green, blue, alpha ), assigned to its colourProvider attribute. If this is not None it overrides the interpolation.

The second is to interpolate between the colour specified by its start, middle and end attributes. Interpolation is based on the value attribute. If value is between 0.0 and 0.5, interpolation is between start and middle. If it is from 0.5 to 1.0, it is between middle and end.

A new ColourGUIShader is created using the GUI.ColourShader function.

Member Function Documentation

def reset( self ):

This method resets the colour of the shader to be exactly the destination. It bypasses any inherent animation to the target colour.

Attribute Documentation

colourProvider

This attribute can be assigned a ColourProvider, which then specifies the colour for the shader, overriding the colour derived using value to interpolate between start, middle and end. By default, colourProvider is None.

Type:
ColourProvider

end

The end attribute is the colour to associate with a value of 1.0. The colour of the shader is linearly interpolated between the start, middle and end attributes, using the value attribute. When value is between 0.5 and 1.0, it is interpolated between middle and end.

The value is a Vector4, with the components (red, green, blue, alpha), each between 0 and 255. Alpha is ignored

Type:
Vector4

middle

The middle attribute is the colour to associate with a value of 0.5. The colour of the shader is linearly interpolated between the start, middle and end attributes, using the value attribute. When value is between 0.0 and 0.5, it is interpolated between start and middle. When value is between 0.5 and 1.0, it is interpolated between middle and end.

The value is a Vector4, with the components (red, green, blue, alpha), each between 0 and 255. Alpha is ignored

Type:
Vector4

speed

This attribute specifies how many seconds the colour of the shader takes to adjust when the value attribute is assigned to.

Type:
Float

start

The start attribute is the colour to associate with a value of zero. The colour of the shader is linearly interpolated between the start, middle and end attributes, using the value attribute. When value is between 0.0 and 0.5, it is interpolated between start and middle.

The value is a Vector4, with the components (red, green, blue, alpha), each between 0 and 255. Alpha is ignored.

Type:
Vector4

value

The value attribute is used to linearly interpolate the colour of the shader between the start, middle and end colours. Values between 0.0 and 0.5 are interpolated between start and middle, values between 0.5 and 1.0 are interpolated between middle and end.

If speed is non-zero, then when value is assigned to, the colour takes speed seconds to move from its current colour to the interpolated colour chosen by the new value.

Type:
Float


ConsoleGUIComponent - BigWorld client Documentation

ConsoleGUIComponent Class Reference

[GUI Module]

ConsoleGUIComponent is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Member Functions

def clear( self ):
def columnLeft( self, columnIndex ):
def prints( self, str ):
def rowTop( self, rowIndex ):
def toggleFontScale (deprecated)( self ):
def visibleHeight( self ):
def visibleWidth( self ):

Attributes

characterSize | Read-Only Vector2
cursor | Vector2
editCallback | Callable Python object, which takes one argument
editCol | Integer
editColour | Write-Only Vector2
editEnable | Integer (treated as boolean)
editLineLength | Integer
editPrompt | String
editRow | Integer
editText | String
lineColour | Write-Only Vector4

Detailed Description

This class has been deprecated in favour of script based solutions that take advantage of multiline TextGUIComponents.

This class is used to supply an editable console, which renders characters and a flashing cursor to the screen. It can be switched between edit and non-edit mode using the editEnable attribute, which defaults to non-edit mode. The position of the cursor can be moved around using the editRow and editCol attributes. Text can be written straight to the console programatically using the prints function. There is no support for wrapping, so only the portion of the string that fits on the screen is drawn.

When in edit mode, if the user presses enter then the callback function specified by editCallback is called, with the entered text as an argument. By default, the console does nothing with the entered text. The callback function is required to do anything with it, including adding it to a previous line of the screen. Once the callback function has completed, the console clears the edit line.

BigWorld consoles use font size matching to select which font will be used to render text. With font size matching, whenever a new screen resolution is selected, the font that yields the number of columns that best matches the ideal console width will be chosen from the list of available fonts. The list of fonts is defined in resource.xml's system/consoleFonts entry. The number of visible columns and rows, thus, will change whenever the resolution changes. The visibleWidth and visibleHeight methods can be used to retrieve the current number of columns and rows. rowTop and columnLeft can be used to get the x and y screen position, respectively, of any character in the console.

A new ConsoleGUIComponent is created using the GUI.Console function.

Member Function Documentation

def clear( self ):

This function clears all text from the Console.

def columnLeft( self, columnIndex ):

This will return the left side y position of the console columns at the given index, in clip space.

Parameters:
columnIndex index to a column of text in the console.

Returns:
left side x position to the column, in clip space.

def prints( self, str ):

This function renders a string to the console at the position specified by the editRow and editCol attributes.

Note that if, immediately after calling the prints function, the cursor position is not updated then the next tick will overwrite the string with the editText.

Parameters:
str the string to print to the console.

def rowTop( self, rowIndex ):

This will return the upper y position of the console row at the given index, in clip space.

Parameters:
rowIndex index to a row of text in the console.

Returns:
upper y position to the row, in clip space.

def toggleFontScale (deprecated)( self ):

This will toggle between using a fixed size font and scaling the font to fit the current window size. Scaling is off by default.

Note: this function has been deprecated in favor of font size matching. Please, refer to the class overview for more information.

def visibleHeight( self ):

This will return the number of rows visible for this console in the current screen resolution.

def visibleWidth( self ):

This will return the number of columns visible for this console in the current screen resolution.

Attribute Documentation

characterSize

This attribute represents the size of a character on the screen.

Type:
Read-Only Vector2

cursor

This attribute is the read only position of the cursor, in character coordinates. Character (0,0) is the top left, with the horizontal component first, and the vertical second. Assigning to the attribute does not cause an error, but has no effect.

Type:
Vector2

editCallback

This attribute is a callback function that gets called when the user presses enter when editing. The function should take one argument which is set to the editString as it was when the enter key was pressed.

Type:
Callable Python object, which takes one argument

editCol

This attribute is the vertical position of the cursor, in character coordinates. Zero means the leftmost column of the screen, increasing editRow values refer to positions further to the right.

Assigning to this attribute moves the cursor to the specified column.

Type:
Integer

editColour

This attribute sets the edit line colour.

Type:
Write-Only Vector2

editEnable

This attribute enables editing on the console. If it is non-zero (true) then the cursor is displayed, and user input is accepted. If it is set to zero (false), then the cursor is hidden and user input is not accepted.

Type:
Integer (treated as boolean)

editLineLength

This represents the maximum length of the edit string.

Type:
Integer

editPrompt

This attribute is the prompt that will be displayed before the edit line of the console. The user is not able to move the cursor into the prompt.

Edits to this attribute are effected immediately, changing the prompt on the current edit line.

Type:
String

editRow

This attribute is the vertical position of the cursor, in character coordinates. Zero means the top row of the screen, increasing editRow values refer to positions further down the screen.

Assigning to this attribute moves the cursor to the specified row.

Type:
Integer

editText

This is the text that is currently being edited. It is displayed in the console immediately to the right of the editPrompt. On assignment the text is immediately changed on the screen, moving the editCursor to the end of the string.

Type:
String

lineColour

This write-only attribute is used to set the colour of the line of text specified by the editRow attribute. It takes a Vector4, interpreted as (red, green, blue alpha), where each number should be between 0. and 255.0.

Type:
Write-Only Vector4


CursorCamera - BigWorld client Documentation

CursorCamera Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

BaseCamera → PyObjectPlus

Member Functions

def shake( self, duration, amount ):

Attributes

firstPerson | Integer
inaccuracyProvider | Vector4Provider
limitVelocity | Integer
maxDistHalfLife | Float
maxVelocity | Float
movementHalfLife | Float
pivotMaxDist | Float
pivotMinDist | Float
pivotPosition | Vector3
reverseView | Integer
source | MatrixProvider
target | MatrixProvider
targetMaxDist | Read-Only Float
terrainMinDist | Float
turningHalfLife | Float
uprightDirection | Vector3

Detailed Description

The CursorCamera is a camera that looks at a particular object (specified by the target MatrixProvider attribute), looking in a direction specfied by the source MatrixProvider atrribute. The camera's desired position is pivotMaxDistance behind the target offset by pivotPosition, which is a Vector3 which gets interpreted in the source-space. After the desired position has been offset by pivotPosition, it is then clipped to the geometry, and moved forwards along the source z-axis if necessary to give it a clear line of site to the target position.

The desired position is where the camera will move towards being. If either the target moves, or one of the parameters to the CursorCamera change, then it may no longer be in this position, at that point, it will start moving towards it. If the maxVelocity attribute is non-zero, then its movement speed is limited to be no more than maxVelocity. In addition the movementHalfLife attribute specifies how long it will take to move half the distance from its current position to the desired position. Thus, it will slow down as it approaches the desired position, approaching it smoothely.

It is also possible to set the camera to firstPerson mode, where it sits exactly on the target position and looks in the source direction.

A new CursorCamera is created using BigWorld. CursorCamera function.

Member Function Documentation

def shake( self, duration, amount ):

This function causes the camera to start shaking for the specified period. The amount vector specifies the direction and magnitude (in source space) to move the camera.

If shake is called before a previous shake has finished, it overwrites the existing shake.

Parameters:
duration | a float specifying the time (in seconds) to shake for.
amount | a vector3 specifying the direction and magnitude of the shaking.

Returns:
None

Attribute Documentation

firstPerson

If this is set to non-zero, then the camera will sit at the target position, rather than behind it. This will make it look like first person view, rather than the usual third person. It defaults to 0 (third person view).

Type:
Integer

inaccuracyProvider

If this is set to non-NULL, then the camera will tick the given Vector4Provider and use the x,y values as yaw,pitch adjustments. an example use for this is implementing an unsteady sniper rifle scope.

Type:
Vector4Provider

limitVelocity

This attribute, if set to non-zero prevents the camera moving faster than maxVelocity when trying to return to its desired position. Once it reaches its desired position, limitVelocity is automatically set to 0.

The movementHalfLife attribute specifies how long the camera should take to move half the distance between its current position and its desired position. As long as this gives a speed which is less than maxVelocity then limitVelocity has no efect. However, if the limitVelocity is non-zero, and maxVelocity is less than this desired speed, then the camera speed will be limited to maxVelocity.

Type:
Integer

maxDistHalfLife

This attribute is the half life with which the difference between targetMaxDist and pivotMaxDist is decayed.

Type:
Float

maxVelocity

The maximum speed that the camera can move at when trying to return to its desired position. This is only used if limitVelocity is non-zero.

Type:
Float

movementHalfLife

The time it takes for the camera to move half the distance from its current position to its desired position. This is used every tick to update the velocity the camera is moving at so that it slows down as it approaches its desired position.

The desired position is pivotMaxDistance behind the target back along the direction specified by source. This point is offset by pivotPosition, and then clipped to geometry, and moved forwards along the z-axis if neccessary to give a clear view of the target

Type:
Float

pivotMaxDist

This attribute specifies how far behind the target the camera wants to sit. It is measured backwards along the line specified by the source attribute. When it is set to a new value, that value will not actually be reached immediately, rather it will be smoothly approached with a half life of maxDistHalfLife.

Type:
Float

pivotMinDist

This attribute has been deprecated, and no longer performs a useful function.

Type:
Float

pivotPosition

The pivotPosition is an offset from the position pivotMaxDistance behind the target on the source line. The calculation of the desired camera position is done as follows. The source MatrixProvider specifies a direction. If pivotPosition is (0,0,0) then the camera position is pivotMaxDistance back along this direction from the target. If pivotPosition in something else, then it is used as an offset from this point, with increasing x moving it to the right of the target, increasing y moving it up from the target and increasing z moving it towards the target.

After the desired position has been offset by pivotPosition, it is then clipped to the geometry, and moved forwards along the z-axis if necessary to give it a clear line of site to the target position.

The desired position is where the camera will move towards being. If either the target moves, or one of the parameters to the CursorCamera change, then it may no longer be in this position, at that point, it will start moving towards it. If the maxVelocity attribute is non-zero, then its movement speed is limited to be no more than maxVelocity. In addition the movementHalfLife attribute specifies how long it will take to move half the distance from its current position to the desired position. Thus, it will slow down as it approaches the desired position, approaching it smoothely.

Type:
Vector3

reverseView

If this is set to non-zero, then the camera will be in front of the target looking backwards, rather than behind looking forwards. It defaults to zero.

Type:
Integer

source

The source is a MatrixProvider, which supplies the direction for the camera to look in. It will look at the position specified in the target attribute, along the orientation specified in this attribute.

Type:
MatrixProvider

target

The target is a MatrixProvider, which supplies the location of the object to look at. The rest of the matrix is not used, only the position components.

Type:
MatrixProvider

targetMaxDist

This attribute returns the target maximum distance from the pivot, set the last time that pivotMaxDist was changed.

Type:
Read-Only Float

terrainMinDist

This attribute has been deprecated, and no longer performs a useful function.

Type:
Float

turningHalfLife

The time in seconds it takes for the camera to turn half the angle from its current line behind the target to the line specified by source.

Type:
Float

uprightDirection

The direction which the camera treats as up, relative to the source frame of reference. By default it is (0,1,0).

Type:
Vector3


DataSection - BigWorld client 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


Debug - BigWorld client Documentation

Debug Class Reference

[PostProcessing Module]

Debug is part of the PostProcessing module. More...

import PostProcessing

Parent Classes

PyObjectPlus

Member Functions

def phaseUV( self, effect, phase, nEffects, nPhases ):

Attributes

renderTarget PyRenderTarget.

Detailed Description

This class records each step of the entire PostProcessing chain into a render target, allowing you to see every single step.

This kind of debugging is required as the individual phases in the PostProcessing chain may (and should) be re-using render targets.

Member Function Documentation

def phaseUV( self, effect, phase, nEffects, nPhases ):

This method returns the texture coordinates for the given effect/phase pair, packed into a Vector4 as ( bl.x, bl.y, tr.x, tr.y ), or l, b, r, t )

Parameters:
effect | index of the effect within the PostProcessing chain
phase | index of the phase within the effect
nEffects | number of effects
nPhases | number of phases within the desired effect

Returns:
Vector4 packed uv coordinates of the phase

Attribute Documentation

renderTarget

The Debug object requires a render target to do its work. With this attribute you can provide the Debug object with a render target of whatever size and format you like.

Type:
PyRenderTarget.


DiffDirProvider - BigWorld client Documentation

DiffDirProvider Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

MatrixProvider → PyObjectPlus

Attributes

source | Read-Write MatrixProvider.
target | Read-Write MatrixProvider.

Detailed Description

This is a MatrixProvider which provides a matrix representing the direction between the points specified by two matrices. An instance of this class can be created via the factory method BigWorld. DiffDirProvider.

It is not possible to directly access many of the internal attributes of a DiffDirProvider. To view this data it is necessary to construct a Matrix which is a copy of this, & read the values from it. For example:
# create a DiffDirProvider which points in the same direction as the
# translation of matrix2 minus the translation of matrix1
ddp = BigWorld.DiffDirProvider( matrix1, matrix2 )

# create a Matrix from the DiffDirProvider
m = Math.Matrix( ddp )

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

Instances of this class are typically used in conjunction with a Tracker to cause nodes in a model to point towards something. For example, this could be used to cause a character to turn it's head so as to look at another object.

Attribute Documentation

source

Gives the position from which the matrix this provides points.

Type:
Read-Write MatrixProvider.

target

Gives the position towards which the matrix this provides points.

Type:
Read-Write MatrixProvider.


DirectionCursor - BigWorld client Documentation

DirectionCursor Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

InputCursor → PyObjectPlus

Member Functions

def forceLookSpring( self ):
def yawPitch( self, yaw, pitch ):

Attributes

invertVerticalMovement | Integer
lookSpring | Integer
lookSpringIdleTime | Float
lookSpringOnMove | Integer
lookSpringRate | Float
matrix | Read-Only MatrixProvider
maxPitch | Float
maxYaw |
minPitch | Float
minYaw |
mouseHVBias | Float
mouseSensitivity | Float
pitch | Float
roll | Float
yaw | Float
yawReference |

Detailed Description

The DirectionCursor object acts as a view target for the player entity. It accepts mouse events and represents its direction based on the update. It is represented as a direction vector from the origin intersecting a point on a sphere centered on the origin.

The origin represents the observer's eyes in local coordinate space. The direction represents the line of sight along observer's view direction.

The attributes of the direction cursor receive their default values from the <directioncursor> section of engine_config.xml.

You can obtain the direction cursor using the function BigWorld.dcursor()

Member Function Documentation

def forceLookSpring( self ):

This function forces a return to a neutral pitch

Returns:
None

def yawPitch( self, yaw, pitch ):

This function gets and optionally sets the yaw and pitch of the direction cursor. It takes 0, 1 or 2 arguments. If one argument is supplied, it is the new yaw. If Two arguments are supplied, they are the yaw and pitch. It returns a list of the yaw and the pitch in all cases.

Parameters:
yaw | (optional) The new yaw for the direction cursor
pitch | (optional) The new pitch for the direction cursor

Returns:
a list with the first element being the yaw, and the second being the pitch

Attribute Documentation

invertVerticalMovement

If this attribute is set to 0, then moving the mouse upward causes the pitch of the DirectionCursor to increase (ie look upwards more), and down causes it to decrease. For any other value, moving the mouse up causes the pitch of the DirectionCursor to decrease (ie look downwards more), and down to increase.

Type:
Integer

lookSpring

This attribute determines whether or not the pitch reverts to 0 once lookSpringIdleTime has elapsed, with no further changes to the DirectionCursor. If it is set non-zero, then, once lookSpringIdleTime has elapsed, it will move towards zero at lookSpringRate. If it is zero, then the DirectionCursor's pitch will remain where it was set, unless lookSpringOnMove is non-zero at which point, the pitch reverts to zero.

Like all DirectionCursor attributes, its default is read in from engine_config.xml.

Type:
Integer

lookSpringIdleTime

This is the time (in seconds) that the rotation of the DirectionCursor must remain unchanged before it starts restoring its pitch to zero. This will only happen if the lookSpring flag is non-zero.

Like all DirectionCursor attributes, its default is read in from engine_config.xml.

Type:
Float

lookSpringOnMove

If this attribute is set to true, then if the origin of the DirectionCursor is changed, the pitch will start moving towards zero at lookSpringRate radians per second.

Like all DirectionCursor attributes, its default is read in from engine_config.xml.

Type:
Integer

lookSpringRate

This attribute is the rate (in radians per second) at which the pitch of the DirectionCursor restores itself to zero, if it decides to do lookSpring behaviour. This will happen either if lookSpring is true, and lookSpringIdleTime has elapsed, or if lookSpringOnMove is true, and the DirectionCursor's origin is changed.

Like all DirectionCursor attributes, its default is read in from engine_config.xml.

Type:
Float

matrix

The transformation matrix which sums up the location and orientation of the direction cursor. The pitch, yaw and roll, as well as the origin are all stored inside this.

Type:
Read-Only MatrixProvider

maxPitch

This is an upper bound for pitch. It is only checked when a mouse movement attempts to change the pitch. That is, if maxPitch is assigned to be less than the current pitch, then pitch will not automatically change to be within bounds. Similarly, if pitch is assigned a value above maxPitch, the limit will not be applied until the user moves the mouse.

Like all DirectionCursor attributes, its default is read in from engine_config.xml. However, in the cofig file, it is specified in degrees, while in python, it is in radians.

Type:
Float

maxYaw

This attribute is the maximum yaw that the direction cursor will go to. Only checked if yawReference is set. Positive yaw values are on the right of yawReference as seen from above.

minPitch

This is a lower bound for pitch. It is only checked when a mouse movement attempts to change the pitch. That is, if minPitch is assigned to be greater than the current pitch, then pitch will not automatically change to be within bounds. Similarly, if pitch is assigned a value below minPitch, the limit will not be applied until the user moves the mouse.

Like all DirectionCursor attributes, its default is read in from engine_config.xml. However, in the cofig file, it is specified in degrees, while in python, it is in radians.

Type:
Float

minYaw

This attribute is the minimum yaw that the direction cursor will go to. Only checked if yawReference is set. Negative yaw values are on the left of yawReference as seen from above.

mouseHVBias

This effects whether the mouse is more sensitive in the Horizontal or Vertical directions. It is clamped to be between 0 and 1, with 1 meaning horizontal motion is greatest, and vertical is completely disregarded, and 0 meaning vertical motion is most sensative, with horizontal being disregarded. To make both axes more sensitive use the mouseSensitivity attribute.

Like all DirectionCursor attributes, its default is read in from engine_config.xml

Type:
Float

mouseSensitivity

How sensitive the DirectionCursor is to mouse movements. Higher numbers mean more sensative. This effects both horizontal and vertical sensitivity. In order to change the ratio of sensativity between horizontal and vertical, use the mouseHVBias.

Like all DirectionCursor attributes, its default is read in from engine_config.xml

Type:
Float

pitch

The pitch (whether it is tipped up or down) of the direction cursor. Positive numbers are looking upwards, negative are looking downwards. If this is set, then the direction cursor moves to the new pitch at 0.5 radians per second, rather than just popping.

Type:
Float

roll

The roll (whether it is tipped to the left or the right) of the direction cursor. If this is set, then the direction cursor moves to the new pitch at 0.5 radians per second, rather than just popping.

Type:
Float

yaw

The yaw (rotation around the Y-axis) of the direction cursor. If this is set, then the direction cursor moves to the new pitch at 0.5 radians per second, rather than just popping.

Type:
Float

yawReference

This attribute is the matrix whose direction is used as a reference when enforcing the min/max yaw limits.


DumbFilter - BigWorld client Documentation

DumbFilter Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Filter → PyObjectPlus

Detailed Description

This subclass of the Filter class simply sets the position of the entity to the most recent position specified by the server, performing no interpolation. It ignores position updates which are older than the current position of the entity.

A new DumbFilter can be created using BigWorld. DumbFilter function.


Effect - BigWorld client Documentation

Effect Class Reference

[PostProcessing Module]

Effect is part of the PostProcessing module. More...

import PostProcessing

Parent Classes

PyObjectPlus

Attributes

bypass | Vector4Provider.
name | String.
phases | List.

Detailed Description

This class allows the post-processing manager to work with a generic list of effects; it also ensures that all effects are python objects.

Attribute Documentation

bypass

Type:
Vector4Provider.

name

Type:
String.

phases

This attribute represents the individual phases within an effect. It is managed as a list, so you can add, remove and re-order the phases within the effect.

Type:
List.


Entity - BigWorld client Documentation

Entity Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def addModel( self, model ):
def addTrap( self, radius, function ):
def delModel( self, model ):
def delTrap( self, trapID ):
def hasTargetCap( self, targetCap ):
def prints( self, string ):
def setInvisible( self, invisible ):
def setPortalState( self, permissive, triFlags ):

Callback Methods

def boidsLanded( self ):
def enterWorld( self ):
def leaveWorld( self ):
def onBecomeNonPlayer( self ):
def onBecomePlayer( self ):
def onControlled( self, isControlled ):
def onEnterSpace( self ):
def onEnterWorld( self ):
def onGeometryMapped( self, spaceName ):
def onLeaveSpace( self ):
def onLeaveWorld( self ):
def onRestore( self, position, direction, spaceID, vehicleID, dict ):
def prerequisites( self ):
def reload( self ):
def targetBlur( self, The ):
def targetFocus( self, The ):
def targetModelChanged( self ):

Attributes

base | Read-Only PyBase
cell | Read-Only PyServer
filter | Filter
id | Read-Only float
inWorld | Read-Only bool
isClientOnly | Read-Only Boolean
isPoseVolatile | Read-Only bool
matrix | Read-Only EntityMProv
model | Read-Only PyModel
models | list of PyModels
physics | Write-Only int/Physics
pitch | Read-Only float
position | Read-Only Vector3
roll | Read-Only float
server | Read-Only PyServer
spaceID | Read-Only int
targetCaps | list of integers
targetFullBounds | bool
vehicle | Read-Only Entity
yaw | Read-Only float

Detailed Description

This is the Client component of the Distributed Entity Model. It is responsible for handling the visual aspects of the Entity, updates from the server, etc...

It is possible to create a client-only Entity using BigWorld.createEntity function.

Member Function Documentation

def addModel( self, model ):

This function adds a PyModel to this Entity's list of usable Models

Parameters:
model (PyModel) The PyModel to add to the list

Returns:
(none)

def addTrap( self, radius, function ):

This function adds a sphere of awareness around this Entity, invoking a callback method whenever the contents of the Trap changes. The callback method is provided upon creation of the Trap and should have the following prototype;

def trapCallback( self, entitiesInTrap ):

The "entitiesInTrap" argument is a list containing references to the entities contained inside the trap.

BigWorld.addPot is a cheaper method that only works for players.

See:
BigWorld.addPot

Parameters:
radius | (float) The radius of the sphere around this Entity
function | (float) The callback function

Returns:
(integer) The ID of the newly created Trap

def delModel( self, model ):

This function removes a PyModel to this Entity's list of usable Models

Parameters:
model (PyModel) The PyModel to remove from the list

Returns:
(none)

def delTrap( self, trapID ):

This function removes a Trap (sphere of Entity awareness) from around the player.

Parameters:
trapID (float) The ID of the Trap to remove

Returns:
(none)

def hasTargetCap( self, targetCap ):

This function checks whether this Entity has the given target capability.

Parameters:
targetCap (int) The targeting capability to check against

Returns:
(bool) Returns true if capability matches, false otherwise

def prints( self, string ):

This function writes the Entity's ID, followed by the given string to the BigWorld console

Parameters:
string (string) The string to display in the console

Returns:
(none)

def setInvisible( self, invisible ):

This function fades the visibility of the player in and out. It can only be called on a Player entity.

Raises a TypeError if this method is not called on the player entity.

Parameters:
invisible (bool) True to make Entity invisible, False to make it reappear

def setPortalState( self, permissive, triFlags ):

The position of the entity must be within 1 metre of the portal that is to be configured, otherwise the portal will probably not be found. No other portal may be closer.

The cell entity has an identical method. This also adds an object into the collision scene and disables navigation through the doorway when the portal is closed.

Parameters:
permissive | Whether the portal is open or not.
triFlags | Optional argument that sets the flags on the portal's triangles as returned from collision tests.

Callback Method Documentation

def boidsLanded( self ):

This callback method is called on entities using the boids filter. It lets the entity know when the boids have landed. A typical response to this notifier is to delete the boids models.

See:
BigWorld.BoidsFilter

def enterWorld( self ):

This method is called when the entity enters into the player's AoI. On the client, this means that the entity has just been placed in the world. Most of the entity's initialisation code should be placed in this method instead of the entity's __init__ method because at the time that the __init__ method is called the entity has not been placed in the world. Furthermore, the enterWorld method can be called multiple times for the same entity because the entity is reused if it exits the player's AoI and re-enters it within a short period of time.

This callback has been deprecated, instead use onEnterWorld.

The leaveWorld method is called when the entity leaves the AoI.

def leaveWorld( self ):

This function is called when the entity leaves the player's AoI. On the client, this means that the entity is about to be removed from the world. The entity may not be destroyed immediately after this call. The same entity may be re-used if it re-enters the player's AoI a short time after leaving.

This callback has been deprecated, instead use onLeaveWorld.

def onBecomeNonPlayer( self ):

This callback method is called in response to a call to BigWorld.player() It signals that an entity is no longer the player, and its script is just about to become an instance its original class, instead of the player avatar class.

See:
BigWorld.player
Entity.onBecomePlayer

def onBecomePlayer( self ):

This callback method is called in response to a call to BigWorld.player() It signals that an entity has become the player, and its script has become an instance of the player class, instead of its original avatar class.

See:
BigWorld.player
Entity.onBecomeNonPlayer

def onControlled( self, isControlled ):

This callback method is called when the local entity control by the client has been enabled or disabled. See the Entity.controlledBy() method in the CellApp Python API for more information.

Parameters:
isControlled Whether the entity is now controlled locally.

def onEnterSpace( self ):

This function is called when the entity changes space. This can occur, for example, when other entities teleport between spaces with the player entity.

def onEnterWorld( self ):

This method is called when the entity enters into the player's AoI. On the client, this means that the entity has just been placed in the world. Most of the entity's initialisation code should be placed in this method instead of the entity's __init__ method because at the time that the __init__ method is called the entity has not been placed in the world. Furthermore, the enterWorld method can be called multiple times for the same entity because the entity is reused if it exits the player's AoI and re-enters it within a short period of time.

It has a PyResourceRefs object passed in as the first parameter. This object holds onto the prerequisites that were loaded from the prerequisites method. It is up to the script programmer to manage the lifetime of the prerequisites.

The leaveWorld method is called when the entity leaves the AoI.

def onGeometryMapped( self, spaceName ):

This callback method tells the player entity about changes to the geometry in its current space. It is called when geometry is mapped into the player's current space. The name of the spaces geometry is passed in as a parameter

Parameters:
spaceName name describing the space's geometry

def onLeaveSpace( self ):

This function is called when the entity changes space. This can occur, for example, when other entities teleport between spaces with the player entity.

def onLeaveWorld( self ):

This function is called when the entity leaves the player's AoI. On the client, this means that the entity is about to be removed from the world. The entity may not be destroyed immediately after this call. The same entity may be re-used if it re-enters the player's AoI a short time after leaving.

def onRestore( self, position, direction, spaceID, vehicleID, dict ):

This callback method informs the player entity to restore itself to a previous state given the description provided by the server.

Parameters:
position | position
direction | direction
spaceID | space
vehicleID | vehicle
dict | dictonary of attributes

def prerequisites( self ):

This callback method is called before the entity enters the world. It asks the entity for a list of resources that are required by the entity. The entity is not added to the world until its prerequisite resources are loaded. The loading of prerequisite resources is done in a background thread, meaning that entities can thus enter the world without causing a loading pause to the main rendering thread.

The entity should return a tuple of resource IDs that represent its list of prerequisites.

def reload( self ):

This callback method is called in response to reloading scripts. It allows the entity to reload itself, and attach itself to its associated objects again.

def targetBlur( self, The ):

This callback method is called in response to a change in the targeted entity. It notifies the player that an entity has is no longer the current target.

Parameters:
The orginially targetted entity.

def targetFocus( self, The ):

This callback method is called in response to a change in the targeted entity. It notifies the player that an entity has just become the current target.

Parameters:
The newly targetted entity.

def targetModelChanged( self ):

This callback method is invoked on the player entity when the primary model of currently targeted entity has changed. This allows the player script to reset any trackers, gui components or special effects refering to the targets old model.

The currently targetted entity is passed as a parameter.

Attribute Documentation

base

Communicates with Base component if Base is Proxy, otherwise this attribute is not available.

Type:
Read-Only PyBase

cell

Communicates with Cell component of this Entity.

Type:
Read-Only PyServer

filter

Movement interpolation filter for this Entity.

Type:
Filter

id

Unique Entity identifier, shared across Cell, Base and Client

Type:
Read-Only float

inWorld

True when Entity is in the world (ie, added to a BigWorld Space), false when it is not

Type:
Read-Only bool

isClientOnly

This property is True if it is a client-only entity.

Type:
Read-Only Boolean

isPoseVolatile

On initialisation, if the definition for this Entity includes a volatile clause, this attribute will be true. If the components of the volatileInfo attribute on the Cell entity are cleared, then this value will become false and the onPoseVolatile notification method will be triggered. This is defined as follows:
    def onPoseVolatile( self, isVolatile ):
where isVolatile will be false (0). The notfication method will also be called when the volatileInfo attribute is set after being cleared. In this case, isVolatile will be true. This method is also called when control of the entity's position by this client is granted or withdrawn, for both server-side entities and client-side entities. They can be distinguished by checking if the 'physics' attribute is available. (It is not called in this case for the Player entity as the client always controls it)

Type:
Read-Only bool

matrix

Current matrix representation of this Entity in the world.

Type:
Read-Only EntityMProv

model

Current Model visible to user

Type:
Read-Only PyModel

models

List of PyModels attached to Entity

Type:
list of PyModels

physics

When this Entity becomes controlled, this attribute becomes available to allow a Physics object to be attached to this Entity. The physics attribute is not available if this Entity is not controlled. See BigWorld.controlEntity().

Assigning an int representing one of the supported physics styles to the physics property of an entity creates and attaches a Physics object to the entity. The constants for the different physics styles are accessible in the BigWorld module.

Current physics styles are as follows:

STANDARD_PHYSICS: Suitable for player, other controlled animals, etc. HOVER_PHYSICS: Hovering vehicle physics. CHASE_PHYSICS: Causes controlled Entity to follow exact movements of Entity being chased. Has no effect unless Physics::chase() activated. TURRET_PHYSICS: Useful for controlled turrets, guns, etc.

Other custom physics can be integrated into BigWorld and assigned their own integer creation flag. Once set, the appropriate physics module will be created and assigned to this attribute. The appropriate Physics style can then be accessed through this attribute.

Type:
Write-Only int/Physics

pitch

Current pitch of Entity

Type:
Read-Only float

position

Current position of Entity in world

Type:
Read-Only Vector3

roll

Current roll of Entity

Type:
Read-Only float

server

Communicates with Cell component of this Entity. Deprecated: The cell attribute should be used instead.

Type:
Read-Only PyServer

spaceID

Stores ID of BigWorld Space in which this Entity resides

Type:
Read-Only int

targetCaps

Stores the current targeting capabilities for this Entity. These will be compared against another set of targeting capabilities to determine whether this Entity should be included in a list of potential targets.

Type:
list of integers

targetFullBounds

If true, targeting uses the full bounding box of this Entity. This, however, will allow the player to target an entity using the extreme corners of the bounding box (which may be out in the middle of open space). Setting this to false will shrink the bounding box used for testing, and will also only select the entity if two points on the bounding box (one at the top and one at the bottom) are visible.

See the watcher values "Client Settings/Entity Picker/Lower Pct." and "Client Settings/Entity Picker/Sides Pct." for the shrink amount control factors.

Type:
bool

vehicle

Stores the vehicle Entity to which this Entity is attached. None if not on vehicle.

Type:
Read-Only Entity

yaw

Current yaw of Entity

Type:
Read-Only float


EntityDirProvider - BigWorld client Documentation

EntityDirProvider Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

MatrixProvider → PyObjectPlus

Attributes

pitchIndex | Read-Write Integer.
source | Read-Write Entity.
yawIndex | Read-Write Integer.

Detailed Description

This is a MatrixProvider which provides a matrix with the direction an entity faces. An instance of this class can be created via the factory method BigWorld. EntityDirProvider.

It is not possible to directly access many of the internal attributes of an EntityDirProvider. To view this data it is necessary to construct a Matrix which is a copy of this, & read the values from it. For example:
# create an EntityDirProvider which provides the direction faced by the
# entity anEntity
edp = BigWorld.EntityDirProvider( anEntity, 1, 0 )

# create a Matrix from the EntityDirProvider
m = Math.Matrix( edp )

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

Instances of this class are typically used in conjunction with a Tracker to turn nodes in a model towards an entity's facing direction.

Attribute Documentation

pitchIndex

The index of the entity's axis which is to be interpreted as pitch (0:yaw, 1:pitch, 2:roll).

Type:
Read-Write Integer.

source

The entity whose facing direction this provides.

Type:
Read-Write Entity.

yawIndex

The index of the entity's axis which is to be interpreted as yaw (0:yaw, 1:pitch, 2:roll).

Type:
Read-Write Integer.


EntityMProv - BigWorld client Documentation

EntityMProv Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

MatrixProvider → PyObjectPlus

Attributes

notModel bool

Detailed Description

This is a special MatrixProvider for an Entity. It is useful if the Entity and Model matrix differ.

Attribute Documentation

notModel

If the Model and entity position are expected to be different throughout the course of their respective lifetimes, then this attribute can be used to flag which should be regarded as the authoritative in-game position. If true, this MatrixProvider will track the Entity's matrix; If false, it will always provide the Model's. It can be changed at any time to switch between the two and defaults to false, since the Model is the visual representation of the Entity on the Client.

Type:
bool


EventCategory - BigWorld client Documentation

EventCategory Class Reference

[FMOD Module]

EventCategory is part of the FMOD module. More...

import FMOD

Member Functions

def stopAllEvents( self ):

Attributes

muted | Read-write boolean
muted | Read-write boolean
pitch | Read-write float
volume | Read-write float

Detailed Description

An EventCategory is a wrapper for an FMOD::EventCategory, and is a virtual folder used to organize event data into generic categories such as music. Allows volume and pitch changes to be applied to all events within the group.

For more information about event categories and how they are used, please see the FMOD Designer API documentation and the FMOD Designer User Manual, both available from www.fmod.org.

Member Function Documentation

def stopAllEvents( self ):

Stops all events in this category and subcategories.

Attribute Documentation

muted

Determines whether or not events in this category are currently muted.

Type:
Read-write boolean

muted

Determines whether or not events in this category are currently paused.

Type:
Read-write boolean

pitch

The pitch modification for this event category (0.0 is normal pitch).

Type:
Read-write float

volume

The overall volume for this event category (0.0 is silent, 1.0 is full volume).

Type:
Read-write float


EventGroup - BigWorld client Documentation

EventGroup Class Reference

[FMOD Module]

EventGroup is part of the FMOD module. More...

import FMOD

Member Functions

def loadEventData( self, Optional ):

Attributes

isLoaded | Read-only boolean
isPlaying | Read-only boolean
memoryUsed | Read-only unsigned integer

Detailed Description

An EventGroup is a wrapper for an FMOD::EventGroup, and provides an interface to control the loading and unloading of data by group. Groups are created using the event hierachy in the FMOD Designer tool.

Please see the FMOD Designer API documentation and the FMOD Designer User Manual, both are located in your FMOD install directory.

Member Function Documentation

def loadEventData( self, Optional ):

Loads the resources for all events within an event group.

Parameters:
Optional Bool whether or not the client should block until the events have been loaded. Defaults to true.

Attribute Documentation

isLoaded

Whether this group is currently loading.

Type:
Read-only boolean

isPlaying

Whether this group contains any events which are currently playing.

Type:
Read-only boolean

memoryUsed

Memory used by this event group.

Type:
Read-only unsigned integer


EventProject - BigWorld client Documentation

EventProject Class Reference

[FMOD Module]

EventProject is part of the FMOD module. More...

import FMOD

Member Functions

def freeEventData( self ):
def release( self ):
def stopAllEvents( self, Bool ):

Attributes

memoryUsed Unsigned Int

Detailed Description

An EventProject is a wrapper for an FMOD::EventProject.

Please see the FMOD Designer API documentation and the FMOD Designer User Manual, both are located in your FMOD install directory.

Member Function Documentation

def freeEventData( self ):

Frees the resources for an EventGroup and all subgroups under it.

def release( self ):

Release this event project and all the events/eventgroups that it contains. This object * will no longer be valid once this is called.

def stopAllEvents( self, Bool ):

Stop all events in

Parameters:
Bool immediately stop all sounds ignoring the "Fadeout time" property

Attribute Documentation

memoryUsed

Memory used by this event project.

Type:
Unsigned Int


EventReverb - BigWorld client Documentation

EventReverb Class Reference

[FMOD Module]

EventReverb is part of the FMOD module. More...

import FMOD

Attributes

active | Read-write boolean
maxDistance | Read-write float
maxDistance | Read-write float
position | Read-write Vector3
source | Read-write MatrixProvider

Detailed Description

A EventReverb provides access to FMOD Event Reverbs.

Attribute Documentation

active

Activates/deactivates this reverb effect within the 3D world.

Type:
Read-write boolean

maxDistance

The minimum distance the listener has to be to this reverb object before the reverb effect is applied at full volume.

Type:
Read-write float

maxDistance

The maximum distance at which the reverb affects the listener. The reverb effect is not audible outside this radius.

Type:
Read-write float

position

The centre position of the reverb. This is overwritten with the output of the source attribute if it has been specified.

Type:
Read-write Vector3

source

The matrix provider which will be used to determine the location of the reverb within the world. This overwrites the position attribute.

Type:
Read-write MatrixProvider


Filter - BigWorld client Documentation

Filter Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def reset( self, time ):

Detailed Description

This is the abstract base class for all Filter objects. Filters are used to interpolate volatile data of entities (the position and the orientation) between server updates of these variables.

The only functionality defined in the base class is the reset function, which resets the filter to have its current time set to the specified time.

Every entity has a filter attribute. Assigning a filter to that attribute sets that entity to be the owner of the specified filter. This will make the filter process server updates for that entity.

Member Function Documentation

def reset( self, time ):

This function resets the current time for the filter to the specified time.

Filters use the current time to interpolate forwards the last update of the volatile data from the server. Setting this time to a different value will move all entities to the place the filter thinks they should be at that specified time.

As a general rule this shouldn't need to be called.

Parameters:
time a Float the time to set the filter to.


FlashGUIComponent - BigWorld client Documentation

FlashGUIComponent Class Reference

[GUI Module]

FlashGUIComponent is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Attributes

movie PyMovieView

Detailed Description

The FlashGUIComponent is a GUI component used to display a flash movie on the screen. It inherits from SimpleGUIComponent.

It delegates all drawing, input handling to flash. It can have an associated python script, like any gui components.

The flash movie will draw within the bounds of this gui component.

A new FlashGUIComponent is created using the GUI.Flash function.

For example:
mvDef = Scaleform.createMovie( "scaleform/flash_ui.swf" )
g = GUI.Flash( mvDef.createInstance() )
GUI.addRoot( g )
setattr( g.movie, "_root.actionScriptVariable", "hello world" )
g.movie.invoke( "_root.OpenMenuLevel2" )

This example creates and displays a FlashGUIComponent, sets and action script text variable to "hello world" then calls an action script function via the invoke() call.

Attribute Documentation

movie

The Scaleform movie view used by this GUI component.

Type:
PyMovieView


FlashTextGUIComponent - BigWorld client Documentation

FlashTextGUIComponent Class Reference

[GUI Module]

FlashTextGUIComponent is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Member Functions

def reset( self ):
def stringDimensions( self, text ):
def stringWidth( self, text ):

Attributes

explicitSize | Boolean
font | String
fontSize |
multiline |
text | String
underline |
wordWrap |

Detailed Description

The FlashTextGUIComponent is a GUI component used to display text on the screen. It inherits from SimpleGUIComponent.

It uses the Scaleform DrawTextAPI to display the text. It can display text in various fonts, and can have its text assigned dynamically.

A new FlashTextGUIComponent is created using the GUI.FlashText function.

For example:
tx = GUI.FlashText( "hello there" )
GUI.addRoot( tx )
tx.text = "goodbye"
This example creates and displays a FlashTextGUIComponent with the text "hello there", and then changes it to say "goodbye" immediately afterwards.

Member Function Documentation

def reset( self ):

This method resets the FlashTextGUIComponent if it has become dirty. This method is useful if you change the text label, and then immediately in the python script you wish to read out the labels new size. If you don't call reset, then the label size will only be recalculated when the label is next updated and drawn.

def stringDimensions( self, text ):

This function returns a 2-tuple containing the dimensions (in pixels) that the specified string will take when rendered to the FlashTextGUIComponent using its current font.

Parameters:
text The string to measure the length and height of.

Returns:
A 2-tuple of integers, the render width and height of the string in pixels.

def stringWidth( self, text ):

This function returns the width (in pixels) that the specified string will take when rendered to the FlashTextGUIComponent using its current font.

Parameters:
text The string to measure the length of.

Returns:
An integer, the rendered width of the string in pixels.

Attribute Documentation

explicitSize

This attribute specifies whether the text component will resize itself to fit exactly within the given text dimensions, or whether the size of the component automatically resizes to reflect the best on-screen size (default)

If this flag is turned off (default) the text component resizes itself such that exactly one texel equals one pixel on-screen, for the clearest possible text. In this instance, width and height are read-only properties, and are correct after the text label is set, or the screen resolution has changed.

If this flag is turned on, the text component will draw itself into the given dimensions. This may result in text with an incorrect aspect ratio. In this instance, width and height are read/write.

When the flag is turned on, setting either the width or the height to 0 will maintain the correct aspect ratio. After setting the width or height to 0, the width and height attributes will update to reflect the actual size of the text.

When the flag is turned on, setting both width and height to 0 will set the text to the optimal size (one texel = one pixel). In order to do this, the width and height must be set at the same time, i.e. you must use textComponent.size = (0,0)

Type:
Boolean

font

This attribute specifies the path to the font file that is used to render the text.

The font name must be one available in the loaded GFxFont library, this is configured along with your Scaleform initialisation.

For example:
tx = GUI.FlashText( "test" )
tx.font = "default_small"
This example applies the default_small font to the text

Type:
String

fontSize

This attribute sets the font size in points. Scaleform can display a font in any size. Larger font sizes are drawn using geometry instead of textures, and can affect performance adversely if not used with care.

multiline

This attribute deteremines whether or not the text string is drawn across multiple lines.

text

The text to be displayed in the component. It will be rendered using the font specified in the font attribute. The component will be resized to fit the text, if a new string is assigned to it. It doesn't wrap text, so if the string is too long to fit on the screen it will just extend off the edges.

If multiple lines of text are desired, then multiple GFxTextGUIComponents are required.

Type:
String

underline

This attribute deteremines whether or not the text string should be underlined.

wordWrap

This attribute deteremines whether or not the text string should wrap. This attribute only applies if multiline is also True.


FlexiCam - BigWorld client Documentation

FlexiCam Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

BaseCamera → PyObjectPlus

Attributes

actualDir | Vector3
actualPos | Vector3
positionAcceleration | Float
preferredPitch | Read-Only Float
preferredPos | Vector3
preferredYaw | Read-Only Float
target | MatrixProvider
timeMultiplier | float
trackingAcceleration | float
uprightDir | Vector3
viewOffset | Vector3

Detailed Description

The camera object that follows a particular target. The camera has an actual position and a preferred position relative to the target. The camera's preferred viewing direction is centered on the target minus some offset vector. There is also a current viewing direction for the camera.

As the camera's view and position are not immediately bound to the preferred position and direction, they have accelerations associated with them. These values can also be adjusted.

The default position is the default preferred position for the camera when at rest, that is, it is not being influenced by the character turning or looking around.

A new FlexiCam is created using BigWorld. FlexiCam function.

Attribute Documentation

actualDir

This attribute is the forward direction, in world coordinates, that the camera is facing at the current moment. If it is set, then the camera will move back to pointing at the target (modified by the viewOffset) with a half life of trackingAcceleration.

Type:
Vector3

actualPos

This attribute specifies where, in world coordinates the camera is at the current time. If it is assigned to, it moves the camera to the specified position.

The camera will not neccessarily remain at this position, as it moves towards the position specified by preferredPos relative to its target. It will move at a rate specified by positionAcceleration.

Type:
Vector3

positionAcceleration

This attribute is the half-life for movement from the camera's actualPos to it's desiredPos. That is, it will move half the distance remaining in this time, causing it to slow down as it approaches its desiredPos.

If this is set to zero, then actualPos is always at the desired position.

Type:
Float

preferredPitch

This read-only attribute specifies the camera's preferred pitch, relative to its target. This is calculated directly from the preferredPos attribute.

For example:
>>>	flex.preferredPos = (0,1,-1)
>>>	flex.preferredPitch
-0.78539816339
In the example, we place the camera one unit above and one unit behind the target, which gives it a pitch of -pi/4.

Type:
Read-Only Float

preferredPos

This attribute specifies where the camera positions itself, relative to the targets frame of reference. It is a Vector3. Positive x-component places the camera to the right of the target, negative to the left. Positive y component places the camera above the target negative below. Positive z component places the camera in front of the target, negative behind. Where ever the camera is positioned, it will orient itself to point towards the target.

This attrtibute specifies the camera's "preferred" position. If the target suddenly moves, or preferred position is assigned to, it will move towards this position over positionAcceleration seconds.

Its actual position at all times, whether in the preferred position or not, is specified by actualPos.

Type:
Vector3

preferredYaw

This read-only attribute specifies the camera's preferred yaw, relative to its target. This is calculated directly from the preferredPos attribute.

For example:
>>>	flex.preferredPos = (0,1,-1)
>>>	flex.preferredYaw
0.0
In the example, we place the camera one unit above and one unit behind the target, which gives it a yaw of zero when looking at the target.

Type:
Read-Only Float

target

This attribute is the the MatrixProvider that specifies what position in world coordinates that the FlexiCam should look at, and also specifies the frame of reference that the preferredPos is specified in.

The camera actually looks at the point specified by viewOffset, relative to target.

If the target MatrixProvider is updated, then the camera will move from its actualPos to its preferred position with a half life of positionAcceleration seconds. If it needs to turn to look at the target it will turn with a half life of trackingAcceleration seconds.

Type:
MatrixProvider

timeMultiplier

Before the FlexiCam is updated, the time delta is scaled by this attribute. This scales the speed at which the camera moves and turns.

Type:
float

trackingAcceleration

This attribute is the half-life for turning towards the target point. The target point is specified by viewOffset, interpreted in the frame of reference specified by the target attribute.

Half life means that it turns half the angle between its current direction and the desired direction in this time. This causes it to slow its rate of turn as it approaches the desired direction.

Type:
float

uprightDir

This attribute specifies the axis, in world coordinates that will be vertical on the camera.

Type:
Vector3

viewOffset

This attribute is the offset from target, specified in target coordinates, that the camera moves towards looking at.

It turns towards this target, if it is moved away, with a half-life of trackingAcceleration seconds.

Type:
Vector3


FootTrigger - BigWorld client Documentation

FootTrigger Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyAttachment → PyObjectPlusWithWeakReference

Attributes

dustSource | SourcePSA
footstepCallback | Callable Object
maxLod | Float
odd | Integer

Detailed Description

A FootTrigger is a PyAttachment which can be attached to nodes in a model to test for them hitting the ground. It is capable of both creating particles from a SourcePSA which it stores, and also calling a function on each footstep.

The FootTrigger works by tracking the height of the node it is attached to, relative to a rest position. Whenever this height gets bellow a given threshold, the trigger does a coarse collision test for a potential footstep. The test is performed againt any object in the collision scene which the trigger approaches from above. This includes terrain, shells and static models. It doesn't include entities, however. If the collision test yields true, a footstep is flagged. The threshold level can be set using the field <environment/footprintThreshold> in resources.xml.

In normal biped usage, two would be used, one attached to the right foot node, one to the left. More than two can be used, however, the odd attribute is treated as boolean, so processing of leg specific effects is limited to right and left.

FootTriggers are created by the BigWorld. FootTrigger() function.

Example:
leftTrigger  = BigWorld.FootTrigger( 1 )
rightTrigger = BigWorld.FootTrigger( 0 )
# dustSourcePSA is the particle system action to create the dust
leftTrigger.dustSource =  dustSourcePSA
rightTrigger.dustSource = dustSourcePSA
# model is the model we want to add FootTriggers to
lfoot = model.node( "biped R Foot" )
rfoot = model.node( "biped L Foot" )
lfoot.attach( leftTrigger )
rfoot.attach( rightTrigger )

Attribute Documentation

dustSource

The dustSource attribute is a SourcePSA (The particle system action responsible for creating particles), that will have its SourcePSA.force method called when the foot strikes the ground.

Type:
SourcePSA

footstepCallback

A callback function object, which is called when the foot strikes the ground. The function is supplied with two arguments, the first is the velocity that the model is moving at, the second is a flag which is 0 if it is a right foot, 1 if it is a left foot.

Type:
Callable Object

maxLod

If the FootTrigger is greater than maxLod away from the camera, it will not be processed or drawn.

Type:
Float

odd

This attribute is used to distinguish between different FootTriggers. It is passed to the callback function as an argument.

Footstep triggers were designed for bipedal use, and it was envisaged that 0, means that this is a right foot, anything else means a left foot. However, it would be possible to interpret it differently.

Type:
Integer


FrameGUIComponent - BigWorld client Documentation

FrameGUIComponent Class Reference

[GUI Module]

FrameGUIComponent is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Attributes

cornerTextureName | A string, which must be the filename of a texture.
edgeTextureName | A string, which must be the filename of a texture.

Detailed Description

This class inherits from SimpleGUIComponent. In addition to the basic (tiled) image displayed by the SimpleGUIComponent, it adds extra images on top to form a frame around the image.

It uses two extra textures. The first is the corner texture, which is split into four quarters, which are rendered in the corresponding corners of the overall component. The width and height of the corners is based on the tiledWidth and tiledHeight attributes of the component.

The second extra texture is the edge texture. This is assumed to be oriented correctly to display along the bottom edge of the FrameGUIComponent. It is then mirrored to display along the top, and rotated to display along either side edge.

The height of the top and bottom edges is specified by the tiledHeight attribute, and the texture is tiled along the top and bottom using the tiledWidth attribute.

The width of the side edges is specified by the tiledWidth attribute, and the texture is tiled long the side edges using the tiledHeight attribute.

The background image is always displayed tiled, using the tiledWidth and tiledHeight attributes. It is rendered across the entire surface of the FrameGUIComponent, with the corners and edges rendered on top of it.

A new FrameGUIComponent is created using GUI.Frame function.

Attribute Documentation

cornerTextureName

This attribute is the name of the texture used on the corners of the FrameGUIComponent. Assigning a filename to this causes the corners to load the named texture.

The specified texture is split into 4 equal quarters, each being a corner. These corners are rendered in the corresponding corner of the FrameGUIComponent. The size of each corner is specified by the tiledWidth and tiledHeight attributes.

Type:
A string, which must be the filename of a texture.

edgeTextureName

This attribute is the name of the texture used on the edges of the FrameGUIComponent. Assigning a filename to this causes the edges to load the named texture.

The specified image is assumed to be oriented correctly to be displayed on the bottom edge. It is mirrored to be displayed on the top edge, and rotated to be displayed on the side edges.

The edge's height on the top and bottom is specified using the tiledHeight attribute, and it is tiled along the top and bottom using the tiledWidth attribute.

The edge's width on the sides is specified using the tiledWidth attribute, and it is tiled along the sides using the tiledHeight attribute.

Type:
A string, which must be the filename of a texture.


FrameGUIComponent2 - BigWorld client Documentation

FrameGUIComponent2 Class Reference

[GUI Module]

FrameGUIComponent2 is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Detailed Description

This class inherits from SimpleGUIComponent. It draws a resizable frame in 1 draw call, using a very specific texture layout. Please see the CCM for diagrams and information on how to author the texture map. A new FrameGUIComponent2 is created using GUI.Frame2 function.


FreeCamera - BigWorld client Documentation

FreeCamera Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

BaseCamera → PyObjectPlus

Attributes

fixed | Integer
invViewProvider | Read-Only MatrixProvider

Detailed Description

A FreeCamera is a camera that can be moved around using the mouse and arrow keys. It doens't have any ties to entities, and doesn't do any physics or geometry checks, so it can be used to easily explore the world.

It processes both mouse and keyboard events, and consumes the events it uses. It consumes: all mouse events, and all key events involving the arrow keys.

It inherits from BaseCamera.

A FreeCamera can be created using the BigWorld. FreeCamera function.

Attribute Documentation

fixed

If this attribute is set to non-zero then the camera remains fixed in position, and does not move in response to the mouse and arrow keys. This can be useful if there is more than one FreeCamera in use, and you only want to move one at once. It defaults to 0, which means it can be moved around.

Type:
Integer

invViewProvider

This attribute is the view matrix for the camera. It is a MatrixProvider.

Type:
Read-Only MatrixProvider


GUIShader - BigWorld client Documentation

GUIShader Class Reference

[GUI Module]

GUIShader is part of the GUI module. More...

import GUI

Parent Classes

PyObjectPlus

Detailed Description

This is the abstract base class for all GUI shaders. A GUI shader is something that you apply to a GUI component, and it modifies the way in which the component is drawn. It also modifies the way that components children are drawn.

GUIShaders are added to components using the SimpleGUIComponent.addShader method and removed using the SimpleGUIComponent.delShader method. All other gui components inherit these from SimpleGUIComponent.


GoboComponent - BigWorld client Documentation

GoboComponent Class Reference

[GUI Module]

GoboComponent is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Attributes

freeze
secondaryTexture

Detailed Description

This GoboComponent acts like other gui components, but blends the gui component texture with another specified PyTextureProvider, using the alpha channel of the component's texture.

If you associate a render target with the gobo component, you can also freeze and unfreeze the secondary PyTextureProvider.

A recommended use of the gobo component is to create a post-processing effect, and use the output of that effect as the second texture stage in the gobo component.

This is for example perfect for binoculars and sniper scopes.

For example, in the following code:

comp = GUI.Gobo( "gui/maps/gobo_binoculars.dds" )
comp.materialFX="SOLID"
comp.secondTexture=myBlurredRenderTarget.texture
GUI.addRoot( comp )

This example will display a binocular gobo, and where the alpha channel is relatively opaque in the binocular texture map, a blurred version of the scene is drawn.

Attribute Documentation

freeze

This attribute, when set to a PyRenderTarget, stows the current state of the secondary TextureProvider and displays it; essentially freezing the current state. To unfreeze, set the render target to None.

secondaryTexture

This attribute provides the second texture that is blended with the component's texture attribute.


GraphGUIComponent - BigWorld client Documentation

GraphGUIComponent Class Reference

[GUI Module]

GraphGUIComponent is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Attributes

frequency | float
gridColour | float
gridSpacing | float
input | Vector4Provider
lineColours | list of Vector4
maxY | float
minY | float
nPoints |
showGrid | float

Detailed Description

The GraphGUIComponent is a GUI component used to display a line graph of a Vector4Provider on the screen.

A new GraphGUIComponent is created using GUI.Graph function.

Attribute Documentation

frequency

This specifies the rate at which the graph will be updated. If frequency is less than 0, the update rate will be in frames (ticks). If it is greater than 0, it will be in seconds. Defaults to 0.033

Type:
float

gridColour

Specifies the colour to use when drawing the background grid. Defaults to (255, 255, 255, 255).

See:
GraphGUIComponent.showGrid
GraphGUIComponent.gridSpacing

Type:
float

gridSpacing

Specifies the grid spacing for the background grid, in pixels. Defaults to 10.

See:
GraphGUIComponent.showGrid
GraphGUIComponent.gridColour

Type:
float

input

This stores the information to be displayed on the screen. The Vector4Provider is represented as 4 line graphs, one for each of the x,y,z,w components.

Example:
import GUI
import Math
g = GUI.Graph( "" )
GUI.addRoot(g)
g.input = Math.Vector4Product()
g.input.a = Math.Vector4LFO()
g.input.b = ( 1.0, 0.8, 0.4, 0.2 )
g.frequency = 0.015
g.nPoints = 100
g.size = (1.5, 1.5)

Type:
Vector4Provider

lineColours

This list configures the colours used to display each line in the graph (maximum of four lines).

Type:
list of Vector4

maxY

Specifies the maximum height that the graph will be displayed on the screen. Value should be between minY and 1.0 (top of screen). Defaults to 1.0

Type:
float

minY

Specifies the minimum height that the graph will be displayed on the screen. Value should be between maxY and 0.0 (bottom of screen). Defaults to 0.0

Type:
float

nPoints

This stores the number of points that will be displayed in the graph. Defaults to 25.

showGrid

Toggles the display of a background grid. Defaults to False.

See:
GraphGUIComponent.gridSpacing
GraphGUIComponent.gridColour

Type:
float


GroundNormalProvider - BigWorld client Documentation

GroundNormalProvider Class Reference

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

Parent Classes

Vector4Provider → PyObjectPlus

Attributes

avatarDropFilter AvatarDropFilter

Detailed Description

This class implements a Vector4Provider to the ground normal of an AvatarDropFilter. It does this by maintaining a weak reference to the filter instance.

Attribute Documentation

avatarDropFilter

This attribute returns the AvatarDropFilter weakly reference by the provider or None if the filter has been destroyed.

Type:
AvatarDropFilter


GuiAttachment - BigWorld client Documentation

GuiAttachment Class Reference

[GUI Module]

GuiAttachment is part of the GUI module. More...

import GUI

Parent Classes

PyAttachment → PyObjectPlusWithWeakReference

Attributes

component | SimpleGUIComponent Stores the GUI component that is to be attached to a
faceCamera | Boolean Turn on to make the GUIAttacment's component use the
reflectionVisible | Boolean Determines whether or not this GUI attachment will be

Detailed Description

This class is a basic adaptor between PyAttachment and SimpleGUIComponent.

If you wish to display gui elements in the 3D scene ( and sorted into the scene ) then use this class as a container for your gui hierarchy, and attach this object onto a PyModel or other PyAttachment object.

Note that if you wish to receive input like most gui components, then you can still use the attached gui component's focus property as per normal.

eg, guiSomeImage = GUI.Simple(imageFile) guiAttach = GUI.Attachment() guiAttach.component = guiSomeImage self.model.rightHand = guiAttach # Where rightHand is PyModelNode (model hard-point) GUI.addRoot(guiSomeImage)

Current Model will now run around with the image showing in its right hand...

Attribute Documentation

component

Type:
SimpleGUIComponent Stores the GUI component that is to be attached to a

faceCamera

Type:
Boolean Turn on to make the GUIAttacment's component use the

reflectionVisible

Type:
Boolean Determines whether or not this GUI attachment will be


Homer - BigWorld client Documentation

Homer Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Motor → PyObjectPlus

Attributes

arrivalCountLimit | Integer. Default is 1.
goneTime | Float.
proximity | Float. Default is 0.1.
proximityCallback | Callback Function (python function model, or an instance of a
scale | Float. Default is 0.
scaleTime | Float. Default is 1.
speed | Float (units/s). Default is 0.1.
target | MatrixProvider.
tripTime | Float. Default is 0.
turnAxis | A sequence of 3 floats ( x, y, z ). Default is ( 1, 0, 0 ).
turnRate | Float. Default is 0.f.

Detailed Description

A Homer is a Motor that moves a model towards a target (MatrixProvider). Additionally an optional proximity callback can be set for the Homer to call once the model it is moving gets within a specified (proximity) distance of its target.

A new Homer Motor is created using BigWorld. Homer function.

Attribute Documentation

arrivalCountLimit

The attribute arrivalCountLimit is used to limit the number of times an model may need to move a smaller distance than that required by the frame duration and speed to reach the target (ie the last frame before it reaches the target). This acts to trigger the proximity callback, even if the model is not within proximity distance of the target. This is a failsafe so that if the proximity is too small it acts to stop the Homer from "buzzing" around its target - in effect never reaching it target because the model's position cannot move close enough to the target to get inside its proximity radius.

Type:
Integer. Default is 1.

goneTime

The attribute goneTime is the cumulative amount of time that the Homer has been acting on the model (in seconds). It is increased by the frame duration at the end of every frame, provided that tripTime > 0. It is 0 otherwise.

Type:
Float.

proximity

Proximity specifies how close to the "target" the model must get before the Homer Motor calls proximityCallback.

Type:
Float. Default is 0.1.

proximityCallback

The attribute proximityCallback is used to assign a callback function to the Homer Motor that is triggered once the model that the Homer is moving gets within "proximity" distance of "target".

Type:
Callback Function (python function model, or an instance of a

scale

The attribute scale is used to apply a scaling factor to the model over time. If scale > 1 then the model will start at its original size and be scaled linearly over scaleTime seconds to reach the specified scale. When the model reaches half-way point of its trip (based on its movement duration as a fraction of tripTime), it scales back to its original size, regardless of whether or not it has reach its maximum scale.

Type:
Float. Default is 0.

scaleTime

The attribute scaleTime is the duration over which the model will be scaled linearly to the relative size of "scale". When the model reaches half-way (based on its movement duration as a fraction of tripTime), it scales back to its original size, regardless of whether or not it has reach its maximum scale.

Type:
Float. Default is 1.

speed

The attribute speed specifies the speed at which the Homer will move the model towards its destination.

Type:
Float (units/s). Default is 0.1.

target

This attribute specifies a target MatrixProvider. The Homer Motor will trigger an optional callback when the model comes within proximity distance of the target.

Type:
MatrixProvider.

tripTime

The attribute tripTime specifies how long (in seconds) the Homer will take to reach its target. If the speed and tripTime are not in agreement for the time it should take travelling directly towards the target, then the Homer will arc the model towards its target, keeping the speed and tripTime valid by effectively increasing the distance the Homer has to travel towards the target.

If tripTime <= 0 then it is ignored and the Homer makes the model travel directly towards its target.

If tripTime > 0 then it is reduced by the frame duration at the end of each frame.

Type:
Float. Default is 0.

turnAxis

The attribute turnAxis specifies the axis that will be be pointed towards the model as the Homer turns and moves towards its target.

Type:
A sequence of 3 floats ( x, y, z ). Default is ( 1, 0, 0 ).

turnRate

The attribute turnRate specifies the maximum rate (rad/s) at which the Homer can turn to face "turnAxis" at the "target".

Type:
Float. Default is 0.f.


LatencyGUIComponent - BigWorld client Documentation

LatencyGUIComponent Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Detailed Description

This class is used to display the word "Offline" on the screen if the client is not connected to the server. If the client is connected to the server, then the visible attribute of the LatencyGUIObject is automatically set to false.

This class inherits functionality from SimpleGUIComponent.


LatencyInfo - BigWorld client Documentation

LatencyInfo Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Vector4Provider → PyObjectPlus

Detailed Description

The LatencyInfo class is a sub class of Vector4Provider that has an overloaded value attribute. This attribute is overloaded to return a 4 float sequence consisting of ( 1, minimum latency, maximum latency, average latency ) if the client is connected to a server. If the client is not connected to the server then the value attribute returns ( 0, 0, 0, 0 ).

Call the BigWorld. LatencyInfo function to create an instance of a LatencyInfo object.


LinearHomer - BigWorld client Documentation

LinearHomer Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Motor → PyObjectPlus

Attributes

acceleration | float
align | MatrixProvider
blendOutTime | float
offsetProvider | MatrixProvider
pitchRollBlendInTime | float
proximity | float
proximityCallback | CallbackFunction
revDelay | int
target | MatrixProvider
up | 3-tuple
velocity | 3-tuple

Detailed Description

A LinearHomer is a Motor that accelerates a model towards a target (MatrixProvider). Additionally an optional proximity callback can be set for the LinearHomer to call once the model it is moving gets within a specified (proximity) distance of its target. It has a different set of features to a Homer Motor.

A new LinearHomer Motor is created using BigWorld. LinearHomer function.

Attribute Documentation

acceleration

The attribute acceleration specifies the rate of acceleration at which the LinearHomer will move the model towards its destination. Default is 0.1

Type:
float

align

If provided, aligns this motor to the given matrix.

Type:
MatrixProvider

blendOutTime

Time in seconds it should take to blend out pitch and roll animations.

Type:
float

offsetProvider

If provided, this will offset Motor from the Model by the given amount

Type:
MatrixProvider

pitchRollBlendInTime

Time in seconds it should take to blend in pitch and roll animations.

Type:
float

proximity

Proximity specifies how close to the "target" the model must get before the Homer Motor calls proximityCallback. Default is 0.1

Type:
float

proximityCallback

The attribute proximityCallback is used to assign a callback function to the LinearHomer Motor that is triggered once the model that the LinearHomer is moving gets within "proximity" distance of "target". Default is None.

Type:
CallbackFunction

revDelay

Provides an initial delay for the motor in ticks.

Type:
int

target

This attribute specifies a target MatrixProvider. The Homer Motor will trigger an optional callback when the model comes within proximity distance of the target.

Type:
MatrixProvider

up

Specifies which axis is up.

Type:
3-tuple

velocity

Velocity is the current direction and speed of the Model the Motor is driving. Changing the velocity will cause a change in momentum.

Type:
3-tuple


Matrix - BigWorld client 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


MatrixAnimation - BigWorld client Documentation

MatrixAnimation Class Reference

[Math Module]

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

import Math

Parent Classes

MatrixProvider → PyObjectPlus

Attributes

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

Detailed Description

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

Keyframe values are specified as a list of tuples containing a time and a MatrixProvider. These are assumed to be in ascending order, so if a keyframe has a time which is before that of the previous keyframe, the Matrix which is provided will insantly snap to the new value, rather than transitioning smoothly. Also, the MatrixAnimation 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 MatrixAnimation 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.

A new MatrixAnimation is created using Math.MatrixAnimation function.

Attribute Documentation

keyframes

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

loop

Type:
boolean

time

Type:
Read-Write float


MatrixGUIShader - BigWorld client Documentation

MatrixGUIShader Class Reference

[GUI Module]

MatrixGUIShader is part of the GUI module. More...

import GUI

Parent Classes

GUIShader → PyObjectPlus

Member Functions

def reset( self ):

Attributes

blend | integer (treated as boolean)
eta | float
target | MatrixProvider

Detailed Description

This class is a GUI shader that transforms the four corners of each component it is applied to by a matrix. This affects the position the components are drawn on the screen, without actually changing the components themselves.

The four corners have Vector3 positions in screen space, which has (-1,-1,z) in the bottom left and (1,1,z) in the top right. The z component is used for sorting purposes only. This matrix transforms those points within screen space.

The target matrix is a MatrixProvider, so it can be updated dynamically.

The MatrixGUIShader can also blend(linearly interpolate) from its current target to a newly specified target. It takes eta seconds from the last time the target changed before the applied transform reaches the transform specified by the target.

A new MatrixGUIShader is created using GUI.MatrixShader function.

Member Function Documentation

def reset( self ):

This method sets the current matrix to the target matrix, immediately.

Attribute Documentation

blend

This attribute specifies whether to blend from the current transform to that specified by the target MatrixProvider. If this attribute is non-zero (true) then blending is performed, over eta seconds. If this attribute is zero (false) then the target transform is just applied instantly.

It defaults to 1 (true).

Type:
integer (treated as boolean)

eta

This attribute specifies how many seconds it will take to blend from the current transformation of the components to the target transform. This is only used if the blend attribute is non-zero.

It defaults to 0.0.

Type:
float

target

This attribute specifies the MatrixProvider that is used to transform the components that this is attached to. The transformation is applied within clip space ( (-1,-1) is the bottom left of the screen, (1,1) is the top right).

If blend is 0 (false) then any changes to the target MatrixProvider are reflected instantaneously in the transformation of the components.

If blend is non-zero (true), then the the components will move from their current transformations to the transform specified by the target in eta seconds.

It defaults to None.

Type:
MatrixProvider


MatrixInverse - BigWorld client 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 client 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 client 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.


MeshGUIAdaptor - BigWorld client Documentation

MeshGUIAdaptor Class Reference

[GUI Module]

MeshGUIAdaptor is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Attributes

attachment | PyAttachment This attribute stores the attachment that is to be incorporated into the GUI.
transform | MatrixProvider This atttribute stores the orientation and a

Detailed Description

This class is a basic adaptor between SimpleGUIComponent and PyAttachment.

If you wish to display pyAttachments in the GUI scene then use this class as a container for your attachment, and attach the desired object onto it. @code eg, guiSomeImage = GUI.Simple(imageFile) guiSomeAttachment = BigWorld.Model(modelFile) guiMesh = GUI.MeshAdaptor() guiMesh.attachment = guiSomeAttachment guiMesh.transform = someMatrixProvider guiSomeImage.addChild(guiMesh) GUI.addRoot(guiSomeImage) @endcode Model will now be displayed in GUI. someMatrixProvider can be updated to change the orientation of Model, and the model can have animations performed on it like any other.

Note that this class draws during GUI time, meaning that the Z-Buffer is unavailable. For this reason, it is only recommended to use this class for displaying custom-built meshes, for example custom shaped GUI borders or frames that are specifically made for this purpose (are flat and/or draw using additive or alpha blending)

If you want to render your character in the user interface, then it is more appropriate to use a PyModelRenderer or PySceneRenderer.

Attribute Documentation

attachment

Type:
PyAttachment This attribute stores the attachment that is to be incorporated into the GUI.

transform

Type:
MatrixProvider This atttribute stores the orientation and a


Minimap - BigWorld client Documentation

Minimap Class Reference

[GUI Module]

Minimap is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Member Functions

def add( self, pMatrix, component ):
def addSimple( self, MatrixProvider, colour ):
def addTextureLayer( self, Intenger, pTexture, Vector2, Vector2 ):
def delAllTextureLayers( self ):
def delTextureLayer( self, Integer ):
def remove( self, Intengeer ):

Attributes

cellBounds | List of Floats
cellBoundsVisible | Boolean
currentRange | Float
maskName | String
mouseEntryPicking |
pointSizeScaling | Vector2
range | Float
rotate | Boolean
simpleEntriesVisible | Boolean
simpleEntryMap | String
simpleEntrySize | Float
viewpoint | MatrixProvider
zoomSpeed | Float

Detailed Description

This class is a GUI component that can display a scrolling map, with entries displayed on the map.

Member Function Documentation

def add( self, pMatrix, component ):

Adds an entry to the minimap. This function takes a MatrixProvider and a GUI component. The GUI component is rotated when its matrix rotates, so these minimap icons can represent the facing of the matrix.

Parameters:
pMatrix | MatrixProvider. Matrix Provider for the entry on the minimap.
component | GUI Component. A GUI Component to draw on the minimap.

def addSimple( self, MatrixProvider, colour ):

Adds an entry to the minimap. This function takes a MatrixProvider and a colour. The entry is represented via the minimap's simple entry map, and all simple entries are drawn in a batch, i.e. with a single draw call. This is a much faster way to draw a lot of entries in the minimap than by using the Minimap.add function.

Parameters:
MatrixProvider | pMatrix. Matrix Provider for the entry on the minimap.
colour | PyColour. 4-tuple (r,g,b,a) representing the colour to display for the entry.

Returns:
Integer A handle used to identify this entry on the minimap, which can be used to remove the entry from the minimap.

def addTextureLayer( self, Intenger, pTexture, Vector2, Vector2 ):

Adds a texture layer to the minimap. You can overlay as many textures as you like to provide the map display. They will be draw in order of layer, with a smaller layer number being draw behind a larger layer number.

Parameters:
Intenger | Layer number.
pTexture | TextureProvider
Vector2 | World map dimensions (world width, world depth). The width and height is in metres, and for example this might be the width and depth of the entire space, for an outdoor minimap. You may set this to a negative value, as in some cases the texture map may be upside-down.
Vector2 | World map anchor (where the centre of the texture is).

def delAllTextureLayers( self ):

Delete all previously added texture layers from the minimap.

def delTextureLayer( self, Integer ):

Delete a previously added texture layer from the minimap.

Parameters:
Integer Layer number.

def remove( self, Intengeer ):

Removes an entry from the minimap. You must pass the minimap handle returned from either Minimap.add or Minimap.addSimple in order to remove an entry from the minimap.

Parameters:
Intengeer Handle. Minimap Handle returned from add or addSimple.

Attribute Documentation

cellBounds

Vector of floats, in groups of 4, representing all cell boundaries.

Type:
List of Floats

cellBoundsVisible

Turn on or off the display of the cell bounds

Type:
Boolean

currentRange

Actual range in metres the minimap shows around the camera, or the visible radius of the minimap. Setting the current range will change the range immediately, but will not change the desired range.

Type:
Float

maskName

Resource name of the texture that is used to mask out the minimap. The alpha in the mask texture is multiplied over the map itself to stamp out an appropriate shaped border.

Type:
String

mouseEntryPicking

The minimap can check whether the mouse is hovering over entries, and give the minimap's gui script a callback when the selected entry has changed. If you enable mouseEntryPicking, you will receive one of two callback functions :

#Mouse is over a new entry
def onEntryFocus( self, handle )
#Mouse is no longer over an entry
def onEntryBlur( self, handle )

pointSizeScaling

Linear equation to determine the size of the point sprites used to draw the simple entries. The linear equation is of the form y = a + bx, and this attribute is a Vector2 describing (a,b) Set to (0,0) to disable scaling, and enable use of the simpleEntrySize attribute.

Type:
Vector2

range

Desired range in metres the minimap shows around the camera, or the visible radius of the minimap. Setting the desired range will take zoomSpeed seconds to get there.

Type:
Float

rotate

Whether the minimap should rotate so that the camera directio is always facing up on the map. False (default) means North is always up. True means the camera direction is always up.

Type:
Boolean

simpleEntriesVisible

Turn on or off the display of the simple entries.

Type:
Boolean

simpleEntryMap

Resource name of the texture that is used to display simple entry, or, entries added with the addSimpleEntry function. Simple Entries are all drawn with a single texture map, and are batched for maximum drawing speed / minimum number of draw calls.

Type:
String

simpleEntrySize

The size in pixels that simple entries should be drawn. Simple Entries are all drawn with a single texture map, and are batched for maximum drawing speed / minimum number of draw calls. This attribute is only used if pointSizeScaling == (0,0)

Type:
Float

viewpoint

Viewpoint from which the minimap sees the world. It only uses the position if rotate is set to False, or it uses both the position and the forward vector if rotate is set to True. If no viewpoint is provided, the camera matrix is used instead.

Type:
MatrixProvider

zoomSpeed

Time in seconds it takes for the minimap to zoom between one range and another.

Type:
Float


Motor - BigWorld client Documentation

Motor Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

owner Read-Only PyModel

Detailed Description

This is the abstract base class for objects that change a models position and orientation. Models contain a list of motors, and each tick every motor gets a chance to update the position and rotation of the model, as well as the animation that the model is playing. Without any motors, Models do not follow the entity, but remain at their initial position and orientation.

By default, a newly created Model has one Motor, which is an ActionMatcher.

Attribute Documentation

owner

This read only attribute is the PyModel which the motor is controlling.

Type:
Read-Only PyModel


MouseCursor - BigWorld client Documentation

MouseCursor Class Reference

[GUI Module]

MouseCursor is part of the GUI module. More...

import GUI

Parent Classes

InputCursor → PyObjectPlus

Attributes

active | boolean
automaticCursorManagement | boolean
clipped | boolean
dynamic | boolean
hotSpot | Vector2
position | Vector2
shape | str
texture | PyTextureProvider
visible | boolean

Detailed Description

The MouseCursor class encapsulates all information and operations related to the mouse cursor in SimpleGUI. Its is used to activate mouse events propagation and to provide access to mouse related properties (like position, visibility and shape). It implements the InputCursor interface.

Cursor shapes are defined via the mouse cursors definition file. The name of the cursor definition xml resource file can be set in the resources.xml file, in the gui/cursorsDefinitions field. It defaults to "gui/mouse_cursors.xml". Bellow, you can see an example of a cursor definition file:

<mouse_cursors>
    <arrow>
        <hotSpot> 8 8 </hotSpot>
        <texture> gui/maps/cursor_arrow.tga </texture>
    </arrow>
    ...
</mouse_cursors>

Where:
    arrow:		an arbitrary name identifying the cursor.
    hotSpot:	2D position defining this cursor's hot-spot.
    texture:	texture resource to be rendered as the mouse cursor.

From the Python scripts, you can change the mouse shape and other
properties and set it as the active cursor, like in the example bellow:

    import GUI
    import BigWorld

    mc = GUI.mcursor()
    mc.shape = "arrow"
    mc.visible = True
    mc.position = (0.5, 0.5)
    BigWorld.setCursor( mc )

Attribute Documentation

active

Mouse cursor current activity status. Will be true if the
mouse cursor is the current active cursor (see BigWorld.setCursor).
Read-only property.

Type:

boolean

automaticCursorManagement

Enables/disables automatic cursor managmeent. When true, the BigWorld client controls the cursor
shape and adjusts it when required. when falsh an external window (usually web page)
controls the cursor

Read and write property.

Type:

boolean

clipped

Enables/disables mouse clipping. When true, the mouse cursor will be clipped to
the client region of the window whenever the window is in focus. Useful in
conjunction with hiding the cursor (e.g. when in mode where the mouse is used
to control the camera).

Read and write property.

Type:

boolean

dynamic

Mouse cursor current dynamic flag value. Read and write property.

Type:

boolean

hotSpot

Mouse cursor's current hot-spot. Read and write property.

Type:

Vector2

position

Current position of the mouse cursor (in clip space).
Read and write property.

Type:

Vector2

shape

Currently active cursor shape. Read and write property.

Possible values are defined in the mouse cursor definition file.

Type:

str

texture

Current texture used by the mouse cursor if any, wrapped in a
PyTextureProvider. Read and write property.

Will only return a valid texture if the current cursor was set
using the texture attribute. Otherwise, returns an empty
PyTextureProvider.

When using the texture attribute to set the cursos shape, the
current hotSpot will be preserved. You may reset it to the desired
new value, either before or after setting the texture, using the
hotSpot property (see BigWorld.hotSpot).

See below an example of how to use the texture property to
dynamically generate a mouse cursor from a model in the game:

render = BigWorld.PyModelRenderer(32,32)
model  = BigWorld.Model('sets/items/grail.model')
model.zoomExtents(True)
render.models = [model]
render.render()
import GUI
mouse = GUI.mcursor()
mouse.hotSpot = (0, 0)
mouse.visible = True
mouse.texture = render.texture
BigWorld.setCursor(mouse)

Type:

PyTextureProvider

visible

Mouse cursor current visibility status. Read and write property.

Type:

boolean


MusicSystem - BigWorld client Documentation

MusicSystem Class Reference

[FMOD Module]

MusicSystem is part of the FMOD module. More...

import FMOD

Member Functions

def freeSoundData( self ):
def getParameterValue( self, name ):
def loadSoundData( self, blocking ):
def promptCue( self, name ):
def reset( self, type, callback ):
def setCallback( self, callback ):
def setParameterValue( self, name, value ):

Attributes

memoryUsed | Unsigned Int
muted | Bool
paused | Bool
volume | Float

Detailed Description

A MusicSystem provides access to the FMOD::MusicSystem Please refer to "fmodex.chm" in your FMOD install directory for more information.

The MusicSystem singleton can be accessed via the FMOD.getMusicSystem function.

Member Function Documentation

def freeSoundData( self ):

Frees sound data for the music system.

Returns:
Nothing.

def getParameterValue( self, name ):

Gets the value of a given music system parameter.

Parameters:
name The name of the parameter.

Returns:
Float.

def loadSoundData( self, blocking ):

Loads sound data for the music system.

Parameters:
blocking Whether the loading should block or be asynchronous.

Returns:
Nothing.

def promptCue( self, name ):

Triggers an instantaneous cue.

Parameters:
name The name of the cue.

Returns:
Nothing.

def reset( self, type, callback ):

Resets the music system.

Parameters:
type | The type of callback "SEGMENT_START", "SEGMENT_END", "RESET" or "BEAT".
callback | The python method to call.

Returns:
Nothing.

def setCallback( self, callback ):

Sets a callback so that when certain music behaviours happen, they * can be caught by the user.

Parameters:
callback The callable python object, which will be called with a single parameter.

Returns:
Nothing.

def setParameterValue( self, name, value ):

Sets the value of a given music system parameter.

Parameters:
name | The name of the parameter.
value | The value to set the parameter to.

Returns:
Nothing.

Attribute Documentation

memoryUsed

Memory used by this event group.

Type:
Unsigned Int

muted

Mutes or unmutes the music system.

Type:
Bool

paused

Pauses or unpauses the music system.

Type:
Bool

volume

Volume of the music system

Type:
Float


OACommandWrapper - BigWorld client Documentation

OACommandWrapper Class Reference

[OpenAutomateWrapper Module]

OACommandWrapper is part of the OpenAutomateWrapper module. More...

import OpenAutomateWrapper

Parent Classes

PyObjectPlus

Attributes

benchmark String

Detailed Description

This class wraps an oaCommand which gives information about a command

Attribute Documentation

benchmark

Contains the current benchmark name (invalid only for run benchmark commands)

Type:
String


OANamedOptionWrapper - BigWorld client Documentation

OANamedOptionWrapper Class Reference

[OpenAutomateWrapper Module]

OANamedOptionWrapper is part of the OpenAutomateWrapper module. More...

import OpenAutomateWrapper

Parent Classes

PyObjectPlus

Member Functions

def setComparison( self, optionType, comparisonValArg ):

Attributes

comparisonOp | String
dataType | BWOpenAutomate::eOAOptionDataType
enumValue | String
maxValueFloat | float
maxValueInt | int
minValueFloat | float
minValueInt | int
name | String
numSteps | int
parentName | String

Detailed Description

This class wraps an oaNamedOptionStruct which send information about a named option to the OpenAutomate program

Member Function Documentation

def setComparison( self, optionType, comparisonValArg ):

Set the value compared to the dependent parent option in order to see if this option is actionve

Parameters:
optionType | a String specifying the option type
comparisonValArg | a value being compared to the parent option

Attribute Documentation

comparisonOp

Stores the operation used to compare the parent value with ComparisonVal

Type:
String

dataType

Stores the data type of this option

Type:
BWOpenAutomate::eOAOptionDataType

enumValue

Stores the value of this option if its type is enum

Type:
String

maxValueFloat

Stores the maximal value for this option

Type:
float

maxValueInt

Stores the maximal value for this option

Type:
int

minValueFloat

Stores the minimal value for this option

Type:
float

minValueInt

Stores the minimal value for this option

Type:
int

name

Stores the name of this option

Type:
String

numSteps

Stores the number of steps between the minimal and maximal value

Type:
int

parentName

Stores the name of the parent option for options dependencies

Type:
String


OAVersionStructWrapper - BigWorld client Documentation

OAVersionStructWrapper Class Reference

[OpenAutomateWrapper Module]

OAVersionStructWrapper is part of the OpenAutomateWrapper module. More...

import OpenAutomateWrapper

Parent Classes

PyObjectPlus

Detailed Description

This class wraps a oaVersionStruct which gives version information about OpenAutomate


Orbitor - BigWorld client Documentation

Orbitor Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Motor → PyObjectPlus

Attributes

distanceScaler |
endSpeed | Float. Default is 4.0
maxAccel | Float. Default is 5.0
maxSpeed | Float. Default is 4.0
proximity | Float. Default is 0.1.
proximityCallback | Callback Function (python function model, or an instance of a
slowHeigth | Float. Default is 2.0.
speed | Float (units/s). Default is 0.1.
spinRadius | Float. Default is 5.0.
startSpin |
target | MatrixProvider.
weightingFunction |
wobble | bool. Default is true.
wobbleFreq | Float. Default is 1.0.
wobbleMax | Float. Default is 0.5.

Detailed Description

An Orbitor is a Motor that moves a model towards a target (MatrixProvider) and when within a certain distance starts to move towards an orbiting path around the target. Additionally an optional proximity callback can be set for the Orbitor to call once the model it is moving gets within a specified (proximity) distance of its target.

A new Orbitor Motor is created using BigWorld. Orbitor function.

Attribute Documentation

distanceScaler

The attribute distanceScaler used in comination with a weigthng function to change relative weigths of spin and attraction with distance, can be used to create a spiriling effect around the target.

endSpeed

The attribute specifies the end speed that the motor will travel (when spinning).

Type:
Float. Default is 4.0

maxAccel

The attribute specifies the maximum acceleration of the motor

Type:
Float. Default is 5.0

maxSpeed

The attribute specifies the maximum speed that the motor will travel

Type:
Float. Default is 4.0

proximity

Proximity specifies how close to the "target" the model must get before the Orbitor Motor calls proximityCallback.

Type:
Float. Default is 0.1.

proximityCallback

The attribute proximityCallback is used to assign a callback function to the Orbitor Motor that is triggered once the model that the Orbitor is moving gets within "proximity" distance of "target".

Type:
Callback Function (python function model, or an instance of a

slowHeigth

The slowHeight Attribute sets a verticle distance at which the verticle motion towards a target becomes damped and slows to zero

Type:
Float. Default is 2.0.

speed

The attribute speed specifies the speed at which the Orbitor will move the model towards its destination.

Type:
Float (units/s). Default is 0.1.

spinRadius

The attribute spinRadius specifies the orbit radius of the object controlled by the motor

Type:
Float. Default is 5.0.

startSpin

The attribute startSpin specifies the distance from the orbiting radius when the trajectory starts to move into an orbiting path.

target

This attribute specifies a target MatrixProvider. The Orbitor Motor will trigger an optional callbacks when the model comes within proximity distance of the target.

Type:
MatrixProvider.

weightingFunction

The attribute weightingFunction is an index that selects from a list of possible functions that define how the orbitors behaviour moves from purely linear to orbiting. Mainly for testing.

wobble

The attribute wobble is a bool that determines weaher orbitor will oscillate in the verticle axis.

Type:
bool. Default is true.

wobbleFreq

The attribute wobbleFreq sets the frequency of oscillation.

Type:
Float. Default is 1.0.

wobbleMax

The attribute wobbleMax sets the maximum vertcle heigth of oscillation

Type:
Float. Default is 0.5.


OrthogonalNodeInfo - BigWorld client Documentation

OrthogonalNodeInfo Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

BaseNodeInfo → PyObjectPlus

Attributes

pitchAxis | int
yawAxis | int

Detailed Description

This is a subclass of BaseNodeInfo. An Instance of this class describes a system by which PyModelNode instances can be affected by a Tracker. Such an instance can be used by a Tracker to apply pitch changes to one model node, and yaw changes to another. This can be used very effectively with models which represent machinery that turns on swivel joints. The values which control this behaviour are all provided to the factory method used to create this (BigWorld. OrthogonalNodeInfo). Once created, only the pitch and yaw axis can be accessed and/or changed.

Refer to the Tracker class documentation for an overview of the tracker system and related code samples.

Attribute Documentation

pitchAxis

Describes which axis to rotate along to change pitch. This value was provided upon creation (see BigWorld. OrthogonalNodeInfo()). Values of 1, 2 and 3 represent the x, y and z axis repectively. Negative values cause the desired axis to be inverted.

Type:
int

yawAxis

Describes which axis to rotate along to change yaw. This value was provided upon creation (see BigWorld. OrthogonalNodeInfo()). Values of 1, 2 and 3 represent the x, y and z axis repectively. Negative values cause the desired axis to be inverted.

Type:
int


Oscillator - BigWorld client Documentation

Oscillator Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Motor → PyObjectPlus

Member Functions

def canSee( self, position ):

Attributes

amplitude | Float.
offset | Float.
period | Float.

Detailed Description

The Oscillator class is a Motor that "oscillates" a model. It applies an oscillating rotational component to the models world transform.

A sine function is applied across the period of oscillation, producing oscillations in radians from -1 to 1. Amplitude is applied as a scaling factor to this result, producing an oscillation from -amplitude to +amplitude in radians. Offset is applied as an addition to offset the start of the period (in seconds).

Example:
model = BigWorld.Model( "path/to/model/mymodel.model" )
oscillator = BigWorld.Oscillator( 0, 4, -1 )
model.addMotor( oscillator )

Member Function Documentation

def canSee( self, position ):

The canSee function determines whether the input position is within "line of sight" of the object being oscillated. Line of sight is defined as within +/- 0.5 radians of yaw in the viewing direction and within a distance of 60 units.

Parameters:
position Sequence of 3 floats ( x, y, z ).

Returns:
Integer as boolean. 1 (true) if the position is within "line of sight", 0 (false) otherwise.

Attribute Documentation

amplitude

The attribute amplitude is a scaling factor to the magnitude of the oscillation, resulting in a rotational oscillation from -amplitude to +amplitude in radians. If amplitude is negative then the Oscillator will make the object rotate instead of oscillate.

Type:
Float.

offset

The attribute offset is applied as an addition to the start of the period, effectively offsetting the starting angle of oscillation.

Type:
Float.

period

The attribute period specifies the period of oscillation (in seconds).

Type:
Float.


Oscillator2 - BigWorld client Documentation

Oscillator2 Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Oscillator → Motor → PyObjectPlus

Detailed Description

The Oscillator2 class is a Motor that "oscillates" a model. It applies an oscillating rotational component around the world origin to the model's world transform (this is in contrast to the Oscillator which applies the rotational component around the model's origin).

Oscillator2 is an extension of the Oscillator class. See Oscillator for more information.

Example:
model = BigWorld.Model( "path/to/model/mymodel.model" )
oscillator2 = BigWorld.Oscillator2( 0, 4, -1 )
model.addMotor( oscillator2 )


Physics - BigWorld client Documentation

Physics Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def chase( self, entity, distance, tolerance ):
def flood( self ):
def movingForward( self, maxDistance, destination ):
def seek( self, destination, timeout, verticalRange, callback ):
def stop( self ):
def teleport( self, position, direction ):
def teleportSpace( self, spaceID ):
def teleportVehicle( self, vehicle ):

Attributes

angular | Float
angularMouse |
brake |
buoyancy | Float
chasing | Read-Only Integer
collide | Integer
collideObjects | Integer
collideTerrain | Integer
dcLocked | Integer
fall |
fallingVelocity | Read-Only Float
gravity | Float
inWater | Boolean
isMovingNotifier | Callable Object, taking one argument
joystickBackSpeed | Float
joystickEnabled | Boolean
joystickFwdSpeed | Float
maximumSlope | Float
modelDepth | Float
modelHeight | Float
modelWidth | Float
moving | Read-Only Integer
nudge | Vector3
oldStyleCollision | Integer
ripperBrakeDrag |
ripperDesiredHeightFromGround |
ripperElasticity |
ripperGravity |
ripperMaxThrust |
ripperMinHeightFromGround |
ripperThrustDropOffHeight |
ripperThrustDropOffRate |
ripperTurnRate |
ripperXDrag |
ripperYDownDrag |
ripperYUpDrag |
ripperZDrag |
scrambleHeight | Float
seeking | Read-Only Integer
smoothingTime | float
targetDest | MatrixProvider
targetSource | MatrixProvider
thrust |
thrustAxis |
turn | Float
uncorrectedVelocity | Read-only Vector4Provider
userDirected | Integer
userDriven | Integer
velocity | Vector3
velocityMouse | String
viscosity | Float
waterSurfaceHeight | Float

Detailed Description

This class controls the movement of a controlled entity. It applies physics to the entity, applying its velocity, geometry checks and gravity.

An entity is controlled if it is the player entity, or it has the BigWorld.controlEntity function called on it.

Physics objects are created by assigning a value to an entity's physics attribute. The value is an integer, indicating which physics object type to create. For example

>>> entity.physics = 1
>>>	entity.physics
Physics at 0x00eafe87
causes a new physics of type 1 to be created

Member Function Documentation

def chase( self, entity, distance, tolerance ):

Calling the chase function makes the entity attached to the Physics start chasing the specified entity. It faces towards it, and attempts to remain the specified distance away from it. If it is within the optionally specified tolerance of the desired distance, then it doesn't bother trying to move away. Note that the entity will not move unless you also have physics.velocity set. The z component of velocity is the forward speed, and the x component of velocity is the strafe speed.

Parameters:
entity | The Entity to chase after.
distance | The distance to try and remain from the entity.
tolerance | The optional tolerance range for distance. If the entity is within this, it doesn't bother moving.

def flood( self ):

This function is unsupported.

def movingForward( self, maxDistance, destination ):

This method finds out how far we can go 'moving forward.'

It stops whenever a collision would slow the velocity to less than half the original velocity, or when the input maxDistance is reached.

Parameters:
maxDistance | This is a float, which specifies the maximum distance to check for forward movement, in the current direction the entity is facing.
destination | This is an optional Vector4Provider that overrides the maximum distance argument, if you specify this argument the destination is used as the end point, instead of current direction * maxDistance.

Returns:
Vector3 The allowable end position for movement.

def seek( self, destination, timeout, verticalRange, callback ):

The seek function is called to make the entity move to a particular location and yaw. It moves at the speed contained in the velocity attribute of Physics. It turns towards the destination, and moves in a straight line towards it until it is close, and then turns to face the desired yaw. If it gets blocked by geometry, it keeps trying to move until it times out.

Once it either arrives or times out, it calls a callback function.

To cancel, call the seek function passing None for destination and callback.

Parameters:
destination | This is a Vector4, with the first three elements being the location to seek to, the fourth being the yaw to seek to.
timeout | The time in seconds to seek for, before timing out. Use a negative value to have no time limit.
verticalRange | How close the entity has to be vertically to the destination to be considered to have arrived.
callback | The callable object to call once the seek ends. It gets one argument, which is 1 if the seek succeeded, 0 otherwise.

def stop( self ):

This method stops all movement.

def teleport( self, position, direction ):

This function moves the entity to the specified location, and optionally, direction. The change takes effect the next time avatar or flight-mode Physics is run (this frame or next, depending on when the call is made - usually this frame) This call can be combined with the other teleport calls.

Parameters:
position | A Vector3 that is the position to teleport to
direction | An optional Vector3 which if specified is the direction to teleport to (yaw, pitch, roll), otherwise the direction is unchanged.

def teleportSpace( self, spaceID ):

This function moves the entity into the specified space. The change takes effect the next time avatar or flight-mode Physics is run. This call can be combined with the other teleport calls.

Parameters:
spaceID The id of the space to teleport to

def teleportVehicle( self, vehicle ):

This function moves the entity into the specified vehicle. The change takes effect the next time avatar or flight-mode Physics is run. This call can be combined with the other teleport calls. Note that a vehicle can be a moving platform or a more conventional transportation device (ie, car). Because of this the physics fall attribute plays a major role in determining whether the player remains on the vehicle. For moving platforms, the fall attribute should remain as 1, so when a player steps off the edge, the will 'leave' the vehicle. In other cases, such as when a player is to control the vehicle, the fall attribute should be set to 0. For controlling a vehicle, refer to BigWorld.controlEntity() and the wards attribute on the Proxy...

Parameters:
vehicle The vehicle entity to teleport to

Attribute Documentation

angular

Entity angular velocity, in radians per second. The entity will try to turn at this pace. The angular velocity will only be used if the entity is not chasing another entity (see chase) nor seeking a specified position (see seek).

See:
Physics.chase
Physics.seek

Type:
Float

angularMouse

This attribute is no longer supported.

brake

This attribute is unsupported.

buoyancy

This attribute affects how quickly an entity rises to the surface of the water (set by waterSurfaceHeight) when it is in the water (set by the inWater flag). Units are in m/s. You should set its value greater than gravity to enable the entity floating up in water.

Type:
Float

chasing

This read only attribute is set to 1 if the entity is chasing a target, 0 otherwise. Chasing is a behaviour where the physics moves the entity towards a target entity, trying to remain a specified distance from it. It is initiated by calling the chase method.

Type:
Read-Only Integer

collide

This attribute determines whether or not the entity performs collision testing with models in the world. If it is non-zero, then if the entity collides with anything which it cannot walk up, it tries to slide along it. If this fails, then it stops. If the attribute is zero, then the entity's behaviour depends on the fall attribute. If fall is zero, then the entity will pass through objects without colliding, although it glides over terrain. If fall is non-zero, then the entity will glide over both objects and terrain. Note: This property is only active if oldStyleCollision is true.

Type:
Integer

collideObjects

This attribute determines whether or not the entity performs collision with the objects (shells and models) in the world. This property is only active if oldStyleCollision is false.

Type:
Integer

collideTerrain

This attribute determines whether or not the entity performs collision with the terrain in the world. This property is only active if oldStyleCollision is false. Note: indoor shells are objects not terrain.

Type:
Integer

dcLocked

If this attribute is set to non-zero and there is a targetSource and targetDest attribute set, then the entity will face in the direction from targetSource to targetDest. If this attribute is set to zero, then this behaviour is switched off.

Type:
Integer

fall

This attribute determines whether gravity effects the entity or not. If it is non-zero, then it will fall towards the ground at a rate determined using the gravity attribute. If it is zero then the entity will not fall towards the ground at all.

fallingVelocity

This read only attribute shows the current vertical velocity of the entity due to gravity and/or buoyancy. Positive means falling.

Type:
Read-Only Float

gravity

This attribute determines how quickly the entity falls towards the ground. It is an acceleration measured in metres per second per second. It defaults to 9.8.

Type:
Float

inWater

This attribute tells the physics module whether it should treat the entity as being in water or not. If inWater is set to True, then the buoyancy, viscosity and waterSurfaceHeight come into effect.

Type:
Boolean

isMovingNotifier

This attribute is a callback function, which is called whenever the entity transitions between moving and not moving or from not moving to moving. The function will be supplied with one argument, which is the isMoving attribute. It will be 1 if the entity has started moving, and 0 if it stops.

Type:
Callable Object, taking one argument

joystickBackSpeed

This attribute is the speed (in metres per second) at which the entity will move backward if the joystick is being used as a controller and is pressed backwards.

Type:
Float

joystickEnabled

If True, then the physics will take input from the connected joystick. Defaults to False.

Type:
Boolean

joystickFwdSpeed

This attribute is the speed (in metres per second) at which the entity will move forward if the joystick is being used as a controller and is pressed forwards.

Type:
Float

maximumSlope

This attribute is the angle, in degrees, of the maximum slope the entity can move onto.

Type:
Float

modelDepth

This attribute is used to override the bounding box depth of the model, which is used for physics collision tests. If this is set to zero, then the value from the bounding box of the model is used instead, otherwise this attribute is.

Type:
Float

modelHeight

This attribute is used to override the bounding box height of the model, which is used for physics collision tests. If this is set to zero, then the value from the bounding box of the model is used instead, otherwise this attribute is.

Type:
Float

modelWidth

This attribute is used to override the bounding box width of the model, which is used for physics collision tests. If this is set to zero, then the value from the bounding box of the model is used instead, otherwise this attribute is.

Type:
Float

moving

This read only attribute is set to 1 by the system if the entity moved during the last tick, and to 0 otherwise. If velocity is non-zero, but it is unable to move due to geometry constraints, then the attribute will be zero.

Type:
Read-Only Integer

nudge

Setting this attribute to a particular Vector3 adds that vector to the entity's position in the next tick. The value is set back to the zero vector after every tick. It can be read from but, unless it is read immediately after setting it, it will always read as the zero vector.

Type:
Vector3

oldStyleCollision

This attribute determines if the old style collision flags, or the new style collision flags are used. Note: in BigWorld 3, old style collision behaviour will be deprecated.

Type:
Integer

ripperBrakeDrag

This attribute is unsupported.

ripperDesiredHeightFromGround

This attribute is unsupported.

ripperElasticity

This attribute is unsupported.

ripperGravity

This attribute is unsupported.

ripperMaxThrust

This attribute is unsupported.

ripperMinHeightFromGround

This attribute is unsupported.

ripperThrustDropOffHeight

This attribute is unsupported.

ripperThrustDropOffRate

This attribute is unsupported.

ripperTurnRate

This attribute is unsupported.

ripperXDrag

This attribute is unsupported.

ripperYDownDrag

This attribute is unsupported.

ripperYUpDrag

This attribute is unsupported.

ripperZDrag

This attribute is unsupported.

scrambleHeight

This attribute is the height of the step up which the entity can climb. When moving, it performs a collision test this high above the bottom of the entity, in the direction of motion. If it hits anything, then the entity is unable to move, otherwise it moves.

If it is set to zero, then Physics will use 1/3 of the height of the model instead.

Type:
Float

seeking

This read only attribute is set to 1 by the system while seeking towards a particular point, initiated by calling the seek function. Once the entity has arrived or failed, seeking is set to 0 again.

Type:
Read-Only Integer

smoothingTime

For the Player entity, changes in velocity are smoothed over a set amount of time to simulate momentum. This smoothing time is specified in seconds.

Type:
float

targetDest

If the dcLocked attribute is set to non-zero, then the entity will face in the yaw from the location of targetSource to the location of targetDest.

Type:
MatrixProvider

targetSource

If the dcLocked attribute is set to non-zero, then the entity will face in the yaw from the location of targetSource to the location of targetDest.

Type:
MatrixProvider

thrust

This attribute is unsupported.

thrustAxis

This attribute is unsupported.

turn

In avatar style physics, setting this attribute to a particular value adds that value to the entity's yaw in the next tick. The value is set back to zero after every tick. It can be read from but, unless it is read immediately after setting it, it will always read as zero.

This attribute is not supported on physics styles other than avatar.

Type:
Float

uncorrectedVelocity

The velocity in metres per second that the entity actually moved at. This takes into account the intended velocity, slowing down for moving up slopes, gravity, etc. It does not take into account physics corrections for horizontal collisions or hitting the maximum slope limit. Note that the vertical velocity does take collision due to gravity into account.

The uncorrectVelocity is a Vector4Provider and its main raison d'etre is to be used as a velocityProvider for the ActionMatcher. Hooking up these two can provide action matching that is slightly less twitchy when colliding with objects, depending on how your actions are setup.

Type:
Read-only Vector4Provider

userDirected

This attribute determines whether the user is controlling the entity, or it is being controlled by script. If it is set to non-zero, then the direction cursor is used to determine direction, otherwise yaw and pitch can be directly set.

If this is set to non-zero on an entity which is not the player entity, it also will use the direction cursor to determine direction.

Type:
Integer

userDriven

This attribute is designed for use with a joystick, rather than a keyboard. When using a joystick if this is set to zero, then the user is not controlling the entity, otherwise they are. When a keyboard is the primary form of input, this has no effect.

This can be used on any entity, regardless of whether it is the player entity or not.

Type:
Integer

velocity

The velocity in metres per second that the entity is trying to move at. Forces acting on the entity do not change its velocity attribute. If the entity collides with a wall, It will stop moving, but the velocity attribute will remain set to its previous value.

The ActionMatcher doesn't use this attribute when choosing an action. Instead, it matches using the displacement of the model from its previous position.

Type:
Vector3

velocityMouse

The velocity mouse determines what role the mouse has in determining the velocity of the entity. It is a string, which can take three (case sensative) possible values:

- "Direction" which means that the mouse affects the direction of the velocity only. The magnitude is as specified in the velocity attribute, in the direction specified in the velocity attribute, as applied relative to the frame of reference of the directioncursor.

- "MouseX" which means that horizontal movement of the mouse is used to scale the magnitude of the velocity attribute. Direction is entirely specified by the velocity attribute. In order for this to be useful the velocity attribute needs to have a scaling factor built in to it, meaning it is no longer specified in m/s, and in general needs to be considerably bigger than it would normally be. For example, (0,0,100) moves the entity at roughly a walking pace.

- "MouseY" which means that vertical movement of the mouse is used to scale the magnitude of the velocity attribute. Direction is entirely specified by the velocity attribute. In order for this to be useful the velocity attribute needs to have a scaling factor built in to it meaning it is no longer specified in m/s, and in general needs to be considerably bigger than it would normally be. For example, (0,0,100) moves the entity at roughly a walking pace.

Type:
String

viscosity

This attribute affects how quickly an entities falling speed is damped when it has entered water (set by the inWater flag). Units are in m/s.

Type:
Float

waterSurfaceHeight

This attribute tells the physics module where the surface of the water is. It is used to make the entity float up to the appropriate height. It is only used if inWater is set to True.

Type:
Float


Plane - BigWorld client 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


PlayerAvatarFilter - BigWorld client Documentation

PlayerAvatarFilter Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Filter → PyObjectPlus

Detailed Description

This class inherits from Filter. It updates the position and yaw of the entity to the most recent update received from the server.

A new PlayerAvatarFilters can be created using the BigWorld. PlayerAvatarFilter() function.


PlayerMProv - BigWorld client Documentation

PlayerMProv Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

MatrixProvider → PyObjectPlus

Detailed Description

This class inherits from MatrixProvider, and can be used to access the position of the current player entity. Multiple PlayerMProvs can be created, but they will all have the same value.

There are no attributes or functions available on a PlayerMProv, but it can be used to construct a PyMatrix from which the position can be read.

A new PlayerMProv is created using BigWorld.PlayerMatrix function.


ProjectionAccess - BigWorld client Documentation

ProjectionAccess Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def rampFov( self, newFov, time ):

Attributes

farPlane | Float
fov | Float
nearPlane | Float

Detailed Description

This class exposes the projection matrix, and allows manipulation of the clipping planes and the field of view.

There is one projection matrix for the client, which is accessed using BigWorld.projection(). This is automatically created by BigWorld.

Member Function Documentation

def rampFov( self, newFov, time ):

This function changes from the current fov (field of view, in radians) to the specified one over the specified time period. It does this using linear interpolation. Note the fov is measured vertically.

Parameters:
newFov | The fov to move toward
time | The time in seconds to take to move between the current fov and the specified fov

Attribute Documentation

farPlane

This attribute is the distance to the far clipping plane for the current camera. All geometry further from the eye than this will be clipped out.

Type:
Float

fov

The vertical field of view of the current camera, measured in radians. This number must be between 0 and pi. Setting to a number outside of this is likely to cause video driver crashes.

Type:
Float

nearPlane

This attribute is the distance to the near clipping plane for the current camera. All geometry closer to the eye than this will be clipped out.

Type:
Float


Propellor - BigWorld client Documentation

Propellor Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Motor → PyObjectPlus

Attributes

actualTurn | float
maxThrust | float
momentum | Vector3
throttle | float
timeScale | float
turnHalflife | float
turnRate | float
wheelPosition | float
xDrag | float
yDrag | float
zDrag | float

Detailed Description

This class moves an object with the effect of a propellor or other point source of force. A throttle value is used to determine the desired level of force. A wheelPosition is used to determine a desired turn rate, which is then adjusted over time for smoother transition. With the throttle and WheelPosition driving the motor, other values can be set, such as drag, etc, to affect the overall behaviour of the motor.

A new Propellor Motor is created using BigWorld. Propellor function.

Attribute Documentation

actualTurn

Used to dampen the wheel's response. Each update, the actualTurn rate will be 'decayed' from wheelPosition to this value based upon the turnHalfLife and current time step (which can be adjusted with timeScale) and stored for the next update. Defaults to 0.0.

Type:
float

maxThrust

This is the maximum thrust that can be applied to the model. Defaults to 0.075.

Type:
float

momentum

The current momentum being applied to the model.

Type:
Vector3

throttle

Determines the current level of force for this motor.

Type:
float

timeScale

Can be used to scale the integration time of the motor. Defaults to 1.0 (no change - using real-time).

Type:
float

turnHalflife

How quickly the desired turn is approached. Defaults to 10.

Type:
float

turnRate

The degree to which the motor can turn over time. Defaults to 0.005.

Type:
float

wheelPosition

This value represents the desired rate of turn. Higher values will turn more, lower values turn less.

Type:
float

xDrag

Drag along the x-axis. Defaults to 0.2.

Type:
float

yDrag

Drag along the y-axis. Defaults to 1.0.

Type:
float

zDrag

Drag along the z-axis. Defaults to 0.01.

Type:
float


PyAmpParticleRenderer - BigWorld client Documentation

PyAmpParticleRenderer Class Reference

[Pixie Module]

PyAmpParticleRenderer is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemRenderer → PyObjectPlus

Attributes

circular | Integer as boolean. 0 or 1. Default is false (0).
height | Float. Default is 1.0.
steps | Float. Default is 1.0.
textureName | String. Default is "".
useFog |
variation | Float. Default is 1.0.
width | Float. Default is 0.25.

Detailed Description

AmpPartileRenderer is a ParticleRenderer that renders segmented lines from the particle position back to the origin of the particle system. It can be used for effects such as electricty.

Eg. (bad ascii art warning) 3 line segments from start point (s) to end point (e)
  /\
 /  \
s    \  e
      \/

The origin referred to below is either the source position of the particle system (in the case of a non-circular AmpParticleRenderer) or the position of the previous particle (ordered by the age of the particle - in the case of a circular AmpParticleRenderer).

A new PyAmpParticleRenderer is created using Pixie.AmpParticleRenderer function.

Attribute Documentation

circular

Circular determines whether the origin is the source position of the particle system, or the position of the previous particles (ordered by age).

Type:
Integer as boolean. 0 or 1. Default is false (0).

height

Height is applied as a division to the length of the line, to determine texture repeat along the u coordinate in uv texture coordinate space.

Type:
Float. Default is 1.0.

steps

Steps is the number of lines drawn between the start of the line (origin) and the end of the line (particle position).

Type:
Float. Default is 1.0.

textureName

Name of the texture used to render the lines.

Type:
String. Default is "".

useFog

Specifies whether the renderer should enable scene fogging or not. You may want to turn off scene fogging if you are using particle systems in the sky box, or if you want to otherwise explicitly control the amount of fogging via the tint shader fog blend control.

variation

Variation is a scaling factor for random variation of the segment positions when the number of steps is > 1. The default random factor is 0 to 1 scaled by this value and function ofthe line length.

Type:
Float. Default is 1.0.

width

Width is the thickness of the lines drawn.

Type:
Float. Default is 0.25.


PyAttachment - BigWorld client Documentation

PyAttachment Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlusWithWeakReference

Attributes

attached | Read-Only Integer
inWorld | Read-Only Integer
matrix | Read-Only MatrixProvider

Detailed Description

Any object type which can be attached to something else inherits from PyAttachment. Examples of PyAttachment are PyModel, ParticleSystem and PySplodge. A PyAttachment can be attached to various things, among them PyModelNodes and Entitys.

For example, to attach a model to an entity:
e.model = myModel # model is a subclass of PyAttachment

To attach a particle system to the right hand of a character model:
# myPS is a particle system, which inherits from PyAttachment
character.node( "biped R Hand" ).attach( myPS )

Attribute Documentation

attached

This attribute indicates whether or not this attachment is already attached to something. It is 1 if the attachment is attached, 0 otherwise.

This attribute should be checked before trying to attach to something, because you can't attach to something if it is already attached to something else. First you must detach the PyAttachment from whatever it is attached to. If this is an entity, you can set the entity's model attribute to None. If it is attached to a PyModelNode, you can call the detach function.

Type:
Read-Only Integer

inWorld

This attribute is used to determine whether the attachment has been added to the world. It is read only, and is set to 1 if the Attachment is in the world, 0 otherwise.

Type:
Read-Only Integer

matrix

This matrix is the transformation between the frame of reference of the object the PyAttachment is attached to, and the PyAttachment's root node.

Type:
Read-Only MatrixProvider


PyAxisEvent - BigWorld client Documentation

PyAxisEvent Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

axis
dTime
value

Detailed Description

This class represents an input event generated by moving a joystick axis.

Attribute Documentation

axis

The axis that was moved by the user. This can be one of the following values, defined in Keys.py:

Keys.AXIS_LX	= 0
Keys.AXIS_LY	= 1
Keys.AXIS_RX	= 2
Keys.AXIS_RY	= 3
}@

dTime

The time since that axis was last processed.

value

The axis movement value, ranged between -1.0 and +1.0.


PyBarrierPSA - BigWorld client Documentation

PyBarrierPSA Class Reference

[Pixie Module]

PyBarrierPSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Member Functions

def allowParticles( self ):
def bounceParticles( self ):
def box( self, corner, oppositeCorner ):
def removeParticles( self ):
def sphere( self, center, radius ):
def verticalCylinder( self, axisPoint, radius ):
def wrapParticles( self ):

Detailed Description

PyBarrierPSA is a PyParticleSystemAction that acts as an invisible barrier to particles. It can take the form of a plane, box, vertical cylinder, or sphere. The barrier is "weak" in the sense that particles could possibly penetrate the barrier for a short period of time (the barrier only acts once the particle has penetrated the barrier), before being pushed back into the interior or removed.

The barrier can remove particles that hit the barrier, or bounce them off the barrier. Only one shape, and collision action can be active at one time for each BarrierPSA.

A new PyBarrierPSA is created using Pixie.BarrierPSA function.

Member Function Documentation

def allowParticles( self ):

Set the BarrierPSA to allow particles to collide with it (effectively turns it off).

def bounceParticles( self ):

Set the BarrierPSA to bounce particles that collide with it.

def box( self, corner, oppositeCorner ):

Specifies that the BarrierPSA should take the shape of a Box. Coordinates are in world space.

Parameters:
corner | Sequence of 3 floats. One corner of the box.
oppositeCorner | Sequence of 3 floats. Opposite corner of the box.

def removeParticles( self ):

Set the BarrierPSA to remove particles that collide with it.

def sphere( self, center, radius ):

Specifies that the BarrierPSA should take the shape of a sphere. Coordinates are in world space.

Parameters:
center | Sequence of 3 floats. Center of the sphere.
radius | Float. Radius of the sphere.

def verticalCylinder( self, axisPoint, radius ):

Specifies that the BarrierPSA should take the shape of a vertical cylinder. Coordinates are in world space.

Parameters:
axisPoint | Sequence of 3 floats. Point on axis of cylinder.
radius | Float. Radius of cylinder.

def wrapParticles( self ):

Set the BarrierPSA to allow particles to wrap around it.


PyBlurParticleRenderer - BigWorld client Documentation

PyBlurParticleRenderer Class Reference

[Pixie Module]

PyBlurParticleRenderer is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemRenderer → PyObjectPlus

Attributes

textureName |
time | Float.
useFog |
width |

Detailed Description

BlurParticleRenderer is a ParticleSystemRenderer that draws a trail for each particle, but does so in a more efficient manner than the TrailParticleRenderer.

The BlurParticleRenderer draws a single straight trail for each particle, by drawing a textured line using the particle's current velocity negated.

Due to this, the trails drawn by the BlurParticleRenderer will not exhibit bends - however, there is no memory overhead for using this renderer.

A new PyBlurParticleRenderer is created using Pixie.BlurParticleRenderer function.

Attribute Documentation

textureName

This attribute specifies the name of the texture used to render the trails of the particles.

time

The time attribute specifies the length of the trail, in seconds. The length of the tail is (particle velocity * time) Default value is 0.25.

Type:
Float.

useFog

Specifies whether the renderer should enable scene fogging or not. You may want to turn off scene fogging if you are using particle systems in the sky box, or if you want to otherwise explicitly control the amount of fogging via the tint shader fog blend control.

width

This attribute specifies the width of the line renderer as the trail on the particles.


PyChunkLight - BigWorld client Documentation

PyChunkLight Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlusWithVD

Member Functions

def recalc( self ):

Attributes

bounds | Read-Write Vector4Provider
colour | Read-Write Vector4
diffuse | Read-Write Boolean
innerRadius | Read-Write Float
outerRadius | Read-Write Float
position | Read-Write Vector3
priority | Read-Write Integer
shader | Read-Write Vector4Provider
source | Read-Write MatrixProvider
specular | Read-Write Boolean
visible | Read-Write boolean

Detailed Description

This is a script controlled omni light which can be used as a diffuse and/or specular light source for models and shells. This is not the class used for environmental lights or lights which have been placed in the editor.

The colour, radius, and position properties of the light can be set to static values via the colour, innerRadius and outerRadius, and position attributes. Alternatively, They can be set to dynamic values via the source, bounds, and shader attributes. These will override the static values when specified. This gives you the ability to dynamically alter the light's look, or attach it to moving models in the scene.

The strength of a PyChunkLight at a point is determined by it's innerRadius, outerRadius, and the distance between the point and the PyChunkLight. If the distance is less than innerRadius, then the light is applied at full strength (regardless of outerRadius). The strength of the light falls off linearly from full to 0 between innerRadius and outerRadius, and is 0 from outerRadius onwards.

Code Example:
# This sets up a few PyChunkLight objects which show some of the things
# that they can do.

# import Math module
import Math

# create a simple diffuse light source at position (0, 0, 0)
simpleDiffuse = BigWorld.PyChunkLight()
simpleDiffuse.innerRadius = 1
simpleDiffuse.outerRadius = 3
simpleDiffuse.position = (0, 0, 0)
simpleDiffuse.colour = (255, 255, 255, 0) # white
simpleDiffuse.specular = 0
simpleDiffuse.diffuse = 1
simpleDiffuse.visible = True

# create a simple specular light source
simpleSpecular = BigWorld.PyChunkLight()
simpleSpecular.innerRadius = 1
simpleSpecular.outerRadius = 3
simpleSpecular.position = (5, 0, 0)
simpleSpecular.colour = (255, 255, 255, 0) # white
simpleSpecular.specular = 1
simpleSpecular.diffuse = 0
simpleSpecular.visible = True

# create a light source which does not disperse
noDissipate = BigWorld.PyChunkLight()
noDissipate.innerRadius = 2
noDissipate.outerRadius = 1.5
noDissipate.position = (10, 0, 0)
noDissipate.colour = (255, 255, 255, 0) # white
noDissipate.specular = 1
noDissipate.diffuse = 1
noDissipate.visible = True

# create a light source which follows the player entity
followPlayer = BigWorld.PyChunkLight()
followPlayer.innerRadius = 1
followPlayer.outerRadius = 3
followPlayer.source = BigWorld.player().matrix
followPlayer.colour = (255, 255, 255, 0) # white
followPlayer.specular = 1
followPlayer.diffuse = 1
followPlayer.visible = True

# create a light source which is attached to the player's hand
# NB: the hand node is assumed to be called "HP_right_hand" in this
# example.  Examine the model in ModelViewer to determine the node name
# in your model.
followPlayerHand = BigWorld.PyChunkLight()
followPlayerHand.innerRadius = 1
followPlayerHand.outerRadius = 3
followPlayerHand.source = BigWorld.player().model.node("HP_right_hand")
followPlayerHand.colour = (255, 255, 255, 0) # white
followPlayerHand.specular = 1
followPlayerHand.diffuse = 1
followPlayerHand.visible = True

# create a light source which changes colour over time at position
# (15, 0, 0)
pulseShader = Math.Vector4Animation()
pulseShader.duration = 1.0
pulseShader.keyframes = [ ( 0.0, (200, 0,   0, 0) ),    # red at 0.0s
                          ( 0.5, (0,   0, 200, 0) ),    # blue at 0.5s
                          ( 1.0, (200, 0,   0, 0) ) ]   # red at 1.0s
pulse = BigWorld.PyChunkLight()
pulse.innerRadius = 1
pulse.outerRadius = 3
pulse.position = (15, 0, 0)
pulse.shader = pulseShader
pulse.specular = 1
pulse.diffuse = 1
pulse.visible = True

# create a light source which changes radius over time
growBounds = Math.Vector4Animation()
growBounds.duration = 1.0
growBounds.keyframes = [ ( 0.0, ( 0, 0, 0, 0 ) ),    # 0 at 0.0s
                         ( 0.5, ( 2, 1, 0, 0 ) ),    # 2 at 0.5s
                         ( 1.0, ( 0, 0, 0, 0 ) ) ]   # 0 at 1.0s
grow = BigWorld.PyChunkLight()
grow.position = (20, 0, 0)
grow.colour = (255, 255, 255, 0) # white
grow.bounds = growBounds
grow.specular = 1
grow.diffuse = 1
grow.visible = True

Member Function Documentation

def recalc( self ):

Recalculates the effects of the light. The initial setup of a PyChunkLight does not require this to be called.

Returns:
None.

Attribute Documentation

bounds

When specified, this overwrites the innerRadius and outerRadius attributes with the first and second components of the Vector4 it provides, respectively.

Type:
Read-Write Vector4Provider

colour

The colour of the light source in RGBA form. This is overwritten with the output of the shader attribute if it has been specified.

Type:
Read-Write Vector4

diffuse

If true, this provides a light source for diffuse shaders. This defaults to true.

Type:
Read-Write Boolean

innerRadius

The radius around the centre of the light within which the strength of the light does not drop off. This is overwritten with the first component of the output of the bounds attribute if it has been specified.

Type:
Read-Write Float

outerRadius

If greater than innerRadius, this is the radius around the centre of the light at which the strength of the light becomes zero. If this is less than or equal to innerRadius, then there is no area around the light in which its effect dissipates. This is overwritten with the second component of the output of the bounds attribute if it has been specified.

Type:
Read-Write Float

position

The centre of the light source. This is overwritten with the output of the source attribute if it has been specified.

Type:
Read-Write Vector3

priority

A priority bias used when sorting lights to determine the most relevant set of lights for a particular object. This is useful to ensure important lights will always be considered before other lights (e.g. a player's torch).

Type:
Read-Write Integer

shader

When specified, this overwrites the colour attribute with the Vector4 it provides.

Type:
Read-Write Vector4Provider

source

When specified, this overwrites the position attribute with it's translation.

Type:
Read-Write MatrixProvider

specular

If true, this provides a light source for specular shaders. This defaults to false.

Type:
Read-Write Boolean

visible

Dictates whether this light illuminates things.

Type:
Read-Write boolean


PyChunkModel - BigWorld client Documentation

PyChunkModel Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Detailed Description

NOTE: This class has been deprecated - Use a static PyModelObstacle instead

A PyChunkModel is a PyObjectPlus wrapper around a simple model which is treated by BigWorld as a part of the level geometry. It can be used to dynamically place objects such as buildings in the world. These objects can be created and deleted, but not modified. Instances of this class are generated by the BigWorld. PyChunkModel factory method, as in the following example:

# Import Math library
import Math

# Place a PyChunkModel in the world at ( 0, 10, 0 )
modelName = "objects\models\items\Trees & Plants\oak4.model"
matrix = Math.Matrix()
matrix.setTranslate( ( 0, 10, 0 ) )
newPyChunkModel = BigWorld.PyChunkModel( modelName, $p.spaceID, matrix )

# now remove it
del( newPyChunkModel )

PyChunkModel instances are not returned by BigWorld.chunkInhabitant.


PyChunkSpotLight - BigWorld client Documentation

PyChunkSpotLight Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlusWithVD

Member Functions

def recalc( self ):

Attributes

bounds | Read-Write Vector4Provider
colour | Read-Write Vector4
cosConeAngle | Read-Write Float
diffuse | Read-Write Boolean
direction | Read-Write Vector3
innerRadius | Read-Write Float
outerRadius | Read-Write Float
position | Read-Write Vector3
priority | Read-Write Integer
shader | Read-Write Vector4Provider
source | Read-Write MatrixProvider
specular | Read-Write Boolean
visible | Read-Write boolean

Detailed Description

This is a script controlled spot light which can be used as a diffuse and/or specular light source for models and shells. This is not the class used for environmental lights or lights which have been placed in the editor.

The colour, radius, cone size, direction and position properties of the light can be set to static values via the colour, innerRadius and outerRadius, cosConeAngle, direction and position attributes. Alternatively, They can be set to dynamic values via the source, bounds, and shader attributes. These will override the static values when specified. This gives you the ability to dynamically alter the light's look, or attach it to moving models in the scene.

The strength of a PyChunkSpotLight at a point is determined by it's innerRadius, outerRadius, and the distance between the point and the PyChunkSpotLight. If the distance is less than innerRadius, then the light is applied at full strength (regardless of outerRadius). The strength of the light falls off linearly from full to 0 between innerRadius and outerRadius, and is 0 from outerRadius onwards.

Code Example:
# This sets up a PyChunkSpotLight object which shows some of the things
# that it can do.

# create a light source which is attached to the player's hand
# NB: the hand node is assumed to be called "HP_right_hand" in this
# example.  Examine the model in ModelViewer to determine the node name
# in your model. In the example models this points out from the palm.
followPlayerHand = BigWorld.PyChunkSpotLight()
followPlayerHand.innerRadius = 1
followPlayerHand.outerRadius = 10
followPlayerHand.cosConeAngle = 0.9 # ~25 degrees from center
followPlayerHand.source = BigWorld.player().model.node("HP_right_hand")
followPlayerHand.colour = (255, 255, 255, 0) # white
followPlayerHand.specular = 1
followPlayerHand.diffuse = 1
followPlayerHand.visible = True

Member Function Documentation

def recalc( self ):

Recalculates the effects of the light. The initial setup of a PyChunkSpotLight does not require this to be called.

Returns:
None.

Attribute Documentation

bounds

When specified, this overwrites the innerRadius and outerRadius attributes with the first and second components of the Vector4 it provides, respectively.

Type:
Read-Write Vector4Provider

colour

The colour of the light source in RGBA form. This is overwritten with the output of the shader attribute if it has been specified.

Type:
Read-Write Vector4

cosConeAngle

The cos of the cone angle. 1.0 = zero size cone 0.0 = 180 degree cone (90 degrees on each side)

Type:
Read-Write Float

diffuse

If true, this provides a light source for diffuse shaders. This defaults to true.

Type:
Read-Write Boolean

direction

The direction of the light source. This is overwritten with the output of the source attribute if it has been specified.

Type:
Read-Write Vector3

innerRadius

The radius around the centre of the light within which the strength of the light does not drop off. This is overwritten with the first component of the output of the bounds attribute if it has been specified.

Type:
Read-Write Float

outerRadius

If greater than innerRadius, this is the radius around the centre of the light at which the strength of the light becomes zero. If this is less than or equal to innerRadius, then there is no area around the light in which its effect dissipates. This is overwritten with the second component of the output of the bounds attribute if it has been specified.

Type:
Read-Write Float

position

The centre of the light source. This is overwritten with the output of the source attribute if it has been specified.

Type:
Read-Write Vector3

priority

A priority bias used when sorting lights to determine the most relevant set of lights for a particular object. This is useful to ensure important lights will always be considered before other lights (e.g. a player's torch).

Type:
Read-Write Integer

shader

When specified, this overwrites the colour attribute with the Vector4 it provides.

Type:
Read-Write Vector4Provider

source

When specified, this overwrites the position attribute with it's translation.

Type:
Read-Write MatrixProvider

specular

If true, this provides a light source for specular shaders. This defaults to false.

Type:
Read-Write Boolean

visible

Dictates whether this light illuminates things.

Type:
Read-Write boolean


PyCollidePSA - BigWorld client Documentation

PyCollidePSA Class Reference

[Pixie Module]

PyCollidePSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Attributes

elasticity | Float. Recommend values are 0.0 to 1.0.
maxAddedRotation | Float. Recommend values are 0.0 to 1.0.
minAddedRotation | Float. Recommend values are 0.0 to 1.0.
soundEnabled |
soundSrcIdx |
soundTag |

Detailed Description

PyCollidePSA is a PyParticleSystemAction that collides particles with the collision scene, based upon their position and velocity.

A new PyCollidePSA is created using Pixie.CollidePSA function.

Attribute Documentation

elasticity

This sets the amount of elasticity in the collision. 0 indicates no reflection of velocity in the direction of the collision normal. 1 indicates full reflection of velocity in the direction of collision normal. The default value is 0.

Type:
Float. Recommend values are 0.0 to 1.0.

maxAddedRotation

This specifies the maximum amount of spin added to the particle when it collides ( dynamically scaled by velocity ). The actual value varies randomly between min and max added rotation. The value is interpreted as an absolute amount, so a particle that is not currently spinning can begin spinning upon a collision. If negative, the spin will decrease / be dampened.

Type:
Float. Recommend values are 0.0 to 1.0.

minAddedRotation

This specifies the minimum amount of spin added to the particle when it collides ( dynamically scaled by velocity ). The actual value varies randomly between min and max added rotation. The value is interpreted as an absolute amount, so a particle that is not currently spinning can begin spinning upon a collision. If negative, the spin will decrease / be dampened.

Type:
Float. Recommend values are 0.0 to 1.0.

soundEnabled

Not supported.

soundSrcIdx

Not supported.

soundTag

Not supported.


PyCopyBackBuffer - BigWorld client Documentation

PyCopyBackBuffer Class Reference

[PostProcessing Module]

PyCopyBackBuffer is part of the PostProcessing module. More...

import PostProcessing

Parent Classes

Phase → PyObjectPlus

Attributes

name | String.
renderTarget | PyRenderTarget.

Detailed Description

This class derives from PostProcessing::Phase, and provides a way to get a copy of the back buffer in a render target.

It uses a draw cookie to know when the back buffer has been updated. If backBufferCopy.draw is called but the render target already has the latest copy of the render target then it optimises out the draw call. Note this optimisation only works if you reuse the same PyCopyBackBuffer phase instance.

Attribute Documentation

name

Arbitrary name identifying this phase.

Type:
String.

renderTarget

The render target in which a copy of the back buffer will be placed. Internally the DirectX function StretchRect is used, so please refer to the DirectX documentation for information on restrictions regarding pairs of back buffer formats and render target formats.

Type:
PyRenderTarget.


PyDye - BigWorld client Documentation

PyDye Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyFashion → PyObjectPlus

Attributes

matter | Read-Only String
tint | Read-Only String

Detailed Description

A dye is used to apply a particular material to a piece of geometry in a model. Dyes are specified in the .model file(s) which the PyModel was created from.

In the model file, a <dye> section is given a <matter> name, which creates an extra attribute for the PyModel in python of that name. It also contains a <replaces> which should be the name of a particular primitiveGroup in the .visual file. The <dye> section also contains a list of <tints>, which have a <name> and a <material> section. By assigning the name (as a string) to the models named attribute that material is applied to the <replaces> geometry of the model.

Dye attributes are special, in that when written to, they accept a string, which is the name of a tint. On reading them, they return a PyDye object, which has a tint attribute with the name that was written.

This class inherits from PyFashion.

For example, the if the following is an extract from the model file:

<dye>
    <matter> Chest </matter>
    <replaces>	Torso </replaces>
    <tint>
        <name>	Blue </name>
        <material>
            <diffuseTexture>	bluetex.dds	</diffuseTexture>
        </material>
    </tint>
    <tint>
        <name>	Red </name>
        <material>
            <diffuseTexture>	redtex.dds	</diffuseTexture>
        </material>
    </tint>
</dye>

This assumes that somewhere in the .visual file is a primitivegroup called Torso ( the field ).

This creates a named attribute on the PyModel called chest, which can be assigned either "Red" or "Blue". This assignment has the effect of applying either the redtex.dds diffuse texture, or the bluetex.dds, respectively.

Then, in python, if M contains the model object created from this .model file, then the following would be a possible console example:

>>> d = M.Chest
>>> d
PyDye at 0x0b771f770
>>> dir(d)
[ 'matter', 'tint' ]
>>> d.matter
'Chest'
>>> d.tint
'Default'
>>> M.Chest = "Red" # applies redtex.dds to the model's Torso
>>> d = M.Chest
>>> d
PyDye at 0x0b771f850
>>> d.matter
'Chest'
>>> d.tint
'Red'

Attribute Documentation

matter

The name of the attribute within the model file that this dye will apply to.

Type:
Read-Only String

tint

The name of the tint that specifies which material this dye will apply to the geometry.

Type:
Read-Only String


PyEntities - BigWorld client Documentation

PyEntities Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

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

Detailed Description

A class which emulates a dictionary of PyEntity objects indexed by their id attributes. Instances of this class do 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 given does not exist in the dictionary. Instances of this class are used by the engine to present lists of entities to script. They cannot be created via script, nor can they be modified.

Example:
e = BigWorld.entities # this is a PyEntities object
e[ 100 ] # returns the entity with ID 100
len( e ) # returns the number of entities in this dictionary

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

Used to determine whether an entity with a specific ID is listed in this PyEntities object.

Parameters:
key An integer key to look for.

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

def has_key( self, key ):

Used to determine whether an entity with a specific ID is listed in this PyEntities object.

Parameters:
key An integer key to look for.

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

def items( self ):

Generates a list of the items (ID:entity pairs) listed in this object.

Returns:
A list containing all of the ID:entity pairs, represented as tuples containing one integer, and one entity.

def items( self ):

Generates a list of the items (ID:entity pairs) listed in this object.

Returns:
A list containing all of the ID:entity pairs, represented as tuples containing one integer, and one entity.

def keys( self ):

Generates a list of the IDs of all of the entities listed in this object.

Returns:
A list containing all of the keys, represented as integers.

def keys( self ):

Generates a list of the IDs of all of the entities listed in this object.

Returns:
A list containing all of the keys, represented as integers.

def values( self ):

Generates a list of all the entities listed in this object.

Returns:
A list containing all of the entities.

def values( self ):

Generates a list of all the entities listed in this object.

Returns:
A list containing all of the entities.


PyFashion - BigWorld client Documentation

PyFashion Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Detailed Description

This class is the abstract base class for objects that change the appearance of a model. In particular, PyDye, ActionQueuer, PyMorphControl and Tracker all inherit from it.


PyFilterQuad - BigWorld client Documentation

PyFilterQuad Class Reference

[PostProcessing Module]

PyFilterQuad is part of the PostProcessing module. More...

import PostProcessing

Parent Classes

FilterQuad → PyObjectPlus

Attributes

samples List of Vector3s.

Detailed Description

A PyFilterQuad can be used by a PyPhase object, and provides the geometry for the phase. The FilterQuad performs n-taps on the source material's textures, in groups of 4. If you specify more than 4 taps, then the filter quad will draw using n/4 passes. For these operations, you should make sure the material you use is additive, so the results can accumulate.

Attribute Documentation

samples

Type:
List of Vector3s.


PyFlarePSA - BigWorld client Documentation

PyFlarePSA Class Reference

[Pixie Module]

PyFlarePSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Attributes

colourize | Integer as boolean. 0 or 1.
flareName | String.
flareStep | Integer. 0..n.
useParticleSize | Integer as boolean.

Detailed Description

PyFlarePSA is a PyParticleSystemAction that draws a lens flare at the location of one or more particles (either the oldest particle, all particles or every n particles). The flare resource used to draw the flare is specified when the PyFlarePSA is created using the FlarePSA factory function in the Pixie module.

Attribute Documentation

colourize

Specifies whether the flare should be colourized from the colour of the particle. Default is 0 (false).

Type:
Integer as boolean. 0 or 1.

flareName

This value determines which lens effect resource to use for flares. Default is empty string.

Type:
String.

flareStep

This value determines which particles have a flare drawn on them. 0 is leader only, 1 is all particles, 2..x is every X particles. Default is 0.

Type:
Integer. 0..n.

useParticleSize

Specifies whether the effect should use the size of the particle for its size. Default is 0 (false).

Type:
Integer as boolean.


PyFont - BigWorld client Documentation

PyFont Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def stringDimensions( self, text, multiline, colourFormatting ):
def stringWidth( self, text, multiline, colourFormatting ):

Attributes

name

Detailed Description

This class exposes a reference to a font.

Member Function Documentation

def stringDimensions( self, text, multiline, colourFormatting ):

This function returns a 2-tuple containing the dimensions (in pixels) that the specified string will take when rendered to a TextGUIComponent using this font.

Parameters:
text | The string to measure the length and height of.
multiline | Optional boolean. Whether or not newline characters should be wrapped.
colourFormatting | Optional boolean. Whether or not this string is using formatting tags.

Returns:
A 2-tuple of integers, the render width and height of the string in pixels.

def stringWidth( self, text, multiline, colourFormatting ):

This function returns the width (in pixels) that the specified string will take when rendered to a TextGUIComponent using this font.

Parameters:
text | The string to measure the length of.
multiline | Optional boolean. Whether or not newline characters should be wrapped.
colourFormatting | Optional boolean. Whether or not this string is using formatting tags.

Returns:
An integer, the rendered width of the string in pixels.

Attribute Documentation

name

Get the name of this font.


PyForcePSA - BigWorld client Documentation

PyForcePSA Class Reference

[Pixie Module]

PyForcePSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Attributes

vector Sequence of 3 floats.

Detailed Description

PyForcePSA is a PyParticleSystemAction that applies a constant acceleration to particles in a particular direction.

A new PyForcePSA is created using Pixie.ForcePSA function.

Attribute Documentation

vector

This is a vector describing the direction and magnitude of the acceleration to be applied to the particles. The default value is (0.0, 0.0, 0.0).

Type:
Sequence of 3 floats.


PyGraphicsSetting - BigWorld client Documentation

PyGraphicsSetting Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def addOption( self, label, desc, isSupported ):
def registerSetting( self ):

Attributes

callback

Detailed Description

This class is a graphics setting that calls into python to allow arbitrary script code implementation.

Each GraphicsSetting object offers a number of options. There is always one and only one active option at any one time.

The callback function is called whenever the option is changed. It takes one parameter, which is the newly selected option for this graphics setting.

Member Function Documentation

def addOption( self, label, desc, isSupported ):

Parameters:
label | UI label to display for the option
desc | More detailed help string for the option.
isSupported | Whether the current host system supports this option.

Returns:
int Index to the newly added option.

def registerSetting( self ):

Attribute Documentation

callback


PyIME - BigWorld client Documentation

PyIME Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

candidates | Read-Only list of Unicode strings
candidatesVertical | Read-Only boolean
candidatesVisible | Read-Only boolean
composition | Read-Only Unicode string
compositionAttr | Read-Only Array of integers
compositionCursorPosition | Read-Only int
currentlyVisible | Read-Only boolean
enabled | Read-Write boolean
language | Read-Only string
reading | Read-Only Unicode string
readingVertical | Read-Only boolean
readingVisible | Read-Only boolean
selectedCandidate | Read-Only int
state |

Detailed Description

Provides access to the current IME state for the client process. This cannot be directly instanciated and is accessed via the BigWorld.ime singleton object.

Attribute Documentation

candidates

Contains a list of possible candidates based on the keystrokes entered by the user.

Type:
Read-Only list of Unicode strings

candidatesVertical

Determines whether ot not the candidate list is horizontal or vertical for the current language.

Type:
Read-Only boolean

candidatesVisible

Determines whether or not the candidate list should be displayed to the user.

Type:
Read-Only boolean

composition

Contains the unicode string representing the current composition entered by the user.

Type:
Read-Only Unicode string

compositionAttr

Of the same length as the composition string, this specifies the current conversion attributes for each character in the string.

Possible values are:

ATTR_INPUT					= 0
ATTR_TARGET_CONVERTED		= 1
ATTR_CONVERTED				= 2
ATTR_TARGET_NOTCONVERTED	= 3
ATTR_INPUT_ERROR			= 4
ATTR_FIXEDCONVERTED			= 5

Type:
Read-Only Array of integers

compositionCursorPosition

Index into the composition string representing where the input cursor is currently located.

Type:
Read-Only int

currentlyVisible

If this is true, then there are IME components with which the user are currently interacting (e.g. composition string and/or candidate list).

Type:
Read-Only boolean

enabled

Controls whether or not IME is enabled for the client. For example, you would set this to True when an IME enabled edit control comes into focus and then set it to False when it loses focus.

Type:
Read-Write boolean

language

Reflects the current language selected by the user. Supported languages are are:

"NON_IME"	- A language that does not require an IME.
"CHS"		- Chinese (Simplified)
"CHT"		- Chinese (Traditional)
"JAPANESE"	- Japanese
"KOREAN"	- Korean

Type:
Read-Only string

reading

Contains the unicode string representing the current reading string entered by the user.

Type:
Read-Only Unicode string

readingVertical

Determines whether ot not the reading string is horizontal or vertical for the current language.

Type:
Read-Only boolean

readingVisible

Determines whether or not the reading string should be displayed to the user.

Type:
Read-Only boolean

selectedCandidate

Index into the candidate selection list of the currently highlighted candidate.

Type:
Read-Only int

state

Reflects the current state of the IME. Possible values are:

"OFF"		- The IME is turned off.
"ON"		- The IME is active.
"ENGLISH"	- The IME is active, but is in alpha numeric mode.


PyIMEEvent - BigWorld client Documentation

PyIMEEvent Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

candidateSelectionChanged
candidatesChanged
candidatesVisibilityChanged
compositionChanged
compositionCursorPositionChanged
readingChanged
readingVisibilityChanged
stateChanged

Detailed Description

This class is used to notify the scripts when an IME state change has occured. It has a set of flags to determine which properties on the global PyIME object have changed.

Attribute Documentation

candidateSelectionChanged

If this is True, then the PyIME.selectedCandidate attribute has changed.

candidatesChanged

If this is True, then the PyIME.candidates attribute has changed.

candidatesVisibilityChanged

If this is True, then the PyIME.candidatesVisible attribute has changed.

compositionChanged

If this is True, then the PyIME.composition attribute has changed.

compositionCursorPositionChanged

If this is True, then the PyIME.compositionCursorPosition attribute has changed.

readingChanged

If this is True, then the PyIME.reading attribute has changed.

readingVisibilityChanged

If this is True, then the PyIME.readingVisible attribute has changed.

stateChanged

If this is True, then the PyIME.state attribute has changed.


PyJitterPSA - BigWorld client Documentation

PyJitterPSA Class Reference

[Pixie Module]

PyJitterPSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Member Functions

def setPositionSource( self, generator ):
def setVelocitySource( self, generator ):

Attributes

affectPosition | Integer as boolean. 0 or 1.
affectVelocity | Integer as boolean. 0 or 1.

Detailed Description

PyJitterPSA is a PyParticleSystemAction that adds random motion to the particles. JitterPSA can affect the position and/or veclocity of the particles.

The position source and/or velocity source will need to be set before this ParticleSystemAction will produce a visible effect - both default to ( 0, 0, 0 ).

Position and Velocity "jitter" are calculated each frame.

A new PyJitterPSA is created using Pixie.JitterPSA function.

Member Function Documentation

def setPositionSource( self, generator ):

Sets a new VectorGenerator as a jitter position source for the particles.

Parameters:
generator VectorGenerator. Jitter position source for the particles.

def setVelocitySource( self, generator ):

Sets a new VectorGenerator as a jitter velocity source for the particles.

Parameters:
generator VectorGenerator. Jitter velocity source for the particles.

Attribute Documentation

affectPosition

This is a flag to determine whether JitterPSA affects position. Default value is 0 (false).

Type:
Integer as boolean. 0 or 1.

affectVelocity

This is a flag to determine whether JitterPSA affects velocity. Default is 0 (false).

Type:
Integer as boolean. 0 or 1.


PyKeyEvent - BigWorld client Documentation

PyKeyEvent Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def isAltDown( self ):
def isCtrlDown( self ):
def isKeyDown( self ):
def isKeyUp( self ):
def isModifierDown( self ):
def isMouseButton( self ):
def isRepeatedEvent( self ):
def isShiftDown( self ):

Attributes

character
cursorPosition
key
modifiers
repeatCount

Detailed Description

This class represents an input event generated by a key (whether it be keyboard, mouse, or joystick).

Member Function Documentation

def isAltDown( self ):

This method returns whether or not either alt key was down when this event occurred.

Returns:
A boolean indicating whether or not alt was down.

def isCtrlDown( self ):

This method returns whether or not either control key was down when this event occurred.

Returns:
A boolean indicating whether or not control was down.

def isKeyDown( self ):

Determines whether or not this is a key down event.

Returns:
A boolean indicating whether or not this is a key down event.

def isKeyUp( self ):

Determines whether or not this is a key up event.

Returns:
A boolean indicating whether or not this is a key up event.

def isModifierDown( self ):

This method returns whether or not any of the modifier keys (i.e. shift, alt, or control) were down when this event occured.

Returns:
A boolean indicating whether or not a modifier was down.

def isMouseButton( self ):

Determines whether or not this event refers to a mouse button.

Returns:
A boolean indicating whether or not this is a mouse button.

def isRepeatedEvent( self ):

Returns true if this event is due to auto-repeat, false otherwise.

Returns:
A boolean indicating whether or not this is an auto-repeat event.

def isShiftDown( self ):

This method returns whether or not either shift key was down when this event occurred.

Returns:
A boolean indicating whether or not shift was down.

Attribute Documentation

character

The Unicode character that was generated by this key event. If the key did not generate a character then this attribute is None.

cursorPosition

The clip-space position of where the mouse cursor was when the event occured.

key

The key-code of the key that generated this event.

modifiers

Modifiers indicates which modifier keys were pressed when the event occurred, and can include MODIFIER_SHIFT, MODIFIER_CTRL, MODIFIER_ALT.

repeatCount

Represents the repeat count for this key. This will be zero for the very first key press. It will be -1 if it is a key-up event.


PyLoft - BigWorld client Documentation

PyLoft Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyAttachment → PyObjectPlusWithWeakReference

Attributes

endPoint | MatrixProvider. Default is None.
maxAge | float. Default is 0.1.
textureName |
threshold | float. Default is 0.1

Detailed Description

* The PyLoft is a PyAttachment. It lofts a shape along a path, drawing a * single texture over the resultant mesh with no repeats.

* Shape : A line between the particle where it is first created, and the * position of a MatrixProvider.

* Path : The line between each particle in turn, in order from youngest to * oldest.

* The path is progressively refined down to a threshold level, meaning that * the longest distance between points is no more than threshold metres.

Example:
loft  = BigWorld.Loft( "optional_texture_name" )
m = BigWorld.player().model
m.node( "biped Head" ).attach( loft )
loft.endPoint = m.node( "biped R Clavicle" )

Attribute Documentation

endPoint

This is a MatrixProvider that gives shape to the loft. If an endpoint is provided, the loft is created using a shape, where the shape is a line connecting the attachment point and the endpoint matrix.

Type:
MatrixProvider. Default is None.

maxAge

This specifies how long into the past the loft should draw.

Type:
float. Default is 0.1.

textureName

This attribute specifies the name of the texture used to render the loft trail. The texture is stretched once along the entire loft, with the u-axis of the texture mapped along the path, and the v-axis mapped along the shape.

threshold

This specifies how far the source points must move before a path point is output. It filters out minute movements causing rendering anomalies.

Type:
float. Default is 0.1


PyMagnetPSA - BigWorld client Documentation

PyMagnetPSA Class Reference

[Pixie Module]

PyMagnetPSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Attributes

minDist | Float.
source | MatrixProvider.
strength | Float.

Detailed Description

The PyMagnetPSA PyParticleSystemAction sets up an acceleration on particles towards a particular point (magnitude based upon the square of the distance from that point).

A new PyMagnetPSA is created using Pixie.MagnetPSA function.

Attribute Documentation

minDist

minDist exists to avoid singularity type effects when a particle approaches the source of the attraction. It is used when calculating attraction instead of the particles distance to the source, when the particles distance to the source < minDist. Default value is 1.0.

Type:
Float.

source

Source is a MatrixProvider specifying the point to which particles are attracted. Default value is the origin of the ParticleSystem to which this ParticleSystemAction is attached.

Type:
MatrixProvider.

strength

The strength attribute is applied as a scaling factor to force of attraction between particles, and the MagnetPSA's source. Default value is 1.0.

Type:
Float.


PyMatrixSwarmPSA - BigWorld client Documentation

PyMatrixSwarmPSA Class Reference

[Pixie Module]

PyMatrixSwarmPSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Attributes

targets List of MatrixProvider objects. Default is empty [].

Detailed Description

PyMatrixSwarmPSA causes particles to "swarm" around a list of targets. This PyParticleSystemAction causes the particle to have is position transformed by the matrix of one of the targets rather than the source of the particle system. The particles are divided evenly among the targets.

A new PyMatrixSwarmPSA is created using Pixie.MatrixSwarmPSA function.

Attribute Documentation

targets

This is a list of target MatrixProvider objects to apply to particles instead of source of the particle systems transform.

Type:
List of MatrixProvider objects. Default is empty [].


PyMeshParticleRenderer - BigWorld client Documentation

PyMeshParticleRenderer Class Reference

[Pixie Module]

PyMeshParticleRenderer is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemRenderer → PyObjectPlus

Attributes

doubleSided | Bool.
materialFX | String.
sortType | String.
visual | String.

Detailed Description

MeshParticleRenderer is a ParticleSystemRenderer which renders each particle as a mesh object. MeshParticles are exported from 3D Studio Max using mesh particle option in Visual Exporter. A MeshParticle .visual file contains up to 15 unique simple pieces of mesh. The mesh particle renderer will use each one of these pieces as a single particle.

From BigWorld 1.8 and on, the MeshParticleRenderer can not render standard visuals. You should use VisualParticleRenderer instead.

Attribute Documentation

doubleSided

Specifies whether or not to draw the mesh pieces double sided.

Type:
Bool.

materialFX

Specifies the MaterialFX to use to draw the meshes into the scene. Each value specifies either a special effect, or a source and destination alpha-blend setting for the material. If no value is specified, materialFX defaults to 'SOLID'. The possible values are listed below:

SOLID: not alpha blended. source = ONE, destination = ZERO

ADDITIVE: alpha blended. source = SRC_ALPHA, destination = ONE

BLENDED: alpha blended. source = SRC_ALPHA, destination = INV_SRC_ALPHA

Refer to the DirectX documentation for a description of how material settings affect alpha blending.

Type:
String.

sortType

Specifies the sort type. The possible values are listed below:

NONE: minimal sorting. Choose this method if speed is paramount and the visual artifacts introduced are not noticeable. The particle system as a whole will be rendered in order with respect to other sorted objects, and the triangles contained within will be sorted back to front, however the particles themselves will render out of order.

QUICK: sorting is done in a way that allows the renderer to still draw in groups of 15, which introduced some sorting inaccuracies but maintains most of the speed of unsorted mesh particles. This method is highly recommended if you cannot notice the sorting innacuracies.

ACCURATE: sorting of individual objects and triangles is performed, which provides the most accurate sorting but breaks the ability of the renderer to perform fast 15-at-a-time rendering, thus decreasing rendering performance. If you choose this sorting method, make sure you double check the performance hit induced.

Refer to the DirectX documentation for a description of how material settings affect alpha blending.

Type:
String.

visual

This is the name of the mesh particle type to use for the particles. Default value is "".

Type:
String.


PyMetaParticleSystem - BigWorld client Documentation

PyMetaParticleSystem Class Reference

[Pixie Module]

PyMetaParticleSystem is part of the Pixie module. More...

import Pixie

Parent Classes

PyAttachment → PyObjectPlusWithWeakReference

Member Functions

def addSystem( self, particle_system ):
def clear( self ):
def duration( self ):
def force( self, num ):
def load( self, name ):
def nSystems( self ):
def removeAllSystems( self ):
def removeSystem( self, particle_system ):
def render( self ):
def save( self, name ):
def system( self, particle_system ):
def update( self, dt ):

Detailed Description

The PyMetaParticleSystem can contain several PyParticleSystem objects, allowing them to function as a single object. As a PyAttachment, the PyMetaParticleSystem can be attached to other BigWorld objects.

A new PyMetaParticleSystem is created using Pixie.MetaParticleSystem function.

Member Function Documentation

def addSystem( self, particle_system ):

This function adds a ParticleSystem to the MetaParticleSystem container.

Parameters:
particle_system The ParticleSystem to add to this container.

def clear( self ):

This function calls the clear method of each contained ParticleSystem (effectively removes all particles from all contained ParticleSystems).

def duration( self ):

This function looks for a sink in each contained ParticleSystem and returns the maximum age of each particle system, returns -1 if no sinks are found

def force( self, num ):

This method forces each ParticleSystem contained within the MetaParticleSystem to forcibly create num units of particles. The number of particles created by each unit are dependant upon the individual ParticleSystems forcedUnitSize in an attached source ParticleSystemAction (see SourcePSA).

Parameters:
num An integer representing the number of units to force on the SourcePSA of all contained ParticleSystems.

def load( self, name ):

This function loads a saved MetaParticleSystem definition from an XML file.

Parameters:
name Name of the XML file to load.

def nSystems( self ):

This function returns the number of ParticleSystems contained within this MetaParticleSystem.

def removeAllSystems( self ):

This function removes all ParticleSystems from the MetaParticleSystem container.

def removeSystem( self, particle_system ):

This function removes a ParticleSystem from the MetaParticleSystem container.

Parameters:
particle_system Either a string containing the name of the ParticleSystem or a reference to the ParticleSystem to be removed.

def render( self ):

Draws all ParticleSystems contained within this MetaParticleSystem. You do not need to call this method.

def save( self, name ):

This functions saves a MetaParticleSystem definition to an XML file.

Parameters:
name Name of the XML file to save to.

def system( self, particle_system ):

This function returns a reference to a ParticleSystem within the container, or None if no matching ParticleSystem is found.

Parameters:
particle_system String containing the name of the ParticleSystem to return.

def update( self, dt ):

Updates all particle systems contained within this MetaParticleSystem by the specified time slice dt. You do not need to call this method.

Parameters:
dt Time interval to update particle system by (in seconds).


PyModel - BigWorld client Documentation

PyModel Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyAttachment → PyObjectPlusWithWeakReference

Member Functions

def action( self, actionName ):
def addMotor( self, motor ):
def alignTriangle( self, vertex0, vertex1, vertex2, randomYaw ):
def cue( self, identifier, function ):
def delMotor( self, motor ):
def getSound( self, s ):
def node( self, nodeName, local ):
def origin( self, nodeName ):
def playSound( self, s ):
def reflectOffTriangle( self, vertex0, vertex1, vertex2, fwd ):
def restoreActionQueue( self, state ):
def rotate( self, angle, vAxis, vCentre ):
def saveActionQueue( self, state ):
def straighten( self ):
def zoomExtents( self, upperFrontFlushness, xzMultiplier ):

Attributes

actionScale | Float
bounds | Read-Only MatrixProvider
height | Float
inWorld | Read-Only Integer
motors | List of Motors
moveAttachments | Boolean
moveScale | Float
outsideOnly | Integer
position | Vector3
queue | Read-Only List of Strings
root | Read-Only PyModelNode
scale | Vector3
shimmer | Integer
sources | Read-Only List of Strings
stipple | Integer
stopSoundsOnDestroy | bool
tossCallback | Function object
unitRotation | Read-Only Float
visible | Integer
visibleAttachments | Integer
yaw | Float;

Detailed Description

PyModels are renderable objects which can be moved around the world, animated, dyed (have materials programatically assigned) and attached to.

PyModels are constructed using the BigWorld.Model function, which takes the resource id of one or more .model files. Each of these individual models is loaded, and combined into a supermodel, which is the PyModel.

For example, to load a body and a head model into one supermodel:

model = BigWorld.Model( "models/body.model", "models/head.model" )

Models which are attached to entities can have Motors. These are objects which control how the model moves in response to its parent entity moving. The default Motor for a PyModel is an ActionMatcher which also takes care of synchronising animations with the movement of the model (for example, playing Idle when it stands still, and Walk when it moves at walking speed).

In order to animate a PyModel, you play actions on it. You do this by calling an ActionQueuer object. These are available as named attributes from the PyModel, as well as by using the action function to look up the name.

For example:
ac1 = model.Walk
ac2 = model.action("Walk")
both obtain the same ActionQueuer object. The action can be played by calling the object, as follows:
model.Walk()

Actions are defined in the .model file.

A PyModel can also have one or more instances of PyDye. These are available as named attributes, in exactly the same way that actions are. The PyDye can be assigned a string which names a particular tint, which will change the material which is applied to a particular piece of geometry on the model.

For example:
# Apply the Red tint (which is defined in the .model file) to the Chest
# PyDye.
model.Chest = "Red"

In addition, a PyModel can have hardpoints. A hardpoint is a node that has a prefix of "HP_" on its name. This is defined in the .model file. A PyAttachment can be attached to a hardpoint by assigning it to an attribute with that hardpoints name.

For example, if there were a node named HP_RightHand:
# attach the sword model to the biped's right hand
biped.RightHand = sword

Member Function Documentation

def action( self, actionName ):

This method looks up an action by name from an internal list of actions and returns an ActionQueuer object if it finds it. Otherwise a Python type error is thrown.

Parameters:
actionName A string which is the name of the action to search for.

Returns:
The ActionQueuer object named actionName.

def addMotor( self, motor ):

This method adds the specified object to the model's list of Motors. All motors in this list are able to influence the movement and animation of the model based on the state of the entity which owns it.

Parameters:
motor A Motor which is to be added to the model

Returns:
None

def alignTriangle( self, vertex0, vertex1, vertex2, randomYaw ):

This method aligns a model to the given triangle (specified as three points in world space, taken in a clockwise direction). The resultant world matrix will be in the middle of the triangle, with its z-axis along the triangles normal. If randomYaw is true, The model's y-axis will be random; otherwise it will be along the world's positive y-axis if the y component of the triangle's normal (in world space) is less than 0.95; otherwise along the world's positive x-axis.

For example:
m.alignTriangle( (1, 0, 0), (-1, 0, 0), (0,0,1), 0)
results in the model lying on its back, with its head pointing along the world's positive x-axis. Wheras
m.alignTriangle( (1, 0, 0), (-1, 0, 0), (0,1,0), 0)
results in the model standing upright, facing in the world's negative z-axis.

Parameters:
vertex0 | A Vector3 specifying the first point of the triangle to align to.
vertex1 | A Vector3 specifying the second point of the triangle to align to.
vertex2 | A Vector3 specifying the third point of the triangle to align to
randomYaw | A boolean specifying whether or not to apply a random yaw to the model.

Returns:
None

def cue( self, identifier, function ):

This method is not yet supported.

This method sets the default response for the given cue identifier.

A cue is a named frame inside an animation, that is exported with the model. If this function is used to set up a callback function then anytime that named frame gets played, the function will be called.

For example, assuming that there was a cue named Impact in the swordSwing animation, which is played using the SwordSwing ActionQueuer, then the following example will print "Sword hit target" at that point in the animation.

def onImpact( t ):  print "Sword hit target at time", t
biped.cue( "Impact", onImpact )
biped.SwordSwing()

It raises a TypeError if the given function parameter is not callable. It raises a ValueError if the identifier is unknown.

Parameters:
identifier | A String. The cue identifier we are setting a response for.
function | A callable object. The callback for that cue identifier.

def delMotor( self, motor ):

This method removes the specified object to the models list of Motors. All motors in this list are able to influence the movement and animation of the model based on the state of the entity which owns it.

Parameters:
motor A Motor which is to be removed from the model

Returns:
None

def getSound( self, s ):

Returns a PySound for a 3D sound event at the location of the model. The sound can subsequently be played by calling its play() method.

For sound naming semantics, please see FMOD.playSound().

Parameters:
s The name of the sound

Returns:
The PySound for this sound event

def node( self, nodeName, local ):

Returns the named node. If the name is empty string, the root node is returned. If the named node doesn't exist then an exception is generated. Using this method is not valid for blank models and will raise an exception.

Parameters:
nodeName | A string specifying the name of the node to look up.
local | (optional) A local transform for the node. This is a matrix provider that premultiplies itself with the node's world transform, effectively creating a new node to attach things to.

Returns:
The node with the specified name. ValueError is raised if the node does not exist.

def origin( self, nodeName ):

Make the named node the origin of the model's coordinate system, if a node with that name exists. If it does, return 1, otherwise 0.

Parameters:
nodeName The name of the node to make the origin

def playSound( self, s ):

Plays a 3D sound at the location of the model.

For sound naming semantics, please see FMOD.playSound().

Parameters:
s The name of the sound

Returns:
The PySound for this sound event

def reflectOffTriangle( self, vertex0, vertex1, vertex2, fwd ):

This method reflects the Vector3 specified by the fwd argument off the specified triangle, and places the model in the centre of the triangle facing in the direction of the reflected vector. The model's vertical will be will be along the world's positive y-axis if the new unit forward vector has a world space y component less than 0.95, otherwise along the world's positive z-axis.

Parameters:
vertex0 | A Vector3 specifying the first point, in world space, of the triangle to align to.
vertex1 | A Vector3 specifying the second point, in world space, of the triangle to align to.
vertex2 | A Vector3 specifying the third point, in world space, of the triangle to align to.
fwd | The vector, in world space, to reflect off the triangle, giving the new forward direction for the model.

Returns:
A Vector3, which is the new forward direction for the model in world space.

def restoreActionQueue( self, state ):

This function is used to restore the state of the pyModel's action queue. This useful when doing a change to the pyModel's supermodel which would involve reloading the supermodel and its animation and action states.

Parameters:
state DataSectionPtr to restore the state from.

Returns:
Returns True (1) whether the restore operation was able to completely restore the previous state of the action queue, False (0) otherwise. The restore operation may fail if an action that was in the actionQueue is no longer part of the refreshed supermodel.

def rotate( self, angle, vAxis, vCentre ):

This method rotates a model about an arbitrary axis (and optionally an arbitrary centre). A centre may be specified, otherwise it defaults to (0,0,0). The centre is relative to the origin of the model.

Parameters:
angle | The angle to rotate the model through.
vAxis | A Vector3 axis about which to rotate the model. This axis will pass through vCentre.
vCentre | A Vector3 through which vAxis passes, when the rotation about it is applied. It defaults to (0,0,0).

Returns:
None

def saveActionQueue( self, state ):

This function is used to save the state of the pyModel's action queue. This useful when doing a change to the pyModel's supermodel which would involve reloading the supermodel and its animation and action states.

Parameters:
state DataSectionPtr to save the state to.

def straighten( self ):

This method straightens a model, i.e. removes all rotations (including yaw) from it. It also removes any scaling effects, leaving nothing but the translation part of the world matrix.

Returns:
None

def zoomExtents( self, upperFrontFlushness, xzMultiplier ):

This method places the model at the origin, scaled to fit within a 1 metre cube; that is, its longest dimension will be exactly 1 metre. Its placement within the cube depends on upperFrontFlushness. If upperFrontFlushness is non-zero it moves the model to be flush with the top front of the cube, rather than the bottom.

You have the option of placing a model in a box is wider than it is tall. To do this, set the xzMultiplier to the (width / height) of the box.

Parameters:
upperFrontFlushness | Whether to align with the top-front or the bottom-rear.
xzMultiplier | ( default 1.0 ) for placing a model in a non-cubic box.

Returns:
None

Attribute Documentation

actionScale

This attribute sets the model's action's animation speed scale. The higher the actionScale the faster the model's actions are played.

Type:
Float

bounds

This read-only attribute gives the bounding box for the model. It returns a MatrixProvider. The matrix specifies what transformation would need to be applied to a 1x1x1 cube placed at the world-space origin to scale, rotate and translate it to bound the model. The bounds themselves are read in from the <boundingBox> property of the .visual file that was used to create the model, and don't update to reflect the current pose of the model.

This MatrixProvider can be used with the BoundingBoxGUIComponent to find the smallest bounding rectangle of the model, in relation to the current viewport on the world.

Type:
Read-Only MatrixProvider

height

This is the height of the bounding box used for collision detection. Changing this variable sets the top of the bounding box to height above the existing bottom of the bounding box.

Type:
Float

inWorld

This attribute is used to determine whether the model has been added to the world. It is read only, and is set to 1 if the Model is in the world, 0 otherwise. In order to add a model to the world, you can attach it to another model, or set the model attribute of an entity to this PyModel.

Type:
Read-Only Integer

motors

This attribute is the list of motors which affect the position and rotation of the model, based on the position and rotation of the owning entity. It is generally manipulated using the addMotor and delMotor functions on the model. On creation, an entity's model has an ActionMatcher as its only motor.

Type:
List of Motors

moveAttachments

This attribute can be set to allow motors to function on attached objects. By default this flag is turned off, because calling move on all known nodes on all PyModels can take a measurable amount of time, even if there are no motors attached. Note the action matcher is a motor, turn this flag on to allow the action matcher to apply to attached objects.

Type:
Boolean

moveScale

This attribute sets the model's actions's movement speed scale. The higher the moveScale the faster the model moves.

Type:
Float

outsideOnly

Indicates that this model is only ever positioned in outside chunks. This allows the engine to optimise processing on this model. There are extra processing steps that need to be done if this model is capable of being inside. If it is only ever going to be outside, then optimise by setting this attribute to 1. By default it is 0.

Type:
Integer

position

The position of the model within the world, as a 3d vector. This is in theory write as well as read, however if there are motors attached to the model, then those motors will often update the models position every tick, at which point any data written will be overwritten before it gets rendered at the new position. In a model with no motors though, you can set the models position by writing to this attribute.

Type:
Vector3

queue

This read only attribute is a list of the names of the actions which have been queued up to play.

Type:
Read-Only List of Strings

root

This read-only attribute is the root node of the model.

Type:
Read-Only PyModelNode

scale

Used to scale the model in each of the 3 dimensions. Takes a vector3, each component of which specifies the scale for the model in the corresponding dimension. This only effects the rendering of the model, not its bounding box for collision tests

Type:
Vector3

shimmer

This attribute ovverides the model's shaders and draws all opaque pixels into the shimmer channel.

Type:
Integer

sources

This read-only attribute is a list of the resource ids of all the models that make up the super model. In the case of a simple model this is a list of just one resource id.

Type:
Read-Only List of Strings

stipple

This attribute sets the model and its attachments into stipple mode, meaning the model is drawn with a screen-based mask that only allows drawing on every other pixel. It can be used as a cheap invisibility or transparency effect.

Type:
Integer

stopSoundsOnDestroy

Controls whether or not sounds attached to this model are stopped when this model is destroyed. This attribute is set to True by default, however you may want to set this to False if you have a special effect whose model may disappear before its sound events have finished playing.

Type:
bool

tossCallback

This attribute is the callback function that gets called every time the model moves from one chunk to another. There are no specific arguments supplied to the function.

Type:
Function object

unitRotation

This attribute allows scripts to access the difference in yaw between the model and the direction the ActionMatcher (if one is present) is matching to.

Type:
Read-Only Float

visible

This attribute controls whether or not the model is rendered. If it is set to 0, the model is not rendered, anything else and it is rendered.

Type:
Integer

visibleAttachments

This attribute can be set to allow hiding of model but update of animation and drawing of attachments (or allowing selective control of their individual visibility). Only meaningful when visible flag is set to false.

Type:
Integer

yaw

The rotation of the model about its own (rather than the world's) y-axis. This is, in theory, write as well as read, however if there are motors attached to the model, then those motors will often update the models yaw every tick, at which point any data written will be overwritten before it gets rendered at the new yaw. In a model with no motors though, you can set the models yaw by writing to this attribute.

Type:
Float;


PyModelNode - BigWorld client Documentation

PyModelNode Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

MatrixProviderLiaison → MatrixProvider → PyObjectPlus

Member Functions

def attach( self, attachment ):
def detach( self, attachment ):

Attributes

attachments | List of PyAttachments
inWorld | Read-Only Integer
local | Read-Only MatrixProvider
name | Read-Only String

Detailed Description

A PyModelNode is a MatrixProvider which is weighted with other nodes to calculate the transformation matrix for a particular piece of geometry. In a biped for example, "biped Spine", "biped Spine1" and "biped Pelvis" are all nodes which are used to transform the torso geometry.

PyAttachments can be attached to PyModelNodes, which will store them in the attachments attribute.

PyModelNodes cannot be created dynamically, but are part of a PyModel, which is loaded from a .model file. They can be accessed using the node function, which obtains the PyModelNode of the specified name from a model.

A PyModelNode's matrix is only updated after the owning model's nodes are updated, which is at draw time. This means that from script the very first time you create a PyModelNode referece it's internal transform wil not yet be set. You will have to wait until the owning model updates and draws at least once before accessing the node's matrix.

For example:
myNode = model.node( "biped Head" )
obtains the head node of the model.

Member Function Documentation

def attach( self, attachment ):

This function takes a PyAttachment and attaches it to the node. The attachment must not already be attached to something. Attaching it causes the attachment to appear with its root node with the same position and rotation as this node. It also sets the attachments inWorld attribute to the inWorld Attribute of this PyModelNode.

Examples of things which can be attached are models and particle systems.

Parameters:
attachment the PyAttachment to be attached to this node.

def detach( self, attachment ):

This function takes a PyAttachment, and tries to detach it from this node. This will fail and error if the attachment wasn't attached to this node when the call was made.

Raises a ValueError if the given attachment is not attached to this node.

Parameters:
attachment the PyAttachment to be detached from this node.

Attribute Documentation

attachments

This attribute is the list of all PyAttachments which are attached to this node. PyAttachments can be added and removed from the list using the attach and detach functions.

Type:
List of PyAttachments

inWorld

This attribute is used to determine whether the parent model has been added to the world. It is read only, and is set to 1 if the Model is in the world, 0 otherwise. In order to add a model to the world, you can attach it to another model, or set the model property of an entity to this Model.

Type:
Read-Only Integer

local

This attribute is the local transform for the node. The local transform is pre-multiplied to the node matrix and affects every attached object.

Type:
Read-Only MatrixProvider

name

This attribute is the name of the node

Type:
Read-Only String


PyModelObstacle - BigWorld client Documentation

PyModelObstacle Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

attached | Read-only bool
bounds | Read-only MatrixProvider
dynamic | bool
matrix | MatrixProviderPtr
sources | Read-only tuple of strings
vehicleID | uint32

Detailed Description

The PyModelObstacle object is a Model that is integrated into the collision scene. They have no motors, attachments or fashions, like a PyModel and so are driven by a single MatrixProvider, which is often linked to the Entity that will use the PyModelObstacle. the PyModelObstacle can be dynamic and move around the world, still engaged in the collision scene, or static, remaining in a single location. In the latter case, it makes sense for the owner Entity to be stationary in the world, otherwise the PyModelObstacle and Entity position would be dispersed, which is undesirable. The PyModelObstacle should be assigned to the self.model attribute of an Entity to become part of the world and once this occurs, the dynamic or static state of the PyModelObstacle is fixed and cannot be changed. PyModelObstacles are more expensive that standard PyModels, hence should only be used when completely necessary.

PyModelObstacles are constructed using BigWorld. PyModelObstacle function.

Attribute Documentation

attached

This flag is set to true when the PyModelObstacle is assigned to an Entity. Once this occurs, it is placed in the collision scene and no further changes can be made to its dynamic nature.

Type:
Read-only bool

bounds

Stores the bounding box of the PyModelObstacle as a MatrixProvider.

Type:
Read-only MatrixProvider

dynamic

If true, PyModelObstacle will be treated as dynamic, otherwise static. Note: This value should be set upon creation. Once it is attached/assigned, it cannot be changed.

Type:
bool

matrix

This is the transform matrix for the PyModelObstacle. As the MatrixProvider is updated, the PyModelObstacle will follow it.

Type:
MatrixProviderPtr

sources

This is the set of .model resources specified upon creation

See:
BigWorld.PyModelObstacle

Type:
Read-only tuple of strings

vehicleID

To place PyModelObstacle on a vehicle, set the vehicleID to the EntityID of the vehicle. To alight from the vehicle, set it back to 0. This parameter is used to identify platforms when applying gravity e.g. MovingPlatform.py.

Type:
uint32


PyModelRenderer - BigWorld client Documentation

PyModelRenderer Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlusWithWeakReference

Member Functions

def render( self ):

Attributes

dynamic | Integer
models | List of PyModels
texture | Read-Only PyTextureProvider

Detailed Description

This class is used to render a model to a PyTextureProvider, which can be used by gui components, such as a SimpleGUIComponent to render that model to the screen. It can either render a single frame of a model or provide a dynamic PyTextureProvider which updates every frame.

In order for a model to be rendered, it must not be attached to anything, which means that it cannot be in the world.

The camera is positioned at (0,1,-1), looking at (0,-1,1). It cannot be configured.

The models scale, position and rotation attributes can be used to setup the model in the correct position. The model can have Actions playing on it.

Multiple models are all added to the same render space, and rendered at whatever position they are placed at.

The background for the render has an alpha of zero.

A new PyModelRenderer is created using the BigWorld.PyModelRenderer function.

Example:
# create a new model to render
mod = BigWorld.Model( "objects/models/characters/biped.model" )

# create the model renderer
mr = BigWorld.PyModelRenderer( 256, 256 )
mr.models = [ mod ]

# the pyModelRenderer camera is setup well to look at a unit cube.
# here we make the model fit into that cube
mod.zoomExtents()

# setting the renderer to dynamic means it will update every frame.
# this is good for animating models, or if there is a motor attached
# (for example an oscillator, which makes it spin around)
# usage : mr.dynamic = 1

# however in this case, the biped model isn't animating, and there is
# no motor attached.  therefore we have to call render() explicitly.
# Note that render MUST be called before accessing the texture() attribute.
mr.dynamic = 0
mr.render()

# create a component to display it in
cmp = GUI.Simple( "somedummytexture.bmp" )
cmp.texture = mr.texture
GUI.addRoot( cmp )

Member Function Documentation

def render( self ):

This function causes the PyModelRender to redraw all of its models with all their current fashions (Animations, dyes, etc). This function call is not necessary if the dynamic attribute is set to non-zero, because it will automatically render every tick.

Attribute Documentation

dynamic

If this attribute is zero (its default), then it only updates its texture when the render() function is called. If it non-zero, then every tick it updates the texture to reflect any changes in the models.

Type:
Integer

models

This attribute is a list of all the models that will be rendered.

Type:
List of PyModels

texture

This attribute is the read-only PyTextureProvider which can be used by something like the SimpleGUIComponent to provide a dynamic texture to render.

Type:
Read-Only PyTextureProvider


PyMorphControl - BigWorld client Documentation

PyMorphControl Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyFashion → PyObjectPlus

Attributes

input | MatrixProvider
targetNames | List of Strings

Detailed Description

This class is used to blend morph targets onto a PyModel, using blend weights specified in a MatrixProvider. The list of morph targets is specified by the targetNames attribute, the MatrixProvider is specified by the input attribute.

To apply the PyMorphControl to a model, it should be assigned to an arbitrarily named attribute of that model. In order to function correctly, the named morph targets should all have been exported as part of the model's primitives.

If more than one PyMorphControl is applied to a model at once, then the morph targets of both of them are weighted together.

A new PyMorphControl is created using the BigWorld. PyMorphControl function.

For example:
mat = Math.Matrix()
mat.setElement( 0, 0, 2.0 ) # set the blend weight for "openLips" to 2.0
mat.setElement( 0, 1, 1.0 ) # set the blend weight for "closedLips" to 1.0
self.model.myMorphControl = BigWorld.PyMorphControl()
self.model.myMorphControl.input = mat
self.model.myMorphContro.targetNames = [ "openLips", "closedLips" ]
This example sets the model to have its lips two thirds open, assuming that the two named morph targets existed on the model.

Attribute Documentation

input

This attribute takes a MatrixProvider, whose elements are mapped to the items in the targetNames attribute, with the first row being mapped to the first four items, the next row being mapped to the next four items, and so on, for up to sixteen items. Elements beyond the last item of targetNames are ignored.

Each element of the MatrixProvider is treated as the blend weight for the morph target named in the corresponding targetName item.

Type:
MatrixProvider

targetNames

This attribute is a list of names of morph targets that this PyMorphControl will blend between. It will blend using the weights supplied in the input attribute, which is a MatrixProvider, whose items are mapped to the names in this attribute.

All the named targets should have been exported as morph targets in the models primitive file, or undefined behaviour will result.

Type:
List of Strings


PyMouseEvent - BigWorld client Documentation

PyMouseEvent Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

cursorPosition
dx
dy
dz

Detailed Description

This class represents an input event generated by moving the mouse.

Attribute Documentation

cursorPosition

The clip-space position of where the mouse cursor was when the event occured.

dx

The movement delta in the X direction.

dy

The movement delta in the Y direction.

dz

The movement delta in the Y direction (i.e. mouse wheel).


PyMovieDef - BigWorld client Documentation

PyMovieDef Class Reference

[Scaleform Module]

PyMovieDef is part of the Scaleform module. More...

import Scaleform

Parent Classes

PyObjectPlus

Member Functions

def createInstance( self, bool ):
def setAsFontMovie( self ):

Detailed Description

This class wraps Scaleform's Movie Definition and provides lifetime control and python access to its API.

A Movie Definition contains the resources for an .swf file, and allows creation of instanced views of the movie.

Movie Definitions can also be loaded for the sole purpose of providing fonts for other movies and for flash text components.

Member Function Documentation

def createInstance( self, bool ):

This function creates an instance of the movie definition. * It returns a PyMovieView object.

Parameters:
bool [optional] Specifies whether the frame1 tags of the * swf movie are executed or not during the createInstance call. * Default: true

def setAsFontMovie( self ):

Set this movie as the font source for the DrawTextManager, which is * used by FlashTextComponents to draw with.


PyMovieView - BigWorld client Documentation

PyMovieView Class Reference

[Scaleform Module]

PyMovieView is part of the Scaleform module. More...

import Scaleform

Parent Classes

PyObjectPlus

Member Functions

def gotoFrame( self, Integer ):
def gotoLabeledFrame( self, String, Integer ):
def handleKeyEvent( self, event ):
def handleMouseButtonEvent( self, event ):
def handleMouseEvent( self, event ):
def hitTest( self, position ):
def invoke( self ):
def restart( self ):
def setExternalInterfaceCallback( self, Callable ):
def setFSCommandCallback( self, Callable ):
def setFocussed( self ):
def setPause( self, Boolean ):

Attributes

backgroundAlpha | Read-Write Float.
scaleMode |
userData |
visible |

Detailed Description

This class wraps Scaleform's Movie View and provides lifetime control and python access to its API.

A Movie View is an instanced view of a Movie Definition, and can only be created via the PyMovieDef.createInstance() method.

Member Function Documentation

def gotoFrame( self, Integer ):

This function moves the playahead to the specified frame. Note that * calling this function may cause ActionScript tags attached to the * frame to be bypassed.

Parameters:
Integer The frame number to go to.

def gotoLabeledFrame( self, String, Integer ):

This function moves the playahead to the frame with the given label. * If the label is not found, the function will return false.

Parameters:
String | The frame label to go to.
Integer | Offset from the label.

Returns:
Boolean Whether or not the label was found.

def handleKeyEvent( self, event ):

Call this method to pass a key event into the underlying flash movie. If the * movie handles the event, this method will return True.

Parameters:
event A PyKeyEvent object.

Returns:
True if the event was handled, False if it was not

def handleMouseButtonEvent( self, event ):

Call this method to pass a mouse button event into the underlying flash movie. If the * movie handles the event, this method will return True.

Parameters:
event A PyKeyEvent object.

Returns:
True if the event was handled, False if it was not

def handleMouseEvent( self, event ):

Call this method to pass a mouse move event into the underlying flash movie. If the * movie handles the event, this method will return True.

Parameters:
event A PyMouseEvent object.

Returns:
True if the event was handled, False if it was not

def hitTest( self, position ):

This method is used to determine if a given screen space position intersects with * any geometry in the Flash movie (based on the last rendered viewport). It is useful * for allowing mouse events to pass through transparent parts of a Flash based HUD.

Parameters:
position Position in clip space.

Returns:
True if the position intersected with movie geometry, False if not.

def invoke( self ):

This function calls a function in the movie's ActionScript. It takes a string name * of the ActionScript method to call, and any number of arguments to be passed through. * If the second argument is a list, then that will be used as the argument list.

* For example:

* @{ * view.invoke( "_root.functionName" ) # Call function with no parameters * view.invoke( "_root.functionName", 1, 2, 3 ) # Call function with three args * view.invoke( "_root.functionName", [1,2,3] ) # This call is equivalent * @}

def restart( self ):

This function restarts the flash movie.

def setExternalInterfaceCallback( self, Callable ):

This function sets up the callback function used * to handle ActionScript's external interface command.

Parameters:
Callable A callable Python object (e.g. a method or * function). This will be passed two parameters: * the command name, and a tuple containing the * command arguments.

def setFSCommandCallback( self, Callable ):

This function sets up the callback function used * to handle ActionScript's fscommand.

Parameters:
Callable A callable Python object (e.g. a method or * function). This will be passed two parameters: * the command name, and a tuple containing the * command arguments.

def setFocussed( self ):

This function selects this movie as having IME focus, and * finalises IME support for the previously focussed movie.

* Once focussed, the movie will internally tell IME which * dynamic text fields are focussed, and IME will appear * accordingly.

def setPause( self, Boolean ):

This function sets the pause mode of the movie.

Parameters:
Boolean Flag specifying whether or not to pause the movie.

Attribute Documentation

backgroundAlpha

Sets the background color alpha applied to the movie clip. * Set to 0.0f if you do not want the movie to render its background * (ex. if you are displaying a hud on top of the game scene). * The default value is 1.0f, indication full opacity.

Type:
Read-Write Float.

scaleMode

This attribute stores the movie view scale mode, * which describes how the movie should display when the * viewing dimensions are not the same as the original * flash movie size.

userData

This attribute stores the User data object associated * with the movie. The data can be any object.

visible

Sets the visibility state of the movie view. Movie Views that * are invisible do not draw, and do not advance.


PyMozillaEvent - BigWorld client Documentation

PyMozillaEvent Class Reference

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

Parent Classes

PyObjectPlus

Attributes

intValue | int
rect | tuple of 4 ints
stringValue | string
stringValue2 | string
uri | string

Detailed Description

This class contains the event state that is passed to the listener for a BigWorld. WebPageProvider

@see WebPageProvider.listener for usage

Attribute Documentation

intValue

int value for this event

Type:
int

rect

rectangle for this event

Type:
tuple of 4 ints

stringValue

string value for this event

Type:
string

stringValue2

second string value for this event

Type:
string

uri

The url that this event is for

Type:
string


PyNodeClampPSA - BigWorld client Documentation

PyNodeClampPSA Class Reference

[Pixie Module]

PyNodeClampPSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Attributes

fullyClamp Bool

Detailed Description

PyNodeClampPSA is a PyParticleSystemAction that locks a particle to the Node the particle system is attached to. Any motion or change in position of the Node is also appied to the particles in the particle system.

A new PyNodeClampPSA is created using Pixie.NodeClampPSA function.

Attribute Documentation

fullyClamp

If set to true, the particles are clamped directly to the particle system position. If false, the particles are moved relatively each frame by the amount the particle system moved by.

Type:
Bool


PyObjectPlus - BigWorld client 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.


PyOrbitorPSA - BigWorld client Documentation

PyOrbitorPSA Class Reference

[Pixie Module]

PyOrbitorPSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Attributes

affectVelocity | Integer as boolean.
angularVelocity | Float.
point | Sequence of 3 floats.

Detailed Description

PyOrbitorPSA is a PyParticleSystemAction that causes particles to orbit around a point.

A new PyOrbitorPSA is created using Pixie.OrbitorPSA function.

Attribute Documentation

affectVelocity

affectVelocity is used to specify whether the OrbitorPSA affects a particle's velocity as well as it's position. Default is 0 (false).

Type:
Integer as boolean.

angularVelocity

angularValocity is used to specify the angular velocity of the orbit in degrees per second.

Type:
Float.

point

point specifies the center point around which the particles orbit. Default is (0.0, 0.0, 0.0).

Type:
Sequence of 3 floats.


PyOutputWriter - BigWorld client 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


PyParticleSystem - BigWorld client Documentation

PyParticleSystem Class Reference

[Pixie Module]

PyParticleSystem is part of the Pixie module. More...

import Pixie

Parent Classes

PyAttachment → PyObjectPlusWithWeakReference

Member Functions

def action( self, index ):
def addAction( self, action ):
def clear( self ):
def duration( self ):
def force( self, num ):
def load( self, filename ):
def removeAction( self, action ):
def render( self ):
def save( self, filename ):
def size( self ):
def update( self, dt ):

Attributes

actions | List of ParticleSystemAction.
capacity |
explicitDirection | Tuple of 3 float values.
explicitPosition | Tuple of 3 float values.
fixedFrameRate | Float
maxLod | Float.
renderer | ParticleSystemRenderer.
windFactor | Float value containing the windHalfLife.

Detailed Description

The PyParticleSystem class provides a base particle system to manage particles. A particle system must have particle system actions attached to it to specify how the particle system evolves over time.

A particle system must have at least a souce particle generator (SourcePSA) and a renderer specified for it to be able to generate particles. The two main types of particle renderers are SpriteParticleRenderer and MeshParticleRenderer.

A new PyParticleSystem is created using Pixie.ParticleSystem function.

Member Function Documentation

def action( self, index ):

Returns an action from the particle system.

Parameters:
index An index to the type of action. This is the id of the type of ParticleSystemAction you are looking for (see ParticleSystemAction for these values).

Returns:
A reference to the action if found (to the first created if multiple actions of that type exisit in the particle system) or None if none of that type of action belongs in the particle system.

def addAction( self, action ):

Adds a particle system action to the particle system.

Parameters:
action A reference to an instance of PyParticleSystemAction.

def clear( self ):

Removes all particles from the particle system.

def duration( self ):

This function looks for a sink in each contained ParticleSystem and returns the maximum age of each particle system, returns -1 if no sinks are found

def force( self, num ):

Forces particle system to spawn num particles.

Parameters:
num The number of particle to spawn (default num = 1).

def load( self, filename ):

Loads a particle system definition from an XML file.

Parameters:
filename name of the XML file to read from.

def removeAction( self, action ):

Removes a particle system action from the particle system.

Parameters:
action Either an index to the type of action to be removed (the first will be removed if there is more than one of that type) or a reference to an instance of ParticleSystemAction. The index is the id of the type of ParticleSystemAction you want to remove (see ParticleSystemAction for these values).

def render( self ):

Draws the particle system. You do not need to call this method.

def save( self, filename ):

Saves a particle system definition to an XML file.

Parameters:
filename name of the XML file to write to.

def size( self ):

Retrieves the number of currently active particles.

Returns:
The number of currently active particles.

def update( self, dt ):

Updates the particle system by the specified time slice dt. You do not need to call this method.

Parameters:
dt Time interval to update particle system by (in seconds).

Attribute Documentation

actions

This contains a list of actions acting on the Particle System.

Type:
List of ParticleSystemAction.

capacity

This specifies the maximum number of particles that can be present in the particle system.

explicitDirection

This sets the particle system to always use this direction as its direction (ignore world transform). Default is ( 0, 0, 1 ) and is not active. Setting either explicitPosition or explicitDirection sets a flag internal to the particle system to use the explicit values (this is off by default, and cannot be turned off once turned on).

Type:
Tuple of 3 float values.

explicitPosition

Set the particle system to always use this location as its position (ignore world space). Default is ( 0, 0, 0 ) and is not active. Setting either explicitPosition or explicitDirection sets a flag internal to the particle system to use the explicit values (this is off by default, and cannot be turned off once turned on).

Type:
Tuple of 3 float values.

fixedFrameRate

Simulates a fixed frame rate for particle systems. If the value is > 0, this indicates the desired frame rate. If <=0 then the current frame rate is used.

Type:
Float

maxLod

This specifies the maxLod property. The distance from the camera beyond which the particle system will not be drawn.

Type:
Float.

renderer

Renderer for the ParticleSystem. This can be used to set the ParticleSystemRenderer for the ParticleSystem or to access it.

Type:
ParticleSystemRenderer.

windFactor

Specifies how much effect the wind has on the particles velocity. Best values are from 0 to 1 and any negative value is treated as the wind having no effect on the particles. Values are treated as an exponential decay to the wind speed.

Type:
Float value containing the windHalfLife.


PyParticleSystemAction - BigWorld client Documentation

PyParticleSystemAction Class Reference

[Pixie Module]

PyParticleSystemAction is part of the Pixie module. More...

import Pixie

Parent Classes

PyObjectPlus

Attributes

delay | Float.
minimumAge | Float.
typeID | Integer as enumerated value.

Detailed Description

PyParticleSystemAction is the base class of all actions that modify the behaviour of a particle system over time. All actions can have a delay associated with them (the time an action will wait before affecting the particle system) and minimumAge (the age a particle must be before it can be affected by the action).

Multiple PyParticleSystemAction's can be stacked onto the particle system to create more complex behaviour.

Each PyParticleSystemAction has a typeID integer attribute to represent its type. They are as follows:

    PSA_SOURCE_TYPE_ID			 1
    PSA_SINK_TYPE_ID			 2
    PSA_BARRIER_TYPE_ID			 3
    PSA_FORCE_TYPE_ID			 4
    PSA_STREAM_TYPE_ID			 5
    PSA_JITTER_TYPE_ID			 6
    PSA_SCALAR_TYPE_ID			 7
    PSA_TINT_SHADER_TYPE_ID		 8
    PSA_NODE_CLAMP_TYPE_ID		 9
    PSA_ORBITOR_TYPE_ID			10
    PSA_FLARE_TYPE_ID			11
    PSA_COLLIDE_TYPE_ID			12
    PSA_MATRIX_SWARM_TYPE_ID	13
    PSA_MAGNET_TYPE_ID			14
    PSA_SPLAT_TYPE_ID			15

Attribute Documentation

delay

The delay in time from creation of the PyParticleSystemAction before its ParticleSystemAction affects the particle system. Default value is 0.

Type:
Float.

minimumAge

The minimum time a particle must have existed before being affected by the ParticleSystemAction. Default value is 0.

Type:
Float.

typeID

The type ID of the ParticleSystemAction, PSA_FLARE_TYPE_ID (see ParticleSystemAction).

Type:
Integer as enumerated value.


PyParticleSystemRenderer - BigWorld client Documentation

PyParticleSystemRenderer Class Reference

[Pixie Module]

PyParticleSystemRenderer is part of the Pixie module. More...

import Pixie

Parent Classes

PyObjectPlus

Attributes

local | Integer as boolean. 0 or 1.
viewDependent | Integer as boolean. 0 or 1.

Detailed Description

ParticleSystemRenderer is an abstract base class for PyParticleSystem renderers.

Attribute Documentation

local

If local is set to true, the coordinates of the particle system are in local space rather than world space. The viewDependant flag will be false if local set to true. If both are false, implies particle system will be rendered in world space.

Type:
Integer as boolean. 0 or 1.

viewDependent

If viewDependent is set to true, the coordinates of the particle system are in camera space rather than world space (ie, dependant on view). The local flag will be false if viewDependant set to true. If both are false, implies particle system will be rendered in world space.

Type:
Integer as boolean. 0 or 1.


PyPhase - BigWorld client Documentation

PyPhase Class Reference

[PostProcessing Module]

PyPhase is part of the PostProcessing module. More...

import PostProcessing

Parent Classes

Phase → PyObjectPlus

Attributes

clearRenderTarget | Boolean.
filterQuad | PyFilterQuad.
material | PyMaterial.
name | String.
renderTarget | PyRenderTarget.

Detailed Description

This class derives from PostProcessing::Phase, and provides a generic phase designed to be configured entirely via python. A phase is a single step within a PostProcessing Effect. It generally performs a single draw of a filter quad using a material into a render target.

Attribute Documentation

clearRenderTarget

Type:
Boolean.

filterQuad

Type:
PyFilterQuad.

material

Type:
PyMaterial.

name

Type:
String.

renderTarget

Type:
PyRenderTarget.


PyPointSpriteParticleRenderer - BigWorld client Documentation

PyPointSpriteParticleRenderer Class Reference

[Pixie Module]

PyPointSpriteParticleRenderer is part of the Pixie module. More...

import Pixie

Parent Classes

PySpriteParticleRenderer → PyParticleSystemRenderer → PyObjectPlus

Detailed Description

PointSpriteParticleRenderer is a ParticleSystemRenderer which renders each particle as a point sprite.

Texture animation (rolling uv) is not supported, nor are particle sizes on the screen > 64 pixels.

This particle renderer is the quickest to draw, and uses the least amount of graphics memory ( push buffer ).

A new PyPointSpriteParticleRenderer is created using Pixie.PointSpriteParticleRenderer function.


PyPointSpriteTransferMesh - BigWorld client Documentation

PyPointSpriteTransferMesh Class Reference

[PostProcessing Module]

PyPointSpriteTransferMesh is part of the PostProcessing module. More...

import PostProcessing

Parent Classes

FilterQuad → PyObjectPlus

Detailed Description

A PyPointSpriteTransferMesh can be used by a PyPhase object, and provides the geometry for the phase. In this case, the geometry is one point sprite for every pixel on the screen. The PointSpriteTransferMesh performs n-taps on the source material's textures, in groups of 4. If you specify more than 4 taps, then the filter quad will draw using n/4 passes. For these operations, you should make sure the material you use is additive, so the results can accumulate.


PyResourceRefs - BigWorld client Documentation

PyResourceRefs Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def has_key( self, resourceID ):
def items( self ):
def keys( self ):
def pop( self, resourceID ):
def values( self ):

Attributes

failedIDs Read-Only Object

Detailed Description

This class is a resource reference holder. It cannot be constructed explicitly, instead you must call BigWorld.loadResourceListBG - the ResourceRefs object is passed into the callback function. This class holds references to those resources it is initialised with, so as long as you hold a reference to the PyResourceRefs object, you will also be holding onto references to all of its resources.

Member Function Documentation

def has_key( self, resourceID ):

This function returns whether the PyResourceRefs has a reference to the resource given by the key.

Parameters:
resourceID the name of the resource to check.

Returns:
True or False.

def items( self ):

This function returns a list of tuples of (resourceID, object) representing this objects resources by name and their python equivalent

Returns:
list of tuples of (resourceID, object).

def keys( self ):

This function returns the list of resourceIDs.

Returns:
list of strings.

def pop( self, resourceID ):

This function returns the resource associated with a particular resource reference and erases it from PyResourceRefs ownership. If there is no python representation, or if the resource failed to load, None will be returned. In either case the PyResourceRefs object will no longer keep a reference to the resource and this is now up to the caller to manage.

Parameters:
resourceID the name of the required resource.

Returns:
python resource, or None.

def values( self ):

This function returns a list of the python equivalents for the resources held onto by this object.

Returns:
list of resource objects.

Attribute Documentation

failedIDs

This attribute contains a list of resources that failed to load. It is a subset of the resourceIDs list.

Type:
Read-Only Object


PySTLSequence - BigWorld client 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


PyScalerPSA - BigWorld client Documentation

PyScalerPSA Class Reference

[Pixie Module]

PyScalerPSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Attributes

rate | Float.
size | Float.

Detailed Description

PyScalerPSA is a PyParticleSystemAction that scales a particle over time. All particles eventually end up at the specified size, and the rate determines the speed at which they converge linearly to this size.

A new PyScalerPSA is created using Pixie.ScalerPSA function.

Attribute Documentation

rate

Rate per second at which particles scale towards the value size. Default is 0.0.

Type:
Float.

size

Eventual size of the particles as a scaling factor. It's effect is dependant upon the ParticleSystemRenderer. For a SpriteParticleRenderer the size is applied to the width and height of the sprites. Particles are scaled up or down linearly over time to reach this value. Default is 0.0.

Type:
Float.


PySceneRenderer - BigWorld client Documentation

PySceneRenderer Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlusWithWeakReference

Member Functions

def render( self ):

Attributes

cameras | List of Cameras
drawSplodges | Boolean
dynamic | Integer as boolean
fov | radian angle as float
skipFrames | Non-negative Intager
staggered | Integer as boolean
texture | Read-Only PyTextureProvider

Detailed Description

This class is used to render the world, as visible through specified cameras (which inherit from BaseCamera), onto a PyTextureProvider. The size of the texture is specified when the PySceneRenderer is created (using the BigWorld. PySceneRenderer function). If more than one camera is specified, then the texture is divided horizontally between them, with each camera getting a portion to render to.

If the dynamic attribute is non-zero (true), then the texture is updated every tick to reflect the scene showing in each camera. If dynamic is zero (false) then the texture is only updated when the render function is called.

For example:
psr = BigWorld.PySceneRenderer( 100, 100 )
psr.cameras = [ BigWorld.camera() ]
psr.dynamic = 1
cmp = GUI.Simple( "some_random_starting_texture.dds" )
cmp.texture = psr.texture
This example causes the cmp SimpleGUIComponent to render a mini view in the middle of the screen similar to what is showing in the main camera.

Member Function Documentation

def render( self ):

This function causes the PySceneRenderer to update its texture to the view currently visible through the camera when the function is called. This function only needs to be called if the dynamic attribute is zero (false), otherwise it is automatically called each tick.

Attribute Documentation

cameras

This attribute is the list of cameras through which the world is rendered. The texture is divided vertically between the cameras, with the first camera being rendered leftmost, and the last camera being rendered rightmost.

For example:
psr = BigWorld.PySceneRenderer( 100, 100 )
psr.cameras = [ BigWorld.camera() ]

Type:
List of Cameras

drawSplodges

Whether or not to draw splodges in the PySceneRenderer view. Defaults to false, for performance reasons.

Type:
Boolean

dynamic

If this attribute is zero (false) then the texture will only be updated when the render function is called. If this attribute is non-zero (true) then it will be updated every tick.

Type:
Integer as boolean

fov

This attribute represents the field-of-view of the camera, in radians

Type:
radian angle as float

skipFrames

The number of frames to elapse between updates this texture.

Type:
Non-negative Intager

staggered

Controls the frequency of dynamic update. Staggered (true) provides more consistent performance while * un-staggered (false) gives more consistent quality.

Type:
Integer as boolean

texture

This attribute is the texture that the PySceneRenderer draws to. It can be used by components which require a PyTextureProvider, such as the gui components to provide the texture to draw.

The texture will contain a render of the world for each camera in the cameras list. If dynamic is true, then the texture will be updated each tick, otherwise it will only be updated when render is called. If dynamic is not set, then the render function should be called at least once before this is assigned, or it will not render.

The texture will be of the size specified in the BigWorld. PySceneRenderer function that created this object.

For example:
psr = BigWorld.PySceneRenderer( 100, 100 )
psr.cameras = [ BigWorld.camera() ]
psr.render()
com.texture = psr.texture # where com is a SimpleGUIComponent

Type:
Read-Only PyTextureProvider


PyServer - BigWorld client Documentation

PyServer Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Detailed Description

A PyServer is the device through which an entity is able to call methods on it's instance on a server. BigWorld creates two PyServer objects as attributes for each client entity, "cell" and "base", which can be used to send method calls to the entity's cell and base instances, respectively. These cannot be created in script.

PyServer objects have no default attributes or methods, however BigWorld populates them with ServerCaller objects which represent the methods that can be called. These are built using information provided in the entity def files. A ServerCaller object can then be called as if it were the method that it represents, which causes it to add a request to call the appropriate function on the next bundle that is sent to the server.

This is not supported for licensees who have not licensed the BigWorld server technology.


PyShimmerCountProvider - BigWorld client Documentation

PyShimmerCountProvider Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Vector4Provider → PyObjectPlus

Detailed Description

This class is a special-case V4Provider that exposes the current number of visible shimmer objects. It is used to optimise the Heat Shimmer post-process effect.


PySinkPSA - BigWorld client Documentation

PySinkPSA Class Reference

[Pixie Module]

PySinkPSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Attributes

maximumAge | Float.
minimumSpeed | Float.

Detailed Description

PySinkPSA is a PyParticleSystemAction that destroys particles within a ParticleSystem. Particles can be destroyed if they are over a certain age or under or over a particular speed.

A new PySinkPSA is created using Pixie.SinkPSA function.

Attribute Documentation

maximumAge

Particles whose time in existence is greater then maximumAge are removed from the ParticleSystem. Default -1.0. This attribute is ignored if value is < 0.

Type:
Float.

minimumSpeed

Particles with a speed of less than minimumSpeed are removed from the ParticleSystem. Default -1.0. This attribute is ignored if value is < 0.

Type:
Float.


PySourcePSA - BigWorld client Documentation

PySourcePSA Class Reference

[Pixie Module]

PySourcePSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Member Functions

def create( self, number ):
def force( self, number ):
def getPositionSourceMaxRadius( self ):
def setPositionSource( self, generator ):
def setVelocitySource( self, generator ):

Attributes

activePeriod | Float in seconds.
dropDistance | Float.
forcedUnitSize | Integer.
grounded | Integer as boolean. 0 or 1.
ignoreRotation | Integer as boolean. 0 or 1.
inheritVelocity | float
initialColour | Sequence of 4 floats.
initialRotation | Sequence of 2 floats.
maxSpin |
maximumSize | Float.
minSpin |
minimumSize | Float.
motionTriggered | Integer as boolean. 0 or 1.
randomInitialRotation | Sequence of 2 floats.
randomSpin |
rate | Float. Particles per second.
sensitivity | Float. Must be greater than or equal to 0.0001f.
sleepPeriod | Float in seconds.
sleepPeriodMax | Float in seconds.
timeTriggered | Integer as boolean. 0 or 1.

Detailed Description

PySourcePSA is a PyParticleSystemAction that creates particles within a ParticleSystem. Particles can be created at a rate over time, on demand or in response to movement (see the sensitivity attribute) by the node to which the particle system is attached.

A new PySourcePSA is created using Pixie.SourcePSA function.

Member Function Documentation

def create( self, number ):

Queue number particles into the particle creation queue. Particles will be created using the normal creation algorithms for the SourcePSA.

Parameters:
number Integer. Number of particles to add to creation queue.

def force( self, number ):

Force creation of number units (see forcedUnitSize attribute) of particles on the next update.

Parameters:
number Integer. Nomber of units to create.

def getPositionSourceMaxRadius( self ):

Gets the maximum radius for the position source VectorGenerator.

Returns:
Float. Maximum radius.

def setPositionSource( self, generator ):

Sets a new VectorGenerator as a position source for the particles.

Parameters:
generator VectorGenerator. Position source for the particles.

def setVelocitySource( self, generator ):

Sets a new VectorGenerator as a velocity source for the particles.

Parameters:
generator VectorGenerator. Velocity source for the particles.

Attribute Documentation

activePeriod

activePeriod along with sleepPeriod determine an on/off cycle for time created particles.

Type:
Float in seconds.

dropDistance

Distance downwards to check for a grounded particle (see grounded attribute). Default is 15.

Type:
Float.

forcedUnitSize

The unit size for determining number of particles created when forcing particle creation (see force method).

Type:
Integer.

grounded

This attribute if set specifies that the source position's y coordinate if within dropDistance of the ground is set to the ground's y value. Ie it starts on the ground. Default is 0 (false).

Type:
Integer as boolean. 0 or 1.

ignoreRotation

If set particle systems ignore the rotation of the particle system's world tranform's rotation. Default is 0 (false).

Type:
Integer as boolean. 0 or 1.

inheritVelocity

Specifies how much velocity particles should inherit from SourcePSA when spawned, eg, a value of 0.0 will add no extra velocity to spawning particles and a value of 2.0 will add double the SourcePSA's velocity to the spawning particles.

Type:
float

initialColour

RGBA quad of floats for particle colour. Interpreted by mesh particle systems as spin. Default is (0.5, 0.5, 0.5, 1.0).

Type:
Sequence of 4 floats.

initialRotation

Used by Mesh particle systems. Initial Pitch/Yaw. Default is (0.0, 0.0).

Type:
Sequence of 2 floats.

maxSpin

When randomSpin is set, the particle is given a random amount of spin, between minSpin and maxSpin. [The units are 20 radians per second]

maximumSize

Largest scale for generated particle size. Default 1.0.

Type:
Float.

minSpin

When randomSpin is set, the particle is given a random amount of spin, between minSpin and maxSpin. [The units are 20 radians per second]

minimumSize

Smallest scale for generated particle size. Default 1.0.

Type:
Float.

motionTriggered

Flag for motion triggered particle creation. Particles are created when the speed of movement for the particle system exceeds the sensitivity value. The number of particles created is dependant upon the difference between speed and sensitivity divided by the sensitivity.

Type:
Integer as boolean. 0 or 1.

randomInitialRotation

Used by Mesh particle systems. Randomise the initial Pitch/Yaw. Default is (0.0, 0.0).

Type:
Sequence of 2 floats.

randomSpin

If set particle systems will be imbued with a random amount of angular velocity, and a random rotation axis. This property is exclusively for mesh particles.

rate

Rate of particle creation for time triggered particle creation.

Type:
Float. Particles per second.

sensitivity

Sensitivity to movement for motion triggered particle creation. Forced minimum value of 0.0001f. If the speed of movement of the particle system exceeds the sensitivity, then particles are generated (see motionTriggered for more information).

Type:
Float. Must be greater than or equal to 0.0001f.

sleepPeriod

activePeriod along with sleepPeriod determine an on/off cycle for time created particles.

Type:
Float in seconds.

sleepPeriodMax

sleepPeriodMax facilitates a random behaviour to sleepPeriod

Type:
Float in seconds.

timeTriggered

Flag for time triggered particle creation.

Type:
Integer as boolean. 0 or 1.


PySplatPSA - BigWorld client Documentation

PySplatPSA Class Reference

[Pixie Module]

PySplatPSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Attributes

callback

Detailed Description

PySplatPSA is a PyParticleSystemAction that collides particles with the collision scene, based upon their position and velocity. When a particle collides, it dies and calls the given callback class, which must have the following method callback.onSplat( self, (position3),(velocity3),(colour4) )

Note - this is a very expensive particle action, and should be used sparingly! Also note, the current implementation limits the action to 0.5msec per frame - after that, particles will simply fall through geometry.

A new PySplatPSA is created using Pixie.SplatPSA function.

Attribute Documentation

callback

The class that is called when a particle hits the collision scene. The class must have a method onSplat( self, (position3),(velocity3), (colour4) )


PySplodge - BigWorld client Documentation

PySplodge Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyAttachment → PyObjectPlusWithWeakReference

Attributes

maxLod | Read-Write float.
size | Read-Write Vector3.

Detailed Description

A PyAttachment which draws a "splodge" shadow on the ground below the point where it is attached. The shape of this shadow moves in relation to the position of the sun, and is only visible outside. The actual shadow is drawn using the material specified in resource.xml/environment/splodgeMaterial

A new PySplodge is created using BigWorld.Splodge function.

Attribute Documentation

maxLod

The maximum distance from a camera at which this will be drawn.

Type:
Read-Write float.

size

The x and y components of this describe the height and width of the object casting the splodge's shadow. This is used to calculate the size and shape of the splodge as it is drawn on the ground. The z component has no effect.

Type:
Read-Write Vector3.


PySpriteParticleRenderer - BigWorld client Documentation

PySpriteParticleRenderer Class Reference

[Pixie Module]

PySpriteParticleRenderer is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemRenderer → PyObjectPlus

Attributes

frameCount | Integer.
frameRate | Float.
materialFX | String.
textureName | String.
useFog |
viewDependent | Integer as boolean. 0 or 1.

Detailed Description

SpriteParticleRenderer is a ParticleSystemRenderer which renders each particle as a single spin to face polygon.

A new PySpriteParticleRenderer is created using Pixie.SpriteRenderer function.

Attribute Documentation

frameCount

Specifies the number of frames of animation in the texture. Default is 0.

Type:
Integer.

frameRate

Specifies the number of frames of animation per second of particle age. Default is 0.

Type:
Float.

materialFX

Specifies the MaterialFX to use to draw the sprites into the scene. Each value specifies either a special effect, or a source and destination alpha-blend setting for the material. If no value is specified, materialFX defaults to 'BLENDED'. The possible values are listed below:

ADDITIVE: alpha blended. source = SRC_ALPHA, destination = ONE

ADDITIVE_ALPHA: alpha blended. source = ONE, destination = INV_SRC_ALPHA

BLENDED: alpha blended. source = SRC_ALPHA, destination = INV_SRC_ALPHA

BLENDED_COLOUR: alpha blended. source = SRC_COLOUR, destination = INV_SRC_COLOUR

BLENDED_INVERSE_COLOUR: alpha blended. source = INV_SRC_COLOUR, destination = SRC_COLOUR

SOLID: alpha blended. source = ONE, destination = ZERO

SHIMMER: special effect not implemented on PC

Refer to the DirectX documentation for a description of how material settings affect alpha blending.

Type:
String.

textureName

Texture file name of the sprite.

Type:
String.

useFog

Specifies whether the renderer should enable scene fogging or not. You may want to turn off scene fogging if you are using particle systems in the sky box, or if you want to otherwise explicitly control the amount of fogging via the tint shader fog blend control.

viewDependent

Specifies whether the coordinates of the particle system are in camera space (true) rather than world space (false). Default is 0 (false - world space).

Type:
Integer as boolean. 0 or 1.


PyStreamPSA - BigWorld client Documentation

PyStreamPSA Class Reference

[Pixie Module]

PyStreamPSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Attributes

halfLife | Float.
vector | Sequence of 3 floats.

Detailed Description

PyStreamPSA is a PyParticleSystemAction the converges the velocity of particles to the velocity of the stream.

Drag can be simulated by setting the velocity to the zero vector.

A new PyStreamPSA is created using Pixie.StreamPSA function.

Attribute Documentation

halfLife

Half-life of convergence for the particles velocity to the stream velocity in seconds. Default is -1.0. Values should be < 0 for no effect, and >= 0 to have particles converge. 0 indicates instant convergence to the stream velocity.

Type:
Float.

vector

Vector describing the direction and magnitude of the stream velocity to which particle velocity is to be converged. Default is ( 0.0, 0.0, 0.0 ).

Type:
Sequence of 3 floats.


PyTarget - BigWorld client Documentation

PyTarget Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def __call__( self ):
def caps( self, cap ):
def clear( self ):
def debugLock( self, pEntity ):

Attributes

deselectionFov | Read-Write float
entity | Read-Only Entity.
exclude | Read-Write Entity
isEnabled | Read-Write Boolean.
isFull | Read-Only Boolean.
isHeld | Read-Write Boolean.
isHidden | Read-Only Boolean.
maxDistance | Read-Write float
noPartial | Read-Write bool
selectionFov | Read-Write float
skeletonCheckEnabled | Read-Write Boolean.
source | Read-Write MatrixProviderPtr

Detailed Description

The interface to the BigWorld targeting system. All targeting operations are accessed through an instance of this class. An instance of this class is automatically created by the engine as BigWorld.target.

The BigWorld targeting system will choose from a list of potential targets using the following criteria (in order of precedence):
    capabilities
    distance
    field of view
    line of sight

Member Function Documentation

def __call__( self ):

When called, a PyTarget returns the currently targeted entity.

Returns:
The currently targeted entity if it satisfies all capability requirements and is not hidden, otherwise None.

def caps( self, cap ):

This method sets the capability requirements that entities must meet in order to be targetted. This method takes 0 or more arguments.

Examples:

# any entity may be targetted. caps()

# only entities with capability 5 may be targetted. caps( 5 )

# only entities without capability 5 may be targetted. caps( -5 )

# only entities with capability 2, capability 3, and not capability 4 may # be targeted. caps( 2, 3, -4 )

Parameters:
cap A capability requirement of an entity for it to be targetted. If cap > 0, entities must have capability cap on. If cap < 0, entities must have capability -cap off. Including the cap 0 means match none.

Returns:
None.

def clear( self ):

Set the current target to None.

Returns:
None.

def debugLock( self, pEntity ):

Set the current target to pEntity (this is useful for debugging).

Parameters:
pEntity The entity to target.

Returns:
None.

Attribute Documentation

deselectionFov

This is the vertical angle in degrees outside of which the currently targetted Enitity will be automatically deselcted.

Type:
Read-Write float

entity

This provides the current target, which may not be visible or a "full" target (that is, a target that satisfies the capabilities requirements set via caps()).

Type:
Read-Only Entity.

exclude

This is the entity that is to be excluded from targeting operations. Usually this is the Player Entity, however need not be, eg, remote turret, etc...

Type:
Read-Write Entity

isEnabled

This stores whether the targetting system is allowed to select new targets.

Type:
Read-Write Boolean.

isFull

This stores whether or not the current entity is a "full" target. That is, a target that satisfies the capabilities requirements set via caps().

Type:
Read-Only Boolean.

isHeld

This stores whether to try to hold on to the current target entity. If the value is true, the target is kept kept while the entity is within the deselection frustrum and is not hidden for longer than maxHiddenTime_ (see EntityPicker::maxHiddenTime_ in entity_picker.hpp).

Type:
Read-Write Boolean.

isHidden

This shows whether the target is currently held but cannot currently be seen.

Type:
Read-Only Boolean.

maxDistance

This is the distance beyond which Entities will not be considered as potential targets.

Type:
Read-Write float

noPartial

When set, the entity picker will only allow full locks. This can be used to prevent targeting friendlies and buttons, etc, when in a combative state.

Type:
Read-Write bool

selectionFov

This is the vertical angle in degrees within which Enitities may be considered as a new target.

Type:
Read-Write float

skeletonCheckEnabled

This stores whether the targetting system should try to use the skeleton collider method as a selection criterion.

Type:
Read-Write Boolean.

source

This is the matrix that the targeting system will use to identify the location of the Player Entity. This will correspond to PlayerMProv if targeting from the player's current position. Otherwise, it will be the location from which all targeting should be performed, eg, remote turret, etc...

Type:
Read-Write MatrixProviderPtr


PyTextureProvider - BigWorld client Documentation

PyTextureProvider Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

height | Read-Only Integer
name | Read-Only String
owner | Read-Only Object
width | Read-Only Integer

Detailed Description

This class exposes a texture. There are several instances where a texture is required, for example by SimpleGUIComponent. This has two attributes, one called textureName, which takes the filepath of a texture file, the other called texture, which accepts a PyTextureProvider.

A PyTextureProvider can be created using the BigWorld. PyTextureProvider function, which creates a PyTextureProvider from a texture file. This can be useful if a class requires a PyTextureProvider, rather than a texture name.

Several classes (for example PyModelRenderer and PySceneRenderer) have an attribute which exposes a PyTextureProvider. This allows them to expose a dynamic texture, which gets updated on a tick by tick basis.

Attribute Documentation

height

This attribute is the texel height of the texture referenced by the PyTextureProvider.

Type:
Read-Only Integer

name

This attribute is the resource ID of the texture referenced by the PyTextureProvider.

Type:
Read-Only String

owner

This attribute is the owner of the PyTextureProvider. In the case of a PyTextureProvider created directly using the BigWorld. PyTextureProvider function, this is None. In the case of an object which exposes a PyTextureProvider, such as a PyModelRenderer, the owner is the object which does the exposing.

For example:
>>>	mod = BigWorld.Model( "models/man.model" )
>>>	modRend = BigWorld.PyModelRenderer(100, 100)
>>>	modRend.models = [ mod ]
>>>	tex = modRend.texture
>>>	tex.owner
PyModelRender at 0x00ff4565
This example gets the PyTextureProvider out of a PyModelRenderer and checks its owner, which is the PyModelRenderer.

Type:
Read-Only Object

width

This attribute is the texel width of the texture referenced by the PyTextureProvider.

Type:
Read-Only Integer


PyTintShaderPSA - BigWorld client Documentation

PyTintShaderPSA Class Reference

[Pixie Module]

PyTintShaderPSA is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemAction → PyObjectPlus

Member Functions

def addTintAt( self, time, colour ):
def clearAllTints( self ):

Attributes

fogAmount | Float The amount between 0.0 and 1.0.
modulator | Vector4Provider
period | Float The period in seconds.
repeat | Integer as boolean. 0 or 1.

Detailed Description

PyTintShaderPSA is a PyParticleSystemAction that tints a particle according to its age. The initial colour of a particle is ( 0.5, 0.5, 0.5, 1.0 ) in RGBA at time 0 and tinting occurs linearly from one tint to the next tint over the time interval between which they are set. Tints can be set at particular times using the addTintAt function.

A new PyTintShaderPSA is created using Pixie.TintShaderPSA function.

Member Function Documentation

def addTintAt( self, time, colour ):

Adds a colour (RGBA) to blend the tint to at a particular time. Particle colour gets changed linearly between each tint and the previous tint. You can think of the tint like a key frame for an animation.

Parameters:
time | Float. Time at which the tint key should be set in the colour cycle.
colour | Sequence of 4 floats. RGBA

def clearAllTints( self ):

Removes all tint values from the particles.

Attribute Documentation

fogAmount

Specifies the amount of fog to blend in with the animated colour.

Type:
Float The amount between 0.0 and 1.0.

modulator

This modulates the tint colour with an external vector 4 provider. this gives python scripts the ability to fade in particles over time (in addition to the tint being based on the particles age).

Type:
Vector4Provider

period

Specifies the the tint cycle loop time.

Type:
Float The period in seconds.

repeat

Specifies whether the tint cycle loops over the total time sequence. Default is 0 (false).

Type:
Integer as boolean. 0 or 1.


PyTrailParticleRenderer - BigWorld client Documentation

PyTrailParticleRenderer Class Reference

[Pixie Module]

PyTrailParticleRenderer is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemRenderer → PyObjectPlus

Attributes

skip | Integer.
steps | Integer.
textureName |
useFog |
width |

Detailed Description

TrailParticleRenderer is a ParticleSystemRenderer that lofts out a trail based on the cached history of particles. The trail is a textured 3D line that looks good from most angles, except when going straight into/out of the screen, in which case you will see a thin cross.

Because the history of a particles position is cached, the trail of each particle may bend ( as opposed to the BlurParticleRenderer, which will always have straight-line trails )

The TrailParticleRenderer should be used judiciously, because of the memory overhead of the particle history cache. However, it can create great effects using just a small amount of particles.

This renderer will use an extra n * s memory, where n is the capacity of the particle system, and s is the number of steps in each trail.

A new PyTrailParticleRenderer is created using Pixie.TrailParticleRenderer function.

Attribute Documentation

skip

The attribute skip is used to skip the render caching of trail elements every skip-1 frames. Thus if skip is 5, TrailParticleRenderer only caches render elements every 5 frames - based off the formula (frame % skip) == 0. Default value is 0 (no skipping).

Type:
Integer.

steps

The step attribute specifies the number of old particle positions to remember for each of the particles. These are points which the TrailParticleRenderer uses to render the trail lines for each particle. Default value is 5.

Type:
Integer.

textureName

This attribute specifies the name of the texture used to render the trails of the particles.

useFog

Specifies whether the renderer should enable scene fogging or not. You may want to turn off scene fogging if you are using particle systems in the sky box, or if you want to otherwise explicitly control the amount of fogging via the tint shader fog blend control.

width

This attribute specifies the width of the line renderer as the trail on the particles.


PyTransferQuad - BigWorld client Documentation

PyTransferQuad Class Reference

[PostProcessing Module]

PyTransferQuad is part of the PostProcessing module. More...

import PostProcessing

Parent Classes

FilterQuad → PyObjectPlus

Detailed Description

A PyTransferQuad can be used by a PyPhase object, and provides the geometry for the phase. The TransferQuad fills out 4 texture coordinates for its vertices, but each uv coordinate is not offset at all.


PyVisualParticleRenderer - BigWorld client Documentation

PyVisualParticleRenderer Class Reference

[Pixie Module]

PyVisualParticleRenderer is part of the Pixie module. More...

import Pixie

Parent Classes

PyParticleSystemRenderer → PyObjectPlus

Attributes

visual String.

Detailed Description

VisualParticleRenderer is a ParticleSystemRenderer which renders each particle as a visual object. Any visual can be used, although the TintShader will only work on visuals that use effect files that use MeshParticleTint.

Attribute Documentation

visual

This is the name of the visual particle type to use for the particles. Default value is "".

Type:
String.


PyVisualTransferMesh - BigWorld client Documentation

PyVisualTransferMesh Class Reference

[PostProcessing Module]

PyVisualTransferMesh is part of the PostProcessing module. More...

import PostProcessing

Parent Classes

FilterQuad → PyObjectPlus

Attributes

resourceID String.

Detailed Description

This class implements a FilterQuad that just draws a visual file.

Attribute Documentation

resourceID

Type:
String.


PyWaterVolume - BigWorld client Documentation

PyWaterVolume Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

surfaceHeight Float.

Detailed Description

This class implements a python wrapper around a water object. It allows the script programmer to perform queries on the volume.

Attribute Documentation

surfaceHeight

Type:
Float.


PythonServer - BigWorld client Documentation

PythonServer Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def write( self, args ):

Attributes

softspace integer

Detailed Description

This class provides access to the Python interpreter via a TCP connection. It starts listening on port 50001. It accepts telnet requests on this port, allowing access to the python console on the client from a remote machine.

This class is not exposed to the client. It has a Python interface to allow Python to communicate with the object. However, this interface is of no use to the user.

It has a write method, which is called by Python when there is output to display. It has a softspace attribute which is also required for interfacing to Python.

Member Function Documentation

def write( self, args ):

This method is called by Python whenever there is new data for stdout or stderror. We redirect it to all the connections, and then print it out as normal. CRs are subsituted for CR/LF pairs to facilitate printing on Windows.

Parameters:
args A Python tuple containing a single string argument

Attribute Documentation

softspace

This attribute is required to interface with the Python engine.

Type:
integer


ScanDirProvider - BigWorld client Documentation

ScanDirProvider Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

MatrixProvider → PyObjectPlus

Detailed Description

A MatrixProvider whose direction oscillates around the y axis, and may be instructed to call a function when it hits it's leftmost and rightmost limits. An instance of this class can be created via the factory method BigWorld. ScanDirProvider, wherein the amplitude, period, and period offset of the oscillation are specified.

It is not possible to directly access many of the internal attributes of a ScanDirProvider. To view this data it is necessary to construct a Matrix which is a copy of this, & read the values from it. For example:
# create a ScanDirProvider
sdp = BigWorld.ScanDirProvider( math.pi/2, 10, 0 )

# create a MatrixProvider from the ScanDirProvider
m = Math.Matrix( sdp )

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

Instances of this class are typically used in conjunction with a Tracker to cause a nodes in a model to "scan" an area by turning left & right.


ServerCaller - BigWorld client Documentation

ServerCaller Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Detailed Description

These objects are automatically created by BigWorld to populate a PyServer object. Each ServerCaller object provides the link to a single method on the component that the PyServer object represents (ie, Cell or Base). These methods are defined in the .def file and can only exist if the server component exists. A ServerCaller object is accessed by invoking the method that it represents in the PyServer object, eg;

self.cell.method( args )

where self is an Entity, cell is the PyObject created by BigWorld (which is not available if there is no Cell component for this Entity) and method( args ) is the ServerCaller object that represents the method on the Cell that was defined in this Entity's .def file

This is not supported for licensees who have not licensed the BigWorld server technology.


ServerDiscovery - BigWorld client Documentation

ServerDiscovery Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

changeNotifier | Callback Function (python function object, or an instance of a python
searching | Integer. Default is 0.
servers | Read-only list of ServerDiscovery objects

Detailed Description

This class defines an object which can be used to locate BigWorld servers on a local area network and obtain information regarding their current status. An instance of this class is automatically created by BigWorld as BigWorld.serverDiscovery, and no further instances can be created by script. When the searching attribute is set to a value other than 0, where previously it had been equal to 0, the ServerDiscovery broadcasts a request on the LAN for servers to provide it with their details. These details are not received all at once, and may be updated periodically. Each time details are received or updated the function assigned to the changeNotifier attribute is called. This continues to collect server details until the searching attribute is set to 0. When the searching attribute is assigned to 0 all of the server details which have been collected are discarded. As this can only be used over a LAN it would not be very useful for a live MMOG, however it is very useful during testing and development.

Code Example:
# This example prints out the list of known server host names each time
# the list is updated.

# imports
import BigWorld

# print the host names of all the known servers
def listServers():
    print "\nServers:"   # print header
    for s in BigWorld.serverDiscovery.servers:
        print s.hostName   # print entry

# set the server list callback function
BigWorld.serverDiscovery.changeNotifier = listServers

# initiate the search for servers
BigWorld.serverDiscovery.searching = 1

Attribute Documentation

changeNotifier

The changeNotifier attribute is a Python function object which will be called every time a ServerDiscovery::Details object is created or updated in the servers attribute list. It is called with no arguments.

Type:
Callback Function (python function object, or an instance of a python

searching

This attribute can be used to initiate a search for BigWorld servers on the LAN. When this is set to 1 it initiates a search, and when it is set to 0 it stops the current search and clears the servers attribute.

Type:
Integer. Default is 0.

servers

This is a list of ServerDiscovery::Details objects which contain status information for each of the servers that the ServerDiscovery object has found.

Type:
Read-only list of ServerDiscovery objects


ServerDiscoveryDetails - BigWorld client Documentation

ServerDiscoveryDetails Class Reference

[BigWorld Module]

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

import BigWorld

Attributes

hostName | Read-only String
ip | Read-only Integer
ownerName | Read-only String
port | Read-only Integer
serverString | Read-only String
spaceName | Read-only String
uid | Read-only Integer
universeName | Read-only String
usersCount | Read-only Integer

Detailed Description

ServerDiscovery::Details defines an object which describes the current status of a BigWorld server as might be considered useful in a game lobby. Instances of this class are and can only be created by the BigWorld.serverDiscovery object. All attributes of this object are read-only.

Attribute Documentation

hostName

This is the name of the server computer, as returned by a call to the standard getHostName function.

Type:
Read-only String

ip

This is the IP address of the server, expressed as a single integer. If the IP address is considered to be like a base 256 number, then this would be its decimal representation. For example, the IP address 10.11.12.42 would be represented here as 168496170, which is 10 * 256^3 + 11 * 256^2 + 12 * 256^1 + 42 * 256^0.

Type:
Read-only Integer

ownerName

This is the name of the user who launched the server. If the server is running Windows then this would be the value returned by the GetLogin() function, otherwise it would be the value returned by GetUserName().

Type:
Read-only String

port

This is an integer equal to the port on which the server is listening.

Type:
Read-only Integer

serverString

This is a server string of the form :, suitable to be passed into BigWorld.connect()

Type:
Read-only String

spaceName

This string is the name of the space currently playing on the server.

Type:
Read-only String

uid

This integer is the user identification number with which the server was launched. This can be used to differentiate between multiple servers which may be running on the same machine.

Type:
Read-only Integer

universeName

This string is the name of the universe currently playing on the server.

Type:
Read-only String

usersCount

This integer represents the total number of attempts that have been made to connect to the server (by any client).

Type:
Read-only Integer


Servo - BigWorld client Documentation

Servo Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

Motor → PyObjectPlus

Attributes

signal Read-Write MatrixProvider

Detailed Description

The Servo class is a Motor that sets the transform of a model to the given MatrixProvider. As the MatrixProvider is updated, the model will move.

Attribute Documentation

signal

This attribute is the MatrixProvider that sets the model's transform. As this MatrixProvider is updated, the model will be transformed accordingly.

Type:
Read-Write MatrixProvider


SimpleGUIComponent - BigWorld client Documentation

SimpleGUIComponent Class Reference

[GUI Module]

SimpleGUIComponent is part of the GUI module. More...

import GUI

Parent Classes

PyObjectPlusWithWeakReference

Member Functions

def addChild( self, child, name ):
def addShader( self, shader, name ):
def delChild( self, child ):
def delShader( self, shader ):
def handleAxisEvent( self, event ):
def handleDragEnterEvent( self, component, position, dragged ):
def handleDragLeaveEvent( self, component, position, dragged ):
def handleDragStartEvent( self, component, position ):
def handleDragStopEvent( self, component, position ):
def handleDropEvent( self, component, position, dropped ):
def handleKeyEvent( self, event ):
def handleMouseButtonEvent( self, event ):
def handleMouseClickEvent( self, component ):
def handleMouseEnterEvent( self, component, position ):
def handleMouseEvent( self, event ):
def handleMouseLeaveEvent( self, component, position ):
def hasChild( self, child, deepSearch ):
def hitTest( self, mousePos ):
def localToScreen( self, event ):
def reSort( self ):
def save( self, resourceID ):
def screenToLocal( self, event ):

Callback Methods

def onBound( self ):
def onDelete( self ):
def onLoad( self, ds ):
def onSave( self, ds ):

Attributes

angle | Float
children | Read-Only List of (name, SimpleGUIComponent) tuples.
colour | Colour
crossFocus | Boolean
dragFocus | Boolean
dropFocus | Boolean
filterType | String
flip | Integer
focus | Boolean
height | Float
heightMode | String
heightRelative | Boolean
horizontalAnchor | String
horizontalPositionMode | String
mapping | 4-tuple of Vector2s.
materialFX | String
mouseButtonFocus | Boolean
moveFocus | Boolean
parent | weakref proxy to SimpleGUIComponent
pixelSnap | Boolean
position | Vector3
script | Object
shaders | List of (name, Shader) tuples.
size | Vector2
texture | PyTextureProvider
textureName | String
tileHeight | Integer
tileWidth | Integer
tiled | Boolean
verticalAnchor | String
verticalPositionMode | String
visible | Boolean
visibleInAppFocusOnly | Boolean
width | Float
widthMode | String
widthRelative | Boolean

Detailed Description

This class is the base GUI component that by default displays a textured rectangle. It can also use more sophisticated PyTextureProviders to render animations. All other GUI Components are derived from this class.

A new SimpleGUIComponent is created using the GUI.Simple function. This takes a string argument, which is the filepath of a texture to display on the SimpleGUIComponent.

Once the component is created, it can have its texture attribute set to any PyTextureProvider, which supplies either a static or dynamic texture to be mapped across the components rectangle.

The SimpleGUIComponent can have one or more GUIShaders applied to it, which affect the way it is rendered. It can also be resized, tiled, remapped, repositioned and moved.

Children can be added to the component. However, this isn't a full windowing system. The position and orientation of children are specified relative to the screen, not to the parent. However, any shaders which are applied to the parent apply to the children as well.

For example:
c = GUI.Simple( "maps/myPicture.bmp" )
GUI.addRoot( c )
c.size = (2,2)
This example creates a SimpleGUIComponent which covers the entire screen and displays myPicture.bmp.

Member Function Documentation

def addChild( self, child, name ):

This function adds a GUI Component as a child of the current SimpleGUIComponent. This child will depth sort above its new parent, and sort with its siblings according to the depth component of its position attribute. The other components of its position are relative to the screen, rather than its parent SimpleGUIComponent. Additionally, any shaders applied to the parent also get applied to the child.

If a name is not supplied when adding it, then a random name is generated. The child can be addressed by the name as a property of parent. For example

>>>	import GUI
>>>	parent = GUI.Simple( "parent.dds" )
>>>	child = GUI.Simple( "child.dds" )
>>>	parent.addChild( child, "myChild" )
>>>	sameChild = parent.myChild

At this point, sameChild and child refer to the same object

Parameters:
child | the GUI component to be added as a child
name | (optional) the name to insert the child under

def addShader( self, shader, name ):

This function adds a GUIShader to the current SimpleGUIComponent. Shaders can be used to do things such as change the color and alpha of a component, or clip it, or transform it.

If the optional name is not supplied when adding it, then a random name is generated. In addition to appearing in the shaders attribute, this shader will also be available using the name as an attribute of the component.

For example:

>>>	import GUI
>>>	component = GUI.Simple( "component.dds" )
>>>	shader = GUI.ColourShader()
>>>	component.addShader( shader, "myShader" )
>>>	sameShader = component.myShader

In this code, shader and myShader will refer to the same object

Parameters:
shader | The shader to add
name | (optional) The string giving the name to add it under.

def delChild( self, child ):

This function removes a child from the SimpleGUIComponent.

Parameters:
child The GUI Component to remove

def delShader( self, shader ):

This function removes a shader from the SimpleGUIComponent.

Parameters:
shader A shader object to remove

def handleAxisEvent( self, event ):

This method handles axis events for the gui system. If this component doesn't have focus, then it returns 0, meaning it hasnt handled the event. Otherwise, it gives its children a chance to handle the event. If they don't, then it checks if it has an attached script object, and gives that a chance to handle the event.

Parameters:
event a axisEvent is a 3-tuple of one integer and two floats, as follows: (axis, value, dTime) - axis is one of AXIS_LX, AXIS_LY, AXIS_RX, AXIS_RY, with the first letter being L or R meaning left thumbstick or right thumbstick, the second, X or Y being the direction. value is the position of that axis, between -1 and 1. dTime is the time since that axis was last processed.

Returns:
True if the event was handled, False if it wasn't.

def handleDragEnterEvent( self, component, position, dragged ):

This event handler is triggered when a dragged component enters the quad defined by the four corners of a drop accepting component. To have this handler triggered, a component must have dropFocus enabled.

The value returned by the handleDragEnterEvent method will be used to determine if the drop target is willing to accept the component being dragged. That is, the handleDropEvent will not be generated if the handleDragEnterEvent call that preceeded it returned false.

Parameters:
component | The drop target component.
position | mouse position, 2-tuple (x, y).
dragged | The component being dragged.

Returns:
True if the component is willing to accept the dropped item.

def handleDragLeaveEvent( self, component, position, dragged ):

This event handler is triggered when a dragged component leaves the quad defined by the four corners of a drop accepting component. To have this handler triggered, a component must have dropFocus enabled.

Parameters:
component | The drop target component.
position | mouse position, 2-tuple (x, y).
dragged | The component being dragged.

Returns:
True if the event was handled, False if it wasn't.

def handleDragStartEvent( self, component, position ):

This event handler is triggered when a draggable component is first detected as being dragged. A component is detected as being dragged when a left mouse button down event is generated on it and the mouse cursor travels more and the minimun drag distance before the left button is released (see GUI.setDragDistance). To have this handler triggered, a component must have dragFocus enabled.

Because a drag is always preceeded by a mouse button press, a mouse button down event will always be triggered on the clicked component. Some times, it may be necessary to implement the handleMouseButtonEvent and have it to return True in order to prevent the mouse down event to be propagated further to the game scripts.

Parameters:
component | The component being dragged.
position | mouse position of first button down, 2-tuple (x, y).

Returns:
True if the component is willing to be dragged.

def handleDragStopEvent( self, component, position ):

This event handler is triggered when a drag operation has finished. The drag operation finishes when the left mouse button is released. To have this handler triggered, a component must have dragFocus enabled.

Parameters:
component | The component being dragged.
position | mouse position, 2-tuple (x, y).

Returns:
the return value is always ignored.

def handleDropEvent( self, component, position, dropped ):

This event handler is triggered a dragged component is dropped overa drop accepting component. To have this handler triggered, a component must have dropFocus enabled.

Parameters:
component | The drop target component.
position | mouse position, 2-tuple (x, y).
dropped | The dragged component being dropped.

Returns:
the return value is always ignored.

def handleKeyEvent( self, event ):

This method handles key events from the gui system. If this component doesn't have focus, it exits immediatly, ignoring the event and returning false. Otherwise, it gives to each of its children a chance to handle the event. If they don't, then it checks if it has an attached script object, and gives that a chance to handle the event. Last, if the key event is still unhandled, if it is a mouse button event, and if the mouse cursor is active, it tries to forward the event to handleMouseButtonEvent method of the script object, if one is attached.

Parameters:
event A PyKeyEvent containing information about this key event.

Returns:
True if the event was handled, False if it wasn't

def handleMouseButtonEvent( self, event ):

This method handles mouse button events from the gui system. This is similar to handleKeyEvent, however it is only for mouse buttons and will only get posted to a component if the mouse cursor is within the region of the component.

Parameters:
event A PyKeyEvent containing information about this mouse button event.

Returns:
True if the event was handled, False if it wasn't

def handleMouseClickEvent( self, component ):

This event handler is triggered when the a left mouse click occurs. A click is defined by a mouse button down, followed by a button up over the same component. To have this handler triggered, a component must have focus enabled.

A button down followed by a button up may not be detected as a click if the component has dragFocus enabled and the distance from the position of press to that of the release is more than the minimum drag distance (see GUI.setDragDistance).

Because a click is always preceeded by a mouse button press, a mouse button down event will always be triggered on the clicked component. Sometimes, it may be necessary to implement the handleMouseButtonEvent and have it to return True in order to prevent the mouse down event to be propagated to the game scripts.

Parameters:
component The component being clicked.

Returns:
True if the event was handled, False if it wasn't.

def handleMouseEnterEvent( self, component, position ):

This event handler is triggered when the mouse cursor enters the quad defined by the four corners of the component. To have this handler triggered, the component must have crossFocus enabled.

Parameters:
component | The component which the mouse point is entering.
position | mouse position, 2-tuple (x, y).

Returns:
True if the event was handled, False if it wasn't.

def handleMouseEvent( self, event ):

This method handles mouse events for the gui system. If this component doesn't have focus, then it returns 0, meaning it hasnt handled the event. Otherwise, it gives its children a chance to handle the event. If none of it's children consumes the event, it checks if it has an attached script object, and gives that a chance to handle the event.

Parameters:
event A PyMouseEvent object.

Returns:
True if the event was handled, False if it wasn't.

def handleMouseLeaveEvent( self, component, position ):

This event handler is triggered when the mouse cursor leaves the quad defined by the four corners of the component. To have this handler triggered, the component must have crossFocus enabled.

Parameters:
component | The component which the mouse point is leaving.
position | mouse position, 2-tuple (x, y).

Returns:
True if the event was handled, False if it wasn't.

def hasChild( self, child, deepSearch ):

This function determines whether or not this component has the given component as a child. If deepSearch is True, then it will search the children of children right down to the leaves of the GUI tree.

Parameters:
child | The GUI Component to look for.
deepSearch | A boolean specifying whether or not to perform a deep search.

Returns:
Whether or not this component has the given child.

def hitTest( self, mousePos ):

Parameters:
mousePos the position to test

Returns:
True if the position is over the component. False otherwise.

def localToScreen( self, event ):

This method converts the given local coordinates (i.e. relative to the bounds) of this component into clip space of the screen. The units for the input depends on the current width and height modes.

Parameters:
event a Vector2 containing the position relative this component.

Returns:
A Vector2 containing the screen space clip position.

def reSort( self ):

This function reSorts the children of this component according to the third (depth) component of their position attributes. Changing this depth value in a child doesn't automatically reorder the children. An explicit call to this function is required. If all gui components on the screen require reordering then GUI.reSort() can be called instead.

def save( self, resourceID ):

This method persists the SimpleGUIComponent as an xml data section. The method takes a resourceID as an argument, which must end in ".gui". It creates or overwrites the named file. This can then be loaded later using the load method, allowing a quick recreation of the current object.

For example:
# first create a new component and configure it.  This can be done
# interactively at the console.
c = GUI.Simple( "maps/myPicture.bmp" )
c.colour = (255,0,0,0)  # tint the component red
c.save( "gui/myGui.xml" )

# now create a new component, and load it
cnew = GUI.Simple( "maps/someplaceholderimage.bmp" )
cnew.load( "gui/myGui.xml" )
This example creates and saves a gui, and then loads that gui into a new component.

Parameters:
resourceID the filename to save to.

def screenToLocal( self, event ):

This method converts the given position in clip space into the local space relative to the bounds of this component. The units that it is returned in depends on the current width and height modes. If the width or height mode is CLIP, then the corresponding component is returned in clip space of the component (i.e. 0,0 is the center of the component, -1,1 is the top left and 1,-1 is the bottom right).

If the width or height mode is PIXEL, then the coresponding component is returned in pixels relative to the top left of the component.

If the width or height mode is LEGACY, then the corresponding component is returned such that the position is relative to the center of the component, however the left side of the component is the negative distance from the center of the component in the clip space of the screen. Similarly, the right hand side is the positive distance, the bottom is the negative distance and the top is the positive distance.

Parameters:
event a Vector2 containing the position in the clip space of the screen.

Returns:
A Vector2 containing the local space position.

Callback Method Documentation

def onBound( self ):

This method is called when the SimpleGUIComponent has finished loading itself and its children. No parameters are passed into this method.

To process script before the children have loaded, use the onLoad callback method instead.

def onDelete( self ):

This method is called when the SimpleGUIComponent is deleted, if the component has an associated script object. It has no parameters passed in, and expects no return value.

NOTE: Since the component is about to be deleted, extreme care should be taken to avoid adding any references to the component which is about to die.

def onLoad( self, ds ):

This method is called when the SimpleGUIComponent is loaded, before any of its children are loaded.

The data section that contains custom script properties is passed to this callback method. This is the same data section that is passed to the save callback method.

To process script upon completion of the load process, use the onBind callback method instead.

Parameters:
ds the DataSection containing the script properties

def onSave( self, ds ):

This method is called when the SimpleGUIComponent is saving. The data section used for saving is passed into the method. GUI Scripts should save their persistent data into this data section.

Parameters:
ds the DataSection to be used to write script properties

Attribute Documentation

angle

This attribute determines the rotation of the component. It only stores the following values: 0, 90, 180, 270. The angle is measured in degrees, and is measured in a clockwise direction, with 0 being the default the initial position. Also note that if the component is rectangular, rotating it doesn't automatically rescale it, so the image is likely to be distorted in a sideways rotation.

This attribute is applied after the flip attribute.

Type:
Float

children

This attribute is the list of all children of the current component. All children are drawn after their parent. However, note that the position of the children is specified relative to the screen, not relative to their parent. If you want children to inherit the position of the parent, then the parent should be a Window component.

Any shaders which are part of a parent are also applied to children.

In normal usage, this list is not manipulated directly, instead the addChild and delChild functions are called on the SimpleGUIComponent to add and remove children.

Note there is a special python syntax implemented that helps setting and getting children - you can set children directly as attributes. For example : Example:
#Set / Get / Del children using special syntax
s = GUI.Simple( "gui/maps/myGui.dds" )
parent = GUI.Simple( "" )
parent.child = s
child = parent.child
parent.child = None

#Set / Get / Del children using method calls.
#This is functionally equivalent to the example above.
s = GUI.Simple( "gui/maps/myGui.dds" )
parent = GUI.Simple( "" )
parent.addChild( s, "child" )
child = parent.getChild( "child" )
parent.delChild( child )

Type:
Read-Only List of (name, SimpleGUIComponent) tuples.

colour

This attribute is the colour of the SimpleGUIComponent. This colour is a Vector4, with components ranging between 0 and 255. The components are (Red, Green, Blue, Alpha). The numbers are scaled to the 0-1 range, and then each pixel's colour (also in the 0-1 range) is multiplied by the colour.

Note the Australian spelling of the word colour

Type:
Colour

crossFocus

This attribute determines whether or not this SimpleGUIComponent will receive mouse cross (enter and leave) events.

Enter events are generated when the mouse cursor enters the quad defined by the four corners of the component. Leave events are generated when the mouse cursor leaves this same quad.

If focus is False, the mouse cross event handling functions in the attached script object will not be called. If it is True, the mouse cross event handling functions in the attached script object will be called.

When this attribute is set or cleared, the crossFocus method on the attached script object (see the script attribute) gets called, with one argument, which is the new value of the focus attribute.

Type:
Boolean

dragFocus

This attribute determines whether or not this SimpleGUIComponent is a candidate for dragging. When dragged, components will receive drag start and grad stop events.

Drag start events are generated when the dragging operation is first detected (see GUI.setDragDistance). Drag stop events are generated when the mouse left button is release during the drag operation.

If focus is False, the component will not be available for dragging, and the drag event handling functions in the attached script object will not be called. If it is True, the component will be available for dragging, and the drag event handling functions in the attached script object will be called.

When this attribute is set or cleared, the dragFocus method on the attached script object (see the script attribute) gets called, with one argument, which is the new value of the focus attribute.

See:
SimpleGUIComponent.script

Type:
Boolean

dropFocus

This attribute determines whether or not this SimpleGUIComponent can have a dragged component dropped over it. When receiving dragged component, drop target components will receive drag enter, drag leave and drop events.

Drag enter events are generated when a dragged component enters the quad defined by the four corners of a component that has dropFocus enabled. Drag leave events are generated when a dragged component leaves this same quad. Drop events are generated when a dragged component is dropped over a drop accepting component.

The value returned by the drag enter event handler method will be used to determine if the drop target will accept the dragged component. That is, the drop event will not be generated when the left mouse button is release if the earlier enter handler returned false (but the drag stop will always be. See dragFocus).

If focus is False, the component will not accept dropping, and the drag enter/leav and drop event handling functions in the attached script object will not be called. If it is True, the component will accept dropping and the drag enter/leave and drop event handling functions in the attached script object will be called.

When this attribute is set or cleared, the dropFocus method on the attached script object (see the script attribute) gets called, with one argument, which is the new value of the focus attribute.

See:
SimpleGUIComponent.dragFocus
SimpleGUIComponent.script

Type:
Boolean

filterType

This attribute determines what texture filtering is to be to render the SimpleGUIComponent. Possible values are "POINT", when the texel with coordinates nearest to the desired pixel value is used, and "LINEAR", when a weighted average of a 2 x 2 area of texels surrounding the desired pixel is used. Default value is "LINEAR".

Possible values are POINT and LINEAR

Type:
String

flip

This attribute determines whether or not to flip the component in the horizontal direction. If it is zero, then no flipping occurs, otherwise the component is flipped. This attribute is applied before the angle attribute.

Type:
Integer

focus

This attribute determines whether or not this SimpleGUIComponent responds to input events. If focus is False, then no response will be made to the input events, and the event handling functions in the script object will not be called. If it is True, it will respond to events, and event handling functions in the script object will be called.

When this attribute is set or cleared, the focus method on the attached script object (see the script attribute) gets called, with one argument, which is the new value of the focus attribute.

See:
SimpleGUIComponent.script

Type:
Boolean

height

The height of the SimpleGUIComponent. Its interpretation depends on the heightMode attribute. If heightMode is "PIXELS", then height is interpreted as pixels. If heightMode is "CLIP", then it is interpreted as clip-space coordinates so that the height of the screen or the parent WindowGUIComponent is exactly 2.0. If widthMode is "LEGACY" then it is interpreted similarly to "CLIP", however 2.0 is ALWAYS the width of the screen (even if it is a child of a WindowGUIComponent).

If the tiled attribute is False, then changing the height scales height of the texture to match. Otherwise it just changes the height of the component, and the texture tiles to cover the entire surface.

Type:
Float

heightMode

This attribute determines how the height attribute is interpreted. Possible values are "CLIP", "PIXEL", and "LEGACY". See SimpleGUIComponent.height for details on the meaning of these values.

See:
SimpleGUIComponent.height

Type:
String

heightRelative

This attribute determines how the height attribute is interpreted. This attribute has been deprecated, use heightMode instead.

Setting this to True is equivalent to setting heightMode to "LEGACY", and setting this to False is equivalent to setting heightMode to "PIXEL".

See:
SimpleGUIComponent.height

Type:
Boolean

horizontalAnchor

This attribute specifies which part of the SimpleGUIComponent is located by the position attribute, in a horizontal direction. Possible values are "LEFT", "CENTER" and "RIGHT". The default is "CENTER".

Type:
String

horizontalPositionMode

Determines the units used by position.x. See the documentation for SimpleGUIComponent.position for details on how it is interpreted.

Possible values are "CLIP", "PIXEL", "LEGACY". Defaults to "LEGACY".

Type:
String

mapping

This attribute governs the mapping between the corners of the component, and the texture. It consists of 4-tuple of Vector2s. The first component is the top left, second is the bottom left, third is the bottom right and the fourth is the top right.

Each Vector2 specifies the texture address to use for that corner, with (0,0) being topleft, and (1,1) being bottom right. It is acceptable to use numbers outside of 0-1. In this case texture is not tiled. The component is interpolated between these 4 points.

Setting the flip or angle attributes sets the mapping attribute appropriately. However, setting mapping doesn't reset the flip and angle attributes.

Type:
4-tuple of Vector2s.

materialFX

This attribute determines what operation is used to render the SimpleGUIComponent onto the background. Possible values are "BLEND", which applies the alpha channel transparency, "SOLID" which ignores the alpha channel and overwrites the background, and "ADD" which just adds the colour to the existing background colour, making the component look like it is transparent and glowing. The default is "ADD". Note that ADD_SIGNED is a fudge, it basically performs a MOD2 blend with the frame buffer. For most situations this should be fine.

Possible values are ADD, BLEND, BLEND_COLOUR, BLEND_INVERSE_COLOUR, SOLID, MODULATE2X, ALPHA_TEST, BLEND_INVERSE_ALPHA, BLEND2X, ADD_SIGNED

Type:
String

mouseButtonFocus

This attribute determines whether or not this SimpleGUIComponent will receive mouse button events. This is different to the focus property in that mouse button events are only posted when the mouse cursor is within the region defined by the component, and will post to the top most component at the mouse position first.

When this attribute is set or cleared, the mouseButtonFocus method on the attached script object (see the script attribute) gets called, with one argument, which is the new value of the focus attribute.

See:
SimpleGUIComponent.script

Type:
Boolean

moveFocus

This attribute determines whether or not this SimpleGUIComponent will receive mouse move events.

Mouse move events are generated when the mouse cursor moves inside the quad defined by the four corners of the component.

If focus is False, the mouse move event handling functions in the attached script object will not be called. If it is True, the mouse move event handling functions in the attached script object will be called.

When this attribute is set or cleared, the moveFocus method on the attached script object (see the script attribute) gets called, with one argument, which is the new value of the focus attribute.

See:
SimpleGUIComponent.script

Type:
Boolean

parent

Stores a weak reference to this component's parent component. It is None if there is no parent.

Type:
weakref proxy to SimpleGUIComponent

pixelSnap

Toggles on/off pixel snapping. Pixel snapping will, at the vertex shader level, cause the component to the drawn on the nearest pixel boundary. This is useful to avoid filtering issues when trying to achieve 1-1 mapping between GUI artwork and the screen.

Type:
Boolean

position

The position of the SimpleGUIComponent. This is a Vector3. The first two numbers are the horizontal and vertical positions, the third is the depth sort value.

The units used by the horizontal and vertical positions depends on the current values of the horizontalPositionMode and verticalPositionMode attributes.

If the position mode is "CLIP", then the position component is defined in clip space. Note that if the component is a child of a WindowGUIComponent, then the clip coordinates are relative to the dimensions of that parent (e.g. x = -1 would cause the child of the window to be aligned to the left edge of the window). (-1,-1) is the bottom left of the screen/window, (1,1) is the top right of the screen/window. (0,0) is the centre of the screen/window.

If the position mode is "PIXEL", then the coordinate is defined to be in pixels, relative to the top left of the screen (or parent window, if the component is the child of a WindowGUIComponent).

For backwards compatability with old behaviour, a "LEGACY" position mode is provided. In this mode the position is taken to be in clip space as in "CLIP", however if it is a child of a WindowGUIComponent it will will NOT be relative to that window. Newly created components are created in "LEGACY" mode by default, however this may change in a future release.

The horizontalAnchor and verticalAnchor settings impact on the final screen position of the component. horizontalAnchor can either be "LEFT", "CENTER" or "RIGHT", verticalAnchor can be either "TOP", "CENTER" or "BOTTOM". The anchor attributes determine which part of the gui is located by the position attribute. For example, if horizontalAnchor is "CENTER" and position is (0,0,0) in clip space, then the component is horizontally centred on the screen. If horizontalAnchor were "LEFT" then the left of the component would be centred on the screen.

The depth sort value is used to sort between various GUI components with the same parent. The lower numbered components appear on top of higher numbered components. Changing the depth of one component doesn't automatically re-order all other children at the same level of the tree however. The reSort() method needs to be called on the parent, or on GUI if you've changed the position of a root component, to force this.

Note that depth values should be kept between 0 and 1, since some video cards will automatically clip away triangles with z-values outside this range, even if the z-buffer is disabled.

This defaults to (0,0,1)

Type:
Vector3

script

This attribute associates a class with the SimpleGUIComponent. This can contain functions for handling input events. It should define the following functions, even if simply to stub them out:

    def handleKeyEvent( self, event ):
    def handleAxisEvent( self, event ):
    def handleMouseButtonEvent( self, comp, event ):
    def handleMouseClickEvent( self, comp ):
    def handleMouseEnterEvent( self, comp ):
    def handleMouseLeaveEvent( self, comp ):
    def handleMouseEvent( self, comp, event ):
    def handleDragStartEvent( self, comp ):
    def handleDragStopEvent( self, comp ):
    def handleDragEnterEvent( self, comp ):
    def handleDragLeaveEvent( self, comp ):
    def handleDropEvent( self, comp, dropped ):
    def handleLangChangeEvent( self ):
    def focus( self, state ):
    def mouseButtonFocus( self, state ):
    def crossFocus( self, state ):
    def moveFocus( self, state ):
    def dragFocus( self, state ):
    def dropFocus( self, state ):
    def imeFocus( self, state ):
    def onLoad( self, dataSection ):
    def onSave( self, dataSection ):
    def onBound( self ):

The handle event functions are called whenever the SimpleGUIComponent receives the corresponding event. The focus methods are called whenever the SimpleGUIComponents focus attributes are assigned to.

onLoad is called just after the basic attributes have been loaded, but before any children are attached or shaders specified.

onSave is called just after the basic attributes have been saved.

onBound is called after loading and all children and shaders are bound.

If a script is associated with a gui component, then that class must have a class member "factoryString" describing how to create it.

The factoryString which is stored in your .gui file is read in at load time and executed using "Script::runString". This means that the name of the class to construct must be imported into the global namespace. As an example, in FantasyDemo we put all our python gui scripts into the "PyGUI" module, and make sure the PyGUI module is imported into the global namespace in the personality script via the following code :
from Helpers import PyGUI
__import__('__main__').PyGUI = PyGUI

Please see the FantasyDemo personality script for an example of this. Please see the script fantasydemo/res/client/Helpers/PyGUI.py for examples of gui python scripts. Please see the gui files in fantasdemo/res/gui for examples of gui files containing these factory strings.

Type:
Object

shaders

This attribute is the list of all shaders which are applied to this SimpleGUIComponent and to its children. A shader is used to modify the way in which the component is rendered. There are several different shader types: ColourShaders, ClipShaders, MatrixShaders.

This list is not normally manipulated directly, instead the addShader and delShader functions are called on the SimpleGUIComponent to add or remove shaders. However, it is possible to perform direct manipulation on it if you like.

Note there is a special python syntax implemented that helps setting and getting shaders - you can set shaders directly as attributes. For example : Example:
#Set / Get / Del shaders using special syntax
s = GUI.ClipShader()
parent = GUI.Simple( "" )
parent.shader = s
shader = parent.shader
parent.shader = None

#Set / Get / Del shaders using method calls.
#This is functionally equivalent to the example above.
s = GUI.ClipShader()
parent = GUI.Simple( "" )
parent.addShader( s, "shader" )
shader = parent.getChild( "shader" )
parent.delShader( shader )

Type:
List of (name, Shader) tuples.

size

This Vector2 is the width and height of the SimpleGUIComponent, contained in one attribute. Changing either of those attributes will change this, and vice versa. The interpretation of its two attributes depends on widthMode and heightMode. See the documentation for width and height for details on how the size modes affect these values.

Setting the first (width) and/or second (height) component of the passed Vector2 to zero has special meaning. Setting only one of them to zero tells the component to fill-up that zeroed attribute with a value that will preserve the aspect ratio of the assigned texture. Setting both to zero, tells the component to fill-up both width and height attributes with the width and height of the texture, so that one texel on the texture gets mapped to one pixel on the screen. This special semantic only exists when setting the with and height of a component at once, by using the size attribute. Also note that a valid texture must be assigned to the component for the width and height values to be automatically adjusted.

If the tiled attribute is False, then changing the size scales size of the texture to match. Otherwise it just changes the size of the component, and the texture tiles to cover the entire surface.

See:
SimpleGUIComponent.width
SimpleGUIComponent.height

Type:
Vector2

texture

This attribute allows any PyTextureProvider object to be assigned to the component. This allows an object which dynamically updates its texture, for example a PyModelRenderer to supply a texture to the component.

The other way of setting a PyTextureProvider is to set the textureName attribute, which creates a new PyTextureProvider which exposes the named texture.

This attribute may be None, if the component has an empty texture name string.

Type:
PyTextureProvider

textureName

The resource ID of the texture displayed in the component. If this is set to a new texture resource ID (string specifying the fileName of the texture) then the new texture will be loaded.

If it is set to an empty string then the component will be invisible, but its children will be drawn. Note that this is intentionally different to setting the visible flag to false; resetting the visible flag will mean the entire tree underneath the component will also not draw.

Using a gui component with an empty textureName string is useful for creating dummy nodes in the GUI hierarchy, to aid organisation.

Setting this creates a new PyTextureProvider which is assigned to the texture attribute.

Type:
String

tileHeight

The height the texture should be scaled to, in pixels, before it is tiled. This attribute is only meaningful if the tiled attribute is set to True.

Type:
Integer

tileWidth

The width the texture should be scaled to, in pixels, before it is tiled. This attribute is only meaningful if the tiled attribute is set to True.

Type:
Integer

tiled

If this attribute is False, then the texture will be mapped across the entire region of the component (see the mapping attribute). If this attribute is True, then the texture will be mapped to an area which is tileWidth wide, and tileHeight high, and then tiled all over the component. Tiling starts with the top left corner of the texture in the top left of the component.

See:
SimpleGUIComponent.mapping

Type:
Boolean

verticalAnchor

This attribute specifies which part of the SimpleGUIComponent is located by the position attribute, in a vertical direction. Possibe values are "TOP", "CENTER" and "BOTTOM". The default is "CENTER".

Type:
String

verticalPositionMode

Determines the units used by position.y. See the documentation for SimpleGUIComponent.position for details on how it is interpreted.

Possible values are "CLIP", "PIXEL", "LEGACY". Defaults to "LEGACY".

Type:
String

visible

This attribute determines whether or not the SimpleGUIComponent is rendered or not. If it is False, then it will not be rendered, otherwise it will. It defaults to True. Setting visible to false will also implicitly hide all children of the component. If you want to disable rendering of a parent component but still have its children drawn, then set the textureName of the parent to "", an empty string. Note that Simple GUI Components constructed with empty strings are often used as dummy nodes in a GUI tree.

Type:
Boolean

visibleInAppFocusOnly

When this attribute is set to true the component will only be drawn when the application is in focus. Useful for cursors or other components that indicate an input focus to the user.

Type:
Boolean

width

The width of the SimpleGUIComponent. Its interpretation depends on the widthMode attribute. If widthMode is "PIXELS", then width is interpreted as pixels. If widthMode is "CLIP", then it is interpreted as clip-space coordinates so that the width of the screen or the parent WindowGUIComponent is exactly 2.0. If widthMode is "LEGACY" then it is interpreted similarly to "CLIP", however 2.0 is ALWAYS the width of the screen (even if it is a child of a WindowGUIComponent).

If the tiled attribute is False, then changing the width scales width of the texture to match. Otherwise it just changes the width of the component, and the texture tiles to cover the entire surface.

Type:
Float

widthMode

This attribute determines how the width attribute is interpreted. Possible values are "CLIP", "PIXEL", and "LEGACY". See SimpleGUIComponent.width for details on the meaning of these values.

See:
SimpleGUIComponent.width

Type:
String

widthRelative

This attribute determines how the width attribute is interpreted. This attribute has been deprecated, use widthMode instead.

Setting this to True is equivalent to setting widthMode to "LEGACY", and setting this to False is equivalent to setting widthMode to "PIXEL".

See:
SimpleGUIComponent.width

Type:
Boolean


SkeletonCollider - BigWorld client Documentation

SkeletonCollider Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def addCollider( self, collider ):
def doCollide( self, start, direction ):
def getCollider( self, n ):
def load( self, pSection ):
def nColliders( self ):
def save( self, pSection ):

Attributes

impactCollider
impactPoint
impactReflection

Detailed Description

This class is a utility class designed to help implement collisions on dynamic skeletal objects.

It has a list of BoxAttachment objects, and provides a C++ and python interface to coordinate collision testing for that list as a whole.

Member Function Documentation

def addCollider( self, collider ):

This method adds a box attachment to the skeleton collider

Parameters:
collider the box attachment to add

def doCollide( self, start, direction ):

Attempts to collide with this collider. Tests the collection of colliders against the ray that begins at the position defined by the "start" argument, and goes all the way down to the far plane in the direction defined by the "dir" argument.

Parameters:
start | the start point of the collision ray
direction | the direction of the collision ray.

Returns:
True if a hit was detected, false otherwise. Check the impactCollider, impactPoint and impactReflection attibutes for details on the intersection detected.

def getCollider( self, n ):

This method gets a BoxAttachment from the skeleton collider

Parameters:
n the index of the BoxAttachment

Returns:
the BoxAttachment

def load( self, pSection ):

load this collider

Parameters:
pSection the datasection to load from

def nColliders( self ):

returns the number of BoxAttachments in this skeleton collider

Returns:
the number of BoxAttachments in the skeleton collider

def save( self, pSection ):

save this collider

Parameters:
pSection the datasection to save to

Attribute Documentation

impactCollider

The last collider object that was hit

impactPoint

The point in world space of the impact between the last collision ray and the skeleton collider

impactReflection

The collision ray reflected off the last hit object


Sound - BigWorld client Documentation

Sound Class Reference

[FMOD Module]

Sound is part of the FMOD module. More...

import FMOD

Member Functions

def getParentCategory( self ):
def getParentGroup( self ):
def getParentProject( self ):
def param( self, name ):
def play( self ):
def setCallback( self ):
def stop( self ):

Attributes

duration | Float
isVirtual | Bool
muted | Bool
name |
paused | Bool
pitch | Float in the range [0.0, 1.0]
position |
state |
volume | Float in the range [0.0, 1.0]

Detailed Description

A Sound is a handle to a sound event. It can be used to play, stop, and adjust parameters on sounds. It is basically an interface to FMOD::Event. For more information about the concept of sound events and other API intricacies, please see the FMOD Ex API documentation, available from www.fmod.org.

The one major point of difference between a Sound and an FMOD::Event is that a Sound can be retriggered by calling play() without calling stop() in between. What actually happens when you do this is determined by the "Max Playbacks" property of the particular underlying Event. Method calls and/or attribute accesses (other than play()) on a Sound will always refer to the most recently triggered Event; if you want to retain handles to multiple instances of the same Event, you will need to create multiple Sound objects instead of triggering all the events from a single Sound object.

Member Function Documentation

def getParentCategory( self ):

Returns the PyEventCategory which contains this Sound.

Returns:
A PyEventCategory object.

def getParentGroup( self ):

Returns the EventProject which contains this Sound.

Returns:
A PyEventGroup object.

def getParentProject( self ):

Returns the EventProject which contains this Sound.

Returns:
A PyEventProject object.

def param( self, name ):

Returns the SoundParameter object corresponding to the parameter of the given name.

Parameters:
name The name of the parameter.

Returns:
A SoundParameter object.

def play( self ):

Start playing the sound event.

Returns:
A boolean indicating success.

def setCallback( self ):

Set a callback to be triggered by the FMOD::Event

Returns:
Nothing.

def stop( self ):

Stop the sound event.

Returns:
A boolean indicating success.

Attribute Documentation

duration

Returns the length of this sound event in seconds. Will return < 0 on error, which can be caused by asking for the duration of a looping sound.

Type:
Float

isVirtual

True if the sound has lost it's FMOD event handle. This usually occurs when * the max playbacks of the event has been exceeded and the handle has been * stolen. You can attemp to reset the sound to get a valid handle or release * it if you are finished with it. The properties of the sound cannot be * accessed when it is virtual.

* If the 'just fail if quietest' max playback behaviour is specified the * there is no need to reset the sound. BigWorld will try to get a new event * handle every tick. The loudest instances of the event will always be valid.

Type:
Bool

muted

True if the PySound is muted.

Type:
Bool

name

The name of the underlying FMOD::Event.

paused

True if the PySound is paused.

Type:
Bool

pitch

The volume that this sound is (or will be) playing at.

Type:
Float in the range [0.0, 1.0]

position

Read-write access to the 3D position of this sound event. Writing to this attribute will only have an effect if the event's mode has been set to 3D in the FMOD Designer tool. Reading this attribute on a 2D sound will return (0,0,0).

state

Read-only access to the FMOD state of this event.

volume

The volume that this sound is (or will be) playing at.

Type:
Float in the range [0.0, 1.0]


SoundParameter - BigWorld client Documentation

SoundParameter Class Reference

[FMOD Module]

SoundParameter is part of the FMOD module. More...

import FMOD

Attributes

max | Float
min | Float
name |
seekSpeed | Float
value | Float
velocity | Float

Detailed Description

A SoundParameter provides access to sound event parameters and is basically a partial interface to FMOD::EventParameter. For more information about event parameters and how they are used, please see the FMOD Designer API documentation and the FMOD Designer User Manual, both available from www.fmod.org.

Attribute Documentation

max

The maximum legal value for this parameter.

Type:
Float

min

The minimum legal value for this parameter.

Type:
Float

name

The name of this parameter.

seekSpeed

The current seek speed of this parameter. Please see the documentation for FMOD::EventParameter::setSeekSpeed() for details on the mechanics and usage of EventParameter seek speeds.

Type:
Float

value

The current value of this parameter.

Type:
Float

velocity

The current velocity of this parameter. Please see the documentation for FMOD::EventParameter::setVelocity() for details on the mechanics and usage of EventParameter velocities.

Type:
Float


Targeting - BigWorld client Documentation

Targeting Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Attributes

autoAim | AutoAim
autoAimOn | boolean (0 or 1)
defaultDeselectionAngle | float
defaultSelectionAngle | float
defaultSelectionDistance | float
deselectionAngle | float
selectionAngle | float
selectionDistance | float

Detailed Description

This class manages the field of view in which an Entity can become a potential target for any given client. Default values can be specified in engine_config.xml in the <targeting> data section. See BigWorld. PyTarget to see how potential targets are used to select the final target.

Attribute Documentation

autoAim

This attribute provides access to the BigWorld AutoAim object, which is used to define how a camera will behave when a target is in view.

Type:
AutoAim

autoAimOn

If true, AutoAim settings will be used when a target is in view, otherwise, camera behaviour will be as normal, regardless of current target status.

Type:
boolean (0 or 1)

defaultDeselectionAngle

This is the default angle, in degrees, in the field of view at which a potential target will no longer be considered viable.

Type:
float

defaultSelectionAngle

This is the default field of view angle, in degrees, at which an Entity will become a potential target.

Type:
float

defaultSelectionDistance

The default distance at which an Entity can form a potential target.

Type:
float

deselectionAngle

This is the angle, in degrees, in the field of view at which a potential target will no longer be considered viable. Lower values will provide a tighter fov, whilst higher values will keep more targets.

Type:
float

selectionAngle

This is the field of view angle, in degrees, at which an Entity will become a potential target. Lower values will provide a tighter fov, whilst higher values will capture more targets.

Type:
float

selectionDistance

The distance at which an Entity can form a potential target.

Type:
float


TextGUIComponent - BigWorld client Documentation

TextGUIComponent Class Reference

[GUI Module]

TextGUIComponent is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Member Functions

def reset( self ):
def stringDimensions( self, text ):
def stringWidth( self, text ):

Attributes

colourFormatting | Boolean
explicitSize | Integer
font | String
multiline | Boolean
text | String

Detailed Description

The TextGUIComponent is a GUI component used to display text on the screen. It inherits from SimpleGUIComponent.

It can display text in various fonts, and can have its text assigned dynamically.

A new TextGUIComponent is created using the GUI.Text function.

For example:
tx = GUI.Text( "hello there" )
GUI.addRoot( tx )
tx.text = "goodbye"
This example creates and displays a TextGUIComponent with the text "hello there", and then changes it to say "goodbye" immediately afterwards.

Note that setting the SimpleGUIComponent.texture and SimpleGUIComponent.textureName attributes is not supported on TextGUIComponent.

Member Function Documentation

def reset( self ):

This method redraws the TextGUIComponent if it has become dirty. It shouldn't be neccessary to call this function.

def stringDimensions( self, text ):

This function returns a 2-tuple containing the dimensions (in pixels) that the specified string will take when rendered to the TextGUIComponent using its current font.

Parameters:
text The string to measure the length and height of.

Returns:
A 2-tuple of integers, the render width and height of the string in pixels.

def stringWidth( self, text ):

This function returns the width (in pixels) that the specified string will take when rendered to the TextGUIComponent using its current font.

Parameters:
text The string to measure the length of.

Returns:
An integer, the rendered width of the string in pixels.

Attribute Documentation

colourFormatting

If set to True, the text component will look for colour formatting tags embedded within the text. Formatting tags are defined inline and a be of the form:

\cRRGGBBAA;

where RRGGBBAA is a 32-bit hex representation of the desired colour (which must include the alpha value). If a tag is not of this form then it is treated as visible text. Use \\ to escape a tag if neccessary (e.g. to sanitise user inputted text).

The colour property of the component will still be used, and will tint all text within the component by multiplying against the formatted vertex colour.

Note that formatting tags are also parsed when calculating text dimensions.

Type:
Boolean

explicitSize

This attribute specifies whether the text component will resize itself to fit exactly within the given text dimensions, or whether the size of the component automatically resizes to reflect the best on-screen size (default)

If this flag is turned off (default) the text component resizes itself such that exactly one texel equals one pixel on-screen, for the clearest possible text. In this instance, width and height are read-only properties, and are correct after the text label is set, or the screen resolution has changed.

If this flag is turned on, the text component will draw itself into the given dimensions. This may result in text with an incorrect aspect ratio. In this instance, width and height are read/write.

When the flag is turned on, setting either the width or the height to 0 will maintain the correct aspect ratio. After setting the width or height to 0, the width and height attributes will update to reflect the actual size of the text.

When the flag is turned on, setting both width and height to 0 will set the text to the optimal size (one texel = one pixel). In order to do this, the width and height must be set at the same time, i.e. you must use textComponent.size = (0,0)

Type:
Integer

font

This attribute specifies the path to the font file that is used to render the text. Assigning to it causes the new font file to be loaded. If an invalid file is specified, then a Python Error occurs.

By convention, font files are stored in the fonts subdirectory. They are an xml file describing which image to obtain the characters from, and the size and location of each character.

The default font is default_medium.font".

For example:
tx = GUI.Text( "test" )
tx.font = "default_small.font"
This example applies the default_small font to the text

Type:
String

multiline

If set to True, the text component will consider all newline (\n) characters contained within the 'text' property and wrap them accordingly when rendering and calculating text dimensions.

Newlines are treated as a line separator.

Type:
Boolean

text

The text to be displayed in the component. It will be rendered using the font specified in the font attribute. The component will be resized to fit the text, if a new string is assigned to it. It doesn't wrap text, so if the string is too long to fit on the screen it will just extend off the edges.

If multiple lines of text are desired, then multiple TextGUIComponents are required.

Type:
String


Tracker - BigWorld client Documentation

Tracker Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyFashion → PyObjectPlus

Member Functions

def debug( self ):

Attributes

cachedNodeInfo | Read-Only BaseNodeInfo.
directionProvider | Read-Write MatrixProvider.
nodeInfo | Read-Write BaseNodeInfo.
pitch | Read-Write Float.
relativeProvider | Read-Write Integer.
yaw | Read-Write Float.

Detailed Description

Tracker is a subclass of PyFashion that manipulates the yaw and pitch of Node instances in a PyModel to make them face towards (or "track") a target. The target may be another PyEntity / PyModel, an entity's auxilliary data, a specific direction, a point moving through a range of angles (allowing the PyModel to scanning back & forth), or anything else that can be represented by a MatrixProvider.

The following steps set up and use a Tracker:

Create a Tracker object. A new Tracker object is create by calling BigWorld. Tracker(). The factory method doesn't take any parameters, so the attributes of the new object need to be set.

Assign a direction provider. This is the matrix provider which tells the Tracker which direction it should try to orient the PyModelNode objects that it affects. If this is not assigned or is set to None then the Tracker will have no effect, even if the pitch and yaw attributes are manually altered.

Specify whether the direction provider provides an absolute direction, or a direction relative to the model's orientation. Note that this should be set after the direction provider, as this is set to false each time the direction provider is changed.

Specify a NodeInfo (an instance of a child class of BaseNodeInfo). This object contains data used by the Tracker to determine which PyModelNode objects to affect, and to what degree to affect them.

Apply the Tracker to a PyModel. This is achieved by assigning the Tracker object to a member variable belonging to the model. This variable need not exist beforehand, however it can be referenced afterwards (to remove the Tracker, for example).

Code Example: Turning a character model's head to point in the direction the player is facing. This demonstrates a simple use for the EntityDirProvider class.
# NOTE: model refers to the character model to which this is applied
# NOTE: ent refers to the entity whose direction model will turn to face

# create a new Tracker
tracker = BigWorld.Tracker()

# create an EntityDirProvider  which follows the entity's facing and
# apply it to the Tracker
facingDirProvider = BigWorld.EntityDirProvider( ent, 1, 0 )
tracker.directionProvider = facingDirProvider

# create list of secondary nodes
secondaryNodes = [ ( "biped Neck", 0.5 ) ]

# create TrackerNodeInfo & apply to Tracker
nodeInfo = BigWorld.TrackerNodeInfo( model, "biped Head", secondaryNodes,
                                     "None", -100, 100, -100, 100, 100 )
tracker.nodeInfo = nodeInfo

# apply tracker to the model
model.facingTracker = tracker

Code Example: Turning a character model's head to watch another entity. This demonstrates a simple use for the DiffDirProvider class.
# NOTE: model refers to the character model to which this is applied
# NOTE: sourceEntity refers to the entity which owns model
# NOTE: targetEntity is the entity to be watched by model

# create a new Tracker
tracker = BigWorld.Tracker()

# create a DiffDirProvider & apply it to the Tracker
diffDirProvider = BigWorld.DiffDirProvider( sourceEntity.matrix,
                                            targetEntity.matrix )
tracker.directionProvider = diffDirProvider

# create list of secondary nodes
secondaryNodes = [ ( "biped Neck", 0.5 ) ]

# create TrackerNodeInfo & apply to Tracker
nodeInfo = BigWorld.TrackerNodeInfo( model, "biped Head", secondaryNodes,
                                     "None", -100, 100, -100, 100, 100 )
tracker.nodeInfo = nodeInfo

# apply tracker to the model
model.diffDirTracker = tracker

Code Example: Swinging a character model's arms idly back & forth. This demonstrates a use for the ScanDirProvider class, and also the use of negative weightings for secondary nodes. By applying negative weightings to children of the primary node, this example effectively stops the Tracker from applying its transformation to all subsequent nodes. This is shown in the example by the head remaining stationary despite the movement which the Tracker creates lower down the spine.
# NOTE: model refers to the character model to which this is applied

# create a new Tracker
tracker = BigWorld.Tracker()

# create a ScanDirProvider & apply it to the Tracker
scanDirProvider = BigWorld.ScanDirProvider( 1, 5 ) # this scans +/-1 radian
                                                   # every 5 seconds
tracker.directionProvider = scanDirProvider
tracker.relativeProvider = 1

# create list of secondary nodes
secondaryNodes = []
secondaryNodes.append( ( "biped Neck", -0.5 ) )
secondaryNodes.append( ( "biped Head", -0.5 ) )
secondaryNodes.append( ( "biped Spine1", 0.5 ) )

# create a TrackerNodeInfo & apply to the tracker
nodeInfo = BigWorld.TrackerNodeInfo( model, "biped Spine1", secondaryNodes,
                                     "None", -100, 100, -100, 100, 100 )
tracker.nodeInfo = nodeInfo

# apply tracker to the model
model.armSwingTracker = tracker

Member Function Documentation

def debug( self ):

This is used to obtain debug information regarding nodeinfo sizes. This function is not supported and is not intended to be used by game code.

Returns:
A string containing debug information.

Attribute Documentation

cachedNodeInfo

This is the previous nodeInfo, used by the node info blending code. This is provided for debugging purposes, and is not expected to be used by a game.

Type:
Read-Only BaseNodeInfo.

directionProvider

This supplies the pitch and yaw targets. Note that assigning to this attribute also sets the relativeProvider attribute to false.

Type:
Read-Write MatrixProvider.

nodeInfo

This specifies which nodes this tracker affects, and to what extent it affects them.

Type:
Read-Write BaseNodeInfo.

pitch

The pitch currently applied by the tracker. Assigning a value to this causes the model to snap to the specified pitch then turn back towards the pitch supplied by the directionProvider attribute. Note that the model will not be affected if a directionProvider has not been specified, and that the value of this is relative to the world coordinate system regardless of the value of the relativeProvider attribute.

Type:
Read-Write Float.

relativeProvider

If this is non-zero then the nodes are turned to face the target direction in model space. Otherwise world space is used. Note that this is set to zero whenever directionProvider is changed.

Type:
Read-Write Integer.

yaw

The yaw currently applied by the tracker. Assigning a value to this causes the model to snap to the specified yaw then turn back towards the yaw supplied by the directionProvider attribute. Note that the model will not be affected if a directionProvider has not been specified, and that the value of this is relative to the world coordinate system regardless of the value of the relativeProvider attribute.

Type:
Read-Write Float.


TrackerNodeInfo - BigWorld client Documentation

TrackerNodeInfo Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

BaseNodeInfo → PyObjectPlus

Detailed Description

This is a subclass of BaseNodeInfo. This describes a system by which how PyModelNode instances can be affected by a Tracker, and the Node whose frame of reference is used for tracker manupulations. These values are all provided to the factory method used to create this (BigWorld. TrackerNodeInfo), and cannot be accessed afterwards.

Refer to the Tracker class documentation for an overview of the tracker system and related code samples.


UnresolvedUDORefException - BigWorld client Documentation

UnresolvedUDORefException Class Reference

[BigWorld Module]

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

import BigWorld

Detailed Description

This custom exception is thrown when trying to access a reference to a UserDataObject that hasn't been loaded yet.


Vector2 - BigWorld client 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 client 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 client 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 client 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 client 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 client 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 client 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 client 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 client 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 client 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 client 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 client 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 client 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 client 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 client 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


VectorGenerator - BigWorld client Documentation

VectorGenerator Class Reference

[BigWorld Module]

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

import BigWorld

Detailed Description

VectorGenerator is a class that is used by some actions in the ParticleSystem (most notably SourcePSA and JitterPSA) to specify possible (or modifications to) positions and velocities for particles.

This class is not instantiated directly, but uses a python sequence to pass through creation parameters for this class to the underlying C++ objects. The C++ object looks at the string specifying the type of vector generator and passes the arguments to the appropriate factory function for that type of VectorGenerator.

Example (see also SourcePSA):
source = Pixie.SourcePSA( [ "Point", ( 0, 0, 0 ) ],
                          [ "Sphere", ( 0, 0, 0 ), 0.4, 0.2 ] )

Possible initial generators are:

Format: [ "Point", location of the point ] Point: [ "Point", ( 0, 0, 0 ) ] Format: [ "Line", start of line, end of line ] Line: [ "Line", ( 0, 0, 0 ), ( 0, 0.1, 0 ) ] Format: [ "Sphere", center of sphere, maxRadius, minRadius ] Sphere: [ "Sphere", ( 0, 0, 0 ), 0.4, 0.2 ] Box: Format: [ "Box", corner, opposite corner ] [ "Box", ( 0, 0, 0 ), ( 0.1, 0.1, 0.1 ) ] Format: [ "Cylinder", center of the first circle endpoint , center of the second circle endpoint, radius of first circle endpoint , radius of second circle endpoint ] Cylinder: [ "Cylinder", ( 0, 0, 0 ), ( 0, 0.1, 0 ), 0.2, 0.4 ]


Weather - BigWorld client Documentation

Weather Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def windAverage( self, xWind, zWind ):
def windGustiness( self, gust ):

Detailed Description

This class is used to control the weather in the clients world.

The weather object is used to set the wind speed and wind gustiness. The wind affects the rate at which clouds move across the sky, and the pertubations of detail objects such as grass.

Member Function Documentation

def windAverage( self, xWind, zWind ):

This function sets the average velocity of the wind, specified as x and z coordinates. The wind on average blows at this velocity but deviates around it by a random amount which is capped at windGustiness.

The wind determines the direction and speed that clouds move across the sky. This is important, because when weather systems are changed the changes appear 1000m upwind of the user, and are blown across the sky at a rate specified by the wind velocity.

If the wind is changed, then existing clouds continue with their existing velocities, and new clouds are produced with the new velocity, so that the weather gradually switches to blow from a different direction.

The wind velocity is also used to perturb the detail objects, allowing for swaying grass and the like.

Parameters:
xWind | a float. The x component of the winds average velocity.
zWind | a float. The z component of the winds average velocity.

def windGustiness( self, gust ):

This function specifies the gustiness of the wind. This is the largest magnitude by which the actual wind speed can vary from that specified by windAverage, as it varies randomly.

The wind determines the direction and speed that clouds move across the sky. This is important, because when weather systems are changed the changes appear 1000m upwind of the user, and are blown across the sky at a rate specified by the wind velocity.

The wind velocity is also used to perturb the detail objects, allowing for swaying grass and the like.

Parameters:
gust a float. The cap on the random speed of the wind.


WebPageProvider - BigWorld client Documentation

WebPageProvider Class Reference

[BigWorld Module]

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

import BigWorld

Parent Classes

PyObjectPlus

Member Functions

def allowCursorInteraction( self, allow ):
def enableCookies( self, value ):
def enableProxy( self, proxyEnabledIn, proxyHostNameIn, proxyPortIn ):
def evaluateJavaScript( self, script ):
def focusBrowser( self, focus, enable ):
def handleKeyboardEvent( self, keyCodeIn ):
def handleMouseButtonEvent( self, pos, down ):
def handleMouseMove( self, pos ):
def handleUnicodeInput( self, keyCodeIn ):
def height( self ):
def navigate( self, url ):
def navigateBack( self ):
def navigateForward( self ):
def navigateReload( self ):
def scrollByLines( self, lines ):
def set404Redirect( self, url ):
def setDynamic( self, dynamicPage ):
def setSize( self, width, height, exactWidth, exactHeight ):
def texture( self ):
def update( self ):
def url( self ):
def width( self ):

Attributes

constantRefreshDuringNavigation | bool
height | uint32
listener | python object
ratePerSecond | float
texture | PyTextureProvider
url | unicode string
width | uint32

Detailed Description

This class is the wrapper class for one web page. This class can return a PyTextureProvider for the web page and can also be used to send event to the web page and to navigate to different web pages. These will get callbacks upon specific web page navigation events. The implementation is using the MPL LLMozlib library

The constructor takes 6 parameters that all have to be provided

The parameters are: width (uint32) - the width of the web page texture height (uint32) - the height of the web page texture dynamicPage (bool) - dynamic pages are refreshed at a higher rate mipmap (bool) - whether we want to create mipmaps for the texture or not url (unicode string) - the url to open (can be u"" to start with a blank page) graphicsSettingsBehaviour (string) - can be either "EFFECT_QUALITY" or "EFFECT_SCROLLING", this is how the web page responds to the WEB_SETTINGS graphics setting. If EFFECT_QUALITY is used, the web page is scaled to fit the WebPageProvider, if EFFECT_SCROLLING is used, the WebPageProvider shows a smaller view of the web page.

For example:
    webPage = BigWorld.WebPageProvider(800,600, True, True, u"", "EFFECT_QUALITY")
    webPage.navigate("http://www.google.com")
    component.texture = webPage.texture()
This example creates a WebPageProvider which provides the texture of www.google.com to A specific component for rendering.

Member Function Documentation

def allowCursorInteraction( self, allow ):

This method is used to set the browser interaction mode It effects whether it can alter the mouse or not.

Parameters:
allow The new interaction state

def enableCookies( self, value ):

This method enables or disables cookies.

Parameters:
value The Cookies setting

Returns:
bool True for success

def enableProxy( self, proxyEnabledIn, proxyHostNameIn, proxyPortIn ):

This method enables proxy usage by this provider.

Parameters:
proxyEnabledIn | A bool marking whether to enable the proxy usage
proxyHostNameIn | A string representing the proxy host name
proxyPortIn | An int representing the proxy port

Returns:
bool True for success

def evaluateJavaScript( self, script ):

This method is used to evaluate JavaScript code on this web page.

Parameters:
script The JavaScript code to execute

Returns:
The result of this command as a string.

def focusBrowser( self, focus, enable ):

This method is used to set the browser focus mode

Parameters:
focus | The new focus state
enable | Whether to enable the window (currently not used)

def handleKeyboardEvent( self, keyCodeIn ):

This method handles special int keyboard events sent to the web page.

Parameters:
keyCodeIn An int specifying the special key clicked

Returns:
None

def handleMouseButtonEvent( self, pos, down ):

This method handles mouse events sent to the web page. These should be in pixel space of the WebPage.

Parameters:
pos | A Vector2 specifying the position of the button event
down | a bool representing whether the button is down or up

Returns:
None

def handleMouseMove( self, pos ):

This method handles mouse move events sent to the web page. These should be in pixel space of the WebPage.

Parameters:
pos A Vector2 specifying the position of the mouse event

Returns:
None

def handleUnicodeInput( self, keyCodeIn ):

This method handles unicode keyboard events sent to the web page.

Parameters:
keyCodeIn A wide string whose first char represents the key in

Returns:
None

def height( self ):

This method is used to get the height of the web page

Returns:
The height of the webpage

def navigate( self, url ):

This method navigates the web page to a different url

Parameters:
url A unicode string specifying the new url

Returns:
None

def navigateBack( self ):

This method navigates one page back.

Returns:
bool True if succsess

def navigateForward( self ):

This method navigates one page forward.

Returns:
bool True if succsess

def navigateReload( self ):

This method reloads the web page.

Returns:
bool True if succsess

def scrollByLines( self, lines ):

This method handles mouse scrolling events sent to the web page. lines mark how much to scroll

Parameters:
lines A int32 specifying how much to scroll

Returns:
None

def set404Redirect( self, url ):

This method is used to set the default page when the web page isn't found.

Parameters:
url The redirect location

def setDynamic( self, dynamicPage ):

This method is used to set whether this page is dynamic meaning refreshes without someone clicking a link so should get higher refresh rate.

Parameters:
dynamicPage whether this page is static or updates all the time (dynamic)

def setSize( self, width, height, exactWidth, exactHeight ):

This method is used to set the size of the web page

Parameters:
width | The width of the web page
height | The height of the web page
exactWidth | Used for flash GUIs, contains their exact width
exactHeight | Used for flash GUIs, contains their exact height

Returns:
bool True if succsess

def texture( self ):

This method returns the web page texture

Returns:
A texture provider for the webpage

def update( self ):

This method update the web page and the texture

Returns:
None

def url( self ):

This method returns the current web page url

Returns:
The webpage url

def width( self ):

This method is used to get the width of the web page

Returns:
The width of the webpage

Attribute Documentation

constantRefreshDuringNavigation

A value specifiying whether this web page refreshes in a constant rate during navigation The web page will be refreshed one time per second during navigation if this value is true

Type:
bool

height

The height of the web page texture

Type:
uint32

listener

The listener to receive callbacks for this webpage

The listener is a python object that exposes the callbacks from BigWorld. WebPageProvider All the callbacks receive a PyMozillaEvent, although not all properties of the event is used in all callbacks, all callbacks need to return a boolean value to say whether they handled the event

The callbacks that can be defined and their event properties are:

onStatusTextChange - PyMozillaEvent.uri - url for this event - PyMozillaEvent.stringValue - status text

onUpdateProgress - PyMozillaEvent.uri - url for this event - PyMozillaEvent.intValue - progress percentage

onNavigateBegin - PyMozillaEvent.uri - url for this event - PyMozillaEvent.stringValue - status text

onNavigateComplete - PyMozillaEvent.uri - url for this event - PyMozillaEvent.stringValue - status text - PyMozillaEvent.intValue - the http response code

onLocationChange - PyMozillaEvent.uri - url for this event

onClickLinkHref - PyMozillaEvent.uri - url for this event - PyMozillaEvent.stringValue - href for the clicked link - PyMozillaEvent.stringValue2 - target for the clicked link

onClickLinkNoFollow - PyMozillaEvent.uri - url for this event - PyMozillaEvent.stringValue - same as uri

onPageChanged - PyMozillaEvent.uri - url for this event - PyMozillaEvent.rect - angle that has changed

@NOTE not all callbacks have to be supplied, only callbacks that are present will be called

Type:
python object

ratePerSecond

The refresh update rate for the web page. The web page will be refreshed n times per second where n is smaller or equals to this value. This is important as refreshing the web page is currently done in the main thread Creating performance spikes.

Type:
float

texture

The texture of the current web page

Type:
PyTextureProvider

url

The current url

Type:
unicode string

width

The width of the web page texture

Type:
uint32


WindowGUIComponent - BigWorld client Documentation

WindowGUIComponent Class Reference

[GUI Module]

WindowGUIComponent is part of the GUI module. More...

import GUI

Parent Classes

SimpleGUIComponent → PyObjectPlusWithWeakReference

Attributes

maxScroll | Vector2
minScroll | Vector2
scroll | Vector2

Detailed Description

This class forms the basis of windowing functionality for the GUI. Children added to a window are clipped and scrolled inside it. Children of Window components inherit the translation of the window.

If a child has either of its position modes set to "CLIP" then then this window is used as the basis for that child's clip space. In other words (-1,-1) is the bottom left of this window, and (1,1) is the top right of this window, and (0,0) is the centre of this window.

If a child has either of its position modes set to "PIXEL" then the position coordinate will be relative to the top left of this window.

Attribute Documentation

maxScroll

This attribute is the upper bound for the scroll attribute, which specifies an offset for the position of all child components of this window. It is a Vector2 specified in clip space coordinates( (-1,-1) in the bottom left of the screen, (1,1) in the top right).

Type:
Vector2

minScroll

This attribute is the minimum bound for the scroll attribute, which specifies an offset for the position of all child components of this window. It is a Vector2 specified in clip space coordinates( (-1,-1) in the bottom left of the screen, (1,1) in the top right).

Type:
Vector2

scroll

The offset that will be applied to the position attribute of all the children of this window. It is a Vector2 which is specified in clip space coordinates( (-1,-1) in the bottom left of the screen, (1,1) in the top right). It is bounded between the minScroll and maxScroll attributes.

Type:
Vector2


WorldToClipMP - BigWorld client Documentation

WorldToClipMP Class Reference

[GUI Module]

WorldToClipMP is part of the GUI module. More...

import GUI

Parent Classes

MatrixProvider → PyObjectPlus

Attributes

target MatrixProviderPtr The target MatrixProvider is the matrix that is used

Detailed Description

This utility class is a MatrixProvider that provides a clip-space position given a world-space matrix provider. It is primarily used by the MatrixGUIShader.

Attribute Documentation

target

Type:
MatrixProviderPtr The target MatrixProvider is the matrix that is used


 BigWorld Client

Actualised Classes

Modules
BWPersonality
BigWorld
FMOD
GUI
Math
Pixie
PostProcessing
ResMgr
Scaleform
Class List
ActionMatcher
ActionQueuer
AlphaGUIShader
ArmTrackerNodeInfo
AutoAim
AvatarDropFilter
AvatarFilter
BWOpenAutomate
BaseCamera
BaseNodeInfo
BlendNodeInfo
BoidsFilter
Bouncer
BoundingBoxGUIComponent
BoxAttachment
CameraSpeed
ClipGUIShader
ColourGUIShader
ConsoleGUIComponent
CursorCamera
DataSection
Debug
DiffDirProvider
DirectionCursor
DumbFilter
Effect
Entity
EntityDirProvider
EntityMProv
EventCategory
EventGroup
EventProject
EventReverb
Filter
FlashGUIComponent
FlashTextGUIComponent
FlexiCam
FootTrigger
FrameGUIComponent
FrameGUIComponent2
FreeCamera
GUIShader
GoboComponent
GraphGUIComponent
GroundNormalProvider
GuiAttachment
Homer
LatencyGUIComponent
LatencyInfo
LinearHomer
Matrix
MatrixAnimation
MatrixGUIShader
MatrixInverse
MatrixProduct
MatrixProvider
MeshGUIAdaptor
Minimap
Motor
MouseCursor
MusicSystem
OACommandWrapper
OANamedOptionWrapper
OAVersionStructWrapper
Orbitor
OrthogonalNodeInfo
Oscillator
Oscillator2
Physics
Plane
PlayerAvatarFilter
PlayerMProv
ProjectionAccess
Propellor
PyAmpParticleRenderer
PyAttachment
PyAxisEvent
PyBarrierPSA
PyBlurParticleRenderer
PyChunkLight
PyChunkModel
PyChunkSpotLight
PyCollidePSA
PyCopyBackBuffer
PyDye
PyEntities
PyFashion
PyFilterQuad
PyFlarePSA
PyFont
PyForcePSA
PyGraphicsSetting
PyIME
PyIMEEvent
PyJitterPSA
PyKeyEvent
PyLoft
PyMagnetPSA
PyMatrixSwarmPSA
PyMeshParticleRenderer
PyMetaParticleSystem
PyModel
PyModelNode
PyModelObstacle
PyModelRenderer
PyMorphControl
PyMouseEvent
PyMovieDef
PyMovieView
PyMozillaEvent
PyNodeClampPSA
PyObjectPlus
PyOrbitorPSA
PyOutputWriter
PyParticleSystem
PyParticleSystemAction
PyParticleSystemRenderer
PyPhase
PyPointSpriteParticleRenderer
PyPointSpriteTransferMesh
PyResourceRefs
PySTLSequence
PyScalerPSA
PySceneRenderer
PyServer
PyShimmerCountProvider
PySinkPSA
PySourcePSA
PySplatPSA
PySplodge
PySpriteParticleRenderer
PyStreamPSA
PyTarget
PyTextureProvider
PyTintShaderPSA
PyTrailParticleRenderer
PyTransferQuad
PyVisualParticleRenderer
PyVisualTransferMesh
PyWaterVolume
PythonServer
ScanDirProvider
ServerCaller
ServerDiscovery
ServerDiscoveryDetails
Servo
SimpleGUIComponent
SkeletonCollider
Sound
SoundParameter
Targeting
TextGUIComponent
Tracker
TrackerNodeInfo
UnresolvedUDORefException
Vector2
Vector3
Vector4
Vector4Animation
Vector4Basic
Vector4Combiner
Vector4Distance
Vector4LFO
Vector4MatrixAdaptor
Vector4Morph
Vector4Product
Vector4Provider
Vector4Shader
Vector4Swizzle
Vector4Translation
VectorGenerator
Weather
WebPageProvider
WindowGUIComponent
WorldToClipMP