If you are working with DSS via the scripting component (Script_Python), then you will not need to know about anything but PerformHeartbeat. Scripts loaded from files do not have an equivalent to PerformPrivateStartupStep and PerformPublicStartupStep, or StopFactory. You do not need to know about the scheduler, as scripts are executed each heartbeat, at 100 times per second.
When working with Python, an equivalent to the PerformPublicStartupStep can be acheived with this technique:
# Detect if ourObject has been created, if it hasn't it must be the first pass, so do initialization
if 'ourObject' not in locals().keys():
class ourClass :
# Do once off initialization here. The values set here will exist across all instances of the class
def __init__(self):
# Do per instance initialization here
pass
def PerformHeartbeat(self):
# Do per heartbeat work here
pass
ourObject = ourClass()
ourObject.PerformHeartbeat()
- Todo:
- Check if our implementation supports python destructors, as an equivalent to StopFactory?
Any function in the Digital Spaces API that uses a parameter to return its value (e.g. the use of out_Vector3f) will be converted for the scripting API to return a pythonised version of the value instead. So, this example C++ code:
Wml::Vector3f pos;
sceneNode->GetPosition( pos );
is equivalent to the Python code:
pos = sceneNode.GetPosition();
in which
pos will be a 3 value tuple, containing the x, y and z aspects of the vector. This conversion is applied to:
- out_Pairf - two item tuple, containing floats.
- out_Vector3f - three item tuple, containing floats.
- out_Vector4f - four item tuple, containing floats.
- out_Quaternionf - four item tuple, containing floats.
- DIStringList1 - list of strings.
- DIObjectBaseList1 - list of objects (DIObjectBase), objects need to be cast.
- DIDUIDList1 - converts to nothing.
- DIStringPairList - list of two item tuples, containing strings.
Additionally, certain input container types are automatically converted from the convenient Python native types. These are:
- in_Vector3f - tuple or list of 3 floats.
- in_Vector4f - tuple or list of 4 floats.
- in_Quaternionf - tuple of list of 4 floats.
- in_Pairf - tuple of list of 2 floats.
In future, there may be Python specific pair/vector/quaternion classes added, to keep the advantages of the Python container classes while adding functions useful for working with these data types.
Each script is executed within a local variable scope. The "outermost" level of code is not global, as C++ experience might sugest. However, objects can be pre-declared using the Python keyword
global and this will make them available in all scripts.
A convenient trick to test if a global variable is available is to test gloabls().keys(), like so:
if 'variableName' in globals().keys():
varaibleName = newValue
We have found this useful to provide centralized functionality. For example, a data logger object can be created in one script, then fed data from multiple other scripts.
