GTAMods Wiki - User contributions [en]

RpGeometry

2011-04-20T16:50:42Z

Seggaeman: Ok "0 based" was redundant, but I feel the point that attribute and material index are the same thing is correct.

{{RW Section|Geometry|0x000F}}

'''Geometry''' is a container section used in [[model file|DFF files]] as child of a [[Geometry List (RW Section)|Geometry List]] section. The section itself does not store any data at all. All additional information get stored inside a [[Struct (RW Section)|struct section]] which directly follows this one as a child. ''Geometry'' is one of the most important sections inside a <code>.dff</code> model file. It stores geometry information for models (like the mesh and the texture maps).

== Structure ==

The structure differs for most files, but it always gets introduced by the following set of values:

2b - WORD - Flags (See [[Geometry (RW Section)#Flags|below]])
1b - BYTE - Number of UV coordinates used (GTA default is 1)
1b - BYTE - Unknown (usually 0 and 1 on PS2)
4b - DWORD - Triangle count
4b - DWORD - Vertex count
4b - DWORD - Frame count

For all [[RenderWare_binary_stream_file#Common_RW_Version_IDs|versions]] below '''3.4''' also some lightning color values are stored.

4b - DWORD - Ambient color (Represents an DirectX <code>D3DCOLOR</code> value {{ref|1}})
4b - DWORD - Diffuse color (Represents an DirectX <code>D3DCOLOR</code> value)
4b - DWORD - Specular color (Represents an DirectX <code>D3DCOLOR</code> value)

=== Flags ===

The following flags descripe the behaviour of the mesh during the rendering progress. Some of the flags indicate the existance of data inside the following file format.

{|{{Prettytable}} width="100%" class="collapsible"
!width="120px"|Flag
!width="25%"|Binary
!Description
|-
|<center>1</center>||<center><code>0000 0000 0000 0001</code></center>||Is [[wikipedia:Triangle_strip|triangle strip]] (if disabled it will be an triangle list)
|-
|<center>2</center>||<center><code>0000 0000 0000 0010</code></center>||Vertex translation (<code>D3DFVF_XYZ</code>)
|-
|<center>4</center>||<center><code>0000 0000 0000 0100</code></center>||Texture coordinates 1 (<code>D3DFVF_TEX1</code>)
|-
|<center>8</center>||<center><code>0000 0000 0000 1000</code></center>||Vertex colors (<code>D3DFVF_DIFFUSE</code>)
|-
|<center>16</center>||<center><code>0000 0000 0001 0000</code></center>||Store normals (<code>D3DFVF_NORMAL</code>)
|-
|<center>32</center>||<center><code>0000 0000 0010 0000</code></center>||Dynamic vertex lightning ''(?)''
|-
|<center>64</center>||<center><code>0000 0000 0100 0000</code></center>||Modulate material color
|-
|<center>128</center>||<center><code>0000 0000 1000 0000</code></center>||Texture coordinates 2 (<code>D3DFVF_TEX2</code>)
|}

All of those flags (except the first) are used to build up the ''flexible vertex format (FVF)'' {{ref|2}}.

=== Prelightning/Vertex colors ===

If '''flag 8''' is enabled vertex color information for each vertex get stored up next:

4b - DWORD - Vertex color (D3DCOLOR)

The default value is 0x00FFFFFF (representing non-transparent white).

With ''San Andreas'' Rockstar's engine is able to change the vertex colors for ingame nights. Therefor there is an [[List of RW section IDs#Rockstar.27s_Custom_Sections|custom section]] called [[Night Vertex Colors (RW Section)|Night Vertex Colors]]. This prevents the game from loading new models at different times and increments the performance of the engine. Previous games stored copies of the model with different prelightning information and defined it inside the [[TOBJ]] [[IDE]] section.

=== Texture/UV coordinates ===

If '''flag 4''' or '''128''' is set texture coordinates are following next. If both are set then the texture coordinates for the first texture of all vertices are listed before the texture coordinates for the second chanel of all vertices (By default no GTA game ever uses more than 1 UV coordinate at one time).

4b - FLOAT - Texture coordinate U
4b - FLOAT - Texture coordinate V

=== Indices/Attributes ===

The following array holds indices and attributes for each triangle. The number of indices is represented by the third multiple of the triangle count value. So for each triangle the following format gets used:

2b - WORD - Index of first vertex
2b - WORD - Index of second vertex
2b - WORD - Attribute for line/triangle
2b - WORD - Index of third vertex

The "Attribute" is the material index which appears again in the [[Bin Mesh PLG (RW Section)|Bin Mesh PLG]] section.
=== Bounding information ===

The bounding information are used to check weather the mesh is visible for the camera, or not. It only exists once per geometry section.

4b - FLOAT - Center X
4b - FLOAT - Center Y
4b - FLOAT - Center Z
4b - FLOAT - Radius of bounding sphere
4b - DWORD - Has position
4b - DWORD - Has normals

The central vector (<code>D3DXVECTOR3</code>) describes the center of the bounding sphere as an offset from the [[IPL|placement]] of the object inside the real world.

=== Vertex translation info ===

The number of vertices gets defined inside the geometry structure. If '''flag 2''' is set the translation information gets stored for each vertex as a <code>D3DXVECTOR3</code>:

4b - FLOAT - Position X
4b - FLOAT - Position Y
4b - FLOAT - Position Z

The position values are an offset relative to the mesh pivot.

=== Normals ===

In case '''flag 16''' is set the [[wikipedia:Surface_normal|normal vectors]] are the last part of the geometry data structure. They are also stored as a <code>D3DXVECTOR3</code> for each vertex:

4b - FLOAT - Direction X
4b - FLOAT - Direction Y
4b - FLOAT - Direction Z

== Child sections ==

* [[Material List (RW Section)|Material List]]

=== Extension ===

The [[Extension (RW Section)|extension]] of an geometry usually holds the following sections in the order they are listed in here:

* [[Bin Mesh PLG (RW Section)|Bin Mesh PLG]]
* [[Native Data PLG (RW Section)|Native Data PLG]] – (Only for consoles)
* [[Skin PLG (RW Section)|Skin PLG]]
* [[Mesh Extension (RW Section)|Mesh Extension]]
* [[Night Vertex Colors (RW Section)|Night Vertex Colors]]
* [[Morph PLG (RW Section)|Morph PLG]]
* [[2dfx (RW Section)|2dfx]]

== See also ==
* [[Geometry List (RW Section)|Geometry List]]
* [[RenderWare_binary_stream_file|RW file format specification]]

== References ==
{{Note|1}} * http://msdn.microsoft.com/en-us/library/bb172518%28VS.85%29.aspx<br>
{{Note|2}} * http://msdn.microsoft.com/en-us/library/bb172559%28VS.85%29.aspx

{{N|SA|VC}}
[[Category:GTA_3]]

RpGeometry

2011-03-23T19:50:19Z

Seggaeman:

{{RW Section|Geometry|0x000F}}

'''Geometry''' is a container section used in [[model file|DFF files]] as child of a [[Geometry List (RW Section)|Geometry List]] section. The section itself does not store any data at all. All additional information get stored inside a [[Struct (RW Section)|struct section]] which directly follows this one as a child. ''Geometry'' is one of the most important sections inside a <code>.dff</code> model file. It stores geometry information for models (like the mesh and the texture maps).

== Structure ==

The structure differs for most files, but it always gets introduced by the following set of values:

2b - WORD - Flags (See [[Geometry (RW Section)#Flags|below]])
1b - BYTE - Number of UV coordinates used (GTA default is 1)
1b - BYTE - Unknown (usually 0 and 1 on PS2)
4b - DWORD - Triangle count
4b - DWORD - Vertex count
4b - DWORD - Frame count

For all [[RenderWare_binary_stream_file#Common_RW_Version_IDs|versions]] below '''3.4''' also some lightning color values are stored.

4b - DWORD - Ambient color (Represents an DirectX <code>D3DCOLOR</code> value {{ref|1}})
4b - DWORD - Diffuse color (Represents an DirectX <code>D3DCOLOR</code> value)
4b - DWORD - Specular color (Represents an DirectX <code>D3DCOLOR</code> value)

=== Flags ===

The following flags descripe the behaviour of the mesh during the rendering progress. Some of the flags indicate the existance of data inside the following file format.

{|{{Prettytable}} width="100%" class="collapsible"
!width="120px"|Flag
!width="25%"|Binary
!Description
|-
|<center>1</center>||<center><code>0000 0000 0000 0001</code></center>||Is [[wikipedia:Triangle_strip|triangle strip]] (if disabled it will be an triangle list)
|-
|<center>2</center>||<center><code>0000 0000 0000 0010</code></center>||Vertex translation (<code>D3DFVF_XYZ</code>)
|-
|<center>4</center>||<center><code>0000 0000 0000 0100</code></center>||Texture coordinates 1 (<code>D3DFVF_TEX1</code>)
|-
|<center>8</center>||<center><code>0000 0000 0000 1000</code></center>||Vertex colors (<code>D3DFVF_DIFFUSE</code>)
|-
|<center>16</center>||<center><code>0000 0000 0001 0000</code></center>||Store normals (<code>D3DFVF_NORMAL</code>)
|-
|<center>32</center>||<center><code>0000 0000 0010 0000</code></center>||Dynamic vertex lightning ''(?)''
|-
|<center>64</center>||<center><code>0000 0000 0100 0000</code></center>||Modulate material color
|-
|<center>128</center>||<center><code>0000 0000 1000 0000</code></center>||Texture coordinates 2 (<code>D3DFVF_TEX2</code>)
|}

All of those flags (except the first) are used to build up the ''flexible vertex format (FVF)'' {{ref|2}}.

=== Prelightning/Vertex colors ===

If '''flag 8''' is enabled vertex color information for each vertex get stored up next:

4b - DWORD - Vertex color (D3DCOLOR)

The default value is 0x00FFFFFF (representing non-transparent white).

With ''San Andreas'' Rockstar's engine is able to change the vertex colors for ingame nights. Therefor there is an [[List of RW section IDs#Rockstar.27s_Custom_Sections|custom section]] called [[Night Vertex Colors (RW Section)|Night Vertex Colors]]. This prevents the game from loading new models at different times and increments the performance of the engine. Previous games stored copies of the model with different prelightning information and defined it inside the [[TOBJ]] [[IDE]] section.

=== Texture/UV coordinates ===

If '''flag 4''' or '''128''' is set texture coordinates are following next. If both are set then the texture coordinates for the first texture of all vertices are listed before the texture coordinates for the second chanel of all vertices (By default no GTA game ever uses more than 1 UV coordinate at one time).

4b - FLOAT - Texture coordinate U
4b - FLOAT - Texture coordinate V

=== Indices/Attributes ===

The following array holds indices and attributes for each triangle. The number of indices is represented by the third multiple of the triangle count value. So for each triangle the following format gets used:

2b - WORD - Index of first vertex
2b - WORD - Index of second vertex
2b - WORD - Attribute for line/triangle
2b - WORD - Index of third vertex
The "attribute" is the 0 based material index for that triangle.
=== Bounding information ===

The bounding information are used to check weather the mesh is visible for the camera, or not. It only exists once per geometry section.

4b - FLOAT - Center X
4b - FLOAT - Center Y
4b - FLOAT - Center Z
4b - FLOAT - Radius of bounding sphere
4b - DWORD - Has position
4b - DWORD - Has normals

The central vector (<code>D3DXVECTOR3</code>) describes the center of the bounding sphere as an offset from the [[IPL|placement]] of the object inside the real world.

=== Vertex translation info ===

The number of vertices gets defined inside the geometry structure. If '''flag 2''' is set the translation information gets stored for each vertex as a <code>D3DXVECTOR3</code>:

4b - FLOAT - Position X
4b - FLOAT - Position Y
4b - FLOAT - Position Z

The position values are an offset relative to the mesh pivot.

=== Normals ===

In case '''flag 16''' is set the [[wikipedia:Surface_normal|normal vectors]] are the last part of the geometry data structure. They are also stored as a <code>D3DXVECTOR3</code> for each vertex:

4b - FLOAT - Direction X
4b - FLOAT - Direction Y
4b - FLOAT - Direction Z

== Child sections ==

* [[Material List (RW Section)|Material List]]

=== Extension ===

The [[Extension (RW Section)|extension]] of an geometry usually holds the following sections in the order they are listed in here:

* [[Bin Mesh PLG (RW Section)|Bin Mesh PLG]]
* [[Native Data PLG (RW Section)|Native Data PLG]] – (Only for consoles)
* [[Skin PLG (RW Section)|Skin PLG]]
* [[Mesh Extension (RW Section)|Mesh Extension]]
* [[Night Vertex Colors (RW Section)|Night Vertex Colors]]
* [[Morph PLG (RW Section)|Morph PLG]]
* [[2dfx (RW Section)|2dfx]]

== See also ==
* [[Geometry List (RW Section)|Geometry List]]
* [[RenderWare_binary_stream_file|RW file format specification]]

== References ==
{{Note|1}} * http://msdn.microsoft.com/en-us/library/bb172518%28VS.85%29.aspx<br>
{{Note|2}} * http://msdn.microsoft.com/en-us/library/bb172559%28VS.85%29.aspx

{{N|SA|VC}}
[[Category:GTA_3]]

RpGeometry

2011-02-01T05:41:09Z

Seggaeman: /* Flags */ Modulate material color flag in wrong position.

{{RW Section|Geometry|0x000F}}

'''Geometry''' is a container section used in [[model file|DFF files]] as child of a [[Geometry List (RW Section)|Geometry List]] section. The section itself does not store any data at all. All additional information get stored inside a [[Struct (RW Section)|struct section]] which directly follows this one as a child. ''Geometry'' is one of the most important sections inside a <code>.dff</code> model file. It stores geometry information for models (like the mesh and the texture maps).

== Structure ==

The structure differs for most files, but it always gets introduced by the following set of values:

2b - WORD - Flags (See [[Geometry (RW Section)#Flags|below]])
1b - BYTE - Number of UV coordinates used (GTA default is 1)
1b - BYTE - Unknown (usually 0 and 1 on PS2)
4b - DWORD - Triangle count
4b - DWORD - Vertex count
4b - DWORD - Frame count

For all [[RenderWare_binary_stream_file#Common_RW_Version_IDs|versions]] below '''3.4''' also some lightning color values are stored.

4b - DWORD - Ambient color (Represents an DirectX <code>D3DCOLOR</code> value {{ref|1}})
4b - DWORD - Diffuse color (Represents an DirectX <code>D3DCOLOR</code> value)
4b - DWORD - Specular color (Represents an DirectX <code>D3DCOLOR</code> value)

=== Flags ===

The following flags descripe the behaviour of the mesh during the rendering progress. Some of the flags indicate the existance of data inside the following file format.

{|{{Prettytable}} width="100%" class="collapsible"
!width="120px"|Flag
!width="25%"|Binary
!Description
|-
|<center>1</center>||<center><code>0000 0000 0000 0001</code></center>||Is [[wikipedia:Triangle_strip|triangle strip]] (if disabled it will be an triangle list)
|-
|<center>2</center>||<center><code>0000 0000 0000 0010</code></center>||Vertex translation (<code>D3DFVF_XYZ</code>)
|-
|<center>4</center>||<center><code>0000 0000 0000 0100</code></center>||Texture coordinates 1 (<code>D3DFVF_TEX1</code>)
|-
|<center>8</center>||<center><code>0000 0000 0000 1000</code></center>||Vertex colors (<code>D3DFVF_DIFFUSE</code>)
|-
|<center>16</center>||<center><code>0000 0000 0001 0000</code></center>||Store normals (<code>D3DFVF_NORMAL</code>)
|-
|<center>32</center>||<center><code>0000 0000 0010 0000</code></center>||Dynamic vertex lightning ''(?)''
|-
|<center>64</center>||<center><code>0000 0000 0100 0000</code></center>||Modulate material color
|-
|<center>128</center>||<center><code>0000 0000 1000 0000</code></center>||Texture coordinates 2 (<code>D3DFVF_TEX2</code>)
|}

All of those flags (except the first) are used to build up the ''flexible vertex format (FVF)'' {{ref|2}}.

=== Prelightning/Vertex colors ===

If '''flag 8''' is enabled vertex color information for each vertex get stored up next:

4b - DWORD - Vertex color (D3DCOLOR)

The default value is 0x00FFFFFF (representing non-transparent white).

With ''San Andreas'' Rockstar's engine is able to change the vertex colors for ingame nights. Therefor there is an [[List of RW section IDs#Rockstar.27s_Custom_Sections|custom section]] called [[Night Vertex Colors (RW Section)|Night Vertex Colors]]. This prevents the game from loading new models at different times and increments the performance of the engine. Previous games stored copies of the model with different prelightning information and defined it inside the [[TOBJ]] [[IDE]] section.

=== Texture/UV coordinates ===

If '''flag 4''' or '''128''' is set texture coordinates are following next. If both are set then the texture coordinates for the first texture of all vertices are listed before the texture coordinates for the second chanel of all vertices (By default no GTA game ever uses more than 1 UV coordinate at one time).

4b - FLOAT - Texture coordinate U
4b - FLOAT - Texture coordinate V

=== Indices/Attributes ===

The following array holds indices and attributes for each triangle. The number of indices is represented by the third multiple of the triangle count value. So for each triangle the following format gets used:

2b - WORD - Index of first vertex
2b - WORD - Index of second vertex
2b - WORD - Attribute for line/triangle
2b - WORD - Index of third vertex

=== Bounding information ===

The bounding information are used to check weather the mesh is visible for the camera, or not. It only exists once per geometry section.

4b - FLOAT - Center X
4b - FLOAT - Center Y
4b - FLOAT - Center Z
4b - FLOAT - Radius of bounding sphere
4b - DWORD - Has position
4b - DWORD - Has normals

The central vector (<code>D3DXVECTOR3</code>) describes the center of the bounding sphere as an offset from the [[IPL|placement]] of the object inside the real world.

=== Vertex translation info ===

The number of vertices gets defined inside the geometry structure. If '''flag 2''' is set the translation information gets stored for each vertex as a <code>D3DXVECTOR3</code>:

4b - FLOAT - Position X
4b - FLOAT - Position Y
4b - FLOAT - Position Z

The position values are an offset relative to the mesh pivot.

=== Normals ===

In case '''flag 16''' is set the [[wikipedia:Surface_normal|normal vectors]] are the last part of the geometry data structure. They are also stored as a <code>D3DXVECTOR3</code> for each vertex:

4b - FLOAT - Direction X
4b - FLOAT - Direction Y
4b - FLOAT - Direction Z

== Child sections ==

* [[Material List (RW Section)|Material List]]

=== Extension ===

The [[Extension (RW Section)|extension]] of an geometry usually holds the following sections in the order they are listed in here:

* [[Bin Mesh PLG (RW Section)|Bin Mesh PLG]]
* [[Native Data PLG (RW Section)|Native Data PLG]] – (Only for consoles)
* [[Skin PLG (RW Section)|Skin PLG]]
* [[Mesh Extension (RW Section)|Mesh Extension]]
* [[Night Vertex Colors (RW Section)|Night Vertex Colors]]
* [[Morph PLG (RW Section)|Morph PLG]]
* [[2dfx (RW Section)|2dfx]]

== See also ==
* [[Geometry List (RW Section)|Geometry List]]
* [[RenderWare_binary_stream_file|RW file format specification]]

== References ==
{{Note|1}} * http://msdn.microsoft.com/en-us/library/bb172518%28VS.85%29.aspx<br>
{{Note|2}} * http://msdn.microsoft.com/en-us/library/bb172559%28VS.85%29.aspx

{{N|SA|VC}}
[[Category:GTA_3]]

Bin Mesh PLG (RW Section)

2011-01-20T10:10:09Z

Seggaeman:

{{RW Section|Bin Mesh PLG|0x50E}}
The '''Bin Mesh PLG''' section stores face data split according to material indices. It is typically stored inside the [[Extension_(RW_Section)|extension]] of a [[Geometry (RW Section)|geometry section]] and does not hold any child sections.

== Structure ==

4b - DWORD - Face type (Apparently always 1, representing a triangle strip)
4b - DWORD - Number of material splits
4b - DWORD - Number of faces

The number of material splits defines the size of an array which directly follows the structure above. The structure of the array elements (''TMaterialSplitData'') links the material split index to the vertices of the geometry:

4b - DWORD - Number of vertices
4b - DWORD - Material index
Xb - - Array of DWORDs, each entry representing an vertex index.
Array size gets defined by the number of vertices

Material and vertex indices are zero based.

== See also ==
* [[RenderWare_binary_stream_file|RW file format specification]]

{{N|SA|VC}}
[[Category:GTA_3]]

Bin Mesh PLG (RW Section)

2011-01-20T10:07:29Z

Seggaeman:

{{RW Section|Bin Mesh PLG|0x50E}}
The '''Bin Mesh PLG''' section stores face data split according to material indices. It is typically stored inside the [[Extension_(RW_Section)|extension]] of a [[Geometry (RW Section)|geometry section]] and does not hold any child sections.

== Structure ==

4b - DWORD - Face type (Apparently always 1, representing a triangle strip)
4b - DWORD - Number of material splits
4b - DWORD - Number of faces

The number of material splits defines the size of an array which directly follows the structure above. The structure of the array elements (''TMaterialSplitData'') links the material split index to the vertices of the geometry:

4b - DWORD - Number of vertices
4b - DWORD - Material index
Xb - - Array of DWORDs, each entry representing an vertex index. Array size gets defined by the number of vertices

Material and vertex indices are zero based.

== See also ==
* [[RenderWare_binary_stream_file|RW file format specification]]

{{N|SA|VC}}
[[Category:GTA_3]]

Bin Mesh PLG (RW Section)

2011-01-19T14:07:55Z

Seggaeman:

This section stores face data split according to material ID. Bin Mesh PLG has an extension section (ID 0x00000003) as its immediate parent and appears once in every geometry item.

Introduced as follows
SectionID: 0x0000500E (4 bytes)
Size of data: <size> (4 bytes, relative to after RW fileversion)
RW file version: <fileversion> (4 bytes)

Bin Mesh PLG (RW Section)

2011-01-19T14:07:35Z

Seggaeman:

Bin Mesh PLG (RW Section)

2011-01-19T14:06:45Z

Seggaeman:

Bin Mesh PLG (RW Section)

2011-01-19T14:05:29Z

Seggaeman: Created page with 'This section stores face data split according to material ID. Bin Mesh PLG has an extension section (ID 0x00000003) as its immediate parent and appears once in every geometry ite…'

This section stores face data split according to material ID. Bin Mesh PLG has an extension section (ID 0x00000003) as its immediate parent and appears once in every geometry item.

{| {{Introduced as follows:}}
| SectionID: 0x0000500E (4 bytes)
| Size of data: (4 bytes, relative to after RW fileversion)
| RW file version (4 bytes)
|}

Collision File

2010-12-31T06:17:47Z

Seggaeman:

All GTA3 games (GTA III, Vice City and San Andreas) have separate files for the visual and physical representations of their [[Wikipedia:Model (computer games)|models]]. '''Collision models''' are often simply an optimized equivalent of the visual model, reduced in poly count and complexity. The [[Wikipedia:game engine|game engine]] uses them for [[Wikipedia:Collision detection|collision]] and [[Wikipedia:Dynamical simulation|physics]] calculations. Unlike graphics meshes, they are comprised not only of triangles but also spheres and boxes, for which exist faster and more accurate collision algorithms.

One or more collision models are packaged to a '''collision file''', denoted by the [[Wikipedia:file extension |file extension]] <code>.col</code>.

Each collision model is identified by a name, which must be the same as the [[model file]] and the [[item definition]].

== Version Differences ==

The col format was first introduced with [[GTA 3]], referred to as ''version 1'' here. The game's successor [[Vice City]] used exactly the same format.

In the PS2 version of [[GTA San Andreas]], however, a new version was used (''version 2''), which was later updated for the PC and XBOX releases (''version 3'').

=== Feature Matrix ===

The following matrix is supposed to give an in-depth feature overview of the 3 known versions of the GTA collision file format.

{| border="0" cellspacing="4" align="center"
!Feature
!Version 1
!Version 2
!Version 3
|-
| colspan="4" |''Supported by games:''
|-
|'''GTA III'''||'''Y'''||N||N
|-
|'''GTA Vice City'''||'''Y'''||N||N
|-
|'''GTA San Andreas (PS2)'''||'''Y'''||'''Y'''||N
|-
|'''GTA San Andreas (PC/XBOX)'''||'''Y'''||'''Y'''||'''Y'''
|-
|colspan="4" | ''Geometric shapes:''
|-
|'''Collision spheres'''||'''Y'''||'''Y'''||'''Y'''
|-
|'''Collision boxes'''||'''Y'''||'''Y'''||'''Y'''
|-
|'''Collision mesh'''||'''Y'''||'''Y'''||'''Y'''
|-
|'''Face groups'''||N||'''Y'''||'''Y'''
|-
|'''Shadow mesh'''||N||N||'''Y'''
|-
|colspan="4" | ''Miscellaneous:''
|-
|'''Light intensity:'''||N||'''Y'''||'''Y'''
|-
|'''Data compression'''||N||'''Y'''||'''Y'''
|-
|'''Four character code'''||COLL||COL2||COL3
|}

=== Explanation ===

The main difference between the old version 1 format and the new version 2 and 3 formats is the reduced file size. Faces and vertices are only half as big, shrinking models without spheres and boxes to almost 50%.

Also, face groups have been introduced, which should speed up collision tests for large models, provided they are calculated properly.

Another new feature are the light intensity values, which are a simple but effective way to achieve realtime lighting. You can define a 1 byte lighting value per face, which causes characters and vehicles to change their brightness when they step onto the face. This is used to simulate darkness in places where the sun cannot reach, such as under buildings, etc.

And finally version 3 introduces a shadow mesh, which is used to create projected shadows. They only include the faces you want to cast a shadow (like bridges); spheres and boxes are not possible.

You can '''mix''' all formats within one collision file as you wish, just make sure the target game does support all of them (see matrix above).

== File Format ==

As mentioned above, the collision files are containers for one or more collision models. They do not have a header; models are stored linearly without any padding.

So basically, collision files are simply [[archive]]s of collision models.

=== Structures ===

The following data types and structures are used within this article:
* '''INT8/UINT8''' - signed/unsigned 8 bit integer ''(1 byte)''
* '''INT16/UINT16''' - signed/unsigned 16 bit integer ''(2 byte)''
* '''INT32/UINT32''' - signed/unsigned 32 bit integer ''(4 byte)''
* '''FLOAT''' - single precision floating point number ''(4 byte)''
* '''TVector''' - float[3] ''(12 byte)''

Some complex structures vary between the format versions.

<table width="100%" border="0" cellspacing="8">
<tr><th>Structure Name</th><th>Version 1</th><th>Version 2/3</th></tr>
<tr><td>
;TBounds: bounding objects (box & sphere)<br>''(40 byte)''
</td><td>
radius : float;
center : TVector;
min, max: TVector;
</td><td>
min, max: TVector;
center : TVector;
radius : float;
</td></tr>
<tr><td>
;TSurface: surface properties<br>''(4 byte)''
</td><td colspan="2">
material : uint8;
flag : uint8;
brightness : uint8;
light : uint8;
</td></tr>
<tr><td>
;TSphere: collision sphere<br>''(20 byte)''
</td><td>
radius : float;
center : TVector;
surface: TSurface;
</td><td>
center : TVector;
radius : float;
surface: TSurface;
</td></tr>
<tr><td>
;TBox: collision box<br>''(28 byte)''
</td><td colspan="2">
min, max: TVector;
surface : TSurface;
</td></tr>
<tr><td>
;TFaceGroup: face group (see below)<br>''(28 byte)''
</td><th>
(not used)
</th><td>
min, max: TVector;
StartFace,
EndFace : uint16;
</td></tr>
<tr><td>
;TVertex: collision mesh vertex<br>''(12 or 6 byte)''
</td><td>
float[3]
</td><td>
int16[3]
</td></tr><tr><td>
;TFace: collision mesh face<br>''(16 or 8 byte)''
</td><td>
a, b, c: uint32;
surface: TSurface;
</td><td>
a, b, c : uint16;
material: uint8;
light : uint8;
</td></tr>
</table>

* all boxes are axis-aligned

=== Header ===
<table width="100%" border="0" cellspacing="8"><tr><td>
char {4} - FourCC ("COLL", "COL2" or "COL3")
uint32 {4} - file size from after this value (so 8 byte less)
char {20} - collision model name
char {4} - unused, probably part of the name,
but could never be used since dir/img entries are only 24 byte
(and 4 byte are needed for the extension)
TBounds {40} - bounding objects, see above

if (Version >= 2) {
uint16 {2} - number of collision spheres
uint16 {2} - number of collision boxes
uint32 {4} - number of collision mesh faces
uint32 {4} - flags
uint32 {4} - offset collision spheres
uint32 {4} - offset collision boxes
uint32 {4} - unknown offset (0)
uint32 {4} - offset collision mesh vertices
uint32 {4} - offset collision mesh faces
uint32 {4} - unknown offset 2 (0)

if (Version = 3) {
uint32 {4} - number of shadow mesh faces
uint32 {4} - offset shadow mesh vertices
uint32 {4} - offset shadow mesh faces
}
}
</td></tr></table>

* All offsets in col 2/3 format are relative to after the fourcc, so file offset + 4.
* Col 2/3 format does not store the number of vertices. Normally you do not need that, since you would just add the vertex index to the offset in your pointer. But if you do need it, scan the faces for the largest index.

'''Flags:'''
* 2 - not empty (collision model has spheres or boxes or a mesh)
* 8 - has face groups (if not empty)
* 16 - has shadow mesh (col 3)
* apparently other flags are not used

=== Body ===
<table width="100%" border="0" cellspacing="8">
<tr><th>Version 1</th><th>Version 2/3</th></tr>
<tr><td>
uint32 {4} - number of col. spheres
TSphere[] {*} - col. sphere array

uint32 {4} - number of unk. data (0)

uint32 {4} - number of col. boxes
TBox[] {*} - col. box array

uint32 {4} - number of col. vertices
TVertex[] {*} - col. mesh vertex array

uint32 {4} - number of col. faces
TFace[] {*} - col. mesh face array
</td><td>
TSphere[] {*} - col. sphere array

TBox[] {*} - col. box array

TVertex[] {*} - col. mesh vertex array
char {2} - optional padding

FaceGroup[] {*} - col. mesh face groups
uint32 {4} - number of face groups

TFace[] {*} - col. mesh face array

TVertex[] {*} - shad. mesh vertex array
char {2} - optional padding
TFace[] {*} - shad. mesh face array
</td></tr>
</table>

* The unknown section was presumably planned to hold a set of lines, used for collisions with very thin objects (like railings). But this was never confirmed, nor is it used anywhere.
* The sequence of sections in the col 2/3 format as given above can be observed in every file sample. However, since there are offsets now, you could order them however you want.
* There is no offset to face groups, reading them is optional. To read them, go to the start of the face array, go back 4 byte, read the ammount of groups, and go back 28*GroupCount byte. But check the flag in the header for existance of face groups first.
* Vertex indices (a, b and c) in a TFace structure use a 0 based index. The same applies for StartFace and EndFace in TFaceGroup.
* The 2 byte padding after the vertex arrays in col 2/3 is used to provide a 4 byte alignment. It is present if the array's length leaves a rest when divided by 4, i.e. (VertexCount*6) mod 4 != 0.

== Annotations ==
=== Data Compression and Limits ===

In the col 2/3 format not only face indices take up half as much space (uint16 instead of uint32); also vertex coordinates are now stored as so-called [[Wikipedia:Fixed-point arithmetic|fixed-point numbers]].

To convert such an int16 number to a floating point number, simply '''divide it by 128.0'''.

But there is one major disadvantage you have to take care of: meshes are limited to dimensions of +/- 255.99 units on each axis. But this should be no problem, since objects bigger than that would defy the whole purpose of the streaming engine, and should never be used.

=== Face Groups ===

Faces in large col 2/3 meshes (more than 80 faces) are grouped by location, and get a bounding box. This way collision checks can be limited to a special area of interest, to speed them up significantly.

Some statistics: There is an minimum average of 13.8 faces per group, maximum is 50{{ref|1}}. On average there are 31.75 faces per group.

{{note|1}} In the grouping algorithm, a face count of > 50 is the criterion to split a group.

=== Shadow Mesh ===

The so-called "shadow mesh" introduced with version 3 is used to cast real-time shadows in GTA SA. Again, to save cpu time these are reduced to significant parts of the object, like bridges on map parts. Very important is that they '''always have to be closed!''' If there are holes in your mesh, you will get odd projection errors, with shadow triangles floating around.

== Tools ==

=== Version 1 only ===
* [[CollMaker]] [http://www.steve-m.com/downloads/tools/collmaker/] by [[User:Steve-m|Steve M.]] (2002)<br>''Very simple tool that creates single model collision files based on text cordinates as input, such as the text .x files.''
* [[CollEditor]] [http://www.steve-m.com/downloads/tools/colleditor/] by [[User:Steve-m|Steve M.]] (2003)<br>''The first 3D editor for collision files. Allowed simple modification and management of collision models. Not very user-friendly, though, and not bug-free.''
* [[Col IO]] [http://gtatools.com/pafiledb/pafiledb.php?action=file&id=16] by [[User:Delfi|Delfi]] (2004)<br>''Another 3D editor. Unlike CollEditor, this one allowes to drag spheres, boxes and vertices comfortably with the mouse. Mainly suited for vehicles and quite buggy.''

=== All versions ===
* [[KAMS]] [http://www.gtaforums.com/index.php?showtopic=218318] by [[User:Kam|Kam]] (2005)<br>''A collection of scripts for [[Wikipedia:3D Studio Max|3D Studio Max]], including one for import/export of collision files. Does not support face groups.''
* [[CollEditor II]] [http://www.steve-m.com/downloads/tools/colleditor2/] by [[User:Steve-m|Steve M.]] (2005)<br>''And yet another 3D editor, with many features.''

==See also==
* {{GTAF|291542|What's the use of collision spheres?}}
* {{Icon|4}} [[WBD-WBN]] - new format used in GTA IV

{{N|SA|VC}}
[[Category:3D File Formats]][[Category:GTA 3]]