Now that we have model and collision loading in place. Let’s put it all together and take a look at how the meshes are placed to create our beloved cities.

To get to that we need to understand the structure of the game files and how those contribute to the games map.

ℹ️ A lot of this info is based on the knowledge shared on gtamods.com

DAT

One of the first things the games load are the following dat files; default.dat and gta(game version).dat. These dat files are simple text files that tell the engine which file to load.

Let’s open up Vice City’s default.dat and go through the file step by step.

# 
# Load IDEs first, then the models and after that the IPLs
# 

The first couple of lines start with a #. This could be familiar to Godot devs as these are just comments. The engine ignores any line that starts with a #.

Let’s read a little bit further, the first non comment line is:

IDE DATA\DEFAULT.IDE

Now it starts to get interesting. So what does this line mean? We can split it up into two parts; IDE and DATA\DEFAULT.IDE. In this example IDE is the command that tells the engine to load an IDE file also known as Item DEfinition, DATA\DEFAULT.IDE is the relative path of the ide file that should be loaded. We’ll get back to IDE files a little bit later.

Next up we see the following lines (skipping the comments).

TEXDICTION MODELS\MISC.TXD
MODELFILE MODELS\GENERIC\AIR_VLO.DFF
COLFILE 0 MODELS\COLL\VEHICLES.COL

Again this tells the engine to load specific file types.

• TEXDICTION Loads a texture dictionary aka a collection of Textures.
• MODELFILE Loads a model
• COLFILE Loads a collision file.

That’s it for default.dat. Let’s also open gta.dat or in Vice City’s case gta_vc.dat.

This file is pretty similar to default.dat, it contains a bunch of IDE commands, but it does contain two new commands:

SPLASH loadsc2
IPL DATA\MAP.ZON

• SPLASH Switches the splash screen during loading. Fun fact: this only works on the console versions of the game.
• IPL Loads an IPL file also known as a Item PLacement. Again we’ll take a look at those specific files in a bit.

If we take a look at both GTA: III and SA there are a couple more commands that are not used in Vice City.

• IMG Loads an Image archive file
• MAPZONE Loads a zone file in GTA: III. Seems to have been replaced with a regular IPL file in the later games.

IDE

The Item Definition file contains as it name might give away; definitions of items. In all seriousness, the file defines the ID of a model, the TXD it uses and a bunch of other properties depending on the type of the item.

To clear things up, lets checkout default.ide, which is also the first file that got loaded by default.dat.

Again we start the file with a bunch of comments as indicated by #. We can probably skip this explanation next time ;), but do take a look at the comments in the file they contain useful info left by the devs.

Besides the comments, the structure of the file is slightly different from the .dat files we looked at previously. Instead of each line being a command that gets executed this file is split up into sections. Section starts are marked by specific keywords identifying the type of items in that section and the ending is marked by end.

With that out of the way lets have a look the file:

objs
# wheels
160, wheel_sport, generic, 2, 20, 70, 0
# Other entries
end

The objs keyword is the start marker of a section. In this case the Objects section. This section defines regular object aka models.

If we look at the first entry we see: 160, wheel_sport, generic, 2, 20, 70, 0. Lets break it down:

• 160 is the ID of the model, this is a unique ID that is used by the engine to reference this model
• wheel_sport is the name of the DFF (aka a model)
• generic is the name of the TXD (aka the texture archive)
• 2 the amount of meshes in this model
• 20 the draw distance of the first mesh
• 70 the draw distance of the second mesh
• 0 some flags that set special rendering options

So now if the engine is told to load model 160 it will know which model to use, what texture archive to apply and how to render it.

We can go very in depth into every section but for now I’ll give a short summary.

• hier Cutscene objects
• cars Vehicle definitions
• peds Pedestrian definitions

The next couple of sections are not found in default.ide but are used by the game in other ide files:

• tobj Timed objects, spawned only at specific times
• path Used to define paths for vehicles and pedestrians
• 2dfx 2D effects, like lights
• weap Weapon models
• anim Animated objects
• txdp Texture archive extensions

That’s it for the IDE file, lets see how these definitions are actually referenced by IPL files.

IPL

The Item Placement files uses the exact same format as IDE files. It’s a plain text file split up into sections.

If we open Vice City’s airport.ipl in a text editor you’ll see the following lines.

inst
865, ap_tower, 0, -1685.179443, -923.3638916, 13.48704815, 1, 1, 1, 0, 0, 0, 1
# More entries
end

Let’s break it down again.

The section marker is inst short for instance. This section describes which models should be placed where.

Each entry has a lot of properties: 865, ap_tower, 0, -1685.179443, -923.3638916, 13.48704815, 1, 1, 1, 0, 0, 0, 1

• 865 The ID as defined in IDE files
• ap_tower Model name (Not sure if this has any actual purpose as the model is also defined in the IDE)
• 0 The interior this model belongs to
• -1685.179443 The X position
• -923.3638916 The Y position
• 13.48704815 The Z position
• 1 The X scale
• 1 The Y scale
• 1 The Z scale
• 0 The X rotation (quaternion)
• 0 The Y rotation (quaternion)
• 0 The Z rotation (quaternion)
• 1 The W rotation (quaternion)

This is probably the most useful section of IPL files but lets list them all.

• cull Defines zones with some attributes
• pick Defines a pickup
• path Defines paths for vehicles
• occl Defines occlusion zones

The following sections are San Andreas only:

• grge Defines a garage
• enex Defines entry and exit markers for interiors
• cars Defines a parked car generator
• jump Defines a stunt jump
• tcyc Something related to the timecycle
• auzo Defines an audio zone

Next steps

With this knowledge of the IDE and IPL files we should already be able to create something that resembles a map!

We’ll get to the implementation in the next post.

With some basic model loading working (no worries we’ll get to the textures at some point!) it might be nice to look at something completely different; Collision!

What do I mean with collision?

The models we loaded up until now are only used for the visual representation of an object. The chair we loaded might look physical, but if someone would try to sit on it, they would fall through. The reason for this is that it’s lacking a physical model aka a collision model. A collision model defines the shape, and in case of GTA the material, of the model. We use the collision model to define the roads we drive on and the walls we bump into.

Why do we need separate collision models?

Physics are complex, even though we have amazing physics engines and our computers can compute millions of physic interactions per second, simulating everything using their visual representation would be impossible. The visual representation of a model is usually much more detailed than necessary for believable physics simulation.

Instead, physics of video games (and especially in the early 2000) used simplified shapes. Mostly a combination of (ordered by efficiency); spheres, boxes and basic meshes.

The collision file format

The collision format used by the GTA Trilogy has been documented at gtamods.com.

Short summary:

• Collision files contain multiple collision entries.
• Each collision entry can contain an array of Spheres, Boxes and a Mesh shapes.
• The shapes can reference a material which is hardcoded in the engine.

The ramp example

Let’s take a look at generic.col, this file is a collection of multiple col files into one. Also known as a coll archive. In our example we’ll focus on the entry ramp, this is simple collision model that uses all 3 types! A perfect example for this post.

The ramp exists out of 4 shapes:

• 2 Spheres
• 1 Box
• 1 Mesh shape

The spheres are used to cover the top of the pipes on the side. The box is used to cover the long pipe. And the mesh is used for the actual ramp.

Loading the collision data into Godot

Let’s start by creating a StaticBody3D, these are used for static objects like our ramp. As the name implies static bodies are not effected by other physics bodies, perfect for our static ramp.

A physics body like StaticBody3D needs one or multiple CollisionShape3D nodes, which define their shape using a Shape3D. The shapes we are interested in are: SphereShape3D, BoxShape3D and ConcavePolygonShape3D.

To create a StaticBody3D from our coll file all we need to do is convert our Spheres, Boxes and Meshes to Godot equivalents.

Spheres

Creating the SphereShape3D from our collision file data is the easiest. The data contains everything we need; a radius and a position.

Example code:

var collisionShape = new CollisionShape3D();

// Create the shape
var shape = new SphereShape3D();
shape.Radius = sphere.radius;

// Set the shape and update it's position according to the spheres center
collisionShape.Shape = shape;
collisionShape.Position = sphere.center;

As you can see our example uses 2 spheres to cover the top of the pipes:

Boxes

BoxShape3D requires a tiny bit more work to create compared to spheres, as the required data is defined slightly different in the coll file compared to Godots implementation.

The data we got:

• Min (the minimum coordinates of the box). Example: Vector3(-10, -10, 5)
• Max (the maximum coordinates of the box). Example: Vector3(10, 10, 10)

BoxShape3D data:

• Size (the size of the box). Example: Vector3(20, 20, 5)
• Position (center position of the box). Example: Vector3(0, 0, 7.5)

Converting this data is as simple as:

Vector3 size = Vector3.Subtract(max, min)
Vector3 position = (min + max) * 0.5f;

Example code:

var collisionShape = new CollisionShape3D(); 

// Create the shape
var shape = new BoxShape3D();
shape.Size = Vector3.Subtract(box.max, box.min);

// Set the shape and update it's position according to the calculated box center
collisionShape.Shape = shape;
collisionShape.Position = (box.min + box.max) * 0.5f;

A single box collider is used to cover the long pipe:

Mesh

A coll entry can contain a single mesh. The mesh is defined by vertices and faces.

We can convert the mesh to a ConcavePolygonShape3D

Example code:

var collisionShape = new CollisionShape3D();

// Create the mesh shape
var meshShape = new ConcavePolygonShape3D();

// Convert the face / vertex data to a triangle array
var triangleArray = new Vector3[faces.Length * 3];
for (int i = 0; i < faces.Length; i++)
{
    triangleArray[i * 3] = vertices[faces[i].a].ToVector3();
    triangleArray[i * 3 + 1] = vertices[faces[i].b].ToVector3();
    triangleArray[i * 3 + 2] = vertices[faces[i].c].ToVector3();
}

// Apply the triangle data to the meshShape
meshShape.Data = triangleArray;

// Set the shape
collisionShape.Shape = meshShape;

The actual ramp shape is defined using the mesh collider:

Final result

Below the full collision of the ramp:

In part 2 of this series we’ll take a look at slightly more complex models. First up we’ll take a look at a model that uses multiple geometries, this way we can see how the hierarchy is constructed.

Multi geometry model

Let’s take a look at the model SCHAIR.dff. This model is the chair used by Sonny in the intro cutscene of Vice City. This model can be found in the gta3.img archive, you’ll need an image editor to extract the model file from the archive.

If we print the RenderWare structure you can see that the tree is a bit bigger compared to the arrow.dff that we used in the previous part.

RwClump
├── RwFrameList
│   ├── RwExtension
│   │   ├── RwHAnimPlg
│   │   └── RwFrame
│   ├── RwExtension
│   │   ├── RwHAnimPlg
│   │   └── RwFrame
│   ├── RwExtension
│   │   ├── RwHAnimPlg
│   │   └── RwFrame
│   └── RwExtension
│       ├── RwHAnimPlg
│       └── RwFrame
├── RwGeometryList
│   ├── RwGeometry
│   │   ├── RwMaterialList
│   │   │   └── RwMaterial
│   │   │       ├── RwTexture
│   │   │       │   ├── RwString
│   │   │       │   ├── RwString
│   │   │       │   └── RwExtension
│   │   │       └── RwExtension
│   │   └── RwExtension
│   │       └── RwBinMeshPlg
│   └── RwGeometry
│       ├── RwMaterialList
│       │   └── RwMaterial
│       │       ├── RwTexture
│       │       │   ├── RwString
│       │       │   ├── RwString
│       │       │   └── RwExtension
│       │       └── RwExtension
│       └── RwExtension
│           └── RwBinMeshPlg
├── RwAtomic
│   └── RwExtension
├── RwAtomic
│   └── RwExtension
└── RwExtension

The main difference is the amount of frames (4) and geometries (2), accompanied by 2 atomic sections to match the geometry entries to a frame.

Let’s start with taking a look at the frame data inside the FrameList.

Frame 1

Name: "schair_dummy"
ParentIndex: -1

Frame 2

Name: "schair"
ParentIndex: 0

Frame 3

Name: "schrbot"
ParentIndex: 1

Frame 4

Name: "schrtop"
ParentIndex: 1

In this case schair_dummy is the root node which is located at index 0. The parent index is set to -1 which indicates it does not have a parent. schair on the other hand has a parent index of 0, which indicates that it’s parent is schair_dummy. Last but not least we have 2 frames called schrbot and schrtop (Sonny Chair Bottom and Sonny Chair Top) which have a parent index of 1 aka schair.

The hierarchy we end up with is:

schair_dummy
    └── schair
        ├── schrbot
        └── schrtop

If we use the same approach as we used in part 1 of this series, we expect the following, very similar, output hierarchy.

Node3D
└── schair_dummy
    └── schair
        ├── schrbot
        └── schrtop

And here it is schair in Godot.

Fun fact, GTA: III doesn’t make use of skinned meshes for their animated characters, but instead relies on the above technique to construct its models. So here is a little screenshot of Claude:

That’s it for now, we’ll get to Material and Skeleton loading in another part, but first we’ll make a little sidestep and checkout collision loading!

In this first part of the series we discuss model loading. Nothing more visual than rendering our first GTA model.

To load a GTA model we first need to understand the original engine this game used. The original trilogy was based on the RenderWare engine (RW from now on), an engine that was very popular during the time. Many games by different developers where created on this engine, think about titles like Burnout, Tony Hawks Pro Skater 3 and Bully. It was the Unreal Engine of that era.

Lucky for us this means a lot is known about the file formats used by RW based games. Entire tools and libraries where build to inspect the contents of RW files. One of which is called RwAnalyze, this is still one of the best tools (22 years old by now!) to get a grasp of the basic structure of RW files.

As you can see in the above screenshot a dff file is simply 3D data stored in a tree like structure.

An example

Let’s take a closer look at a pretty basic dff file. We can use Vice City’s arrow.dff which can be found in the /models/generic/ directory. This model has only a single mesh, no textures and is pretty much as basic as it gets.

ℹ️ You might notice that there are not that many dff files in the models directory, which might seem odd for a game with hundreds of models. This is because most models are packed into the gta3.img archive file. We’ll get to the details of that file in another part.

The structure

The following tree shows the structure of the dff file.

RwClump
├── RwFrameList
│   └── RwFrame
├── RwGeometryList
│   └── RwGeometry
│       ├── RwMaterialList
│       │   └── RwMaterial
│       ├── RwBinMeshPlg
│       └── RwMorphPlg
└── RwAtomic
    ├── RwParticlesPLG
    └── RwMatEffectsPlg

Let’s have a look at the sections and how they relate to Godot.

RwClump

A container of a frame hierarchy and 3D data. We could create something similar using a Node3D with child nodes.

RwFrameList

List of Frames.

RwFrame

A frame has a name, positioning data and a parent ID. Frames are used to build up the hierarchy of the model. Frames can be used to position geometry, dummies or bones from a skeleton. In Godot this is again similar to a Node3D.

In our case of arrow.dff this frame contains the name “arrow”.

RwGeometryList

List of Geometry

RwGeometry

The visual representation of the model. Contains the vertex, polygon and material data. The Godot equivalent of a Mesh.

RwMaterialList

List of materials

RwMaterial

Material definition, contains the texture name, colors, alpha name etc.

RwBinMeshPlg

Plugin that defines how the geometry is split by materials. Which vertices / polygons use which material. Similar to a Surface on a Mesh in Godot.

RwMorphPlg

I currently don’t support this in my parser, if we need it we’ll probably get to it at some point.

RwAtomic

An atomic matches geometries to a frame. Making it possible to create a hierarchy of geometry. We’ll need this info to setup the mesh / node hierarchy in Godot.

RwParticlesPLG I currently don’t support this in my parser, if we need it we’ll probably get to it at some point.

RwMatEffectsPlg

I currently don’t support this in my parser, if we need it we’ll probably get to it at some point.

Godot

If we take the above arrow.dff example and map that to Godot we can imagine this would end up something like:

Node3D
└── MeshInstance3D (arrow)

Meshes

The first step to create this scene is by converting all RwGeometry sections to a Godot Mesh. Godot offers multiple API’s to create meshes at runtime. In my case I ended up using ArrayMesh. By going through all material splits we can create Surfaces using the AddSurfaceFromArrays method and assign a Material to the Surface by using SurfaceSetMaterial

Hierarchy

Once all meshes and materials are created we have to reconstruct the hierarchy. For this we’ll use the RwFrameList and RwAtomic sections. When a frame is connected to a geometry as indicated by the RwAtomic section we can create a new MeshInstance3D and assign it the Mesh that we created from the geometry. In case no geometry is connected to the frame we’ll just create a simple Node3D node. We’ll hook those nodes up according to the parent / child information of the RwFrame.

The result

With some trial and error this is the result:

I hope you enjoyed this first part of the series. In the next part we’ll take a look at loading more complex models.

As mentioned in my last post (which I apparently posted over a year ago!) I’ve gotten interested in the awesome open source game engine Godot.

In the past year I’ve done some simple projects with Godot, but now it’s time to pick up something bigger. As you might know I’ve worked on a project called OASE in the past. This project aimed to create an Open Source implementation of the GTA Trilogy. It was able to load the map and some missions pretty decently, but it always felt I had to do everything from scratch, writing a graphics engine, an audio engine and all the other things that make up an engine. The engine became a big mess, had a lot of memory issues (in the current state it basically crashes after running for 30 seconds) and whenever I wanted to work on something I had to work my way through the spaghetti. It’s time to leave the OASE mess behind and create a new mess… in Godot.

The goal: Get the GTA Trilogy running in Godot.

Of-course we have multiple similar projects these days, one of which is a completely reverse engineered implementation, which is basically the real deal and nothing can beat that. This project is not meant as a perfect recreation of the trilogy, it’s meant as a learning exercise, sharing my journey towards implementing a full 3D open world game (by 2001 standards).

The plan

The idea is to share the steps I take to get to a playable result. A step can be anything from loading models, playing audio or scripting.

I’ll be using code I’ve written for OASE as a basis. This means that I’ve got parsers ready for most of the file formats. I might still go more in depth in the file formats when I use them in a post.

There are some things to keep in mind.

1. This is not going to be a tutorial. The post will merely give you some ideas of how the GTA internals work (or at least how I interpret them) and how this can be applied in a modern engine like Godot.
2. This won’t be a one to one implementation, the goal is to get something playable, this probably means this will end up as the “We got GTA at home” version of the trilogy.
3. There are currently no plans to open source this project.
4. There might not be a logical order in these posts, switching from one topic to another is how my brain works and stays interested.
5. Last but not least, this project won’t be vibe coded. I want this to be a learning experience.

With all that said, I hope you are as excited about this as I am!

Let the journey begin