Code Hierarchy

From Hero of Allacrost Wiki
Jump to: navigation, search

In this page, we go into detail about the organization and the core components in the Allacrost source code. This includes where in the source tree those components are located, their inter-dependencies, and what purpose they aim to achieve. This information is especially useful to programmers new to the project who are trying to understand how all the pieces fit together.

Allacrost is written in two languages: C++ and Lua. The C++ code is for more structured logic and optimized for performance. Lua, being an interpreted scripting language, does not have a compilation stage. It is used primarily to call functions in the C++ code in order to create custom environments, such as maps.

C++ Code Hierarchy[edit]

Game Engine
The game engine is the core of the Allacrost code base. The code that creates the game experience utilizes the various components of the engine in order to execute the game by playing audio, drawing graphics, processing user input, etc.
Audio Engine
The audio engine uses the OpenAL and vorbisfile libraries to playback sounds (.wav) and music (.ogg). This code is fairly advanced, supporting features such as customized looping, distance attenuation, and support for many audio effects such as fading.
Input Engine
The input engine uses the SDL library to process keyboard, gamepad, and joystick input from the user. This engine component also provides support to allow the player to customize and retain their control settings. Mouse input is not supported by the input engine at this time.
Mode Management Engine
Allacrost operates by utilizing a stack of "game modes". This is what allows us to quickly traverse from a map, into a battle, into a pause state, and then back out again. The mode management engine maintains this stack of game modes.
Script Engine
The script engine's primary purpose is to serve as an interface between Lua (our scripting language) and C++ (our primary language). It utilizes the Lua C API and Luabind libraries to achieve this goal. Support for C++ to read, write, and modify Lua files is provided by this class, as well as mechanisms for allowing Lua to access C++ code constructrs.
System Engine
The system engine provides a wide variety of engine utilities for other pieces of code to make use of. Two of its main purposes are providing timers and an accurate timing update system, as well as providing internationalization support using the gettext library.
Video Engine
The video engine is the largest and most complex of all the game engine components. The video engine uses the OpenGL library for graphics rendering, libpng and libjpeg for image file manipulation, and SDL_ttf for text rendering. The video engine implements support for texture management, text rendering, animation, lighting, special effects, and a long list of other features.
Global Code
The global code contains a series of objects and a manager that implement game elements which need to be shared between more than one game mode. For example, items are a game object that are used both in battles and in character menus. Characters, enemies, skills, are all examples of global objects. This code implements each of those objects, as well as a singleton class which actively maintains global objects which need to be retained on a more permanent basis (such as characters in the party, or inventory). Nearly all global data are retained in a Lua file in one way or another.
Global Main
The primary global code serves as a manager for some types of global content which are created, such as characters. It is also where the save/load feature of the game is implemented, and keeps a record of all the events which have happened in the game up to the point that the player has arrived at.
Global Objects
Global objects include: items, weapon, armor, shards, and key items. These classes are fairly simple and are often passed between different areas of the code.
Global Actors
Global actors include characters, enemies, and a host of other small classes that make it easier to operate with these actors.
Global Skills
Global skills include skills which are executed by characters and enemies (usually in battle), as well as providing support for elemental effects and status effects which are prevalent in the game.
Game Modes
Game modes implement the "meat" of the game. They are the code which drives sprites to move throughout a bustling community, or when the party fights a fierce battle against numerous foes, or allows the player to shop for new equipment for their characters. Game modes make several calls to the various components of the game engine and manipulate global code objects to make this all happen.
Battle Mode
Quite simply, this is the game mode that is active when the game characters are fighting in a battle. It manages a queue of actions that each actor is waiting their turn to take, executes those skills and the graphical and audio effects that accompany them, and interprets user input to take appropriate actiosn.
Boot Mode
Boot mode is the first game mode that the player sees when starting the game. It allows the player to start a new game, load a save game, configure the game's setting, and view the game's credits.
Map Mode
Map mode is active whenever the player is walking around exploring a map in a town or dungeon. It is the largest and most complex of the game modes, implementing A* pathfinding for on-screen sprites, support for scripted action sequences, rendering a mutli-layer tiled environment, and using a variety of scripted visual effects to create a unique atmosphere for each map.
Menu Mode
Menu mode allows the player to view their current party status, including the party's current location, each character's stats and equipment, and all objects in the inventory. It also allows the player to manipulate that data by using items or executing skills, changing equipment or characters, and saving the game.
Pause Mode
Pause mode is active while the game is paused.
Quit Mode
Quit mode is active when the user has requested a quit command, and serves to provide a double confirmation to make sure that the player truly wishes to quit the game or return to the main menu (boot mode).
Shop Mode
Shop mode provides a user interface for the player to purchase and sell wares. It also allows the player to easily examine the differences between their current inventory and the equipment for sale, and provides a shopping cart interface to make transactions.
Game Editor
The Allacrost game editor is a separate program from the game, using the QT4 GUI library to implement its primary interface. It also utilizes the game engine (especially the video engine) in its operation. The two primary purposes of the game editor are to create and edit maps, and to browse or add new game content (media).
Map Editor
The map editor is what we use to create, edit, and refine the basic properties of our maps. Typically, this includes map tile and object (sprite) placement. It also supports the creation of tileset definition files, which are files which define the properties of each tile contained within a tileset image.
Content Editor
The content editor allows the user to browse through and examine game images, playback game sounds or music, or view specific data such as enemy stats. The user may also use this interface to edit or add additions to this game content.
Miscellaneous Code
Miscellaneous code covers anything that does not fall under the previous three general areas. Examples include utility code and a testing interface that is used to help discover problems in the game engine.

Lua Code Hierarchy[edit]