TODO: Update

NeoSlippi

NeoSlippi is a C++ parser for .slp game replay files for Super Smash Brothers Melee. These replays are generated by Slippi recording code.

Installation

It is highly recommended to use NeoSlippi through vcpkg. Install with:

vcpkg install neoslippi

Or in manifest mode add "neoslippi" to your vcpkg.json dependencies.

Other methods of using NeoSlippi may work, but have not been tested and are not officially supported.

Usage

Object-based parsing:

#include <NeoSlippi/NeoSlippi.h>


int main() {
    neo_slippi::Game game = neo_slippi::game("game.slp");
}

Event-driven parsing:

#include <NeoSlippi/NeoSlippi.h>


class FramePrinter : public neo_slippi::Handlers {
    void framePost(neo_slippi::Post& post) override {
        std::cout << std::format("{}:{}\n", post.port.toString(), post.frameNumber);
    }
};

int main() {
    FramePrinter handlers;
    neo_slippi::parse("game.slp", handlers);
}

The game and parse functions are provided in three forms. The basic form takes a Reader parameter which controls how the replay file is read. This provides the most control over reading. The built-in readers are described below, and a custom reader may be provided. Additionally two convenience forms are provided taking a filename and a memory buffer respectively. Best performance may be achieved by using a memory-mapped file with a FixedBufferReader or the memory buffer form (which is a wrapper over FixedBufferReader).

Options

Both APIs provide several options to control the parsing behavior. These may be found in Options.h.

• rollback: When a frame is rollbacked are found in a replay found, controls whether the FIRST, LAST, or ALL versions of the frame are returned. (Default LAST)
• interestedEvents: You may specify which events you are interested in. Only those events will be returned. Parsing fewer events speeds up parsing. (Default ALL)
• fullwidthToHalfwidth: When Shift JIS strings are converted to UTF-8, this option controls whether full-width Latin characters are converted to normal half-width characters. Does not affect full-width Japanese characters. (Default true)
• shiftJisErrorHandling: Controls the handling of errors in decoding ShiftJIS strings. THROW_EXCEPTIONS will raise an exception. GRACEFUL will map invalid character to U+FFFD (REPLACEMENT CHARACTER) or truncate the string.

Readers

A number of Readers are provided for compatibility with different file reading APIs. These may be found in the Reading directory.

• FixedBufferReader: Reads from an in-memory buffer, this buffer must be pre-loaded with the entire .slp file. May be used with memory mapped files, or by using any other file API to read the entire file into memory.
• IStreamReader: Works with C++-style std::istream. Should almost always be used with BufferedReader.
• FileReader: Works with C-style FILE*. Should almost always be used with BufferedReader.
• BufferedReader: Wraps another reader using a buffer to improve performance. This class does not support multi-threaded reading, but it is faster than the built-in buffering of std::istream or FILE*.

Exceptions

These exception types are thrown by this library.

• ParseException: Thrown when there is a problem parsing a .slp file.
• ReadException: Thrown when a file cannot be read.
• ShiftJisException: Indicates an error converting to or from ShiftJIS.
• NoKnownActionStateException: Indicates that a requested action does not exist for a given character.
• NoSuchColorException: Indicates that a requested color does not exist for a given character.

In additiona, std exceptions may be thrown in some cases.

Versions

This project will use a slightly modified semantic versioning scheme. The first two numbers will represent the major and minor version as usual. The second two numbers will represent the major and minor version of the .slp specification that is supported.

For example, the initial release of this project was 1.0.3.16, indicating that the initial release supported version 3.16.0 of the .slp specification.