rw-parser-ng 2.1.1 → 2.3.0

package/README.md

@@ -1,88 +1,288 @@
 # RenderWare Binary Stream Parser NG
 
 [![npm](https://img.shields.io/npm/v/rw-parser-ng.svg)](https://www.npmjs.com/package/rw-parser-ng)
-[![NPM](https://img.shields.io/npm/l/rw-parser-ng.svg)](https://github.com/DepsCian/rw-parser-ng/blob/master/LICENSE)
+[![CI](https://github.com/DepsCian/rw-parser-ng/actions/workflows/test.yml/badge.svg)](https://github.com/DepsCian/rw-parser-ng/actions/workflows/test.yml)
+[![License: GPL-3.0](https://img.shields.io/npm/l/rw-parser-ng.svg)](https://github.com/DepsCian/rw-parser-ng/blob/master/LICENSE)
 
-Parses RenderWare files (`.dff`, `.txd`, `.ifp`) into a usable format.
+A TypeScript library for parsing RenderWare binary stream files used in GTA III, Vice City, and San Andreas.
 
-This is a fork of the original [rw-parser](https://github.com/Timic3/rw-parser) by Timic3, which is no longer active maintained. This version aims to continue development, fix bugs, and add new features.
+This is a maintained fork of [rw-parser](https://github.com/Timic3/rw-parser) by Timic3.
 
-## Features
+## Supported Formats
 
-*   **DFF (Model) Parsing:** Extracts geometry, materials, frames, and skinning data.
-*   **TXD (Texture Dictionary) Parsing:** Extracts texture information, including name, resolution and pixel data.
-*   **IFP (Animation) Parsing:** Extracts animation data, including bone names, keyframes, and timings.
-*   **Cross-Platform:** Works in both Node.js and modern web browsers.
-*   **TypeScript Support:** Fully typed for a better development experience.
+| 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
 
-Install `rw-parser-ng` using pnpm:
+```sh
+bun add rw-parser-ng
+```
 
-```bash
-pnpm install --save rw-parser-ng
+```sh
+npm install rw-parser-ng
 ```
 
 ## Usage
 
-### ES6 Module
-
-```javascript
-import { DffParser, TxdParser, IfpParser } from 'rw-parser-ng';
-import { readFileSync } from 'fs';
-
-// DFF
-const dffBuffer = readFileSync('path/to/your/model.dff');
-const dffParser = new DffParser(dffBuffer);
-const dffData = dffParser.parse();
-console.log(dffData);
-
-// TXD
-const txdBuffer = readFileSync('path/to/your/textures.txd');
-const txdParser = new TxdParser(txdBuffer);
-const txdData = txdParser.parse();
-console.log(txdData);
-
-// IFP
-const ifpBuffer = readFileSync('path/to/your/animation.ifp');
-const ifpParser = new IfpParser(ifpBuffer);
-const ifpData = ifpParser.parse();
-console.log(ifpData);
+### DFF (3D Models)
+
+```typescript
+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)
+
+```typescript
+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)
+
+```typescript
+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)
+
+```typescript
+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
 
-This library can also be used in the browser. You will need a bundler like Webpack or Rollup to handle the Node.js `Buffer` dependency.
+The library works in browsers with a Buffer polyfill (provided by bundlers like Webpack, Vite, or esbuild):
 
-```javascript
+```typescript
 import { DffParser } from 'rw-parser-ng';
 
-async function parseDffFromUrl(url) {
-    const response = await fetch(url);
-    const arrayBuffer = await response.arrayBuffer();
-    const buffer = Buffer.from(arrayBuffer); // Requires Buffer polyfill
+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:
+
+```typescript
+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:
 
-    const dffParser = new DffParser(buffer);
-    const dffData = dffParser.parse();
-    console.log(dffData);
+```typescript
+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:
 
-parseDffFromUrl('path/to/your/model.dff');
+```typescript
+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:
+
+```typescript
+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
 
-1.  Clone the repository: `git clone https://github.com/DepsCian/rw-parser-ng.git`
-2.  Install dependencies: `pnpm install`
-3.  Build the project: `pnpm run build`
-4.  Run tests: `pnpm test`
+Requirements: [Bun](https://bun.sh/) runtime
+
+```sh
+# Install dependencies
+bun install
 
-To watch for changes during development, use `pnpm run dev`.
+# 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 feel free to open an issue or submit a pull request.
+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](https://github.com/Timic3) - Original rw-parser author
+- [MegadreamsBE](https://github.com/MegadreamsBE) - Contributor
+- [AlterSDB](https://github.com/AlterSDB) - Contributor
+- [librw](https://github.com/aap/librw) - RenderWare reference implementation
+- [gta-reversed](https://github.com/gta-reversed/gta-reversed-modern) - GTA SA reverse engineering
 
 ## License
 
-This project is licensed under the GPL-3.0 License. See the [LICENSE](LICENSE) file for details.
+GPL-3.0 - See [LICENSE](LICENSE) for details.

package/lib/codecs/bitmap.d.ts

@@ -0,0 +1,6 @@
+export declare function bgra1555(data: Uint8Array, width: number, height: number): Uint8Array;
+export declare function bgra4444(data: Uint8Array, width: number, height: number): Uint8Array;
+export declare function bgra555(data: Uint8Array, width: number, height: number): Uint8Array;
+export declare function bgra565(data: Uint8Array, width: number, height: number): Uint8Array;
+export declare function bgra888(data: Uint8Array, width: number, height: number): Uint8Array;
+export declare function bgra8888(data: Uint8Array, width: number, height: number): Uint8Array;

package/lib/codecs/bitmap.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bgra1555 = bgra1555;
+exports.bgra4444 = bgra4444;
+exports.bgra555 = bgra555;
+exports.bgra565 = bgra565;
+exports.bgra888 = bgra888;
+exports.bgra8888 = bgra8888;
+var color_1 = require("./color");
+function bgra1555(data, width, height) {
+    var rgba = new Uint8Array(4 * width * height);
+    var offset = 0;
+    for (var i = 0; i < data.length; i += 2) {
+        var _a = (0, color_1.decode1555)((0, color_1.readUInt16LE)(data, i)), a = _a[0], r = _a[1], g = _a[2], b = _a[3];
+        rgba[offset++] = r;
+        rgba[offset++] = g;
+        rgba[offset++] = b;
+        rgba[offset++] = a;
+    }
+    return rgba;
+}
+function bgra4444(data, width, height) {
+    var rgba = new Uint8Array(4 * width * height);
+    var offset = 0;
+    for (var i = 0; i < data.length; i += 2) {
+        var _a = (0, color_1.decode4444)((0, color_1.readUInt16LE)(data, i)), a = _a[0], r = _a[1], g = _a[2], b = _a[3];
+        rgba[offset++] = r;
+        rgba[offset++] = g;
+        rgba[offset++] = b;
+        rgba[offset++] = a;
+    }
+    return rgba;
+}
+function bgra555(data, width, height) {
+    var rgba = new Uint8Array(4 * width * height);
+    var offset = 0;
+    for (var i = 0; i < data.length; i += 2) {
+        var _a = (0, color_1.decode555)((0, color_1.readUInt16LE)(data, i)), r = _a[0], g = _a[1], b = _a[2];
+        rgba[offset++] = r;
+        rgba[offset++] = g;
+        rgba[offset++] = b;
+        rgba[offset++] = 0xff;
+    }
+    return rgba;
+}
+function bgra565(data, width, height) {
+    var rgba = new Uint8Array(4 * width * height);
+    var offset = 0;
+    for (var i = 0; i < data.length; i += 2) {
+        var _a = (0, color_1.decode565)((0, color_1.readUInt16LE)(data, i)), r = _a[0], g = _a[1], b = _a[2];
+        rgba[offset++] = r;
+        rgba[offset++] = g;
+        rgba[offset++] = b;
+        rgba[offset++] = 0xff;
+    }
+    return rgba;
+}
+function bgra888(data, width, height) {
+    var rgba = new Uint8Array(4 * width * height);
+    for (var i = 0; i < data.length; i += 4) {
+        rgba[i] = data[i + 2];
+        rgba[i + 1] = data[i + 1];
+        rgba[i + 2] = data[i];
+        rgba[i + 3] = 0xff;
+    }
+    return rgba;
+}
+function bgra8888(data, width, height) {
+    var rgba = new Uint8Array(4 * width * height);
+    for (var i = 0; i < data.length; i += 4) {
+        rgba[i] = data[i + 2];
+        rgba[i + 1] = data[i + 1];
+        rgba[i + 2] = data[i];
+        rgba[i + 3] = data[i + 3];
+    }
+    return rgba;
+}

package/lib/codecs/color.d.ts

@@ -0,0 +1,6 @@
+export declare function readUInt16LE(buf: Uint8Array, offset: number): number;
+export declare function readUInt32LE(buf: Uint8Array, offset: number): number;
+export declare function decode565(bits: number): [number, number, number];
+export declare function decode555(bits: number): [number, number, number];
+export declare function decode1555(bits: number): [number, number, number, number];
+export declare function decode4444(bits: number): [number, number, number, number];

package/lib/codecs/color.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readUInt16LE = readUInt16LE;
+exports.readUInt32LE = readUInt32LE;
+exports.decode565 = decode565;
+exports.decode555 = decode555;
+exports.decode1555 = decode1555;
+exports.decode4444 = decode4444;
+function readUInt16LE(buf, offset) {
+    return buf[offset] | (buf[offset + 1] << 8);
+}
+function readUInt32LE(buf, offset) {
+    return buf[offset] | (buf[offset + 1] << 8) | (buf[offset + 2] << 16) | (buf[offset + 3] << 24);
+}
+function decode565(bits) {
+    var r = (bits >> 11) & 31;
+    var g = (bits >> 5) & 63;
+    var b = bits & 31;
+    return [(r << 3) | (r >> 2), (g << 2) | (g >> 4), (b << 3) | (b >> 2)];
+}
+function decode555(bits) {
+    return [
+        Math.round((((bits >> 10) & 31) * 255) / 31),
+        Math.round((((bits >> 5) & 31) * 255) / 31),
+        Math.round(((bits & 31) * 255) / 31),
+    ];
+}
+function decode1555(bits) {
+    return [
+        Math.round(((bits >> 15) & 1) * 255),
+        Math.round((((bits >> 10) & 31) * 255) / 31),
+        Math.round((((bits >> 5) & 31) * 255) / 31),
+        Math.round(((bits & 31) * 255) / 31),
+    ];
+}
+function decode4444(bits) {
+    return [
+        Math.round((((bits >> 12) & 15) * 255) / 15),
+        Math.round((((bits >> 8) & 15) * 255) / 15),
+        Math.round((((bits >> 4) & 15) * 255) / 15),
+        Math.round(((bits & 15) * 255) / 15),
+    ];
+}

package/lib/codecs/dxt.d.ts

@@ -0,0 +1,3 @@
+export declare function bc1(data: Uint8Array, width: number, height: number): Uint8Array;
+export declare function bc2(data: Uint8Array, width: number, height: number, premultiplied: boolean): Uint8Array;
+export declare function bc3(data: Uint8Array, width: number, height: number, premultiplied: boolean): Uint8Array;