slippi-js

This is the official Project Slippi Javascript SDK. It provides tools for parsing .slp files into structured data and can be used to compute stats. There are already many built-in stats that are computed by the library but the data provided can also be used to compute your own stats.

Installation

With NPM

npm install @slippi/slippi-js

With Yarn

yarn add @slippi/slippi-js

Browser vs Node.js

This library provides two separate entry points depending on your environment:

Default Export: @slippi/slippi-js (Browser/Web)

The default export is optimized for browser and web environments. It only accepts binary data as input (buffers, ArrayBuffers, Uint8Arrays, etc.) and cannot read files from disk.

import { SlippiGame } from "@slippi/slippi-js";

// Works with binary data
const arrayBuffer = await fetch("game.slp").then((r) => r.arrayBuffer());
const game = new SlippiGame(arrayBuffer);

// Will throw an error in the browser
const game = new SlippiGame("path/to/file.slp"); // ❌ Error!

💡 See the browser-stream example for a demo of real-time replay file stream processing in the browser.

Node.js Export: @slippi/slippi-js/node

The Node.js export is designed for server-side and Node.js environments. It can read files directly from disk using file paths and also accepts binary data. Additionally, it includes Node.js-specific features like console connections, file writing, and streaming utilities.

const { SlippiGame } = require("@slippi/slippi-js/node");
// or with ES modules:
// import { SlippiGame } from "@slippi/slippi-js/node";

// Works with file paths
const game = new SlippiGame("path/to/file.slp"); // ✅

// Also works with binary data
const buffer = fs.readFileSync("path/to/file.slp");
const game = new SlippiGame(buffer); // ✅

Additional Node.js-only exports:

• Console and Dolphin connection utilities for real-time game capture
• SlpFileWriter for creating .slp files

Rule of thumb: Use @slippi/slippi-js/node for Node.js applications and scripts. Use the default @slippi/slippi-js for browser/web applications.

💡 See the realtime-file-reads example for a Node.js script that monitors live games using file system watching.

Quick Start

Writing a Simple Script

1. Create a fresh directory on your disk
2. Inside this new directory, create a file called script.js
3. Fill the script.js file with the following contents:

const { SlippiGame } = require("@slippi/slippi-js/node");

const game = new SlippiGame("test.slp");

// Get game settings – stage, characters, etc
const settings = game.getSettings();
console.log(settings);

// Get metadata - start time, platform played on, etc
const metadata = game.getMetadata();
console.log(metadata);

// Get computed stats - openings / kill, conversions, etc
const stats = game.getStats();
console.log(stats);

// Get frames – animation state, inputs, etc
// This is used to compute your own stats or get more frame-specific info (advanced)
const frames = game.getFrames();
console.log(frames[0].players); // Print frame when timer starts counting down

4. Copy a .slp file into the directory and call it test.slp
5. Browse to the directory from the command line and run the command: npm install @slippi/slippi-js. This should create a node_modules directory in the folder.
6. Run the command: node script.js. This will run the script above and will print data about the test.slp file

💡 Tip: See the examples directory for more advanced usage including live file monitoring and browser-based replay processing.

Examples

The library supports processing replay files in real-time as they're being written. This is useful for live overlays, game monitoring, and analysis tools.

🌐 Browser Stream Example

Demonstrates processing replay files in a web browser with simulated streaming using the low-level SlpStream and SlpParser APIs. Perfect for understanding how to handle chunked data in browser environments.

Features: Interactive web UI, configurable chunk sizes, real-time event log, progress tracking

📂 Realtime File Reads Example

Demonstrates monitoring a directory for live .slp file changes and processing them as they're written using the high-level SlippiGame API in Node.js.

Features: File system watching, live game state (stocks/damage), incremental updates, game end detection

Reading Live Files

When reading files that are actively being written (e.g., during a live game), use the processOnTheFly option:

const { SlippiGame } = require("@slippi/slippi-js/node");

const game = new SlippiGame("path/to/live/file.slp", { processOnTheFly: true });

This allows the SlippiGame instance to read partial files and be re-read as new data becomes available. See the realtime-file-reads example for a complete implementation with file watching.

Development

Setup

git clone https://github.com/project-slippi/slippi-js
cd slippi-js
npm install

Build

npm run build

You can also run npm run watch to continuously build whenever changes are detected.

Test

npm run test