Metadata-Version: 2.4
Name: fourfury
Version: 0.11.0
Summary: Python library for Grand Theft Auto IV archive formats.
Author: fourfury contributors
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# FourFury

FourFury is a Python library for reading, inspecting, extracting, and editing
Grand Theft Auto IV data files. It provides typed APIs for the game's archives,
world placements, collision resources, drawables, textures, navigation graphs,
animation dictionaries, and related metadata.

> [!IMPORTANT]
> FourFury is under active development. Read support is broader than write support,
> and some resource types intentionally permit only fixed-size edits.

## Format support

| Format | Read | Write | Notes |
| --- | :---: | :---: | --- |
| RPF2 | Yes | Yes | Search, extraction, creation, and unencrypted output |
| RPF3 | Yes | No | Audio archives with hash-only member identities |
| RAGE AUD | Yes | No | Extensionless banks and streams, typed codecs, metadata, PCM/IMA decoding, WAV export, and raw Vorbis access |
| IMG3 | Yes | Yes | Search, extraction, creation, and resource padding handling |
| CUT | Yes | Lossless text | Cutscene clocks, scene and asset resolution, flags, models, effects, variations, attachments, and preserved IMG padding |
| carcols.dat | Yes | Lossless source | Vehicle colors, scanner descriptors, and 3/4-channel model combinations |
| handling.dat | Yes | Lossless source | Typed physical handling, flags, and bike, boat, and aircraft subhandling |
| VehicleExtras.dat / vehOff.csv / animgrp.dat | Yes | Lossless source | Boat boarding points, vehicle camera offsets, and vehicle animation groups |
| GXT | Yes | Yes | GTA IV text databases, named and flat layouts, hash lookup, 8/16-bit text, and cache integration |
| IDE | Yes | Yes | Lossless definitions with typed archetypes, complete vehicle rows, MLO topology, and model-bound 2DFX lights |
| IPL | Yes | Yes | Lossless sectioned text with typed GTA IV OCCL boxes |
| gta.dat | Yes | Yes | Lossless level manifests, typed directives, device paths, and multi-path entries |
| images.txt | Yes | Yes | Ordered archive lists with explicit placement-sidecar modes |
| water.dat | Yes | Yes | Lossless water triangles and quads, runtime flags, geometry queries, and neutral mesh export |
| WPL | Yes | Yes | Placements, MLO and IDE-light resolution, explicit LOD hierarchies, world portals, and instance flags |
| GTXD | Yes | Yes | Texture-parent chains and cycle detection |
| NOD | Yes | Yes | Navigation nodes, links, costs, and topology validation |
| WNV | Yes | Limited | Navigation meshes, portals, edges, cover points, and quadtrees |
| WBN | Yes | Limited | Primitive, mesh, curved-wheel, composite, and BVH collision with fixed-size edits |
| WBD | Yes | Limited | Collision dictionaries and fixed-size edits |
| TUNE | Yes | Lossless text | Fragment physics source configuration |
| WAD | Yes | No | Animation dictionaries, tracks, chunks, and decoded channels |
| WBS | Yes | No | Facial blend shapes, sparse vertex deltas, and same-container WDD/WDR bindings |
| WDD | Yes | No | Hash-addressed drawable dictionaries and neutral model projection |
| WDR | Yes | No | Drawables plus neutral model projection |
| WFT | Yes | No | Fragment drawables, physics hierarchy, embedded lights, typed collision shapes, neutral projection, and IDE light binding |
| WTD | Yes | No | Texture dictionaries and DDS export |

See [DOCUMENTATION.md](DOCUMENTATION.md) for examples, field behavior, writer
constraints, and current limitations.

## Installation

FourFury requires Python 3.11 or newer. Install the latest release from PyPI:

```powershell
python -m pip install fourfury
```

For an editable installation:

```powershell
git clone https://github.com/Hancapo/fourfury.git
cd fourfury
python -m pip install -e .
```

## Quick start

Open an archive and read one of its entries:

```python
from pathlib import Path

from fourfury import RpfArchive

game = Path(r"D:\Program Files (x86)\Steam\steamapps\common\Grand Theft Auto IV\GTAIV")

with RpfArchive.from_path(game / "pc/data/game.rpf") as archive:
    entry = archive.find_entry("data/taskparams.txt")
    if entry is not None:
        print(entry.read().decode("utf-8"))
```

Index an entire installation when assets may live in different archives:

```python
from fourfury import GameFileCache, GameFileType

with GameFileCache(game) as cache:
    cache.scan()
    asset = cache.require_asset("bm_nylamp1", kind=GameFileType.WFT)
    fragment = cache.load(asset)
```

Episode installations can be scanned as effective base-game overlays:

```python
from fourfury import GameEpisode

with GameFileCache.for_episode(game, GameEpisode.THE_LOST_AND_DAMNED) as cache:
    cache.scan()
    city = cache.map_structure
    print(city.summary())
    print(city.delta.changed_paths)
```

## Documentation

The [complete documentation](DOCUMENTATION.md) covers every supported format,
resource APIs, neutral WDR models, editing constraints, and known limitations.

Release notes live in [CHANGELOG.md](CHANGELOG.md).
