The cs and cel python bindings are generated using the tool swig. This allows to wrap most of the functionality, and to provide somehow pythonic access to both libraries and their plugins. It is worthy to know some general details before diving into programming, specially so currently more extensive c++ documentation can be reused.
The following modules are available in different repositories, they can all be used together.
- cspace The main crystalspace module, wraps all of crystalspace objects.
- pycscegui Bindings for the cs-cegui connector.
- blcelc The main cel module.
- pycel Higher level module specific to the python behaviour layer.
- pycsextra Bindings for the csextra repository.
- pycsexternal Bindings for the csexternal repository.
Main ways of using python with crystalspace
There are many ways to use python with the cs framework, and the main ones will be explained here.
Pure Python cs-only app
This involves creating an app that can be run fully from the python interpreter. There are several tutorials inside cs on how to do this.
Pure Python cs+cel app
Similar to the previous point, but still slightly experimental (currently replicating celstart on python has some problems). This is not recommended yet unless you *really* know what you are doing.
Embedded inside a cs app through cspython
The option for c++ applications that just want to have some subsystems extensible through python. More complex than a python only or celstart embedded python app (obviously), and requires a good knowledge of both python and c++.
Embedded inside a celstart app through the python behaviour layer
CELstart is a cel runtime that contains (or can contain) the whole of cs and cel libraries. This allows to create full apps without any recompilation whatsoever. If you still dont know what celstart is, maybe you want to take a look at its main page before reading on here.
This is the easiest way to get you started, although not necessarily the most powerful way of making apps, it's very appropriate for people starting either with python or crystalspace and can be very rewarding.
CrystalSpace and Cel are both huge libraries with lots of functionality and abstraction over third party libraries. You should spend some time getting familiar with the manuals of both. Also note currently the python api is not perfect, and doesnt tell very precisely how to use the different parts of the library from python. This is being worked on, but you should both be familiar with c++ usage, and with the following notes:
- Output parameters to function are converted into returned parameters. This is so because python doesnt handle references or pointers, so the parameters are more naturally returned.
For example, cel's virtual void iBillboard::GetImageSize(int &w, int &h) should become (w,h) = iBillboard::GetImageSize().
- Most interfaces and classes should be wrapped, but some might not be and need to be added to the bindings.
- In general, callbacks other than iEventHandler wont work, this is still being worked on.
- csString types can always be handled as python strings.
- Most list and iterator classes/interfaces can be handled as python dicts or lists (means they support dict/list notation, not that you can use dicts or lists in place of the cs classes.
- Cel has some special python support added in for behaviours inside the python behaviour layer, you can check the cel manual for info on this. Actually, if going to use celstart, you should check this first.