Tut-request for game-scripting

[mark]

I would like to understand how to script a CS+CEL-Game with python.
I have read the CS-docs and the CEL-doc from once-site and the design paper, but I don't know how to script entities because I did not find any information about that.

So I'm requesting a scripting-tutorial

[deckerego]

I'm not sure how many Python examples there are, but there are a few scripted demos in CS (i.e. demo and pathtut).

[oktal]

I'm thinking of writing a scripting tutorial soon, but it won't include anything about CEL.

For those who don't know, I am the author of the Perl scripting stuff in CS.

[vknecht]

Not exactly a tutorial, and probably outdated, but there's a project
using those : Freeraider
You can browse code at
http://cvs.sourceforge.net/viewcvs.py/freeraider/FR2/

Primary site is at http://freeraider.sourceforge.net/

[dirkk]

If someone could show me to a starting point to CS/python? I didn't find anything in the 'freeraider' ressource.

[mark]

yes, taking a look into the examples is fine when you know the basics, but learning a new mechanism/technique only by examples isn't easy.
And scanning a complete project like planeshift for some basic CS-coding answers is impossible, you have to learn everything about this project first (structures, classes, project-tree, ...) and then you may find what you are searching for.
Learning CS is difficult enough

For example: I want that an AI-Player goes to position x/y/z in a map when event e happens.
This behaviour shall be scriptable with python.
But how to invoke this script from a CS-app?
And how to bind this script to this AI-Player? (with a CEL-PropertyClass, when AI-Player is an Entity?)
What can someone do with scripting? Which methods/classes from CS/CEL are usable (and how)?
(How) Can own methods/classes be made usable for scripting?

[dirkk]

I tried to get a grip on Python scripting, but I don't get the pysimp example to run correctly. It does compile, but it just shows a black window. Obviously this call

Code:

 if (!csInitializer::OpenApplication (object_reg))

fails though I don't see any error. Any ideas why it fails anybody?

[mark]

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!");
pctooltip->Show(50,50);
...

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

So:
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.html
http://cel.sourceforge.net/docs/online/api/
http://www.once.net.nz/wiki/moin.cgi/DevelopersFAQ?action=show
http://planeshift.sourceforge.net/celtut/cel.html
to understand CEL.
---------------8<---------------

What do you think about this tutorial? It's still pure theoretical and not tested with code, but I think that is it.

[dirkk]

Hmm, I didn't deal with CEL at all at this moment. It seems, I should look at it more closer, this much I understood. When are people supposed to take plain CS, CEL or the PlaneShift code base?

Concerning the tutorial, I admit that I didn't understand too much, mostly of course because I don't know CEL. Also, I prefer tutorials with a more 'hands on' over a theoretical approach. But hopefully it is of use for someone who is more into CS/CEL than me.

Regarding my problem above (with the CS codebase) it seems I am one step further. In the csInitializer::RequestPlugins call I added

Code:

CS_REQUEST_REPORTER,
CS_REQUEST_REPORTERLISTENER,

these lines. This way I get an appropriate error message in the CS window saying:

Code:

Warning: could not load plugin 'crystalspace.script.python'

from the crystalspace.pluginmgr.loadplugin.

Just out of curiousity I changed it to LUA, to no avail of course. Now I suspect that CS doesn't find the python.dll or something. I have to check on that.

[mark]

Hmm, I didn't deal with CEL at all at this moment. It seems, I should look at it more closer, this much I understood. When are people supposed to take plain CS, CEL or the PlaneShift code base?

I guess, plain CS is good when you need it as a comfortable OS-independent class-library for developing other software than games.
(Maybe you don't like the STL and cannot use QT or another lib like that)

CEL is a great help for every game based on CS, it implements many many mechanisms you need to design, code and test by yourself when you do not use CEL. It is more high-level so you will have more sparetime when you use it (once you have understood it, of course ... )
My game-project did not use CEL but we saw that CEL takes care of all those tricky things we planned for months. It is really helpful, when you use objects and their graphical representation, events+communication, scripting, etc in your app.

And using planeshift... hmm, I guess this only makes sense when you're a planeshift-developer
Any other project should use CS or CS+CEL, because planeshift is no development kit. (but you can peek how they solved a special problem )

Concerning the tutorial, I admit that I didn't understand too much, mostly of course because I don't know CEL. Also, I prefer tutorials with a more 'hands on' over a theoretical approach. But hopefully it is of use for someone who is more into CS/CEL than me.

The purpose of my tut is to give the reader a basic understanding about the relationships between PL, PC, BL and Behaves from CEL.
When someone reads the available docs, he only gets an idea about CEL's techniques but this is too vague to understand CEL itself and how to use it in a CS-app.
Imagine CEL as a box of Lego-stones:
The available docs only describe the simple stones in that box.
You have to find out how to build complex objects without knowing how to combine the stones.
My tut wants to tell how to combine the stones (assuming you already know them). Creating a complex object should be easy (or at least easier) then.