Purpose of this document is to act as an entry point to system design documentation and explain the relevant concepts that are needed to be able to work with the software side of the project.
Documentation is aimed to be top-down browsable, so that reader can start from the top level and familiarize him/herself with the high level concepts first. After this reader can move to more precice definitions depending on interests.
Image on the right shows concepts relevant on documentation structure. Software is divided into modules, each having a description. Each module itself might be divided into smaller modules, thus creating a module hierarchy. Example of this hierarchy in logical level is e.g. "car - engine - piston".
Each module (despite of the level in hierarchy) contains:
- Zero to One module design
- Module design explains how module is currently implemented in the code. In case module description contains sufficient information about the design, separate design article is not needed.
- Zero to several module proposals
- Design of module changes with time. These changes should ideally be first described as proposals. One module might be under several design changes at the same time, thus creating several module proposals. When module proposals are implemented, their description moves (with refinements) to module design. In case old ideas are seen valuable to keep, they are moved to the archive wiki, otherwise they are just deleted
- One page listing module ideas
- While working with a module, developers often come up with ideas how design could be improved. This article is as a freeform page where these ideas can be written. Ideally these ideas should be refined as TRAC tickets at some point.
High Level Layering
The browsing of system architecture starts from system layering. Picture below follows normal layered architecture conventions: layers on top of other layer is able to use its services. Dependency relations go from top to bottom, so that to upper layers are (or could be) dependent on services of lower layers.
At the highest level there are clients. Clients are using services from the engine. Clients include things like games built on top of the engine functionality and engine utilities, tests and editors. As seen from the picture, clients can use services of the engine from many levels depending on their purpose. E.g. games are most likely built so that they are using only "Engine extensions" and "External libraries". However e.g. test apps and utilities can use also lower levels of the engine. APIs are more likely to change at the lower layers of the engine.
At the lowest level are the external libraries. Both engine and clients utilize their services. External libraries consist of things like SDL, OpenAL and database libraries.
Engine itself is divided into three layers. Engine core is the lowest layer containing the performance critical parts of the engine. Core is written with c++ to ensure its performance characteristics. It contains things like video, model driving and low level event handling.
Engine extensions provide convenient APIs for clients using the engine services. They also contain non-performance critical parts of the engine which are implemented with scripting languages. As a general rule of thumb, client using the extension must use the same scripting language than the extension itself.
Engine core and Engine extensions are bind together with SWIG wrappers. SWIG provides flexible mechanisms to generate bindings between C++ code and different scripting languages.
Language partitioning can be seen from the image on the right.
You can proceed to the lower abstraction levels using the following links.