rwfury 0.3.0

Python library for reading and writing GTA RenderWare DFF, TXD, IMG, and COL files

rwfury

Python library for reading and writing GTA RenderWare DFF (3D model), TXD (texture dictionary), IMG (archive), and COL (collision) files. Supports GTA III, Vice City, and San Andreas.

Features

• DFF parsing with full plugin support: BinMesh, Skin, HAnim, 2dfx, Material Effects, Night Colors, Collision, Specular/Reflection materials
• DFF writing back to binary (round-trip)
• TXD parsing with DDS export and raw RGBA decoding
• IMG archives: read/write v1 (GTA III/VC) and v2 (San Andreas), extract files, parse DFF/TXD directly from memory
• COL parsing/writing for standalone collision files: COL1, COL2, and COL3, including spheres, boxes, face groups, and shadow meshes
• Named collision materials via ColMaterial enum for readable COL surface IDs
• Version-aware: handles RW 3.1 (GTA III) through 3.6 (San Andreas) struct differences automatically
• GenericMesh: format-agnostic mesh representation with flat arrays and byte-packing helpers for easy porting to glTF, FBX, or any custom format
• BinMesh-aware generic export: to_generic_meshes() preserves material splits from BinMesh, including triangle strips
• Zero external dependencies (pure Python, stdlib only)

Installation

pip install rwfury

Requires Python 3.10+. No external dependencies.

Quick start

Read files from an IMG archive

from rwfury import Img, Dff, Txd

# Open an IMG (auto-detects v1 or v2)
img = Img.from_file("gta3.img")

# List contents
print(f"{len(img.entries)} files")
for name in img.list_files()[:10]:
    print(f"  {name}")

# Find a file (case-insensitive)
entry = img.find("cop.dff")
print(f"{entry.name}: {entry.size} bytes")

# Parse DFF/TXD directly from IMG (no temp files)
dff = Dff.from_bytes(img.read("cop.dff"))
txd = Txd.from_bytes(img.read("cop.txd"))

# Extract files to disk
img.extract("cop.dff", "output/")       # single file
img.extract_all("output/")              # everything

Parse a DFF and extract meshes

from rwfury import Dff

dff = Dff.from_file("model.dff")

# High-level mesh extraction (grouped by material)
for entry in dff.get_meshes():
    print(entry["name"], entry["texture"])
    for mesh in entry["meshes"]:
        print(f"  {len(mesh.positions)} vertices, {len(mesh.indices)//3} triangles")
        print(f"  UV sets: {len(mesh.texcoords)}")

Format-agnostic export with GenericMesh

from rwfury import Dff

dff = Dff.from_file("model.dff")

for mesh in dff.to_generic_meshes():
    # Flat arrays ready for GPU upload or any format conversion
    pos_bytes = mesh.positions_as_bytes()      # float32 LE, 3 per vertex
    idx_bytes = mesh.indices_as_bytes("u16")   # uint16 LE (or "u32")
    uv_bytes  = mesh.texcoords_as_bytes(0)     # float32 LE, 2 per vertex
    norm_bytes = mesh.normals_as_bytes()       # float32 LE, 3 per vertex

    # Material info
    print(mesh.texture_name, mesh.diffuse_color)

    # 4x4 transform matrix (row-major, 16 floats)
    print(mesh.transform)

    # Skinning data (if present)
    if mesh.has_skinning:
        bi = mesh.bone_indices_as_bytes()   # uint8, 4 per vertex
        bw = mesh.bone_weights_as_bytes()   # float32, 4 per vertex

Read and write a COL collision file

from rwfury import Col, ColMaterial

col = Col.from_file("model.col")

for model in col.models:
    print(model.name, model.version)
    print(f"{len(model.spheres)} spheres, {len(model.boxes)} boxes")
    print(f"{len(model.vertices)} verts, {len(model.faces)} faces")

    if model.faces:
        face = model.faces[0]
        print(face.material, ColMaterial(face.material).label)

col.to_file("roundtrip.col")

Parse embedded collision from a DFF

from rwfury import Dff

dff = Dff.from_file("model.dff")

if dff.collision:
    col_model = dff.collision.parse()
    if col_model:
        print(col_model.name, len(col_model.faces))

Extract textures from a TXD

from rwfury import Txd

txd = Txd.from_file("textures.txd")

# Export all textures as .dds files
txd.export_to_dds("output_folder/")

# Or get raw RGBA pixel data (for compression, processing, etc.)
for tex in txd.textures:
    rgba_mipmaps, has_alpha = tex.to_rgba()
    # rgba_mipmaps[0] = bytes, width * height * 4, R,G,B,A order
    print(f"{tex.name}: {tex.width}x{tex.height}, alpha={has_alpha}")

Write a modified DFF

from rwfury import Dff

dff = Dff.from_file("original.dff")

# Modify frames, geometry, materials, etc.
dff.frames[0].name = "renamed_frame"

# Write back to binary
dff.to_file("modified.dff")

Create a new IMG archive

from rwfury import Img

# Build a v2 IMG from files
files = {
    "model.dff": open("model.dff", "rb").read(),
    "texture.txd": open("texture.txd", "rb").read(),
}
Img.create_v2(files, "output.img")

Access low-level data

from rwfury import Dff

dff = Dff.from_file("model.dff")

# Frames (skeleton/hierarchy)
for frame in dff.frames:
    print(frame.name, frame.position, frame.parent)
    if frame.hanim:
        print(f"  HAnim: {len(frame.hanim.bones)} bones")

# Geometry details
for geom in dff.geometries:
    print(f"{len(geom.vertices)} verts, {len(geom.triangles)} tris")
    print(f"UV sets: {geom.num_uv_sets}, flags: 0x{geom.flags:04X}")

    # Plugins
    if geom.bin_mesh:
        print(f"BinMesh: {len(geom.bin_mesh.splits)} splits")
    if geom.skin:
        print(f"Skin: {geom.skin.num_bones} bones")
    if geom.night_colors:
        print(f"Night colors: {len(geom.night_colors)} vertices")
    if geom.effects_2dfx:
        print(f"2dfx: {len(geom.effects_2dfx)} effects")

    # Materials
    for mat in geom.materials:
        print(f"  {mat.texture_name} color={mat.color}")
        if mat.specular_texture:
            print(f"    specular: {mat.specular_texture} level={mat.specular_level}")
        if mat.reflection:
            print(f"    reflection: intensity={mat.reflection['intensity']}")

# Collision data
if dff.collision:
    print(f"Embedded collision: {len(dff.collision.raw)} bytes")
    parsed = dff.collision.parse()
    if parsed:
        print(f"  Parsed COL model: {parsed.name}")

API reference

Core classes

Class	Description
Dff	DFF parser/writer. from_file(path), from_bytes(data), to_file(path), get_meshes(), to_generic_meshes()
Txd	TXD parser. from_file(path), from_bytes(data), export_to_dds(folder)
TxdTexture	Single texture entry. to_rgba() decodes any format to raw RGBA bytes
Img	IMG archive. from_file(path), read(name), find(name), extract(), extract_all(), create_v2()
ImgEntry	Archive entry with name, offset, size
Col	COL parser/writer. from_file(path), from_bytes(data), to_file(path), to_bytes()
ColModel	One collision model with bounds, primitives, mesh, face groups, and optional shadow mesh
ColMaterial	Named IntEnum for COL surface material IDs
GenericMesh	Flat-array mesh with *_as_bytes() helpers for format-agnostic export

DFF data classes

Class	Description
DffGeometry	Vertices, normals, triangles, texcoords, vertex colors, materials, and plugins
DffMaterial	Color, texture name, ambient/diffuse/specular, material effects, specular/reflection extensions
DffFrame	Name, position, rotation matrix, parent index, HAnim skeleton data
DffAtomic	Links a frame to a geometry
MorphTarget	Per-morph-target vertices and normals with bounding sphere
BinMeshPLG	Triangle strip/list splits by material
SkinPLG	Bone indices, weights, and inverse bind matrices per vertex
HAnimPLG	Skeleton hierarchy with bone IDs and flags
Effect2dfxEntry	2dfx effect (lights, particles, etc.) with position and typed data
CollisionData	Raw embedded COL data blob

COL data classes

Class	Description
ColBounds	Bounding sphere + AABB data
ColSurface	Collision surface properties: material, flag, brightness, light
ColSphere	Collision sphere primitive
ColBox	Collision box primitive
ColFace	Collision triangle face with material/light
ColFaceGroup	Spatial grouping metadata for COL2/3

GenericMesh properties and methods

Member	Description
vertex_count, triangle_count	Derived from flat array lengths
has_normals, has_colors, has_skinning	Quick checks for optional data
uv_set_count	Number of UV coordinate sets
positions_as_bytes()	Packed float32 LE (12 bytes/vertex)
normals_as_bytes()	Packed float32 LE (12 bytes/vertex)
texcoords_as_bytes(uv_set)	Packed float32 LE (8 bytes/vertex)
colors_as_bytes()	Packed uint8 RGBA (4 bytes/vertex)
indices_as_bytes(fmt)	"u16" or "u32" packed indices
bone_indices_as_bytes()	Packed uint8 (4 bytes/vertex)
bone_weights_as_bytes()	Packed float32 LE (16 bytes/vertex)

Supported formats

Game	RW Version	DFF	TXD	IMG	COL
GTA III	3.1 - 3.3	Read/Write	Read + DDS export	v1 (Read/Write)	COL1 (Read/Write)
GTA Vice City	3.4 - 3.5	Read/Write	Read + DDS export	v1 (Read/Write)	COL1 (Read/Write)
GTA San Andreas	3.6	Read/Write	Read + DDS export	v2 (Read/Write)	COL2/COL3 (Read/Write)

TXD supports D3D8/D3D9 platform textures: PAL4, PAL8, 16-bit (R5G6B5, A1R5G5B5, A4R4G4B4), 32-bit (A8R8G8B8, X8R8G8B8), and DXT1/DXT3/DXT5 compressed.

IMG v1 uses separate .dir + .img files. IMG v2 uses a single .img file with VER2 header.

License

MIT