CppSlippi

CppSlippi 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 CppSlippi through vcpkg. Install with:

vcpkg install cppslippi

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

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

Usage

Object-based parsing:

#include <fstream>

#include <CppSlippi/CppSlippi.h>
#include <CppSlippi/Reading/BufferedReader.h>
#include <CppSlippi/Reading/IStreamReader.h>


int main() {
    cpp_slippi::reading::BufferedReader bufReader(
        cpp_slippi::reading::IStreamReader(
            std::ifstream("game.slp", std::ios::in | std::ios::binary)));

    cpp_slippi::Game game = cpp_slippi::game(bufReader);
}

Event-driven parsing:

#include <iostream>
#include <fstream>

#include <CppSlippi/CppSlippi.h>
#include <CppSlippi/Reading/BufferedReader.h>
#include <CppSlippi/Reading/IStreamReader.h>


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

int main() {
    cpp_slippi::reading::BufferedReader bufReader(
        cpp_slippi::reading::IStreamReader(
            std::ifstream("game.slp", std::ios::in | std::ios::binary)));

    FramePrinter handlers;
    cpp_slippi::parse(bufReader, handlers);
}

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.

• IStreamReader: Works with C++-style std::istream.
• FileReader: Works with C-style FILE*.
• 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.
• 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

Two 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 addition, 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.14, indicating that the initial release supported version 3.14.0 of the .slp specification.