/[adonthell]/doc/architecture/overview.tex
ViewVC logotype

Diff of /doc/architecture/overview.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.3 by ksterker, Sat Feb 22 11:27:05 2003 UTC revision 1.4 by ksterker, Sat Oct 30 13:13:02 2004 UTC
# Line 1  Line 1 
1  \section{Overview}  \section{Overview}
2  \thispagestyle{empty}  \thispagestyle{empty}
3    
4  Before describing the different parts and layers of the engine in detail,  Before describing the different parts and layers of the engine in detail, lets have a look at the big picture.
 lets have a look at the big picture.  
5    
6  \subsection{Design Principles}  \subsection{Design Principles}
7    
8  As Adonthell's development progressed, a few fundamental design decisions have  As Adonthell's development progressed, a few fundamental design decisions have been made. These principles have to be taken into account, whenever a part of the engine is updated or new parts are added. So please read on carefully before you start coding; it may save you much trouble.
 been made. These principles have to be taken into account, whenever a part of  
 the engine is updated or new parts are added. So please read on carefully before you start coding; it may save you much trouble.  
9    
10  \begin{enumerate}  \begin{enumerate}
11  \item {\bf Code and data have to be strictly separated}  \item {\bf Code and data have to be strictly separated}
12    
13  This is probably the most important rule of all. The engine is not intended for a  This is probably the most important rule of all. The engine is not intended for a single RPG, but should instead be able to drive multiple games. For that reason, the code must not contain any game data. Only functionality needed for a RPG may be provided by the engine, not the games themselves.
 single RPG, but should instead be able to drive multiple games. For that reason, the code must not contain any game data. Only functionality needed for a RPG may be provided by the engine, not the games themselves.  
14    
15  \item {\bf The engine should be as flexible as possible}  \item {\bf The engine should be as flexible as possible}
16    
17  Creators of games should have the most possible freedom in designing their  Creators of games should have the most possible freedom in designing their game. That is, the engine shall help people making their own RPGs without limiting their creativity. The game should control the engine, not the other way round. That means that the engine is no interpreter of game data, but rather a library the game may use for common and repetitive tasks.
 game. That is, the engine shall help people making their own RPGs without  
 limiting their creativity. The game should control the engine, not the other  
 way round. That means that the engine is no interpreter of game data, but  
 rather a library the game may use for common and repetitive tasks.  
18    
19  \item {\bf The engine should be easily extendable}  \item {\bf The engine should be easily extendable}
20    
21  To allow people to make quite different types of games, with different rules,  To allow people to make quite different types of games, with different rules, different items, different AI or just a different user interface, the engine needs to be customisable. Therefore, not only game data, but also most of the game mechanics have to be separated from the core engine.
 different items, different AI or just a different user interface, the engine  
 needs to be customisable. Therefore, not only game data, but also most of the  
 game mechanics have to be separated from the core engine.  
22    
23  \item {\bf The engine should be portable}  \item {\bf The engine should be portable}
24    
25  Adonthell shall run on as many different operating systems and  Adonthell shall run on as many different operating systems and
26  hardware architectures as possible. Right now the engine supports BeOS, BSD, Linux, Mac OS X, Solaris and Windows on hardware such as arm, alpha, ia64, ppc, sparc, x86 and possibly other. This has to be taken into account when writing code or utilising third-party libraries.  hardware architectures as possible. Right now the engine supports BeOS, BSD, Linux, Mac OS X, Solaris and Windows on hardware such as arm, alpha, ia64, ppc, sparc, x86 and possibly others. This has to be taken into account when writing code or utilising third-party libraries.
27  \end{enumerate}  \end{enumerate}
28    
29  \begin{figure}[ht]  \begin{figure}[ht]
# Line 43  hardware architectures as possible. Righ Line 32  hardware architectures as possible. Righ
32  \caption{Adonthell engine and surrounding layers}  \caption{Adonthell engine and surrounding layers}
33  \end{figure}  \end{figure}
34    
35  When taking these for points together, we get the following picture of the engine and its surrounding layers: the {\bf engine core} is the only component that has direct access to the {\bf operating system} and underlying hardware. {\bf game specific extensions} -- often written in Python -- may make use of interfaces provided by the engine, but not access the OS. This helps to make sure that a game runs on all platforms supported by the Adonthell engine.  When considering all these four points, we can draw a rough picture of the engine and its surrounding layers: the {\bf engine core} is the only component that has direct access to the {\bf operating system} and underlying hardware. It is written in C++ and provides common functionalities. {\bf Game specific extensions} -- written in Python -- make use of the interface provided by the engine core to implement functionality specific to a game. Avoiding direct access to the OS ensures that games will run on all platforms supported by the Adonthell engine.
36    
37  Both game engine and game extensions may access the game data: maps, graphics, dialogues and so on.  Both game engine and game extensions may access {\bf game data}: maps, graphics, dialogues and so on.
38    
39  \subsection{Architecture}  \subsection{Architecture}
40    
41  We've already seen the different components of an RPG made with the Adonthell engine. Before we dive into the details of the engine, we'll have a look how those components interact.  The engine core isn't a monolithic bloc, but split into a number of modules, each with its own namespace and each compiled into its own library. For each engine module, a corresponding extension module exists to allow access from Python.
42    
43  \begin{figure}[ht]  \begin{figure}[ht]
44  \center  \center
45  \includegraphics{arch.pdf}  \includegraphics{modules.pdf}
46  \caption{Adonthell engine architecture}  \caption{Adonthell engine architecture}
47  \end{figure}  \end{figure}
48    \begin{itemize}
49    \item {\bf Base}
50    
51  The engine consists of two different parts: the {\bf launcher} and the {\bf core} -- or library -- part. The launcher runs when starting the {\tt adonthell} executable. It initialises the different engine subsystems, such as audio and graphics, before giving control to a game specific start script. In future versions, the launcher will also allow users to select between different games; so there are different games installed. \\  The base module contains low level functionality used by most, if not all, the other modules. This includes I/O routines, i18n support, configuration file handling, a timer and more.
52    
53    \item {\bf Backend}
54    
55    A number of modules are accompanied by a backend library, providing the glue between the engine core and third-party code responsible for capturing input and handling audio and video output. Currently, SDL is the only backend supported, but support for other libraries may be added at need.
56    
57    This backend mechanism serves two purposes: first, it should allow to use different, more suitable backends -- like QT or GTK+ -- for our editors while still having full access to the functionality provided by the engine. Second, it limits the dependency upon a single media library. Should SDL 1.2 become obsolete, a port to a different backend would be fairly simple.
58    
59    \item {\bf Main}
60    
61    The main module provides the entry point for applications using the Adonthell engine, both Python scripts or C$++$ programs. It takes care of initializing other modules as requested, parses commandline arguments and a generic configuration file. It then passes control to a user supplied callback (Python) respectively main method (C$++$).
62    
63    \item {\bf Python}
64    
65    The python module provides the C$++$ $<-->$ Python bindings. For one, it is a thin wrapper around the Python C API, allowing access to python scripts, classes and methods from within the engine. At the same time, it provides the functionality for accessing C$++$ objects from within Python scripts.
66    
67    \item {\bf Gfx}
68    
69    The gfx module provides graphic primitives, like surfaces to draw on and image loading/saving abilities. Any video output is routed through this module, meaning all other parts of the library that render something on the screen have no dependencies to the underlying graphic library.
70    
71    \item {\bf Input}
72    
73    The input module keeps track of keyboard, mouse and gamepad input. It also provides a configurable, virtual control device. As with gfx, all user interaction with the engine is routed through this module.
74    
75    \item {\bf Audio}
76    
77    The audio module allows playback of sound effects and background music and provides other sound related functionality to parts of the engine that need them. Primary audio format is Ogg Vorbis.
78    
79    \item {\bf Event}
80    
81    A great deal of gameplay is accomplished through Python methods triggered by various events the engine generates. The event module provides the core event system based on a publish/subscribe mechanism. It also implements a date class to keep track of time in the game world and time events based upon that class.
82    
83    \item {\bf Rpg}
84    
85    The rpg module provides core functionality required by every RPG:  characters, quests, items, inventories and so forth. However, it does not contain complete implementations where this would limit flexibility, only interfaces. Those have to be extended by Python scripts in order to implement the rules of a specific game\footnote{More on this topic can be found in the Adonthell Scripting Guide}.
86    
87    \item{\bf Gui}
88    
89    The gui module provides a themeable widget library, suitable for modelling an unobtrusive game interface. It supports true type fonts through Freetype 2.
90    
91    \item{\bf Map}
92    
93    Low and high level classes for displaying the state of the gameworld to users.
94    \end{itemize}
95    
96    \subsection{Python on board}
97    Python is an easy to learn, interpreted, object oriented programming language -- and as such the perfect means to accomplish some of the design principles mentioned earlier.\\
98    
99    Adonthell's integration with Python works in two ways. In one direction, Adonthell acts as a Python interpreter. Therefore, it can delegate parts of the work to user-supplied scripts, allowing for more flexibility. This can be compared to a plug-in mechanism. In the other direction, all of Adonthell's modules can be accessed from within Python scripts. If a C++ class {\it bar} exists in namespace {\it foo}, a Python script can import it and manipulate it as if it was accessed from C++ code. That way, objects created in Python scripts can be passed to C++ methods or vice versa, with practically now limitations.\\
100    
101    This is accomplished by SWIG, which provides the neccessary glue between C++ and Python. Given a C++ class, SWIG will generate a Python module with the same interface. Internally, all calls to methods of the Python object are routed to the underlying C++ implementation. The gory details of wrapping and unwrapping C++ objects in order to pass them from C++ to Python and back are covered by SWIG. The {\tt pass\_instance} and {\tt retrieve\_instance} template functions supplied by our python module further simplify this task. They are described in the API.\\
102    
103    As a result, the engine can be seen as a library providing bits and pieces of RPG related functionality that can be used to write the actual game in Python. The benefit of that concept is that quite different games can be created without having to touch the underlying engine. One day, a community might form around the engine, providing players with mods and completely new games.
104    
105    % Now that we have an overview of Adonthell's architecture, we will look at select parts of the engine in more detail during the remaining chapters.
106    
 As soon as a game is started (by calling it's init script) all control remains with that game. After completing all game specific initialisation, the init script should start the engine's main loop. This provides basic functionality like input listeners, map and gui rendering. But it also provides hooks for game specific extensions, as we will see later on.  

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26