4.18.4 Python Bindings

Written by Eric Sunshine, sunshine@sunshineco.com.

Crystal Space is accessible from Python in two ways: (1) as a Crystal Space plugin module in which C++ code can call upon Python code, and in which Python code can call upon Crystal Space; (2) as a pure Python module named ‘cspace’ which one can ‘import’ from within Python programs. To use the first option, load the ‘cspython’ plugin as you would load any other Crystal Space plugin, and interact with it via the SCF ‘iScript’ interface (see section The iScript Interface). The second approach allows you to write Crystal Space applications entirely in Python, without any C++ coding.

Once Crystal Space is built and optionally installed, you can use the Python bindings. To do so, you need to make sure that Python can locate the appropriate Crystal Space resources. Follow these instructions:

1. Tell Python where to find ‘cspace.py’ by setting your ‘PYTHONPATH’ environment variable to mention the directory where ‘cspace.py’ resides. If you installed Crystal Space, then it will reside at:

   ${prefix}/share/crystalspace/bindings/python

   where ${prefix} is the installation path (typically, ‘/usr/local’). If you did not install Crystal space, then ‘cspace.py’ will be in the top-level build directory (this will be the ‘CS’ directory if you configured and built in the ‘CS’ directory).

2. Optionally tell Python where to find the ‘_cspace’ shared library. Python should be able to locate the library by consulting ‘PYTHONPATH’ which you already set, but if this fails, mention the directory containing the library in your ‘LD_LIBRARY_PATH’ environment variable on Unix, your ‘PATH’ variable on Windows, or your ‘DYLD_LIBRARY_PATH’ variable on MacOS/X. On Unix and MacOS/X, the library's name is ‘_cspace.so’; and on Windows it is ‘_cspace.dll’. If you installed Crystal Space, then the library will reside at:

   ${prefix}/share/crystalspace/bindings/python

   If you did not install Crystal Space, then it will be in the top-level build directory.

3. If necessary, set your ‘CRYSTAL’ environment variable to allow Crystal Space to locate its plugin modules and other resources.

There are a number of examples illustrating how to ‘import’ the ‘cspace’ module and utilize Crystal Space from within pure Python scripts. These scripts are installed at:

${prefix}/share/crystalspace/bindings/python

If you did not install Crystal Space, then you can find the scripts within the source tree at ‘CS/scripts/python’. In particular, the ‘tutorial#.py’ scripts should be of interest since they mirror the first several C++ tutorial programs (see section Simple Tutorial 1: Basic Setup, World Creation).

You can also access Python from a C++ program by loading the ‘cspython’ Crystal Space plugin module and interacting with it via the SCF ‘iScript’ interface (see section The iScript Interface). The ‘pysimp’ example program (‘CS/apps/pysimp’) illustrates how to do so. In addition to loading the ‘cspython’ plugin, it loads and executes Python code from a sample script (which resides along with the other Python examples noted above).

This document was generated using texi2html 1.76.