TA3D's developer documentation

This document explain how TA3D's source code is subdivided and a few other things needed to build/modify it.

Structure

Here are the files in the src subdir:

• module to manage 3do files (TA's 3D models) and 3dm models
  • 3do.cpp
  • 3do.h
• module to load units's scripts
  • cob.cpp
  • cob.h
• module to manage the developer console
  • console.cpp
  • console.h
• the core of the engine
  • EngineClass.cpp
  • EngineClass.h
• The Unit engine, originaly a part of EngineClass module
  • UnitEngine.cpp
  • UnitEngine.h
• module to load data from FBI files (unit types data)
  • fbi.cpp
  • fbi.h
• module to load GAF files (graphics and animation data)
  • gaf.cpp
  • gaf.h
• module to manage OpenGL extensions and shaders
  • glfunc.cpp
  • glfunc.h
• module to manage the interface
  • gui.cpp
  • gui.h
• header which contains the hash table templates (used by TA3D_hpi module)
  • hash_table.h
• module to read/decrypt/uncompress HPI archives
  • TA3D_hpi.cpp
  • TA3D_hpi.h
• module to use threads
  • cThread.cpp
  • cThread.h
• module to use safe threads
  • cCriticalSection.cpp
  • cCriticalSection.h
• program to view/extract data from HPI files
  • hpiview.cpp
• 3DM Editor, import 3D Models to 3DM format, allows texturings, selecting materials, ...
  • 3dmeditor.cpp
  • 3dmeditor_sub.cpp
• A.I. module
  • ia.cpp
  • ia.h
• the small icon displayed in the top left corner of the window
  • icon.cpp
• module for the introduction and loading screens
  • intro.cpp
  • intro.h
• module for the game menus (main menu, config menu, map selection, stats ...)
  • menu.cpp
  • menu.h
• module for ingame music (need MP3 or/and OGG support)
  • music.cpp
  • music.h
• module which contains the particle engine
  • particles.cpp
  • particles.h
• module for pathfinding
  • pathfinding.cpp
  • pathfinding.h
• module for game scripting
  • script.cpp
  • script.h
• module for ingame noise :-)
  • TA3D_Audio.cpp
  • TA3D_Audio.h
• main module
  • ta3dbase.h
  • ta3d.cpp
  • ta3d.h
• module for the configuration system
  • taconfig.cpp
  • taconfig.h
• module for TA's graphical features
  • tdf.cpp
  • tdf.h
• module to load TA's maps
  • tnt.cpp
  • tnt.h
• module to load weapons data and simulate weapons trajectories
  • weapons.cpp
  • weapons.h
• headers for matrix and vector maths
  • matrix.h
  • vector.h

Dependencies

Here is the list of all the libraries you could need:

• Allegro (game library) - used for mouse & keyboard input, time control, image loading support, sound support, ...
• AllegroGL (add-on to Allegro) - used for interfacing Allegro with OpenGL
• OpenGL - used for drawing
• zlib - used by the hpi module to uncompress some HPIs
• FMOD - used to read/play WAV,OGG,MP3,... files (needed by the sound engine)
• Lua - included in the src/lua dir, used for game scripting

About the code

the engine is subdivided in specialized parts:

• units engine --\
• particles engine |---- running in separate threads (synchronised, base on simulation time)
• weapons engine --/

each UNIT object can be locked using the cCriticalSection object it inherits from.
When you need to lock INGAME_UNITS and UNIT, lock UNIT first, otherwise you might encounter dead locks.

• terrain engine
• features engine
• sound/music engine // Using FMOD, this module only loads and play sounds preventing to play a sound too loud
• AI engine // every AI player runs in its own thread

Each engine part have its own module.
Each engine interact with others. Here is a complete description of these engines:

terrain engine

This engine draws the map on screen. The map is stored in a MAP object.
This object stores graphical data as well as height data and other data relative to the map(metal on surface, ...) The map is stored as a bloc array which contains 3D data and information about the terrain in that bloc. A bloc can be repeated multiple times so you don't waste memory. The map is represented as an array telling which bloc is where. another array stores data about which features are on the map, so you can list visible features to draw them faster. The terrain engine is responsible for detecting what is visible and what is not. When drawing an object on screen, we first check if it is on a visible bloc of the map.

units engine

This is where the game is simulated. It animate units with scripts (it's where there is the script interpreter), control their missions, make them move, draw units (and their shadows), make them interact with each other, ...
All units are stored in an array which isn't reallocated during the game. So units can be identified by a pointer since they won't be moved in this array. The array is subdivided in parts, one for each player, so it's easier to separate the units of a player from the others.

particle engine

Just tell it which particles you want to create and it will animate (physic simulation) them and draw them for you.
It simulates wind, gravity in order to render realistic smoke, fire, dust, explosions ...
Particles are stored in an array which is designed for physic simulation and then drawn as quads using an other array which is better suited for OpenGL's VERTEX_ARRAY.

weapons engine

Same thing as units but for weapons with a small difference: the weapon array may be reallocated during the game.

features engine

It draws every static object on the map: rocks, trees, corpses, ...
Everything is stored into an array but it can be a huge one, so there is another array used to store indexes of features which are on screen (computed by the terrain engine at rendering time) so you don't need to go through the entire feature array when you need to do something!! Features can be flat (sprites) or have a 3D model (from a 3do file or computed from a sprite!!).
Most sprites are drawn flat on the map but some are drawn multiple times as intersecting quads to render trees better. The engine can draw shadows but only for 3D models loaded from a 3do file because shadows cast from computed models really look ugly.

sound/music engine

It loads sound files on the fly and stores a copy into a cache to avoid repeatedly loads the same file. It uses FMOD to play sounds with 2D or 3D effects. It also plays OGG/MP3/... music files in the music dir. The file it plays depends on how the game is going (battle, building), for this it refers to the playlist which is a text file in the root dir. If the playlist file doesn't exist it creates one.

AI engine

Every AI player runs in its own thread. It acts 3 steps :

1. analyse the unit array
2. refresh unit's weights
3. give orders to its units
   Currently difficulty is set by modifying the speed at which the AI is analyzing the game and giving orders.