RenderWare Binary Stream Parser NG

A TypeScript library for parsing RenderWare binary stream files used in GTA III, Vice City, and San Andreas.

This is a maintained fork of rw-parser by Timic3.

Supported Formats

| Format | Extension | Description | |--------|-----------|-------------| | DFF | .dff | 3D model geometry, materials, frames, skinning data | | TXD | .txd | Texture dictionaries with compressed/paletted textures | | IFP | .ifp | Skeletal animations (ANP3, ANPK formats) | | FXP | .fxp | Particle effect systems (GTA SA) |

Supported RenderWare Versions

| Version | Build | Game | |---------|-------|------| | 3.1.0.0 | 200704 | GTA III (PS2) | | 3.2.0.0 | 204800 | GTA III (PC) | | 3.3.0.2 | 208898 | GTA III (PC), Vice City (PS2) | | 3.4.0.3 | 212995 | Vice City (PC) | | 3.4.0.5 | 212997 | GTA III (PS2), Vice City (Android/PC) | | 3.5.0.0 | 217088 | GTA III/VC (Xbox) | | 3.6.0.3 | 221187 | San Andreas |

Installation

bun add rw-parser-ng

npm install rw-parser-ng

Usage

DFF (3D Models)

import { DffParser } from 'rw-parser-ng';
import { readFileSync } from 'node:fs';

const buffer = readFileSync('model.dff');
const parser = new DffParser(buffer);
const dff = parser.parse();

// Access parsed data
console.log(dff.version);                          // "RenderWare 3.6.0.3 (SA)"
console.log(dff.modelType);                        // DffModelType.SKIN | VEHICLE | GENERIC
console.log(dff.geometryList.geometries.length);   // Number of geometries
console.log(dff.frameList.frames.length);          // Number of frames
console.log(dff.dummies);                          // Node names
console.log(dff.animNodes);                        // Animation hierarchy

TXD (Textures)

import { TxdParser } from 'rw-parser-ng';
import { readFileSync } from 'node:fs';

const buffer = readFileSync('textures.txd');
const parser = new TxdParser(buffer);
const txd = parser.parse();

for (const texture of txd.textureDictionary.textureNatives) {
    console.log(texture.textureName);    // Texture name
    console.log(texture.width, texture.height);
    console.log(texture.d3dFormat);      // DXT1, DXT3, DXT5, etc.
    console.log(texture.mipmaps[0]);     // Decoded BGRA pixel data
}

IFP (Animations)

import { IfpParser } from 'rw-parser-ng';
import { readFileSync } from 'node:fs';

const buffer = readFileSync('animation.ifp');
const parser = new IfpParser(buffer);
const ifp = parser.parse();

console.log(ifp.name);                   // Animation pack name
console.log(ifp.version);                // IfpVersion.ANP3 | ANPK

for (const anim of ifp.animations) {
    console.log(anim.name);              // Animation name
    for (const bone of anim.bones) {
        console.log(bone.name, bone.keyframes.length);
    }
}

FXP (Particle Effects)

import { parseFxpFile, parseFxpContent } from 'rw-parser-ng';

// From file path
const project = parseFxpFile('effects.fxp');

// From string content
const content = readFileSync('effects.fxp', 'utf-8');
const project = parseFxpContent(content);

for (const [name, system] of project.systems) {
    console.log(name, system.length);    // System name and duration
    for (const emitter of system.prims) {
        console.log(emitter.name, emitter.textures);
    }
}

Browser Usage

The library works in browsers with a Buffer polyfill (provided by bundlers like Webpack, Vite, or esbuild):

import { DffParser } from 'rw-parser-ng';

const response = await fetch('model.dff');
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(arrayBuffer);

const parser = new DffParser(buffer);
const dff = parser.parse();

API Reference

DFF Parser

The DffParser class parses RenderWare Clump structures:

interface RwDff {
    modelType: DffModelType;           // GENERIC, SKIN, or VEHICLE
    version: string;                   // Human-readable version
    versionNumber: number;             // Numeric version
    geometryList: RwGeometryList;      // Meshes with vertices, normals, UVs
    frameList: RwFrameList;            // Bone/node hierarchy
    atomics: number[];                 // Geometry-to-frame mapping
    dummies: string[];                 // Node names
    animNodes: RwAnimNode[];           // Animation node data
}

Geometry data includes:

• Vertex positions and normals
• Texture coordinates (multiple UV sets)
• Vertex colors
• Triangle indices
• Materials with textures
• BinMesh data for rendering
• Skin weights and bone matrices

TXD Parser

The TxdParser class parses texture dictionaries:

interface RwTextureNative {
    platformId: number;                // D3D8 (0x8) or D3D9 (0x9)
    textureName: string;
    maskName: string;
    width: number;
    height: number;
    depth: number;                     // Bits per pixel
    d3dFormat: string;                 // DXT1, DXT3, DXT5, etc.
    mipmaps: number[][];               // Decoded BGRA data
    alpha: boolean;
    compressed: boolean;
}

Supported texture formats:

• DXT1, DXT2, DXT3, DXT4, DXT5 (S3TC compression)
• Paletted 4-bit and 8-bit
• BGRA 8888, 888, 565, 555, 1555, 4444
• Luminance 8-bit, A8L8

IFP Parser

The IfpParser class parses animation files:

interface RwIfp {
    version: IfpVersion;               // ANP3 or ANPK
    name: string;
    animations: RwIfpAnimation[];
}

interface RwIfpKeyframe {
    time: number;
    position: RwVector3;
    rotation: RwQuaternion;
    scale: RwVector3;
}

FXP Parser

The FXP parser handles GTA San Andreas particle effect definitions:

interface FxProject {
    systems: Map<string, FxSystemBP>;
}

interface FxSystemBP {
    name: string;
    length: number;
    playMode: number;
    cullDist: number;
    boundingSphere: FxBoundingSphere;
    prims: FxEmitterBP[];
}

Supported effect info types: emrate, emsize, emspeed, emdir, emangle, emlife, empos, emweather, emrotation, noise, force, friction, attractpt, attractline, groundcollide, wind, jitter, rotspeed, float, underwater, colour, size, spriterect, heathaze, trail, flat, dir, animtex, colourrange, selflit, colourbright, smoke.

Project Structure

src/
├── core/           # Base classes: ByteStream, RwFile, section definitions
├── common/         # Shared types: vectors, matrices, colors, quaternions
├── codecs/         # Texture decoders: DXT, palette, raster formats
├── dff/            # DFF parser and geometry readers
├── txd/            # TXD parser and bitmap decoder
├── ifp/            # IFP parser (ANP3, ANPK readers)
└── fxp/            # FXP parser and info type handlers

Development

Requirements: Bun runtime

# Install dependencies
bun install

# Build
bun run build

# Watch mode
bun run dev

# Run tests
bun test

# Lint
bun run lint

# Format
bun run format

Contributing

Contributions are welcome. Please open an issue or submit a pull request.

When contributing:

1. Fork the repository
2. Create a feature branch
3. Ensure tests pass with bun test
4. Ensure code passes lint with bun run lint
5. Submit a pull request

Credits

• Timic3 - Original rw-parser author
• MegadreamsBE - Contributor
• AlterSDB - Contributor
• librw - RenderWare reference implementation
• gta-reversed - GTA SA reverse engineering

License

GPL-3.0 - See LICENSE for details.