modern-rbx-parser

A modern TypeScript library for parsing Roblox binary files (.rbxm, .rbxl) in Node.js or the browser. It extracts all instances, their properties and provides convenience helpers for retrieving Animation IDs, Sound IDs and other asset references. The parser is derived from the open‑source rbx-reader project with additional improvements and a more modern API.

Features

• Fast binary parsing of Roblox .rbxm/.rbxl files using a TypeScript implementation adapted from the original rbx-reader project.
• Instance tree and flat list of instances exposed via the returned InstanceRoot and array of Instance objects.
• Property accessors to get and set properties, traverse children, descendants and perform lookups by name or class.
• Animation and Sound ID extraction: find numeric asset identifiers in properties such as AnimationId and SoundId, regardless of whether they are written as a bare number or embedded in an rbxassetid:// URL.
• Extensible: register your own extractors via the additionalExtractors option to discover other kinds of asset references.
• TypeScript first: written in modern TypeScript with strict typings.
• CommonJS & ESM compatible: compile targets both module systems.

Installation

npm install modern-rbx-parser

This package has no runtime dependencies. It can be used both in Node.js and in browser environments that support ArrayBuffer and typed arrays.

Quick start

import { parseBuffer } from 'modern-rbx-parser';

// Read a .rbxm file into an ArrayBuffer (in Node.js)
const fs = require('node:fs');
const buf = fs.readFileSync('./path/to/your/file.rbxm');

// Parse the binary and extract assets
const { root, instances, assets } = parseBuffer(buf.buffer);

console.log(`Found ${instances.length} instances`);
console.log('Animation IDs:', assets.animationIds);
console.log('Sound IDs:', assets.soundIds);

For browsers, fetch the binary file into an ArrayBuffer (e.g. via fetch() and arrayBuffer()) and pass it directly to parseBuffer().

Custom asset extraction

You can register custom extractors to pull out other kinds of asset references. An extractor is a function that receives each instance and returns an array of numeric IDs. For example, to extract Mesh asset IDs you could do the following:

const options = {
  additionalExtractors: {
    meshIds: (inst) => {
      const ids = [];
      if (inst.ClassName === 'MeshPart' && typeof inst.MeshId === 'string') {
        ids.push(...inst.MeshId.match(/\d{3,}/g).map(Number));
      }
      return ids;
    }
  }
};
const { assets } = parseBuffer(buffer, options);
console.log('Mesh IDs:', assets.meshIds);

Limitations

• Binary only: the parser currently supports the binary format. XML formatted Roblox files are not supported.
• Attributes not decoded: the original rbx-reader project includes a WASM module for decoding the AttributesSerialize property. That functionality has been removed here for simplicity. The raw attribute buffer is stored as a property; you can implement your own decoder and populate instance.Attributes if needed.
• Experimental: this library has not been battle‑tested on a wide variety of Roblox assets. Please report bugs or contribute fixes via GitHub.

License

This project is licensed under the GNU General Public License v3.0 or later. It is a derivative of the rbx-reader project, which is also GPL‑licensed.