Take On Mars: Data Structure tutorial
Scripts and Files
First off, let’s start up the loader and extract the game data to a directory of our choice. This will allow us to see exactly what is in Take On Mars. The game’s pack files contain all game data including scripts and models.
Keep in mind that this only extracts the data and is not launch-able. You can place any of this data into a mod or addon.
Two script files are of particular interest, ‘script.c’ and ‘CCGame.c’. These two files are the core files loaded directly from the internal game engine.
script.c
The first, ‘script.c’, is loaded on game engine start, including when you start up Workbench, and contains core functions and entity definitions via includes.
CCGame.c
The latter script, ‘CCGame.c’, is loaded when the game mechanics are initialized, and contains extended entity functions and most importantly, the campaign, also via includes.
Modifying these two scripts allows you to change the entire game if desired, and can allow you to make a completely different type of game, be it Real-Time Strategy or First-Person Shooter, making Take On Mars a truly sandbox platform to build upon.
proto.h
The ‘proto.h’ script is also very important, containing the Script API function definitions from the engine. This is the first place to look when searching for all the functions that handle creating physics objects, dealing with them, and so on.
entities.xml
In addition to this, the ‘entities.xml’ file is used by the Game Editor in the Workbench editing suite to define the editable parameters of each entity type. This file is also loaded directly by the engine.
Scripts for entities, the free fly camera and vehicle configs are all located within the scripts/ folder. For example, the ‘entities.h’ file contains definitions of basic entities used by the game, such as the base ‘GameEntity’ definition from which all Take On Mars entities are parented. So to speak, this folder is the real ‘nuts-and-bolts’ of Take On Mars.
Directories
Vehicle configs are located in the scripts/entities/configs/vehicles/ folder, as text-editable .CFG files. Vehicle controller scripts, which handle the functionality of each vehicle, are located in the scripts/entities/controllers/ folder as text-editable .H files.
The controller scripts contain practically all functionality of individual vehicles. The afore-mentioned configs define individual parts of the vehicle, what model to use, their toughness, joints that bind them together and also which scripts to use.
These scripts then make the vehicle what it is, so a 6 wheeled rover is made to act as such using these controller scripts. This also means you can make an airship, airplane, or rocket ship as you see fit.
Translations
Next, strings are saved in an .XML file for each language and are located in the scripts/ folder as ‘strings_<LANGUAGE>.XML’. Please note though, that right now only the English language is correctly used. You will also notice many other texts in the file dating back to when the engine was used for Carrier Command: Gaea Mission. All Take On Mars texts have a prefix of ‘tkom_’.
Models
Models are stored as binarized .XOB files in the obj/ folder, which are exported from text-based .TXO files. The Workbench editing suite features a model viewer to allow viewing both .TXO and .XOB files, and allows exporting from .TXO to .XOB. The import process from the .FBX format to the .TXO format will be documented elsewhere, so for now let us move on to sounds.
Sound Files
Sound files may be stored as .WAV or .OGG, and are located in the sounds/ folder. Also note the .H text files directly in the sounds/ folder, which are the sound shader files. The ‘shaders2.h’ file in this folder is loaded directly by the engine, and contains includes for the other files in that folder.
Configuring sounds may be done in a text editor or in the Workbench editing suite using the Sound Editor. Settings will be covered in another chapter, now we will look at textures and material definitions.
Textures
Textures are stored as .TGA and .DDS files. Textures can be stored anywhere, but for organizational purposes Take On Mars has them separated between GUI textures and model textures.
Textures for models are usually stored in the same location as the .XOB model file and are also usually stored as .DDS to conserve disk space. Associated with model textures are also material definitions.
Materials
Models do not directly link to a texture file, but rather a material definition, sometimes referred to as a material shader. These shaders work with several textures at once, including normal maps, environment maps and so on, giving the artist maximum control over how his model is displayed in-game.
Similar to the way sounds are loaded, materials have a core file, ‘materials.h’ in the materials/ folder, which is loaded directly by the engine and other material files are included within.
GUI textures on the other hand are stored in the gui/ folder, and are usually stored as .TGA files.
The textures/ folder contains textures that are either used for the terrain or for particle and post-process effects, such as the thermal vision color bars.
Particle effects are stored as .PTC files in the particle/ folder and are not binarized, meaning they can be edited in a text editor if desired. That said particles also have their own editor in the Workbench editing suite.
Graphical User Interface (GUI) data is stored in the gui/ folder. Visual GUI layouts are stored as text-editable .LAYOUT files and feature their own GUI Layout Editor in the Workbench editing suite. Image sets used for icons and buttons are stored as .IMAGESET files with an associated .TGA image file, and also feature their own GUI Imageset Editor in Workbench.
Fonts
Game fonts are stored in the gui/fonts/ folder as binarized .FNT files with an associated .TGA or .DDS image file. These are created using a font generator tool, which will be covered elsewhere.
Animations
Animations for vehicles, characters and cameras are stored in the anm/ folder, which also contains bone definitions. Animations themselves are stored as binarized .ANM files, which are converted from non-binarized .TXA files.
Physics
Next, the physics/ folder contains physics material definitions, which define friction and restitution for different material types. It also contains ragdoll skeleton setups.
Cutscenes
The cutscenes/ folder contains cutscene files as .CUT. Cutscenes support custom camera animations, character and vehicle animations, queued sounds and so on, all that a classic cutscene should support. In Take On Mars this only really applies to the Mission Control room and the main menu, though in modifications you can do whatever you like.
Next up, the worldspat/ folder contains object pattern brush .PAT files, which allow ‘painting’ objects onto the terrain in Workbench. These are also created and edited using the Game editor in the Workbench editing suite.
Moving on, the worlds/ folder contains the actual location files as text-readable .ENT files. These are edited in the Game Editor in the Workbench editing suite, and contain the world’s rocks, terrain, grass, and so on. Objects specific to scenarios or the campaign are created in the in-game editor.
In the worlds/ folder you will also find the ‘sky.xml’ file, which contains individual sky presets. These may be modified in the Game Editor in Workbench, and may also be cloned, copied, or renamed in the Sky Preset Manager in the Worbench suite.
Additionally, you will also find text-editable .PLA files in the worlds/ folder, which are planetary definition files used for the 3D map in the Mission Control room, and define the model to be used, the camera offset and so on.
Some files are not stored in the game’s .PAK files, and are left unpacked directly in the game’s steam directory under <STEAM LOCATION>/SteamApps/Common/Take On Mars/. These are not packed due to an earlier technical limitation which has since been resolved, and will likely be packed in the future.
Here you will find the game’s scenario files in the Scenarios/ folder. Each scenario is stored as a text-editable .SCN file with an associated image .JPG image file. The Campaign/ subfolder contains the missions seen in the game’s locations when playing the Space Program mode.
Scenario files are searched for dynamically by the game’s scripts, so a new scenario is located automatically by the game.
Next, videos are stored as .WMV files in the videos/ folder, which is convenient as they may be viewed on a Windows PC outside the game as well.
The configlists/ folder contains lists for objects, vehicles, and so on. Each list is stored as a text-editable .CFGLIST file, which contains a path and name to each vehicle preset, object preset and so on in the game. These lists are searched for dynamically by the game’s scripts, so a new list is read automatically by the game.
The worlds/ folder here contains text-editable .LOC files for each game location. These are definition files for each location and define where on the relevant planetary body the location is, the reentry offset and velocity, the gravity on the location, the image to be used for the map, and so on.