DFFLoader for Three.js

A modern Three.js loader for RenderWare DFF 3D models and TXD texture dictionaries from GTA San Andreas, Vice City, III and other RenderWare-powered games.

Features

• Three.js r150+ compatible (tested with r170)
• ES Module syntax with proper exports
• TXD Texture Dictionary support - Load textures directly from .txd files
• DXT compression support - DXT1, DXT3, DXT5 texture decompression
• Multi-material meshes - Proper material assignment via BinMesh PLG
• Complete geometry support - Positions, normals, UVs, vertex colors
• Skeletal animation data - Bones and skin weights

Installation

NPM

npm install dff-loader

CDN

<!-- unpkg -->
<script src="https://unpkg.com/three"></script>
<script src="https://unpkg.com/dff-loader"></script>

<!-- or jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/three"></script>
<script src="https://cdn.jsdelivr.net/npm/dff-loader"></script>

Quick Start

With NPM (ES Modules)

import * as THREE from 'three';
import { DFFLoader, TXDLoader } from 'dff-loader';

const scene = new THREE.Scene();
const loader = new DFFLoader();

loader.load('model.dff', (model) => {
    scene.add(model);
});

With CDN (Browser)

<script src="https://unpkg.com/three"></script>
<script src="https://unpkg.com/dff-loader"></script>
<script>
  const { DFFLoader, TXDLoader } = window.DFFLoader;

  const loader = new DFFLoader();
  loader.load('model.dff', (model) => {
      scene.add(model);
  });
</script>

With TXD Textures

import { DFFLoader, TXDLoader } from 'dff-loader';

// First load the texture dictionary
const txdLoader = new TXDLoader();
txdLoader.load('textures.txd', (textures) => {
    // Then load the model with textures
    const dffLoader = new DFFLoader();
    dffLoader.setTextureDictionary(textures);

    dffLoader.load('model.dff', (model) => {
        scene.add(model);
    });
});

Parse from ArrayBuffer

import { DFFLoader, TXDLoader } from 'dff-loader';

// For DFF
const dffLoader = new DFFLoader();
const model = dffLoader.parse(dffArrayBuffer);

// For TXD
const txdLoader = new TXDLoader();
const textures = txdLoader.parse(txdArrayBuffer);

Development Server

git clone https://github.com/Jackal1337/DFF-Loader.git
cd DFF-Loader
npm install
npm run dev

Open http://localhost:3000 and drag & drop .dff and .txd files to view models.

Supported Formats

DFF (3D Models)

Feature	Status
Geometry (vertices, faces)	Complete
Materials	Complete
UV Coordinates	Complete
Vertex Colors	Complete
Normals	Complete
BinMesh PLG (material splits)	Complete
Bone Hierarchy	Complete
Skin Weights	Complete
Morph Targets	Partial
Collision Data	Not supported
2DFX Effects	Not supported

TXD (Texture Dictionaries)

Format	Status
DXT1 (BC1)	Complete
DXT3 (BC2)	Complete
DXT5 (BC3)	Complete
Uncompressed (A8R8G8B8, X8R8G8B8)	Complete
Uncompressed (R5G6B5, A1R5G5B5)	Complete
Paletted (P8, PAL8)	Complete
Paletted (PAL4)	Complete
Mipmaps	Skipped (uses base level)

API Reference

DFFLoader

Extends THREE.Loader

const loader = new DFFLoader(manager);

Methods

• load(url, onLoad, onProgress, onError) - Load DFF from URL
• parse(arrayBuffer) - Parse DFF from ArrayBuffer, returns THREE.Group
• setPath(path) - Set base path for fallback texture loading
• setTextureDictionary(map) - Set texture Map from TXDLoader

TXDLoader

Extends THREE.Loader

const loader = new TXDLoader(manager);

Methods

• load(url, onLoad, onProgress, onError) - Load TXD from URL
• parse(arrayBuffer) - Parse TXD from ArrayBuffer, returns Map<string, {texture, hasAlpha}>

Getting Game Files

DFF and TXD files can be extracted from:

• GTA San Andreas - models/gta3.img, models/player.img
• GTA Vice City - models/gta3.img
• GTA III - models/gta3.img
• Community mods from GTAInside

Extraction Tools

• OpenIV - Modern tool for GTA modding
• IMG Tool - Classic IMG archive tool
• TXD Workshop - TXD texture editor

Technical Notes

RenderWare Chunk Structure

DFF files use the RenderWare binary chunk format:

• Each chunk has a 12-byte header (type, size, version)
• Main chunks: Clump, FrameList, GeometryList, Atomic
• Extensions: BinMesh PLG, Skin PLG, HAnim PLG

BinMesh PLG

GTA SA models use BinMesh PLG extension for material assignment instead of per-triangle material IDs. This loader properly handles both formats.

Texture Formats

TXD textures store D3D format information. The loader automatically detects and decodes:

• Compressed formats via S3TC/DXT decompression
• Various uncompressed pixel formats with correct channel ordering

Browser Compatibility

Requires browsers with:

• ES2020+ support (async/await, optional chaining)
• WebGL 2.0 for Three.js rendering
• ArrayBuffer and TypedArray support

License

MIT

Credits

• Original DFFLoader by andrewixz
• Modernization & TXD Support - Complete rewrite for Three.js r150+

References

• RenderWare Binary Stream
• TXD File Format
• DFF File Format