w3gjs

Asynchronous, fully typed TypeScript implementation of a WarCraft 3 replay (.w3g) parser.

You can use the subcomponents to build your own parser or use the high-level API for standard melee game analysis.

Note: Replays from game version <= 1.14 are not fully supported.

Live Demo

Try the browser-based replay parser — a web app built on top of w3gjs that runs entirely in the browser.

Installation

npm install w3gjs

Usage

See the examples folder for TypeScript usage examples.

For the full API reference, see the documentation.

Running the examples

Use tsx to run any example directly without a compile step:

npx tsx examples/highlevel.ts
npx tsx examples/lowlevel.ts
npx tsx examples/apm-analysis.ts

High Level API

Best suited for parsing standard melee replays.

import W3GReplay from "w3gjs";
const parser = new W3GReplay();
const result = await parser.parse("replay.w3g");
console.log(result);

const W3GReplay = require("w3gjs").default;
const parser = new W3GReplay();

(async () => {
  const result = await parser.parse("replay.w3g");
  console.log(result);
})().catch(console.error);

Low Level API

Extend ReplayParser or listen to its events to implement custom logic.

Two events are emitted:

• basic_replay_information — metadata parsed from the replay header
• gamedatablock — each game data block in order, fully parsed; check the id property to distinguish block types

const ReplayParser = require("w3gjs/dist/lib/parsers/ReplayParser").default;
const fs = require("fs");

(async () => {
  const buffer = fs.readFileSync("./reforged1.w3g");
  const parser = new ReplayParser();
  parser.on("basic_replay_information", (info) => console.log(info));
  parser.on("gamedatablock", (block) => console.log(block));
  await parser.parse(buffer);
})().catch(console.error);

Contributing

Contributions are welcome. Open an issue to discuss ideas or submit a pull request.

Issues

Please include an example replay file when reporting a parsing issue.

License

MIT