Architecture:Main Module

Although the various Adonthell modules can be used from custom programs without utilizing the main module, this is highly discouraged. Not only provides the main module convenient initialization methods, it also contains code to prepare the environment for modules like gfx and input on different operating systems.

Using the Engine from C++

The main module provides a main function (hence the name), so your program will not need one when linking to the main module. Instead, it must provide a special class serving as entry point to your code once the startup process is complete. It should look as follows:

   #include "main/adonthell.h" 
   
   class AdonthellApp : public adonthell::app 
   { 
       // your application entry point 
       int main () 
       { 
           init_modules (GFX | ...); 
           ... 
       } 
   };
   
   AdonthellApp myApp;

It must extend adonthell::app and implement the pure virtual method int main(). This is the method called after basic engine initialization. Exactly one instance of that class should be instanciated. It will be automatically picked up by the main module. The base class adonthell::app gives you access to commandline arguments and further initialization methods, described in more detail in the API.

Using the Engine from Python

The main module provides roughly the same functionality when being used from within a Python script, althuogh a few more lines of code are required:

   from adonthell import main 
   
   class App (main.AdonthellApp): 
   
       # -- your application entry point 
       def main (self): 
           self.init_modules (self.GFX | ...) 
           ... 
           return 0
           
   if __name__ == ’__main__’: 
       theApp = App () 
       theApp.init (theApp.main)

The first difference to the C++ code is that we extend the class AdonthellApp, which is only available in the main module on Python side. It is in turn derived from the aforementioned class adonthell::app, so the methods it provides are available to Python too. The second difference is the call to theApp.init, which makes the applications entry point known to AdonthellApp. It also triggers the startup procedure described below, which will finally call the user supplied method. Note that code placed after theApp.init, will not be executed until the engine quits – if it is executed at all! You have been warned ...

Engine Startup

After having seen how the main module can be used, lets see what happens when using it.

1. Parse command line parameters
   As some parameters override defaults or supply otherwise important information, they are read first. The backend used or the configuration file loaded can be influenced that way.
2. Initialize base module
   Amongst other things, the path to the configuration directory – required for the next step – will be set up. Other game related paths will be initialized too.
3. Read configuration file
   Unless given on the command line, the backend to use is read from the configuration file adonthell.xml. A different config file can be chosen via the command line.
4. Perform platform specifc initialization
   The main module’s backend is loaded. If none was given via command line or configuration file, sdl is used as the fallback. Once loaded, it performs the operating system dependent initialization.
5. Initialize national language support (NLS)
   This causes the game specific language catalogue for the configured locale (or the system locale) to be loaded, if available.
6. Call user-supplied main method
   If all went well so far, the user supplied main method is executed. It should call the init_modules method to further initialize those parts of the engine it requires. Once the main method returns, the engine does some cleanup and finally exits.