Difference between revisions of "Collision File"

From GTAMods Wiki
Jump to navigation Jump to search
(link to col sphere explanation)
m (Coloured matrix for readability)
 
(29 intermediate revisions by 8 users not shown)
Line 1: Line 1:
All GTA3 games (III, VC, SA) 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.
+
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 ]] ".col".
+
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]].
 
Each collision model is identified by a name, which must be the same as the [[model file]] and the [[item definition]].
 
  
 
== Version Differences ==
 
== Version Differences ==
  
The col format was first introduced with [[:category:GTA 3|GTA 3]], referred to as ''version 1'' here. The game's successor [[:category:GTA_VC|Vice City]] used exactly the same format.
+
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 [[:category:GTA_SA|GTA: San Andreas]], however, a new version was used (''version 2''), which was later updated for the PC and XBOX releases (''version 3'').
+
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 ===
 
=== 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.
+
The following matrix is supposed to give an in-depth feature overview of the 4 known versions of the GTA collision file format.
  
<table border="0" cellspacing="4" align="center">
+
{| border="0" cellspacing="4" align="center"
<tr><th>Feature</th><th>Version 1</th><th>Version 2</th><th>Version 3</th></tr>
+
!Feature
<tr><td colspan="4">''Supported by games:''</td></tr>
+
!Version 1
<tr><td>'''GTA III'''</td><th>Y</th><th>N</th><th>N</th></tr>
+
!Version 2
<tr><td>'''GTA: Vice City'''</td><th>Y</th><th>N</th><th>N</th></tr>
+
!Version 3
<tr><td>'''GTA: San Andreas (PS2)'''</td><th>Y</th><th>Y</th><th>N</th></tr>
+
!Version 4
<tr><td>'''GTA: San Andreas (PC/XBOX)'''</td><th>Y</th><th>Y</th><th>Y</th></tr>
+
|-
<tr><td colspan="4">''Geometric shapes:''</td></tr>
+
| colspan="4" |''Supported by games:''
<tr><td>'''Collision spheres'''</td><th>Y</th><th>Y</th><th>Y</th></tr>
+
|-
<tr><td>'''Collision boxes'''</td><th>Y</th><th>Y</th><th>Y</th></tr>
+
|'''GTA III'''||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkred">N</span>||<span style="color:darkred">N</span>||<span style="color:darkred">N</span>
<tr><td>'''Collision mesh'''</td><th>Y</th><th>Y</th><th>Y</th></tr>
+
|-
<tr><td>'''Face groups'''</td><th>N</th><th>Y</th><th>Y</th></tr>
+
|'''GTA Vice City'''||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkred">N</span>||<span style="color:darkred">N</span>||<span style="color:darkred">N</span>
<tr><td>'''Shadow mesh'''</td><th>N</th><th>N</th><th>Y</th></tr>
+
|-
<tr><td colspan="4">''Miscellaneous:''</td></tr>
+
|'''GTA San Andreas (PS2)'''||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkred">N</span>||<span style="color:darkred">N</span>
<tr><td>'''Light intensity:'''</td><th>N</th><th>Y</th><th>Y</th></tr>
+
|-
<tr><td>'''Data compression'''</td><th>N</th><th>Y</th><th>Y</th></tr>
+
|'''GTA San Andreas (PC/XBOX)'''||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>
<tr><td>'''Four character code'''</td><th>COLL</th><th>COL2</th><th>COL3</th></tr>
+
|-
</table>
+
|colspan="4" | ''Geometric shapes:''
 +
|-
 +
|'''Collision spheres'''||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>
 +
|-
 +
|'''Collision boxes'''||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>
 +
|-
 +
|'''Collision lines'''||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>
 +
|-
 +
|'''Collision cones'''||<span style="color:darkred">N</span>||<span style="color:darkred">N</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>
 +
|-
 +
|'''Collision mesh'''||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>
 +
|-
 +
|'''Face groups'''||<span style="color:darkred">N</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>
 +
|-
 +
|'''Shadow mesh'''||<span style="color:darkred">N</span>||<span style="color:darkred">N</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>
 +
|-
 +
|colspan="4" | ''Miscellaneous:''
 +
|-
 +
|'''Light intensity:'''||<span style="color:darkred">N</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>
 +
|-
 +
|'''Data compression'''||<span style="color:darkred">N</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkgreen">'''Y'''</span>
 +
|-
 +
|'''Clump collision'''||<span style="color:darkred">N</span>||<span style="color:darkred">N</span>||<span style="color:darkgreen">'''Y'''</span>||<span style="color:darkred">N</span>
 +
|-
 +
|'''Four character code'''||COLL||COL2||COL3||COL4
 +
|}
  
 
=== Explanation ===
 
=== Explanation ===
Line 41: Line 65:
 
Also, face groups have been introduced, which should speed up collision tests for large models, provided they are calculated properly.
 
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 around realtime lighting. You can define a 1 byte lighting value per face, which causes characters and vehicles to change their brightness. This is used to simulate shadows and dark areas.
+
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 created projected shadows. They only include the faces you want to cast a shadow (like bridges); spheres and boxes are not possible.
+
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).
 
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).
Line 51: Line 75:
 
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.
 
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 arrays of collision models.
+
So basically, collision files are simply [[archive]]s of collision models.
  
 
=== Structures ===
 
=== Structures ===
Line 61: Line 85:
 
* '''FLOAT''' - single precision floating point number ''(4 byte)''
 
* '''FLOAT''' - single precision floating point number ''(4 byte)''
 
* '''TVector''' - float[3] ''(12 byte)''
 
* '''TVector''' - float[3] ''(12 byte)''
 
  
 
Some complex structures vary between the format versions.
 
Some complex structures vary between the format versions.
Line 81: Line 104:
 
;TSurface: surface properties<br>''(4 byte)''
 
;TSurface: surface properties<br>''(4 byte)''
 
</td><td colspan="2">
 
</td><td colspan="2">
  material: uint8;
+
  material   : uint8;
  flag   : uint8;
+
  flag       : uint8;
  unknown : uint8;
+
  brightness : uint8;
  light   : uint8;
+
  light     : uint8;
 
</td></tr>
 
</td></tr>
 
<tr><td>
 
<tr><td>
Line 131: Line 154:
  
 
* all boxes are axis-aligned
 
* all boxes are axis-aligned
 
  
 
=== Header ===
 
=== Header ===
Line 137: Line 159:
 
  char {4}        - FourCC ("COLL", "COL2" or "COL3")
 
  char {4}        - FourCC ("COLL", "COL2" or "COL3")
 
  uint32 {4}      - file size from after this value (so 8 byte less)
 
  uint32 {4}      - file size from after this value (so 8 byte less)
  char {20}      - collision model name
+
  char {22}      - collision model name
  char {4}       - unused, probably part of the name,
+
  short {2}       - model id to apply col to (0-19999)
                   but could never be used since dir/img entries are only 24 byte
+
                   if not valid (i.e. name of target model does
                   (and 4 byte are needed for the extension)
+
                   not match), name is used
 
  TBounds {40}    - bounding objects, see above
 
  TBounds {40}    - bounding objects, see above
 
   
 
   
Line 146: Line 168:
 
   uint16 {2}    - number of collision spheres
 
   uint16 {2}    - number of collision spheres
 
   uint16 {2}    - number of collision boxes
 
   uint16 {2}    - number of collision boxes
   uint32 {4}    - number of collision mesh faces
+
   uint16 {2}    - number of collision mesh faces
 +
  uint8  {1}    - number of collision lines (or cones)
 +
  uint8  {1}    - unused (padding)
 
   uint32 {4}    - flags
 
   uint32 {4}    - flags
 
   uint32 {4}    - offset collision spheres
 
   uint32 {4}    - offset collision spheres
 
   uint32 {4}    - offset collision boxes
 
   uint32 {4}    - offset collision boxes
   uint32 {4}    - unknown offset (0)
+
   uint32 {4}    - offset collision lines (or cones)
 
   uint32 {4}    - offset collision mesh vertices
 
   uint32 {4}    - offset collision mesh vertices
   uint32 {4}    - offset collision mesh faces
+
   uint32 {4}    - offset collision mesh faces (triangles)
   uint32 {4}    - unknown offset 2 (0)
+
   uint32 {4}    - offset triangle planes
 
   
 
   
   if (Version = 3) {
+
   if (Version >= 3) {
 
     uint32 {4}  - number of shadow mesh faces
 
     uint32 {4}  - number of shadow mesh faces
 
     uint32 {4}  - offset shadow mesh vertices
 
     uint32 {4}  - offset shadow mesh vertices
 
     uint32 {4}  - offset shadow mesh faces
 
     uint32 {4}  - offset shadow mesh faces
 +
  }
 +
  if (Version == 4) {
 +
    uint32 {4}  - unknown value (unused)
 
   }
 
   }
 
  }
 
  }
 
</td></tr></table>
 
</td></tr></table>
  
* All offsets in col 2/3 format are relative to after the fourcc, so file offset + 4.
+
* All offsets in col 2/3/4 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.
+
* Col 2/3/4 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:'''
 
'''Flags:'''
 +
* 1 - collision uses cones instead of lines (flag forced to false by engine upon loading)
 
* 2 - not empty (collision model has spheres or boxes or a mesh)
 
* 2 - not empty (collision model has spheres or boxes or a mesh)
 
* 8 - has face groups (if not empty)
 
* 8 - has face groups (if not empty)
Line 212: Line 240:
 
* 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.
 
* 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.
 
* 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.
 
* 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 ==
 
== Annotations ==
Line 219: Line 246:
 
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]].
 
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'''.
+
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.
 
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.
Line 227: Line 254:
 
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.
 
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<sup>1</sup>. On average there are 31.75 faces per group.
+
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.
  
<sup>1</sup> In the grouping algorithm, a face count of > 50 is the criterion to split a group.
+
{{note|1}} In the grouping algorithm, a face count of > 50 is the criterion to split a group.
  
 
=== Shadow Mesh ===
 
=== Shadow Mesh ===
Line 235: Line 262:
 
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.
 
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.
  
 +
=== Limits ===
 +
*Number of vertices - 32767
 +
*Number of faces - 32767
 +
*Vertex position - (-256.0; 256.0) on each axis
 +
The game may also crash if there's too many face groups (more than 1k)
 +
 +
== SFX and particles ==
 +
Interacting with different materials can produce different sound and particle effects. The association between [[SFX]] and particles with material are all [[hardcoded]].
 +
 +
=== GTA III ===
 +
{|class="wikitable sortable"
 +
! Value ||Material ||Gun shell drop{{ref|2}} ||Footstep{{ref|3}} ||Vehicle skidding{{ref|4}}
 +
|-
 +
|0 ||||hard ||32-36 ||19
 +
|-
 +
|1 ||||hard ||32-36 ||19
 +
|-
 +
|2 ||grass ||soft ||37-41 ||158
 +
|-
 +
|3 ||dirt ||soft ||42-46 ||20
 +
|-
 +
|4 ||mud ||soft ||42-46 ||20
 +
|-
 +
|5 ||pavement ||hard ||32-36 ||19
 +
|-
 +
|6 ||metal ||hard ||52-56 ||19
 +
|-
 +
|7 ||||hard ||32-36 ||19
 +
|-
 +
|8 ||||soft ||32-36 ||19
 +
|-
 +
|9 ||metal ||hard ||52-56 ||19
 +
|-
 +
|10 ||metal ||hard ||52-56 ||19
 +
|-
 +
|11 ||metal ||hard ||52-56 ||19
 +
|-
 +
|12 ||metal ||hard ||52-56 ||19
 +
|-
 +
|13 ||metal ||hard ||52-56 ||19
 +
|-
 +
|14 ||metal ||hard ||52-56 ||19
 +
|-
 +
|15 ||metal ||hard ||52-56 ||19
 +
|-
 +
|16 ||metal ||hard ||52-56 ||19
 +
|-
 +
|17 ||||soft ||32-36 ||19
 +
|-
 +
|18 ||sand ||soft ||61-64 ||20
 +
|-
 +
|19 ||water ||- ||57-60 ||20
 +
|-
 +
|20 ||wood ||hard ||47-51 ||19
 +
|-
 +
|21 ||wood ||hard ||47-51 ||19
 +
|-
 +
|22 ||wood ||hard ||47-51 ||19
 +
|-
 +
|23 ||||soft ||32-36 ||19
 +
|-
 +
|24 ||||hard ||32-36 ||19
 +
|-
 +
|25 ||hedge ||soft ||131-135 ||158
 +
|-
 +
|26 ||stone ||hard ||32-36 ||19
 +
|-
 +
|27 ||metal ||hard ||52-56 ||19
 +
|-
 +
|28 ||metal ||hard ||52-56 ||19
 +
|}
 +
 +
For III v1.0:
 +
<ol start="2">
 +
<li>{{note|2}} Array starts at 0x609274. When a character fires a weapon, some weapons produce gun shells that can be seen ejecting from the weapon and falling to the ground. The sound it plays depends on what material the character is standing on. There are three types of landing sounds used: hard, soft, and none. Hard shell drops use SFX 167 and soft ones use SFX 168.</li>
 +
<li>{{note|3}} Array starts at 0x6077EC. Each footstep characters make creates a sound. These values are associated with an entry in the SFX file. The game chooses an SFX to play at random within that range.</li>
 +
<li>{{note|4}} Array starts at 0x607428. Cars can skid across the ground and create a sound. These values are associated with an entry in the SFX file.</li>
 +
</ol>
 +
 +
=== Vice City ===
 +
{| class="wikitable sortable"
 +
! Value || Material || Gun shell drop{{ref|5}} || Footstep{{ref|6}} || Vehicle skid{{ref|7}} ||Vehicle scrape{{ref|8}} || Foot dust{{ref|9}}
 +
|-
 +
|0 ||||hard ||42-46 ||25 ||144 ||&#x2717;
 +
|-
 +
|1 ||||hard ||42-46 ||25 ||144 ||&#x2713;
 +
|-
 +
|2 ||grass ||soft ||496-500 ||154 ||154 ||&#x2717;
 +
|-
 +
|3 ||dirt ||soft ||501-505 ||26 ||26 ||&#x2713;
 +
|-
 +
|4 ||mud ||soft ||501-505 ||26 ||26 ||&#x2717;
 +
|-
 +
|5 ||pavement ||hard ||42-46 ||25 ||144 ||&#x2713;
 +
|-
 +
|6 ||metal ||hard ||511-515 ||25 ||144 ||&#x2717;
 +
|-
 +
|7 ||glass ||hard ||42-46 ||25 ||144 ||&#x2717;
 +
|-
 +
|8 ||||soft ||42-46 ||25 ||144 ||&#x2717;
 +
|-
 +
|9 ||metal door ||hard ||511-515 ||25 ||144 ||&#x2717;
 +
|-
 +
|10 ||metal ||hard ||511-515 ||25 ||144 ||&#x2717;
 +
|-
 +
|11 ||metal ||hard ||511-515 ||25 ||144 ||&#x2717;
 +
|-
 +
|12 ||metal ||hard ||511-515 ||25 ||144 ||&#x2717;
 +
|-
 +
|13 ||metal ||hard ||511-515 ||25 ||144 ||&#x2717;
 +
|-
 +
|14 ||metal ||hard ||511-515 ||25 ||144 ||&#x2717;
 +
|-
 +
|15 ||metal ||hard ||511-515 ||25 ||144 ||&#x2717;
 +
|-
 +
|16 ||metal fence ||hard ||511-515 ||25 ||144 ||&#x2717;
 +
|-
 +
|17 ||||soft ||42-46 ||25 ||- ||&#x2717;
 +
|-
 +
|18 ||sand ||soft ||520-523 ||26 ||26 ||&#x2713;
 +
|-
 +
|19 ||water || - ||516 ||26 ||316 ||&#x2717;
 +
|-
 +
|20 ||wood ||hard ||506-510 ||25 ||144 ||&#x2717;
 +
|-
 +
|21 ||wood box ||hard ||506-510 ||25 ||144 ||&#x2717;
 +
|-
 +
|22 ||wood plank ||hard ||506-510 ||25 ||144 ||&#x2717;
 +
|-
 +
|23 ||tire ||soft ||42-46 ||25 ||144 ||&#x2717;
 +
|-
 +
|24 ||||hard ||42-46 ||25 ||144 ||&#x2717;
 +
|-
 +
|25 ||hedge ||soft ||127-131 ||154 ||154 ||&#x2717;
 +
|-
 +
|26 ||stone ||hard ||42-46 ||25 ||144 ||&#x2717;
 +
|-
 +
|27 ||metal ||hard ||511-515 ||25 ||144 ||&#x2717;
 +
|-
 +
|28 ||metal ||hard ||511-515 ||25 ||144 ||&#x2717;
 +
|-
 +
|29 ||||hard ||42-46 ||25 ||144 ||&#x2717;
 +
|-
 +
|30 ||||hard ||42-46 ||25 ||144 ||&#x2717;
 +
|-
 +
|31 ||bollard ||hard ||42-46 ||25 ||144 ||&#x2717;
 +
|-
 +
|32 ||gate ||hard ||42-46 ||25 ||144 ||&#x2717;
 +
|-
 +
|33 ||sand ||soft ||520-523 ||26 ||26 ||&#x2713;
 +
|}
 +
 +
For VC v1.0:
 +
<ol start="5">
 +
<li>{{note|4}} Array starts at 0x5DCD0F. When a character fires a weapon, some weapons produce gun shells that can be seen ejecting from the weapon and falling to the ground. The sound it plays depends on what material the character is standing on. There are three types of landing sounds used: hard, soft, and none. Hard shell drops use SFX 156 and soft ones use SFX 157.</li>
 +
<li>{{note|5}} Array starts at 0x6B66B0. Each footstep characters make creates a sound. These values are associated with an entry in the SFX file. The game chooses an SFX to play at random within that range.</li>
 +
<li>{{note|6}} Array starts at 0x6B6D3C. Cars and motorcycles can skid across the ground and create a sound. These values are associated with an entry in the SFX file.</li>
 +
<li>{{note|7}} Function located at 0x5D9960. The function plays an SFX whenever a vehicle scrapes against a collision. Many scraping sounds are heavily altered and do not seem to resemble the SFX at first glance.</li>
 +
<li>{{note|8}} Array starts at 0x692554. Particle 53 (PEDFOOT_DUST) is produced for every footstep the player makes on the appropriate material.</li>
 +
</ol>
  
 
== Tools ==
 
== Tools ==
Line 243: Line 430:
 
* [[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.''
 
* [[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 ===
+
=== 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.''
 
* [[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.''
 
* [[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==
+
==See also==
* [http://www.gtaforums.com/index.php?showtopic=291542 What's the use of collision spheres?]
+
* {{GTAF|291542|What's the use of collision spheres?}}
 +
* {{Icon|4}} [[WBD-WBN]] - new format used in GTA IV
  
[[Category:3D File Formats]][[Category:GTA 3]][[Category:GTA VC]][[Category:GTA SA]]
+
{{N|SA|VC|3}}
 +
[[Category:3D File Formats]]

Latest revision as of 15:26, 1 September 2020

All GTA3 games (GTA III, Vice City and San Andreas) have separate files for the visual and physical representations of their models. Collision models are often simply an optimized equivalent of the visual model, reduced in poly count and complexity. The game engine uses them for collision and 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 file extension .col.

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 4 known versions of the GTA collision file format.

Feature Version 1 Version 2 Version 3 Version 4
Supported by games:
GTA III Y N N N
GTA Vice City Y N N N
GTA San Andreas (PS2) Y Y N N
GTA San Andreas (PC/XBOX) Y Y Y Y
Geometric shapes:
Collision spheres Y Y Y Y
Collision boxes Y Y Y Y
Collision lines Y Y Y Y
Collision cones N N Y Y
Collision mesh Y Y Y Y
Face groups N Y Y Y
Shadow mesh N N Y Y
Miscellaneous:
Light intensity: N Y Y Y
Data compression N Y Y Y
Clump collision N N Y N
Four character code COLL COL2 COL3 COL4

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 archives 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.

Structure NameVersion 1Version 2/3
TBounds
bounding objects (box & sphere)
(40 byte)
radius  : float;
center  : TVector;
min, max: TVector;
min, max: TVector;
center  : TVector;
radius  : float;
TSurface
surface properties
(4 byte)
material   : uint8;
flag       : uint8;
brightness : uint8;
light      : uint8;
TSphere
collision sphere
(20 byte)
radius : float;
center : TVector;
surface: TSurface;
center : TVector;
radius : float;
surface: TSurface;
TBox
collision box
(28 byte)
min, max: TVector;
surface : TSurface;
TFaceGroup
face group (see below)
(28 byte)

(not used)

min, max: TVector;
StartFace,
EndFace : uint16;
TVertex
collision mesh vertex
(12 or 6 byte)
float[3]
int16[3]
TFace
collision mesh face
(16 or 8 byte)
a, b, c: uint32;
surface: TSurface;
a, b, c : uint16;
material: uint8;
light   : uint8;
  • all boxes are axis-aligned

Header

char {4}        - FourCC ("COLL", "COL2" or "COL3")
uint32 {4}      - file size from after this value (so 8 byte less)
char {22}       - collision model name
short {2}       - model id to apply col to (0-19999)
                  if not valid (i.e. name of target model does
                  not match), name is used
TBounds {40}    - bounding objects, see above

if (Version >= 2) {
  uint16 {2}    - number of collision spheres
  uint16 {2}    - number of collision boxes
  uint16 {2}    - number of collision mesh faces
  uint8  {1}    - number of collision lines (or cones)
  uint8  {1}    - unused (padding)
  uint32 {4}    - flags
  uint32 {4}    - offset collision spheres
  uint32 {4}    - offset collision boxes
  uint32 {4}    - offset collision lines (or cones)
  uint32 {4}    - offset collision mesh vertices
  uint32 {4}    - offset collision mesh faces (triangles)
  uint32 {4}    - offset triangle planes

  if (Version >= 3) {
    uint32 {4}  - number of shadow mesh faces
    uint32 {4}  - offset shadow mesh vertices
    uint32 {4}  - offset shadow mesh faces
  }
  if (Version == 4) {
    uint32 {4}  - unknown value (unused)
  }
}
  • All offsets in col 2/3/4 format are relative to after the fourcc, so file offset + 4.
  • Col 2/3/4 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:

  • 1 - collision uses cones instead of lines (flag forced to false by engine upon loading)
  • 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

Version 1Version 2/3
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
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
  • 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.
  • 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 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[1]. On average there are 31.75 faces per group.

^ 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.

Limits

  • Number of vertices - 32767
  • Number of faces - 32767
  • Vertex position - (-256.0; 256.0) on each axis

The game may also crash if there's too many face groups (more than 1k)

SFX and particles

Interacting with different materials can produce different sound and particle effects. The association between SFX and particles with material are all hardcoded.

GTA III

Value Material Gun shell drop[2] Footstep[3] Vehicle skidding[4]
0 hard 32-36 19
1 hard 32-36 19
2 grass soft 37-41 158
3 dirt soft 42-46 20
4 mud soft 42-46 20
5 pavement hard 32-36 19
6 metal hard 52-56 19
7 hard 32-36 19
8 soft 32-36 19
9 metal hard 52-56 19
10 metal hard 52-56 19
11 metal hard 52-56 19
12 metal hard 52-56 19
13 metal hard 52-56 19
14 metal hard 52-56 19
15 metal hard 52-56 19
16 metal hard 52-56 19
17 soft 32-36 19
18 sand soft 61-64 20
19 water - 57-60 20
20 wood hard 47-51 19
21 wood hard 47-51 19
22 wood hard 47-51 19
23 soft 32-36 19
24 hard 32-36 19
25 hedge soft 131-135 158
26 stone hard 32-36 19
27 metal hard 52-56 19
28 metal hard 52-56 19

For III v1.0:

  1. ^ Array starts at 0x609274. When a character fires a weapon, some weapons produce gun shells that can be seen ejecting from the weapon and falling to the ground. The sound it plays depends on what material the character is standing on. There are three types of landing sounds used: hard, soft, and none. Hard shell drops use SFX 167 and soft ones use SFX 168.
  2. ^ Array starts at 0x6077EC. Each footstep characters make creates a sound. These values are associated with an entry in the SFX file. The game chooses an SFX to play at random within that range.
  3. ^ Array starts at 0x607428. Cars can skid across the ground and create a sound. These values are associated with an entry in the SFX file.

Vice City

Value Material Gun shell drop[5] Footstep[6] Vehicle skid[7] Vehicle scrape[8] Foot dust[9]
0 hard 42-46 25 144
1 hard 42-46 25 144
2 grass soft 496-500 154 154
3 dirt soft 501-505 26 26
4 mud soft 501-505 26 26
5 pavement hard 42-46 25 144
6 metal hard 511-515 25 144
7 glass hard 42-46 25 144
8 soft 42-46 25 144
9 metal door hard 511-515 25 144
10 metal hard 511-515 25 144
11 metal hard 511-515 25 144
12 metal hard 511-515 25 144
13 metal hard 511-515 25 144
14 metal hard 511-515 25 144
15 metal hard 511-515 25 144
16 metal fence hard 511-515 25 144
17 soft 42-46 25 -
18 sand soft 520-523 26 26
19 water - 516 26 316
20 wood hard 506-510 25 144
21 wood box hard 506-510 25 144
22 wood plank hard 506-510 25 144
23 tire soft 42-46 25 144
24 hard 42-46 25 144
25 hedge soft 127-131 154 154
26 stone hard 42-46 25 144
27 metal hard 511-515 25 144
28 metal hard 511-515 25 144
29 hard 42-46 25 144
30 hard 42-46 25 144
31 bollard hard 42-46 25 144
32 gate hard 42-46 25 144
33 sand soft 520-523 26 26

For VC v1.0:

  1. ^ Array starts at 0x5DCD0F. When a character fires a weapon, some weapons produce gun shells that can be seen ejecting from the weapon and falling to the ground. The sound it plays depends on what material the character is standing on. There are three types of landing sounds used: hard, soft, and none. Hard shell drops use SFX 156 and soft ones use SFX 157.
  2. ^ Array starts at 0x6B66B0. Each footstep characters make creates a sound. These values are associated with an entry in the SFX file. The game chooses an SFX to play at random within that range.
  3. ^ Array starts at 0x6B6D3C. Cars and motorcycles can skid across the ground and create a sound. These values are associated with an entry in the SFX file.
  4. ^ Function located at 0x5D9960. The function plays an SFX whenever a vehicle scrapes against a collision. Many scraping sounds are heavily altered and do not seem to resemble the SFX at first glance.
  5. ^ Array starts at 0x692554. Particle 53 (PEDFOOT_DUST) is produced for every footstep the player makes on the appropriate material.

Tools

Version 1 only

  • CollMaker [1] by Steve M. (2002)
    Very simple tool that creates single model collision files based on text cordinates as input, such as the text .x files.
  • CollEditor [2] by Steve M. (2003)
    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 [3] by Delfi (2004)
    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

See also