[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6 The Python Behaviour Layer

One of the predefined behaviour layers in Crystal Entity Layer is the BLPYTHON behaviour layer. In this behaviour layer PYTHON is used as simple scripting language. This allows one to create game logic using PYTHON, and thus creating full scripting games without need of recompilation.

CS and CEL python bindings

There are several python modules for Crystal Space and CEL:

Also it has to be noted pycel is automatically imported into each behaviour namespace, so you need not import it unless to import * from it.

Behaviours

When using the BLPYTHON behaviour layer you basically create scripts. Every script corresponds to a behaviour for an entity (multiple entities can use it of course).

Every script must include a behaviour of the same name.

A python behaviour has the following structure:

 
# file fovcontrol.py
from pycel import *

class fovcontrol:
        def __init__(self,celEntity):
                print "Initializing fovcontrol...",celEntity.Name
		# get camera from main actor (called camera in this case)
                self.camera = celGetDefaultCamera(Entities["camera"]).Camera
                self.initfov = self.camera.GetFOV ()
		# get/create a pccommandinput
                self.input = celCommandInput(celEntity)
                self.input.Bind("z","zoomin")
                self.input.Bind("x","zoomout")
                self.input.Bind("c","zoom0")
		# get/create a timer
                self.timer = celTimer(celEntity)
                self.timer.WakeUpFrame(CEL_EVENT_PRE)
		# define some initial values
                self.zoomin = False
                self.zoomout = False
		# get initial time
                self.time = Clock.GetCurrentTicks()

	# property class message callbacks
        def pctimer_wakeupframe(self,celEntity,args):
                self.time = Clock.GetCurrentTicks() - self.time
                if self.zoomin:
                        self.camera.SetFOV(int(self.camera.GetFOV()+(5*(self.time/1000.0))),Graphics2D.GetWidth())
                if self.zoomout:
                        self.camera.SetFOV(int(self.camera.GetFOV()-(5*(self.time/1000.0))),Graphics2D.GetWidth())
        def pccommandinput_zoomin1(self,celEntity,args):
                self.zoomin = True
        def pccommandinput_zoomout1(self,celEntity,args):
                self.zoomout = True
        def pccommandinput_zoomin0(self,celEntity,args):
                self.zoomin = False
        def pccommandinput_zoomout0(self,celEntity,args):
                self.zoomout = False
        def pccommandinput_zoom01(self,celEntity,args):
                self.camera.SetFOV(self.initfov,Graphics2D.GetWidth())

As can be seen we have a class with several methods.

First we have the constructor (__init__ function) that gets a pointer to the entity it's being attached to (celEntity). As usual in python all methods in the class get a first parameter that points to the own python class instance (self) of the behaviour, we can use it to save variables for the instance.

After this we have some callback functions, in many situations CEL will call certain functions in our python behaviours so we may react to events. For example pctimer_wakeup is got when the entity receives a wakeup event from a timer, pctrigger_entertrigger is got when the entity enters some trigger's area.

Python behaviours at XML worldfiles

Python behaviours can be set directly in CEL XML format as seen elsewhere in this manual.

Here is an example entity with some property classes and a python behaviour set to it:

 
<addon entityname="camera" plugin="cel.addons.celentity">
  <propclass name="pcmesh">
    <action name="SetMesh">
      <par name="name" string="ActorMesh"/>
    </action>
  </propclass>
  <propclass name="pcdefaultcamera">
    <action name="SetCamera">
      <par name="modename" string="thirdperson"/>
    </action>
  </propclass>
  <propclass name="pccommandinput"/>
  <propclass name="pcmeshselect">
    <action name="SetCamera">
      <par name="entity" string="camera"/>
    </action>
    <action name="SetMouseButtons">
      <par name="buttons" long="2"/>
    </action>
  </propclass>
  <behaviour layer='blpython' name='actor'/>
</addon>

Note the python behaviour will be loaded from the `actor.py' file that must lie somewhere in PYTHONPATH (note `celstart' will add the main folder of your ZIP file to the PYTHONPATH if you're using it).

Usually the celentity addon is placed in a Crystal Space sector inside the world files.

pycel

pycel is a high level layer which defines some aliases for some of the most accessed things:

The PhysicalLayer

The physical layer is your main pointer to CEL functionality, and you'll require this to create entities, destroy them, get string IDs.... It can be accessed from python at `pycel.PhysicalLayer'.

PhysicalLayer dictionaries

All the physical layer dictionaries can be accessed directly from pycel:

Crystal Space plugins

Some often used plugins in CS are ready to use (if present). These are:

getid / fromid

Functions to transform from string to stringid.

parblock

Function to create a celParameterBlock from a python dict or list. This is described in detail later.

CreateEntity / RemoveEntity

These can be accessed directly from pycel to create and destroy entities. Use them in the same way as the physical layer functions of the same name.

Property Class accessors

Some functions are defined to easily create CEL property classes for entities, or access the pre existent ones. This will be described in the next section of this manual.

Accessing entity property classes

Property classes are objects we can create attached to an entity, and which augment the entity with some functionality (see section Property Classes).

First it must be noted to use each property class it must be ensured it is registered at the physical layer, to do this in python simply add the property class factory full name (cel.pcfactory.pcclass) to the `PcFactories' dict (which is a member of the physicallayer but has global access due to pycel layer).

An example of this follows:

 
pcclasses = ["region","tooltip","mesh","solid","meshselect","zonemanager","trigger",
	     "quest","light","inventory","defaultcamera","gravity","movable",
	     "pccommandinput","linmove","actormove","colldet","timer","soundlistener",
	     "soundsource","billboard","properties"]
for pcclass in pcclasses:
	PcFactories.append("cel.pcfactory."+pcclass)

For each property class there are several functions in pycel module that allow easily fetching or creating of the appropiate property class from an entity object:

Where `PropertyClass' would be substituted for the appropiate name, like in celGetTimer, celAddCommandInput...

As an example at the initialization section we could do:

 
    def __init__(self,celEntity):
          self.input = celCommandInput(celEntity)
          self.timer = celAddTimer(celEntity)
          self.timer.WakeUpFrame (CEL_EVENT_POST)
          self.select = celMeshSelect(celEntity)

Messages

Each property class in CEL can generate a number of messages. A python behaviour receives this messages as python function calls with the same name as the message. We can use this calls to respond to events from the different property classes appropiately.

In the first example we're receiving a pctimer_wakeupframe function call each frame, due to the activated pctimer.

Also there are some pccommandinput_* functions, that are triggered by the pccommandinput binds. Notice for each input bind we make through pccommandinput, the behaviour will receive three different events named pccommandinput_bind1, pccommandinput_bind0 and pccommandinput_bind_, respectively for the key press, release and maintain events.

Other property classes like pcmechanicsobject, pcmeshselect, pcbillboard, pcdamage, pclinmove also generate their own special messages.

Message function calls get three parameters. The first is the behaviour class instance, the second the entity receiving the message, and the last a celParameterBlock that holds all message specific values.

You can access the values from the parameter block as a python dict with CEL StringIDs for index instead of normal strings.

 
# a pcbillboard select message
def pcbillboard_select(self,celEntity,args):
       bx = args[getid("cel.parameter.x")]
       by = args[getid("cel.parameter.y")]
       button= args[getid("cel.parameter.button")]

It is possible to test for existence of a certain parameter, or iterate over the values. Also note for efficiency you would save the StringIDs for later use instead of querying them each time.

A final snippet for printing all parameters to a message:

 
def pcbillboard_select(self,celEntity,Args):
       for strid in args.keys():
		print fromid(strid),args[strid]

Sending Messages

Some messages (like __init__ and messages from property classes) are automatically called but you can also define your own messages and call them using the iCelBehaviour.SendMessage function.

To send a message/event to another entity, we must create the same kind of parameter list. There exists a helper function in the physical layer to do this called CreateParameterBlock, and also the `pycel' alias parblock. It accepts either a dict, list or tuple as arguments. If we provide a dict, it will initialize the IDs and values in the parameter block; if we provide a list or tuple, it will only fill the IDs and will require filling the values later:

 
#Creating a parameter block from a list. This is more similar to the c++ method
pars = parblock(["control","x","y"])
pars[getid ("cel.parameter.control")] = "specular"
pars[getid ("cel.parameter.x")] = 15
pars[getid ("cel.parameter.y")] = 200

#Creating a parameter block from a dictionary.
pars2 = parblock({"control":"shininess","x":30,"y":200})

The difference is in speed, usually if you'll be sending the same kind of parameter block many times, you'll want to build it in the constructor from the behaviour, and just fill values before sending. In other situations it can be appropriate to create the entire parameter block from a dict when needed.

After this, the message is sent using SendMessage in the target entity behaviour:

 
Entities["player"].Behaviour.SendMessage("control_variable", None, pars)

A python world for `celstart'

The best way to run python (or XML and python) only CEL worlds is to use the `celstart' CEL application (see section celstart).

For this you will need to load the python behaviourlayer from the celstart configuration file. Another common procedure is to define some starting entity to be created with an app behaviour. From here it is possible to load the map entirely from python although note other setups are possible.

In order to do do this, we would add something like the following to the config file:

 
CelStart.BehaviourLayer.blpython = cel.behaviourlayer.python
CelStart.Entity.bootstrap = bootstrap
CelStart.EntityBehaviour.bootstrap = appinit
CelStart.EntityBehaviourLayer.bootstrap = blpython

This would create a starting entity and load the python behaviour appinit, which would be loaded from the file `appinit.py'.

From this behaviour you can load a map using either CS or CEL API, an usual way of doing this is through a celZoneManager property class (see section Zone Manager) at the initial entity:

 
def __init__(self,celEntity):
	zoneMgr = celZoneManager(celEntity)
	Vfs.ChDirAuto("/tmp/celstart/")
	zoneMgr.Load("/tmp/celstart","level.xml")

Note `/tmp/celstart/' is the VFS path where `celstart' maps the ZIP file initially, so this doesn't change depending on operating system or real file location.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated using texi2html 1.76.