4.18.4.5 Basics

This section instructs you on how "the crystal way" works from python. This is, how you can access interfaces, query object registry plugins, access engine lists and so on.

Accessing the object registry

In crystalspace there is a central registry that keeps track of loaded plugins. You will normally use it for just one thing: getting pointers to loaded plugins.

So, the first thing you need will be to get the object registry handle (or at least know where it is).

In situations when you didnt initialize crystalspace yourself, it will be stored in the cspace module as: cspace.object_reg.

# cs is already loaded.
import cspace
ObjectRegistry = cspace.object_reg

If you created the cs environment from python, it will be the returned value from csInitializer.CreateEnvironment().

import cspace
import sys
ObjectRegistry = cspace.csInitializer.CreateEnvironment(sys.argv)

if not ObjectRegistry:
    print "Fatal error! Couldn't create the environment"

# Note at this point you still have to initialize a lot of things to make
# crystalspace load all its plugins, maybe load a world and so on, check
# the tutorials for information about this.

Querying from the object registry

Once you have the object registry handle, you can query it by using its Get function.

Here follows an example where object registry is used to query the engine:

import cspace

# Get a nice handle for the registry
ObjectRegistry = cspace.object_reg # assumes environment was setup by cspython

# Query the iEngine plugin
engine = ObjectRegistry.Get(cspace.iEngine)

If you are familiar with the c++ api, you know it's done with a special template for convenience. In python the original api becomes usable, plus the template syntax doesnt translate nicely, so you just use ObjectRegistry.Get.

Engine object lists

Normally, you will need to use the engine to query meshes, factories and so on.

You do this by using its api to get the list, and then use the list as a python list that you can query by name, index, or iterate.

Building on the previous example:

from cspace import csVector3
from random import random

# iterate all meshes, and print their names
meshes = engine.GetMeshes()
for mesh in meshes:
    print " * a mesh",mesh.QueryObject().GetName()

# get a certain mesh, and set its position.
if "Cube" in meshes:
    amesh = meshes["Cube"]

    # Set the mesh position to some random value
    v = csVector3(random(),random(),random())
    amesh.GetMovable().SetPosition(v)

Querying an interface from an object

Finally, cs objects usually implement many interfaces, and sometimes you need to access them in order to control specific functionality from a generic handle.

This is done by using the QueryInterface function in the object:

sub_obj = some_cs_obj.QueryInterface(iSomeInterface)

Note in c++ this is done using a special template for convenience, but in python the original interface already works nicely.

For example, a mesh from the engine mesh list can be a particle system, or a general mesh, both with very different capabilities, normally you get an iMeshWrapper from the engine list, which is a generic interface for all mesh types the engine handles.

In this case, the mesh would implement iGeneralMeshState if it is a general mesh, or iParticleSystem for a particle system (or none of both if it belongs to neither group).

The following is a example illustrating how to look through all meshes in the engine, check if they are particles or genmesh, and for each use a function from the api, note, again, we are reusing symbols from the previous examples, and only importing new ones, in order to keep the new ideas easier to see:

from cspace import iParticleSystem, iGeneralMeshState

for mesh in meshes:
    # cant really be both, but favouring clarity over efficiency
    # both queries are done anyways
    partsys = mesh.QueryInterface(iParticleSystem)
    genstate = mesh.QueryInterface(iGeneralMeshState)

    # if its a particle system, get the first emitter, and sets its
    # rate to 10000
    if partsys:
        if partsys.GetEmitterCount ():
            emitter = partsys.GetEmitter(0)
            emitter.SetEmissionRate(1000)
    elif genstate:
        genstate.SetLighting(False)
    # this is advanced part for this example, you can ignore:
    else:
        print "This is not a particle system or genmesh"
        print "Supports the following interfaces:"
        for iface_metadata in mesh.GetInterfaceMetadata():
            print " * "+iface_metadata.interfaceName

Note how you can use iBase's GetInterfaceMetadata to find out interfaces an object supports, although you generally don't need to do this.

This document was generated using texi2html 1.76.