GtaImg 1.1.0

GtaImg - C# Library for GTA IMG Archives

A C# library for reading and manipulating IMG archive files from GTA games (GTA III, Vice City, San Andreas).

Installation

dotnet add package GtaImg

Or via Package Manager:

Install-Package GtaImg

Supported Frameworks

The library targets multiple frameworks for maximum compatibility:

Project Structure

├── GtaImg.sln                          # Solution file
├── src/
│   ├── GtaImg/                         # Main library
│   │   ├── GtaImg.csproj
│   │   ├── IMGArchive.cs               # Main archive class
│   │   ├── IMGEntry.cs                 # Entry structure
│   │   └── IMGException.cs             # Custom exception
│   └── GtaImgTool/                     # GUI application (WPF)
│       ├── GtaImgTool.csproj
│       └── ...
└── tests/
    └── GtaImg.Tests/                   # NUnit tests
        ├── GtaImg.Tests.csproj
        └── IMGArchiveTests.cs

GtaImgTool - GUI Application

A Windows desktop application for viewing and editing IMG archives with a modern dark theme.

Features

• Open/Create Archives: Support for both VER1 (GTA III/VC) and VER2 (GTA SA) formats
• Browse Files: View all entries with name, type, and size information
• Multi-Select: Select multiple files using Ctrl+Click or Shift+Click
• Export Files: Export selected files or all files to any folder
• Import Files: Add files individually, multiple at once, or from a folder
• Delete Entries: Remove selected entries from the archive
• Pack Archive: Defragment the archive to reclaim unused space
• Drag & Drop: Drag IMG files onto the window to open them
• Search/Filter: Quickly find files by name

Running the GUI Tool

dotnet run --project src/GtaImgTool/GtaImgTool.csproj

Keyboard Shortcuts

Features

• Read/Write Support: Open IMG archives in read-only or read-write mode
• VER1 Support: GTA III and Vice City archives (.dir + .img file pairs)
• VER2 Support: GTA San Andreas archives (single .img file)
• Entry Management: Add, remove, rename, and extract entries
• File Import/Export: Easy methods for importing files and extracting entries

Building

dotnet build

Running Tests

dotnet test

Or with verbose output:

dotnet test --verbosity normal

Usage Examples

Opening an Archive (Read-Only)

using GtaImg;

// Open a VER2 archive (GTA SA)
using var archive = new IMGArchive("gta3.img");

// List all entries
foreach (var entry in archive)
{
    Console.WriteLine($"{entry.Name} - {entry.SizeInBytes} bytes");
}

Opening an Archive (Read-Write)

using GtaImg;

// Open for reading and writing
using var archive = new IMGArchive("gta3.img", IMGArchive.IMGMode.ReadWrite);

// Make changes...
archive.Sync(); // Save changes (also called automatically on Dispose)

Creating a New Archive

using GtaImg;

// Create a new VER2 archive
using var archive = IMGArchive.CreateArchive("new_archive.img", IMGArchive.IMGVersion.VER2);

// Add files
archive.ImportFile("mymodel.dff");
archive.ImportFile("mytexture.txd");

Reading Entry Data

using GtaImg;

using var archive = new IMGArchive("gta3.img");

// Read by name
byte[]? data = archive.ReadEntryData("player.dff");

// Or use a stream
using var stream = archive.OpenEntry("player.dff");
if (stream != null)
{
    // Process stream...
}

Extracting Files

using GtaImg;

using var archive = new IMGArchive("gta3.img");

// Extract a single file
archive.ExtractEntry("player.dff", @"C:\extracted\player.dff");

// Extract all files
archive.ExtractAll(@"C:\extracted\all_files");

Adding/Importing Files

using GtaImg;

using var archive = new IMGArchive("gta3.img", IMGArchive.IMGMode.ReadWrite);

// Import from file system
archive.ImportFile(@"C:\mods\custom.dff", "custom.dff");

// Or add from byte array
byte[] myData = File.ReadAllBytes("myfile.txd");
archive.AddEntry("myfile.txd", myData);

Removing and Renaming Entries

using GtaImg;

using var archive = new IMGArchive("gta3.img", IMGArchive.IMGMode.ReadWrite);

// Remove an entry
archive.RemoveEntry("unwanted.dff");

// Rename an entry
archive.RenameEntry("old_name.txd", "new_name.txd");

Packing an Archive

After removing entries, the archive may have "holes" (unused space). Use Pack() to defragment:

using GtaImg;

using var archive = new IMGArchive("gta3.img", IMGArchive.IMGMode.ReadWrite);

// Remove some entries
archive.RemoveEntry("file1.dff");
archive.RemoveEntry("file2.dff");

// Pack to eliminate holes
uint newSize = archive.Pack();
Console.WriteLine($"Archive size is now {newSize} blocks");

Checking Entry Existence

using GtaImg;

using var archive = new IMGArchive("gta3.img");

if (archive.ContainsEntry("player.dff"))
{
    Console.WriteLine("Entry exists!");
}

// Get entry info
var entry = archive.GetEntryByName("player.dff");
if (entry.HasValue)
{
    Console.WriteLine($"Offset: {entry.Value.Offset} blocks");
    Console.WriteLine($"Size: {entry.Value.Size} blocks ({entry.Value.SizeInBytes} bytes)");
}

Detecting Archive Version

using GtaImg;

// Before opening
var version = IMGArchive.GuessIMGVersion("unknown.img");
Console.WriteLine(version == IMGArchive.IMGVersion.VER2 ? "GTA SA format" : "GTA 3/VC format");

// Or from an open archive
using var archive = new IMGArchive("unknown.img");
Console.WriteLine($"Archive version: {archive.Version}");

IMG Format Overview

• Block Size: 2048 bytes
• VER1 (GTA III/VC): Two files - .dir (directory/header) and .img (data)
• VER2 (GTA SA): Single .img file with "VER2" magic header
• Entry Names: Maximum 23 characters

License

This library is released under the MIT License.

Credits

This library is a C# port of the original C++ libgtaformats library by David "Alemarius Nexus" Lerch.

• Original C++ Library: gtatools/libgtaformats