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

$3

``bash
npm install dff-loader
`

$3

`html







`

Quick Start

$3

`javascript
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);
});
`

$3

`html



`

$3

`javascript
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);
});
});
`

$3

`javascript
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);
`

$3

`bash
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

$3

| 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 |

$3

| 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

$3

Extends THREE.Loader

`javascript
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

$3

Extends THREE.Loader

`javascript
const loader = new TXDLoader(manager);
`

#### Methods

- load(url, onLoad, onProgress, onError) - Load TXD from URL
- parse(arrayBuffer) - Parse TXD from ArrayBuffer, returns Map

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

$3

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

Technical Notes

$3

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

$3

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

$3

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+

$3

- RenderWare Binary Stream
- TXD File Format
- DFF File Format