Using GTATools

This page aims to provide a short introduction to using gtatools.

Note that gtatools has currently no stable API, so parts might be changed drastically, be removed or be rewritten at any time. This is because I don't always know where the project is going to go next, and sometimes new features can only be added by changing internals of the engine. If you want to use gtatools, you should either stick to a specific revision, or be prepared to change your code a lot.

The GTATools Programs

Apart from the core libraries, gtatools comes with a few programs.

The command-line programs gtaimg and gtatxd are utilities for working with IMG and TXD archives. Both utilities support reading the files. gtaimg also has experimental writing support. gtaimg can list, extract, append and remove IMG archive entries, and create IMG archives. gtatxd can list textures inside TXD archives and extract them as raw data or PNG files.

You can run gtaimg --help for instructions on how to use the program. The same goes for gtatxd.

The command-line programs nxcommon-test and gtaformats-test provide some automated unit tests for the libnxcommon and libgtaformats libraries. They still only test a few parts of these libraries. You can run them with the option --nxcommon-test-help or --gtaformats-test-help respectively to see how to use them.

gtatools-gui is a GUI program based on Qt that can display all kinds of GTA files. It can e.g. render DFF files, show textures inside TXD files, display RWBS files (DFF and TXD) low-level using a section tree and hex editor, render IFP animations on a specific mesh and other stuff. It can also display IMG files as if they were directories. It is mainly used for playing around with files and debugging the engine, and will frequently crash, so beware. Currently, it works (well, if it works) by setting up "profiles" for specific game installations in the settings. This way, you can e.g. switch between San Andreas and Vice City, or different installations of the same game.

gtatools-test is a highly chaotic prototyping program and the main program that I use for testing the engine. It does whatever I currently want to test, and can serve as a demo tool for the rendering capabilities of the engine. It runs off a configuration file called config.xml which you need to place in either the directory the executable is found in, or the directory it is running from (working directory). You can find an example config.xml here.


libnxcommon is not directly part of gtatools, but kinda maintained along with it. I use it for my other projects, too, and it is meant to contain some general-purpose utility classes and functions as well as some platform abstraction layers. I like to think of it as my personal extended C++ standard library. Many classes (like CString or File) are heavily used throughout gtatools.


libgtaformats is one of the two core libraries of gtatools, and represents the lower-end functionality. It contains all the format loaders for the GTA formats that gtatools supports. You can use it to load a DFF file into a C++ class structure that you can use to do whatever you want for example, like converting it to another mesh file format. You can use it to read textures from TXD archives and display or extract them. You can traverse IMG archives and extract files from them. All kinds of weird and wonderful stuff. It has some experimental writing support for IMG, TXD and RWBS (the low-level format of DFF/TXD) files.

I have written a small example program that lists all files inside the gta3.img file of a GTA game and extracts the first file from it. You might use it to test whether your gtatools build is working. Just change the GTA_ROOT_PATH define to the root of your game.

On my system, I would use the following command to compile the test program:

    g++ -fPIC --std=c++11 -I/home/alemariusnexus/Qt/5.3/gcc_64/include -I/home/alemariusnexus/gtatools-install/include -L/home/alemariusnexus/gtatools-install/lib -o imgtest imgtest.cpp -lgtaformats -lnxcommon
Be sure to specify library and include file search paths to all libraries using -I and -L. The option --std=c++11 is also necessary, because some C++11 features are used in gtatools' headers.

If you want to know more about using it, look at the header files in the format subdirectories. You can also look at the source code of the gtaimg / gtatxd command-line programs for examples on IMG and TXD, at the source code of libgta for its usage inside the engine (like going from a DFF file to a renderable mesh in OpenGL), or at the source code of the format subdirectories of gtatools-gui for using it to display all kinds of GTA file formats.


"Wow. That is some messed-up and convoluted library", I hear you say. That's true, because I don't really know where that one is going. It is built upon the features that libgtaformats provides and implements the engine of GTATools. It is roughly made up of the following parts:

libgta needs quite a modern graphics card to run currently. You will definitely need OpenGL 3.X. 3.1 may or may not work, but I recommend at least 3.2. Specifically, this is why the open-source GPU drivers on Linux do not work right now, because they only provide OpenGL 3.0. This requirement could generally be a bit lower, but OpenGL 2.x can only be supported with some features disabled or some very sinister trickery, and 1.x is definitely not enough, because I'm using shaders all over the place.

I can't really give usage instructions for libgta, because it changes so much. If you think you can take the pain and want to try using it in your own program, you might want to look at the source code of gtatools-test for an example of how to use it. Some parts of gtatools-gui's code might also be interesting, especially the DFF format subdirectory, and the IFPAnimationViewer stuff which use libgta to render models and animations.


Here's a list of things that might go wrong and how to deal with them: