\section{Base Module}
\thispagestyle{empty}

The most basic code is contained in this module, which means that you will definitely need to use it when writing code for Adonthell. As seen before, all the other modules depend on base.

\subsection{Machine-Independence}

One goal of the Adonthell engine is portability, and a number of services to aid this goal are implemented in the base module:

\begin{itemize}
\item {\bf Primitive data types}

All primitive integer types are redefined by the base module. Using them instead of the data types provided by the underlying C library ensures that a short will always be 16 bit and integers 32 bit, regardless of the hardware architecture and operating system.

{\it Note that this is not implemented yet, but by sticking to the types defined in base, it can be added easily. For example, the configure script could define types apporpriately at compile time.}

\item {\bf Endianness}

The same data files should be usable on both little and big endian hardware. Also, save games should be endian independent and both system types should be able to exchange data over a network. That means that there must be a way to convert data from little to big endianness and back. This is done through macros defined in the base module. Make sure to use them whenever data is read or written. The I/O methods described later are already endian independent -- sticking to them where possible will avoid problems too. Btw., data is always stored in little endian format and converted at need.

\item {\bf Game speed}

Since computers tend to get faster and faster, it is important to make the engine independent from CPU speed. The base module allows to specify the duration of a single game cycle. When calling {\tt base::Timer.update} after each cycle, the engine ensures that each cycle consumes exactly that timespan. That way, games will run at constant speed, given a fast enough CPU.

There's also limited support for slower CPUs. If computation of a cycle takes longer than allowed, the engine could react by skipping frames or by disabling costly, but otherwise unneccessary graphic or sound effects.
\end{itemize}

\subsection{Data Persistance}
The engine needs to be able to save the state of the gameworld and restore it at a later date. For that purpose, most objects must be serialized and written to disk. Since objects will change as development progresses, a mechanism is required to keep serialized data at least partially compatible with newer versions of the engine. 

This can be achieved by storing each variable with an id and type information. That way, an old engine can skip over new fields in the serialized data or provide defaults for missing fields if possible. Even if an object can't restore its state from such a data file, it will at least notice that fields are missing and can abort loading in a safe way.\\

Internally, an id, size, type and of course the value of a variable are written to a byte stream that can be later saved or transfered over the network. Multiple variables can be grouped together in a block to avoid confusing variables with the same id. It is therefore recommended to put the contents of each object into a seperate block. 

Blocks are also useful for storing array data with empty ids, thus saving space and time. These array elements can be easily restored by iterating over the contensts of their block.\\

\begin{figure}[ht]
\center
\includegraphics{bytestream.pdf}
\caption{Variable Bytestream Format}
\end{figure}

The figure above shows the bytestream format of a single variable. Multiple variables are concatenated without delimiter. Blocks are treated like variables, with their own type code and contents stored in the value area.

A checksum can be calculated for the whole stream, so data corruption can be detected, although no error correction is possible.\\

As mentioned above, the bytestream is kept in memory. To save it to disk, a wrapper around zlib is provided by the base class that can be used to write it into a compressed file. That reduces the overhead somewhat and keeps file size small. This zlib wrapper can also be used independently from the serialization, to write primitive types or blocks of memory to compressed files. This should be avoided, however, as no compatibility is guaranteed that way.

\subsection{Configuration Files}
The base module provides a way to store configuration parameters in an XML file. The format of the file is very simple. The first level consists of {\it sections}, each of which can contain {\it options} with a value each. To retrieve a certain parameter, the name of the section and option it is kept in needs to be known by interested modules. A default value can be passed -- if an option does not exist it is created with that default value. That way, the engine can start without configuration as long as it can provide a sensible default value for each parameter.\\

As discussed before, a default configuration is read during engine startup. It is automatically written back to disk when the engine quits.\\

With respect to a graphical configuration system, different option types are defined. One of them allows any type of value, others are limited to boolean values or a integer range. A last type allows only selection from a predefined list of values. The parameter type isn't stored in the configuration file, but must be explicitly set by the module requesting the parameter. That way, the configuration is kept free of metadata and easily editable by hand.

\subsection{Game Directories}
Usually, there will be one directory for static gamedata shared by all users and a data directory in the users \$HOME, where saved games and configurations reside. That way, the engine can be installed by a priviledged user and later be used by everyone else. When developing a new game, one might not want to install newly created game data, so a user defined data directory exists as well.\\

To ease the handling of data files, the base module provides a search strategy that operates on those three directories (which will differ for different games, of course). The method {\tt path::open} tries to locate a file in one of the directories in the following order:

\begin{enumerate}
\item Saved Game directory (if specified)
\item User supplied data directory (if specified)
\item Game specific data directory
\end{enumerate}

The first matching file is opened. Data files should always be opened this way instead of requiring them to sit in a fixed location. Later on, this mechanism might be expanded by addon or patch directories that will be added to the search path above.

