/*
   $Id: python.dxt,v 1.1 2001/10/15 15:00:06 gnurou Exp $

   Copyright (C) 2001   Alexandre Courbot
   Part of the Adonthell Project http://adonthell.linuxgames.com

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License.
   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY.

   See the COPYING file for more details.
*/

/*!

\page page7 Python Scripting

Adonthell makes use of Python (http://www.python.org) as a scripting
language. Small modules of Python code are used to controll %game
elements like mapcharacters, mapviews and events or to perform special
tasks like animated cutscenes, etc..

\section whypython Why use a scripting language?
There is an important difference between %game engine and %game %data.
Adonthell's goal is the ability to run different %games without any
modification to the actual %game engine. This requires that %games
using the Adonthell engine can be created without writing a single
line of C++ code.

Most %game %data (maps, characters, etc...) can be easily created with
the help of the respective editor. But some elements need to be controlled
by a program. For example, Non-Player Characters (NPC's) or mapviews. Rather
than having a limited set of behaviors in the engine, it's better to directly
program them using a easy to use, platform independant, interpreted language.
And that is where Python comes in. Using Python, you can easily create your
own behavior scripts (also called \e schedules) for the characters, as
well as other parts of the %game (cutscenes, etc...). Actually, the entire
C++ API is available from Python - so when you create Python scripts
you have exactly the same possibilities you would have when writting them
in C++.

\section usingpython Using Python with Adonthell
The complete Adonthell API is available through the \e adonthell
module, which is imported at startup. There is a little customized
Python interpreter in \e src/tools/pydonthell/ you can use for testing
purposes: go into a valid %game directory, run \e pydonthell from
here and try this little example program:

\verbatim
>>> from adonthell import *
>>> im = image ()
>>> im.resize (100, 100)
>>> im.fillrect_rgb (0, 0, im.length (), im.height (), 255, 0, 0)
>>> im.draw (10, 10)
>>> screen_show ()
\endverbatim

All the classes and methods used in this little script are explained
in the API reference.


\section Running Python scripts
The py_object class is designed to handle most of the Python scripting.
It imports a Python module which should only contain Python classes.
An instance of the selected class is created and you can freely call
it's methods. See the \link py_object py_object class reference \endlink
for more details concerning it's use.

*/