@slippi/slippi-js
Version:
Official Project Slippi Javascript SDK
159 lines (102 loc) • 6.11 kB
Markdown
# `slippi-js`
[](https://npmjs.org/package/@slippi/slippi-js "View this project on npm")
[](https://github.com/project-slippi/slippi-js/actions/workflows/build.yml?query=branch%3Amaster)
[](https://coveralls.io/github/project-slippi/slippi-js)
[](https://github.com/project-slippi/slippi-js/blob/master/LICENSE)
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**
```bash
npm install @slippi/slippi-js
```
**With Yarn**
```bash
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**.
```js
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](./examples/browser-stream/)** 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 includes everything that is in the web export, but can also read files directly from disk using file paths **and** also accepts binary data. It also includes Node.js-specific features like console connections, and SLP file writing.
```js
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](./examples/realtime-file-reads/)** 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:
```js
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](./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](./examples/browser-stream/)
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](./examples/realtime-file-reads/)
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:
```javascript
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](./examples/realtime-file-reads/) for a complete implementation with file watching.
## Development
### Setup
```bash
git clone https://github.com/project-slippi/slippi-js
cd slippi-js
npm install
```
### Build
```bash
npm run build
```
You can also run `npm run watch` to continuously build whenever changes are detected.
### Test
```bash
npm run test
```