Difference between revisions of "IMG archive"

From GTAMods Wiki
Jump to navigation Jump to search
(Tools)
m (Reverted edits by Xmen (talk) to last revision by Fastman92)
Line 27: Line 27:
 
Version 2 archives, introduced with GTA San Andreas, combine <code>.dir</code> and <code>.img</code> files into one <code>.img</code> file. The directory has the same format as in version 1, but is located at the beginning of the archive. Files are again aligned to 2 KB boundaries. File offsets are relative to the start of the whole archive, not to the end of the file list.
 
Version 2 archives, introduced with GTA San Andreas, combine <code>.dir</code> and <code>.img</code> files into one <code>.img</code> file. The directory has the same format as in version 1, but is located at the beginning of the archive. Files are again aligned to 2 KB boundaries. File offsets are relative to the start of the whole archive, not to the end of the file list.
  
==== Header ====
+
  Header
Size of '''8 bytes'''
+
  Offset Type Value
4 byte - CHAR[4] -
+
  0x0 CHAR[4]
4 byte - DWORD - Number of files on list (n)  
+
  0x4 DWORD Number of files on list (n)
 
+
 
==== Entry ====
+
  File list
Size of '''32 bytes''' 
+
  Starts on offset: 0x8
   4 byte - DWORD - File offset, in blocks
+
  Each entry description takes: 32 bytes.
   2 byte - WORD - Size, second priority in blocks
+
  Entry description:
   2 byte - WORD - Size, first priority in blocks
+
 
24 byte - CHAR[24] - File name (0x00) terminated.
+
  Offset Type Value
If Size First Priority is NOT zero, it will be used as file size, else Size Second Priority will be used.
+
   +0x0 DWORD File offset, in blocks (file offset / 2048)
 +
   +0x4 WORD Size, second priority in blocks (file size / 2048)
 +
   +0x6 WORD Size, first priority in blocks (file size / 2048)
 +
  +0x8 CHAR[24] File name NULL (0x00) terminated.
 +
 
 +
  If +6 SizeFirstPriority is NOT zero, +6 will be used as file size, else +4 SizeSecondPriority will be used.
 +
 +
  Zero didn't change resulting value read by IMG editors when treated as DWORD.
 +
 
 +
  File contents
 +
  File contents are right after a file list. They are aligned to 2048 bytes boundaries. It means position of file in IMG archive must be divisible by 2048. Therefore file in sample archive can be stored on offsets 2048, 4096, 6144, 8192 and so forth.
  
 
A major drawback of this format is the complicated extendability. If you have to add many files, it might happen that you run out of space for the directory, and have to move the first file(s) to the end.
 
A major drawback of this format is the complicated extendability. If you have to add many files, it might happen that you run out of space for the directory, and have to move the first file(s) to the end.
Line 99: Line 109:
 
| style="text-align:center" | {{Icon|3}} {{Icon|VC}} || [[ImgEd]] &ndash; by Dan Strandberg
 
| style="text-align:center" | {{Icon|3}} {{Icon|VC}} || [[ImgEd]] &ndash; by Dan Strandberg
 
|-
 
|-
| style="text-align:center" | {{Icon|trilogy}} {{Icon|4}} || [http://www.x-squares.com/File/i/54/IMG-Manager.aspx IMG Manager] &ndash; by {{U|xmen}}
+
| style="text-align:center" | {{Icon|SA}} || {{GTAF|354093|IMG Manager}} &ndash; by {{U|xmen}}
 
|-
 
|-
 
| style="text-align:center" | {{Icon|SA}} || {{GTAG|1503|Spark}} &ndash; by {{U|aru}}
 
| style="text-align:center" | {{Icon|SA}} || {{GTAG|1503|Spark}} &ndash; by {{U|aru}}
Line 107: Line 117:
 
| style="text-align:center" | {{Icon|trilogy}} || [[G-IMG]] &ndash; by {{U|REspawn}}
 
| style="text-align:center" | {{Icon|trilogy}} || [[G-IMG]] &ndash; by {{U|REspawn}}
 
|-
 
|-
| style="text-align:center" | {{Icon|SA}} || {{GTAF|500814|IMG Limit Adjuster}} &ndash; by {{U|fastman92}}
+
| style="text-align:center" | {{Icon|trilogy}} || {{GTAF|500814|IMG Limit Adjuster}} &ndash; by {{U|fastman92}}
 
<!--
 
<!--
 
|-
 
|-

Revision as of 12:10, 27 May 2012

GTA's most commonly used archive files are known by the extension .img. They have a very simple format and currently exist in multiple versions.

Structure

Version 1 - GTA III & VC

Version 1 archives used in GTA III and Vice City, are actually split up into two files: the content directory (.dir) and the actual archive (.img).

The directory is a list of files each with name, offset and size of the file. The values for offset and size have to be multiplied by 2048, since files are aligned to 2 KB boundaries. This means that even a file with only 123 byte content will take up 2 KB in the archive. Files are stored (usually) unsorted, uncompressed and linear (no directory tree).

First you have to find out the number of entries (n). Just divide the filesize of the .dir file by 32 and you will get it.

There is no Header, like in V2 (San Andreas) Files!

Entry: (repeated n times)
4 byte - DWORD - offset of file inside archive (in blocks) 4 byte - DWORD - size of file (in blocks) 24 byte - CHAR[24] - name of file

The .img file itself has no special structure or header, just all the files in 2 KB blocks.

This format was also used in the PC version of Bully: Scholarship Edition.

Version 2 - GTA SA

Version 2 archives, introduced with GTA San Andreas, combine .dir and .img files into one .img file. The directory has the same format as in version 1, but is located at the beginning of the archive. Files are again aligned to 2 KB boundaries. File offsets are relative to the start of the whole archive, not to the end of the file list.

 Header
 Offset		Type		Value
 0x0		CHAR[
 0x4		DWORD		Number of files on list (n)
 
 File list
 Starts on offset: 0x8
 Each entry description takes: 32 bytes.
 Entry description:
 
 Offset		Type		Value
 +0x0		DWORD		File offset, in blocks (file offset / 2048)
 +0x4		WORD		Size, second priority in blocks (file size / 2048)
 +0x6		WORD		Size, first priority in blocks (file size / 2048)
 +0x8		CHAR[24]	File name NULL (0x00) terminated.
 
 If +6 SizeFirstPriority is NOT zero, +6 will be used as file size, else +4 SizeSecondPriority will be used.
 Zero didn't change resulting value read by IMG editors when treated as DWORD.
 
 File contents
 File contents are right after a file list. They are aligned to 2048 bytes boundaries. It means position of file in IMG archive must be divisible by 2048. Therefore file in sample archive can be stored on offsets 2048, 4096, 6144, 8192 and so forth.

A major drawback of this format is the complicated extendability. If you have to add many files, it might happen that you run out of space for the directory, and have to move the first file(s) to the end.

Version 3 - GTA IV

GTA IV introduced yet another .img file format. Not only the format is new, also there can be encrypted archive headers (see below). The internal IMG parser of the game works with 2 kb buffers, which means that the 2 kb bounds from earlier versions (blocks) are still present, yet optional.

IMG Header

The header of an unencrypted file always has a size of 20 bytes.

4 byte - DWORD      - Identifier (0xA94E2A52 if the archive is not encrypted)
4 byte - DWORD      - Version (always 3, if not the format would be differ)
4 byte - DWORD      - Number of Items
4 byte - DWORD      - Table Size (in bytes)
2 byte - WORD       - Size of Table Items (needs to be always 0x10)
2 byte - WORD       - Unknown

IMG Table

The table holds information about the items. Each item header has a size of 16 bytes .

4 byte - DWORD      - Itemsize (in bytes)
4 byte - DWORD      - Resource type
4 byte - DWORD      - Offset (in blocks)
2 byte - WORD       - Used Blocks
2 byte - WORD       - Padding

Item Names' length will be calculate as :

Table Size - (Number of Items * Item Size)

Next that string will be split by '\x0'

A resource type is identified by the 4b DWORD value:

  • 0x01: Generic
  • 0x08: Texture archive
  • 0x20: Bounds
  • 0x6E: Model file
  • 0x24: xpfl

Encryption

The header and directory (table) of IMG archives can be encrypted. This is usually the case if the 4 byte identifier at the start of the file seems invalid. Decryption is done via 16 repetitions of AES-128 in ECB mode.

Additional archives

It is possible to add additional IMG archives to the current default ones. The following examples are lines that can be added anywhere in either the default.dat or gta*.dat files.

GTA III Vice City CDIMAGE MODELS\FOO.IMG
San Andreas IMG MODELS\FOO.IMG

Where FOO can be any name. The FOO.IMG (and FOO.DIR for GTA III and Vice City) must be created and placed within the ..\models folder in these examples. This method is primarily used for modifying version 2 of San Andreas, as well as for storing assets (models/textures/etc.) used in total conversions.

By default GTA San Andreas is able to load max of 8 archives (3 standard archives gta3.img, gta_int.img, player.img and 5 archives defined within default.dat or gta.dat). Using more than 8 archives crashes the game, although this can be fixed with fastman92's IMG Limit Adjuster.

Tools

GTA III Vice City ImgEd – by Dan Strandberg
San Andreas GTA Net GTAForums: IMG Manager – by xmen
San Andreas GTA Net GTAGarage: Spark – by aru
GTA III Vice City San Andreas IMG Tool – by Spooky
GTA III Vice City San Andreas G-IMG – by REspawn
GTA III Vice City San Andreas GTA Net GTAForums: IMG Limit Adjuster – by fastman92
Liberty City Stories Vice City Stories Post.png GTAForums: GTA Stories IMG Tool – by HackMan128
GTA IV SparkIV – by aru
GTA IV OpenIV – by GooD-NTS
GTA IV Shadow-Mapper – by Prince-Link

Libraries

Version 2 only

Version 3 only