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:

`cspace'
This is the main CS python module which provides most of the functionality
in its API.

`blcelc'
This is the main CEL python module which provides most of the
functionality in its API.

`pycel'
This is a high level layer that is accessible when running scripts under the
python behaviourlayer. It provides easy access to some of the common
functionality in CEL, and usually this is what you'll import into your
scripts. Note pycel includes all functionality from both of the above.

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).

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 CELXML format as seen
elsewhere in this manual.

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

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:

`pycel.Entities'
Used to get entity objects by name.

`pycel.EntityTemplates'
Used to get entity templates by name.

`pycel.PcFactories'
Used to get or register property class factories by ID
(like cel.pcfactory.timer).

`pycel.BehaviourLayers'
Used to get or register behaviour layers with CEL.

Crystal Space plugins

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

pycel.Engine
The engine plugin where you can get access to most Crystal Space objects in
your map (iEngine interface)

pycel.Vfs
The virtual file system plugin that you can use to move around the file system
(iVFS interface).

pycel.Clock
The virtual clock plugin, used to get precise times to calculate motion
(iVirtualClock interface).

pycel.Graphics2D
The graphics2d plugin presently in use, used to draw 2D things on the
screen (iGraphics2D interface).

pycel.Graphics3D
The graphics3d plugin presently in use, used to draw 3D things on the
screen (iGraphics3D interface).

pycel.Loader
The loader plugin from Crystal Space, used to load world or library files
(iLoader interface).

pycel.Stringset
The string set plugin, used to transform from CS string IDs to
regular strings (iStringSet interface).

getid / fromid

Functions to transform from string to stringid.

pycel.getid(string)
returns a string ID from the given string.

pycel.fromid(stringid)
returns a string from the given 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).

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.

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:

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: