AGS Game Build process (3.5.*) - adventuregamestudio/ags GitHub Wiki
Following document outlines the building process of an AGS game: source (project) data, final (engine's) data, and build steps between them.
Project data
Game.agf
Big XML file, contains main game data and some extras:
- General game properties
- Global game entities and logical assets (Characters, GUI, Inventory Items, Views, Dialogs, ...)
- Dialog script sources
- Script module references
- Audio clip references
- Sprite references
- Translation file references
- Runtime plugin references
- Editor plugin serialized data
- Default runtime config settings
Auto-generated script headers and modules
- _BuiltInScriptHeader.ash - contains API declaration. This file is atm always embedded into Editor exe (as of 3.5.0).
- _AutoGenerated.ash - generated from the game properties and entities. Contains their declaration that may be required for script. Only exist in program memory (as of 3.5.0).
- _GlobalVariables.ash/asc - generated from global variables component. Only exist in program memory (as of 3.5.0).
- Script headers provided by plugins. These are generated by plugins on demand by Editor and only exist in program memory (as of 3.5.0).
Script modules source files (ash/asc files, except roomXXX.asc)
These are text files which contain AGSScript source for global and custom script modules.
acsprset.spr and sprindex.dat
acsprset.spr is a binary file, contains array of bitmaps corresponding to game sprites. These are added when user imports a sprite in Editor. Bitmaps are optionally compressed using RLE algorithm (as of 3.5.0). sprindex.dat is a binary file, contains an auxiliary info about sprites: their dimensions and an offset table. This file is optional, if it's not present same index could be generated by parsing acsprset.spr.
IMPORTANT: as of 3.5.0 these files are used by both Editor and Engine alike.
roomXXX.crm files
Binary file, contains all the room related data:
- General room properties.
- Local room entities (Objects, Hotspots, Regions, Walkable Areas, Walk-behinds).
- Background bitmaps, compressed using LWZ algorithm.
- Compiled room script.
IMPORTANT: as of 3.5.0 thes files are used by both Editor and Engine, except for the script: Editor does not load compiled room script, but a script source (see below).
Room scripts source files (roomXXX.asc)
These are text files which contain AGSScript source for rooms.
TRS files
These are text files which contain translation table.
AudioCache folder
Contains audio files copied by the editor when you import audio file into the game. These are essentially copies of originals, with generated unique names in auNNNNNN.EXT format.
Speech folder
Contains files for character speech voice-over:
- Audio files with ABCDNNNN.EXT naming format (e.g. EGO5.OGG, CHAR4567.MP3)
- Voice-based lip sync files (*.PAM, *.dat)
Video files
Files with OGV and FLIC extensions. These are not edited by the Editor, and packed into game as is if found in the project root.
Engine data
game28.dta
Binary file contains main game data and some extras:
- General game properties
- Global game entities and logical assets (Characters, GUI, Inventory Items, Views, Dialogs, ...)
- Compiled global and module scripts
- Compiled dialog scripts
acsprset.spr and sprindex.dat
These are direct copies from the project data.
roomXXX.crm files
These are direct copies from the project data.
TRA files
Compiled translation tables.
Audio files
These are direct copies from the project data.
Voice-over audio files
These are direct copies from the project data.
Video files
OGV, FLIC are direct copies from the project data. MPG video files (playable only in Windows at the moment) are put directly into game data by user.
Runtime filesystem
In theory engine is capable of reading all the above files either directly from the disk, or from a CLIB package. In practice, as of now, its programmed to detect a presence of a game package with game28.dta inside before launching the game; but that may be changed in future.
CLIB package
CLIB package format allows to store multiple files packed into one or multiple packages, forming a "file library". The first package always contains a table of contents with full list of assets in the library, package index and offset for each asset.
Build steps
Following is a table that shows how the project data is converted into runtime data, and which procedures are necessary for that. This table splits process in most small steps, to make it easier to design standalone tools and build pipeline. Files that are part of either project source or final game data are marked with bold.
| Input | -> | Output | Comments/Tool |
|---|---|---|---|
| Game.agf | Parse XML, write binary data | game28.dta | |
| Game.agf | Parse XML, generate | _AutoGenerated.ash | agfexport autoash |
| Game.agf | Parse XML, generate | _GlobalVariables.ash | agfexport glvar |
| Game.agf | Parse XML, generate | _GlobalVariables.asc | agfexport glvar |
| Game.agf | Parse XML | List of script modules | agfexport script-list |
| Game.agf | Parse XML | List of image files | |
| Game.agf | Parse XML | List of audio files | |
| Game.agf | Parse XMLConvert dialog scripts to AGSScript | __DialogScripts.asc | agf2dlgasc |
| EDITOR | Query plugins | Plugin's ash-s | |
| _BuiltInScriptHeader.ash_AutoGenerated.ash_GlobalVariables.ashAll Plugins' ash | Merge | Internal script header | |
| Any ascInternal script headerList of script modulesScript module ash-s | Merge | Prepared script | |
| Any Prepared script | Preprocessor | Preprocessed script | agscc |
| Any Preprocessed script | Compiler | Compiled script (bytecode) | agscc |
| Compiled global scriptCompiled modulesCompiled Dialog script | Write binary data | game28.dta | not needed in 3.6.X |
| Compiled roomXXX script | Write binary data | roomXXX.crm | not needed in 3.6.X |
| Image filesList of image files | Write bitmaps into sprite file | acsprset.spr | |
| acsprset.spr | Parse, write index | sprindex.dat | |
| Game.agfAll roomXXX.crmAll asc | Parse XMLRead room dataParse ascwrite | Any TRS | |
| Any TRS | Parse, write binary data | TRA | trac |
| game28.dtaAny roomXXX.crmAny TRSAny WFN/TTFAny OGV | Package CLIB | game.ags | agspak |
| Audio filesList of audio files | Copy files | AudioCache | |
| AudioCacheList of audio files(?) | Package CLIB | audio.vox | agspak |
| Speech folder | Package CLIB | speech.vox | agspak |