# 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

```ts
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:

```ts
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.