woah, I think I've got it!
I have written this tutorial in german for my team, I hope the translation ist usable:
---------------8<---------------Scripting with CS+CEL
We have (exactly) one PhysicalLayer (PL). The game-server creates it on startup.
The PL creates Entities, for example a cow, whenever we desire this.
We can attach PropertyClasses (PC) to our cow, we do this with the PL (and PL-Factories, but that's not important for python-scripting).
Which PCs an Entity needs must be thought of, we could give our cow a iPcTooltip to show her hitpoints in a tooltip.
(btw: cow does not inherit from the class entity)
ok, let's celebrate:
We didn't mention the BehaviourLayer (BL) yet. That's the thing we will code in C++ or script with python!
Until now we have created a class named "cow" which shall get a tooltip attached.
So we write a class "cowTooltip". This will inherit from BehaviourLayer.
Let's take a look into the API-docs from CEL. There are two classes: iCelBlLayer and iCelBehaviour.
The first one is the BL itself, we create only one BL in the game, just like the PL. (I had to notice that there is a difference between BehaviourLayer and Behave!)
iCelBehaviour * CreateBehaviour (iCelEntity *entity, const char *name)
is a method from the BL.
That means that our BL can attach something (a string) to an entity and this "product" is a Behaviour.
It's possible to call this method more than once, so the entity can get more Behaviours.
This string is the name we choose for our Behaviour, in our example "cowTooltip".
So let's take a look at iCelBehaviour.
The most important method from this class is:
bool SendMessage (const char *msg_id, celData &ret, iCelParameterBlock *params,...)
I wrote that cowTooltip inherits from the BL, so it gets this method which apparently is for communication-purpose.
Every PC posesses one or more message-types we can handle in this method.
For example "pcmeshsel_up" is being sent when the mouse is being moved over a mesh (we can assign a mesh to our cow, that is the 3D-representation we can see on the screen).
In this case the message_id-parameter in the SendMessage()-method is "pcmeshsel_up". Other events may send other message-types, for example "pctimer_wakeup" or "pcinventory_added", ... (you can see a list in the CEL design document and maybe somewhere in the API-docs).
Additional a list of parameters can be delivered too.
So our SendMessage()-method could do something like this when the message-type is "pcmeshsel_up":
pctooltip->SetText(entity->GetName() + " has 20 Hitpoints!");
This will open the tooltip over the cow at position 50/50 and it will show the text "cow has 20 Hitpoints!" (of course you shouldn't hardcode the number 20 *g*)
Entity-creation will be handled by the game-server but the Behaviours can be written in Python.
You may take a look at the files in cel/plugins/behaviourlayer/test, especially behave.cpp and behave.h.
These files contain a general behaviour-class and some behaviours (actor, box, room, printer).
The othere files there are the interface-definition for the CEL-plugin "test"
In the directory cel/plugins/behaviourlayer/python lies the python-plugin. It's partly created by SWIG, an interface-compiler to connect different programming/scripting languages.
In it's interface file blcel.i you can see all the methods that can be used for python-scripting (and that should be allmost everything dealing with PL, BL end PCs)
Oh, and you should have read http://cel.sourceforge.net/design.htmlhttp://cel.sourceforge.net/docs/online/api/http://www.once.net.nz/wiki/moin.cgi/DevelopersFAQ?action=showhttp://planeshift.sourceforge.net/celtut/cel.html
to understand CEL.
What do you think about this tutorial? It's still pure theoretical and not tested with code, but I think that is it.