<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>README.md - fork/slippc @ 0.7.1</title>
<meta name="description" content="README.md in fork/slippc at 0.7.1.">
<meta property="og:title" content="README.md - fork/slippc @ 0.7.1">
<meta property="og:description" content="README.md in fork/slippc at 0.7.1.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="0.7.1" data-tip="62d6bb0e6fbcb7a53789c42365871971ca6ad5ab">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/slippc</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/slippc</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Patrick Crain</span><span class="commit-message" data-commit="7d49c2f5e4846ea498b4dd44ea41bc928cf31035">Added documentation to replay.h; updated readme and changelog; minor tweaks to output of parser and analyzer, including original input filename; bumped parser and analyzer versions to 0.7.0</span><span class="snapshot-sha sha" data-commit="7d49c2f5e4846ea498b4dd44ea41bc928cf31035">7d49c2f</span><time datetime="2021-03-21T13:39:32-05:00" title="2021-03-21 13:39:32 -0500">2021-03-21</time></p>
<header class="topbar"><details class="switcher"><summary>0.7.1</summary><div class="menu"><strong>branches</strong><a href="/fork/slippc/ref/bench/">bench</a><a href="/fork/slippc/ref/compression/">compression</a><a href="/fork/slippc/ref/master/">master</a><a href="/fork/slippc/ref/testing/">testing</a><strong>tags</strong><a href="/fork/slippc/ref/0.4.0/">0.4.0</a><a href="/fork/slippc/ref/0.5.0/">0.5.0</a><a href="/fork/slippc/ref/0.6.0/">0.6.0</a><a href="/fork/slippc/ref/0.6.1/">0.6.1</a><a href="/fork/slippc/ref/0.7.0/">0.7.0</a><a class="current" href="/fork/slippc/ref/0.7.1/">0.7.1</a><a href="/fork/slippc/ref/0.8.0/">0.8.0</a><a href="/fork/slippc/ref/0.8.1/">0.8.1</a><a class="all" href="/fork/slippc/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/slippc/">slippc</a> / <span class="cur">README.md</span></nav>
<span class="view-stats"><span>10.0 KiB</span><span>95 lines</span></span><span class="actions"><a class="raw" href="/fork/slippc/raw/5b7ca74a6fdf10ea4c3826beacda82c04db4f16c/README.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1><strong>slippc</strong> - A Slippi replay (.slp) parser, compressor, JSON converter, and basic analysis program written in C++</h1>
<p>Supports replays up to version 3.7.0. Last updated 2021-03-21. <a href="/fork/slippc/ref/0.7.1/blob/changelog.md">View Change Log</a></p>
<h2>Requirements</h2>
<ul>
<li><em>make</em> and <em>g++</em>, for building <em>slippc</em></li>
<li>[optional] liblzma (a static v5.2.5 library is bundled, run <code>make static</code> to build)</li>
</ul>
<h2>Usage</h2>
<pre>    Usage: slippc -i &lt;infile&gt; [-x | -X &lt;zlpfile&gt;] [-j &lt;jsonfile&gt;] [-a &lt;analysisfile&gt;] [-f] [-d &lt;debuglevel&gt;] [-h]:
      -i     Parse and analyze &lt;infile&gt; (not very useful on its own)
      -j     Output &lt;infile&gt; in .json format to &lt;jsonfile&gt;
      -a     Output an analysis of &lt;infile&gt; in .json format to &lt;analysisfile&gt; (use &quot;-&quot; for stdout)
      -f     When used with -j &lt;jsonfile&gt;, write full frame info (c.f. frame deltas)
      -x     Compress or decompress a replay
      -X     Set output file name for compression
      -d     Run in debug mode (show debug output)
      -h     Show this help message
</pre>
<h2>Basic Overview</h2>
<p><em>slippc</em> aims to be a fast Slippi replay (.slp file) parser, with four primary functions.
First, for those wishing to write their own analysis code in C++, it aims to be a library for storing and manipulating .slp replay files.
Second, to aid with external analysis, it aims to be a converter between the .slp file's internal UBJSON format (which often requires external libraries to parse) into a more human-friendly and readily-parseable JSON format (which most modern languages support natively).
Third, for those wishing to archive their replays, it aims to take advantage of replay file structure to efficiently compress .slp files faster and smaller than any general purpose compression tools.
Finally, for those wishing to analyze hundreds or thousands of .slp replay files relatively quickly, it aims to be a basic replay analysis tool in its own right.</p>
<p><strong>NOTE</strong>: currently, slippc does not function as a standalone library, so manual confirguration is required to use the <em>SlippiReplay</em> struct</p>
<p>For all functions, the <em>Parser</em> class does the job of converting the raw .slp file from UBJSON into an internal data structure in the form of the <em>SlippiReplay</em> struct. Per Fizzi's specifications, the parser is backwards compatibile, handling and skipping unknown events gracefully. For the most part, a <em>SlippiReplay</em> contains the exact same data as is stored in the .slp file: the biggest changes from the raw .slp file include 1) conversions from big-endian types (as used by the Gamecube and stored in UBJSON) to little-endian types (as used in the x86 / x86_64 architectures most modern computers run on), 2) type changes for some other variables (e.g., the Slippi version number is stored as a string rather than as 4 separate bytes), and 3) reorganization of events.</p>
<p>The reorganization of events is the biggest difference between the .slp file structure and the internal <em>SlippiReplay</em> struct.
In brief, data from the "Game Start" and "Game End" events -- as well as data from the "metadata" section of the replay file -- are combined and stored at the top level of the <em>SlippiReplay</em> struct.
Similarly, the "Pre Frame Update" and "Post Frame Update" events at each frame are combined and stored as an array of <em>SlippiFrame</em>s for each player, which in turn are represented with the internal structure <em>SlippiPlayer</em>.
Data that occurs in both the pre-frame and post-frame events have "_pre" and "_post" respectively appended to their field names within the <em>SlippiFrame</em> struct.
Item data is likewise tracked separately by item spawn ID with the internal <em>SlippiItem</em> struct, each of which contains information about items at individual frames stored in the <em>SlippiItemFrame</em> struct.
The top-level <em>SlippiReplay</em> contains 8 slots for <em>SlippiPlayer</em>s, with slots 0-3 corresponding to ports 1-4 and slots 4-7 corresponding to the 2nd Ice Climber for ports 1-4 respectively. Unused slots (either empty ports for slots 0-3 or non-Icies for slots 4-7) contain undefined data.</p>
<h2>Compression</h2>
<p>Passing the -x option to <em>slippc</em> will compress an input .slp file specified with -i to a .zlp file. <em>slippc</em> uses a combination of delta coding, predictive coding, event shuffling, and column shuffling to encode raw .slp files, then compresses them using LZMA compression. Passing the -x option to <em>slippc</em> and a compressed .zlp file with -i will decompress the file to a normal .slp file. To explicitly specify an output filename, you can pass -X [outfilename].</p>
<p><em>slippc</em> validates all compressed files by decompressing them in memory and verifying the decoded file matches the original file. If for whatever reason this decode fails, no .zlp file will be created. As an additional failsafe, <em>slippc</em> will never delete any original files, and will refuse to overwrite existing files if there is a filename conflict.</p>
<p>Compression currently works for all replays between version 1.4.0 and 3.7.0, thought it cannot and will not compress corrupt replay files. Typical compression rates range from 93-97% for most normal replays. Compressed .zlp files may be loaded through <em>slippc</em> for parsed JSON and analysis JSON output.</p>
<h2>JSON Output</h2>
<p>Passing the -j option to <em>slippc</em> will output the .slp file specified with -i as a .json file, which may be opened in any text editor and inspected directly, or further parsed and analyzed using any JSON parser. Most data is presented in integer or float format, as stored in the .slp file. Major additions include the "game_start_raw" field, which is a base64 encoding of Melee's internal structure for initializing a new game, and the "parser_version" field, which describes the semantic versioning version number of the <em>slippc</em> parser used to generate the file. By default, to keep file sizes down, <em>slippc</em> only records deltas between frames (i.e., fields that change) for each player; by passing the -f option, <em>slippc</em> will output a .json with all data at each frame intact, including unchanged fields. The top-level "frame_count" field specifies the total number of frames in each player's "frames" field, with "first_frame" designating Melee's internal frame counter for the first frame (always -123), and "last_frame" designating the final frame of the game.</p>
<h2>Analysis</h2>
<p>Passing the -a option to <em>slippc</em> will perform a basic analysis of the .slp file specified with -i as a .json file (or directly to the console if "-" is passed instead of a filename). Most of the fields are fairly self-explanatory. The "punishes" field for each player contains a list of all combos / techchases / strings performed by the player throughout the duration of the match, along with some very basic statistics about each. The "interactions" field specifies the number of frames each player spent in each interaction state, as described below:</p>
<p><strong>NOTE</strong>: The analyzer assumes each analyzed match is played according to singles tournament settings (2 players, 8 minute timer, 4 stocks, tournament legal stages, no glitch characters). Though it may still work in some cases, analyzer behavior is currently undefined for matches played with non-tournament settings or in teams mode.</p>
<p><strong>NOTE</strong>: The output of some fields (such as neutral wins and combo / string counts) may be different than what is shown, e.g., in the Slippi Replay Browser. This discrepancy is due to differences in the way <em>slippc</em> infers game dynamics and computes certain statistics compared to Fizzi's node.js analyzer.</p>
<h3>Neutral Interactions</h3>
<p>The following are considered neutral states; frame counts should be identical for both players:</p>
<ul>
<li>NEUTRAL: generic neutral state; should always be 0</li>
<li>POSITIONING: players are far apart, and neither player has recently been in hitstun</li>
<li>FOOTSIES: players are close together, and neither player has recently been in hitstun</li>
<li>POKING: one or both players have recently entered hitstun from a single attack</li>
<li>TRADING: both players are currently in hitstun</li>
</ul>
<h3>Offensive &lt;-&gt; Defensive interactions</h3>
<p>The following offensive states are listed with their corresponding defensive states; frame counts should be symmetric for both players:</p>
<ul>
<li>OFFENSIVE &lt;-&gt; DEFENSIVE: generic offensive / defensive states; should always be 0</li>
<li>PRESSURING &lt;-&gt; PRESSURED: the pressuring player has landed a grab in neutral or on defense, or the pressured player is in shield stun</li>
<li>PUNISHING &lt;-&gt; PUNISHED: the player being punished has been in hitstun at least twice in a short period without landing a hit</li>
<li>SHARKING &lt;-&gt; GROUNDING: the grounding player has not touched the ground since last entering hitstun</li>
<li>TECHCHASING &lt;-&gt; ESCAPING: the techchasing player landed a grab while on offense, or the escaping player is in a tech or missed-tech state</li>
<li>EDGEGUARDING &lt;-&gt; RECOVERING: the recovering player has recently been in hitstun while off stage and has not since landed or grabbed ledge</li>
</ul>
<h2>Future Plans</h2>
<ul>
<li>Compile to an actual library so the parser can be used by other programs</li>
<li>Make analyzer more robust (meta-analysis for multiple replays, full support for Ice Climbers, analyzing games with more than 2 players, etc.)</li>
</ul>
<h2>Credits</h2>
<ul>
<li><a href="https://github.com/JLaferri">Fizzi</a>, for creating Slippi in the first place and for writing the node.js code as a reference for how to parse and analyze the .slp files</li>
<li><a href="https://github.com/NikhilNarayana">Nikki</a>, for substantial work on Slippi and help answering several questions related to the Slippi code base</li>
<li><a href="https://github.com/andrew-epstein">Andrew Epstein</a>, for helping debug and fix a number of crashes</li>
<li><a href="https://github.com/hohav">melkor</a>, for the original idea to shift replays to a columnar representation for better compression</li>
<li><a href="https://github.com/b3nd3r-ssbm">b3nd3r-ssbm</a>, for code contributions to make sure things work on Windows</li>
<li><a href="https://github.com/cbartsch">cbartsch</a>, for miscellaneous code fixes</li>
</ul>
<h2>References</h2>
<ul>
<li><a href="https://github.com/project-slippi/project-slippi">Project Slippi's main GitHub page</a></li>
<li><a href="https://github.com/project-slippi/slippi-wiki/blob/master/SPEC.md">Fizzi's .slp replay file specifications</a></li>
<li><a href="https://docs.google.com/spreadsheets/d/1JX2w-r2fuvWuNgGb6D3Cs4wHQKLFegZe2jhbBuIhCG8/edit">SSBM 1.02 data sheet</a> (contains state info, internal game IDs, and other Melee stuff)</li>
</ul>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>**slippc** - A Slippi replay (.slp) parser, compressor, JSON converter, and basic analysis program written in C++</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">Supports replays up to version 3.7.0. Last updated 2021-03-21. [View Change Log](./changelog.md)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"><a-p>##</a-p> <a-tt>Requirements</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"><a-p>  * </a-p>_make_ and _g++_, for building _slippc_</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">  <a-p>* </a-p>[optional] liblzma (a static v5.2.5 library is bundled, run `make static` to build)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text"><a-p>## </a-p><a-tt>Usage</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"><a-p>    Usage: slippc -i &lt;infile&gt; [-x | -X &lt;zlpfile&gt;] [-j &lt;jsonfile&gt;] [-a &lt;analysisfile&gt;] [-f] [-d &lt;debuglevel&gt;] [-h]:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"><a-p>      -i     Parse and analyze &lt;infile&gt; (not very useful on its own)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"><a-p>      -j     Output &lt;infile&gt; in .json format to &lt;jsonfile&gt;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"><a-p>      -a     Output an analysis of &lt;infile&gt; in .json format to &lt;analysisfile&gt; (use &quot;-&quot; for stdout)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"><a-p>      -f     When used with -j &lt;jsonfile&gt;, write full frame info (c.f. frame deltas)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"><a-p>      -x     Compress or decompress a replay</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"><a-p>      -X     Set output file name for compression</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"><a-p>      -d     Run in debug mode (show debug output)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-p>      -h     Show this help message</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>## </a-p><a-tt>Basic Overview</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"><a-p>_slippc_ aims to be a fast Slippi replay (.slp file) parser, with four primary functions.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"><a-p>First, for those wishing to write their own analysis code in C++, it aims to be a library for storing and manipulating .slp replay files.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p>Second, to aid with external analysis, it aims to be a converter between the .slp file&#39;s internal UBJSON format (which often requires external libraries to parse) into a more human-friendly and readily-parseable JSON format (which most modern languages support natively).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"><a-p>Third, for those wishing to archive their replays, it aims to take advantage of replay file structure to efficiently compress .slp files faster and smaller than any general purpose compression tools.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>Finally, for those wishing to analyze hundreds or thousands of .slp replay files relatively quickly, it aims to be a basic replay analysis tool in its own right.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>**NOTE**: currently, slippc does not function as a standalone library, so manual confirguration is required to use the *SlippiReplay* struct</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"><a-p>For all functions, the *Parser* class does the job of converting the raw .slp file from UBJSON into an internal data structure in the form of the *SlippiReplay* struct. Per Fizzi&#39;s specifications, the parser is backwards compatibile, handling and skipping unknown events gracefully. For the most part, a *SlippiReplay* contains the exact same data as is stored in the .slp file: the biggest changes from the raw .slp file include 1) conversions from big-endian types (as used by the Gamecube and stored in UBJSON) to little-endian types (as used in the x86 / x86_64 architectures most modern computers run on), 2) type changes for some other variables (e.g., the Slippi version number is stored as a string rather than as 4 separate bytes), and 3) reorganization of events.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-p>The reorganization of events is the biggest difference between the .slp file structure and the internal *SlippiReplay* struct.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"><a-p>In brief, data from the &quot;Game Start&quot; and &quot;Game End&quot; events -- as well as data from the &quot;metadata&quot; section of the replay file -- are combined and stored at the top level of the *SlippiReplay* struct.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>Similarly, the &quot;Pre Frame Update&quot; and &quot;Post Frame Update&quot; events at each frame are combined and stored as an array of *SlippiFrame*s for each player, which in turn are represented with the internal structure *SlippiPlayer*.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"><a-p>Data that occurs in both the pre-frame and post-frame events have &quot;\_pre&quot; and &quot;\_post&quot; respectively appended to their field names within the *SlippiFrame* struct.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"><a-p>Item data is likewise tracked separately by item spawn ID with the internal *SlippiItem* struct, each of which contains information about items at individual frames stored in the *SlippiItemFrame* struct.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"><a-p>The top-level *SlippiReplay* contains 8 slots for *SlippiPlayer*s, with slots 0-3 corresponding to ports 1-4 and slots 4-7 corresponding to the 2nd Ice Climber for ports 1-4 respectively. Unused slots (either empty ports for slots 0-3 or non-Icies for slots 4-7) contain undefined data.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"><a-p>## </a-p><a-tt>Compression</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>Passing the -x option to _slippc_ will compress an input .slp file specified with -i to a .zlp file. _slippc_ uses a combination of delta coding, predictive coding, event shuffling, and column shuffling to encode raw .slp files, then compresses them using LZMA compression. Passing the -x option to _slippc_ and a compressed .zlp file with -i will decompress the file to a normal .slp file. To explicitly specify an output filename, you can pass -X [outfilename].</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>_slippc_ validates all compressed files by decompressing them in memory and verifying the decoded file matches the original file. If for whatever reason this decode fails, no .zlp file will be created. As an additional failsafe, _slippc_ will never delete any original files, and will refuse to overwrite existing files if there is a filename conflict.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>Compression currently works for all replays between version 1.4.0 and 3.7.0, thought it cannot and will not compress corrupt replay files. Typical compression rates range from 93-97% for most normal replays. Compressed .zlp files may be loaded through _slippc_ for parsed JSON and analysis JSON output.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"><a-p>## </a-p><a-tt>JSON Output</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>Passing the -j option to _slippc_ will output the .slp file specified with -i as a .json file, which may be opened in any text editor and inspected directly, or further parsed and analyzed using any JSON parser. Most data is presented in integer or float format, as stored in the .slp file. Major additions include the &quot;game\_start\_raw&quot; field, which is a base64 encoding of Melee&#39;s internal structure for initializing a new game, and the &quot;parser\_version&quot; field, which describes the semantic versioning version number of the _slippc_ parser used to generate the file. By default, to keep file sizes down, _slippc_ only records deltas between frames (i.e., fields that change) for each player; by passing the -f option, _slippc_ will output a .json with all data at each frame intact, including unchanged fields. The top-level &quot;frame_count&quot; field specifies the total number of frames in each player&#39;s &quot;frames&quot; field, with &quot;first\_frame&quot; designating Melee&#39;s internal frame counter for the first frame (always -123), and &quot;last\_frame&quot; designating the final frame of the game.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"><a-p>## </a-p><a-tt>Analysis</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"><a-p>Passing the -a option to _slippc_ will perform a basic analysis of the .slp file specified with -i as a .json file (or directly to the console if &quot;-&quot; is passed instead of a filename). Most of the fields are fairly self-explanatory. The &quot;punishes&quot; field for each player contains a list of all combos / techchases / strings performed by the player throughout the duration of the match, along with some very basic statistics about each. The &quot;interactions&quot; field specifies the number of frames each player spent in each interaction state, as described below:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>**NOTE**: The analyzer assumes each analyzed match is played according to singles tournament settings (2 players, 8 minute timer, 4 stocks, tournament legal stages, no glitch characters). Though it may still work in some cases, analyzer behavior is currently undefined for matches played with non-tournament settings or in teams mode.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"><a-p>**NOTE**: The output of some fields (such as neutral wins and combo / string counts) may be different than what is shown, e.g., in the Slippi Replay Browser. This discrepancy is due to differences in the way _slippc_ infers game dynamics and computes certain statistics compared to Fizzi&#39;s node.js analyzer.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>### </a-p><a-tt>Neutral Interactions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>  The following are considered neutral states; frame counts should be identical for both players:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"><a-p>  * NEUTRAL: generic neutral state; should always be 0</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>  * POSITIONING: players are far apart, and neither player has recently been in hitstun</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"><a-p>  * FOOTSIES: players are close together, and neither player has recently been in hitstun</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"><a-p>  * POKING: one or both players have recently entered hitstun from a single attack</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"><a-p>  * TRADING: both players are currently in hitstun</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"><a-p>### </a-p><a-tt>Offensive &lt;-&gt; Defensive interactions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"><a-p>  The following offensive states are listed with their corresponding defensive states; frame counts should be symmetric for both players:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"><a-p>  * OFFENSIVE &lt;-&gt; DEFENSIVE: generic offensive / defensive states; should always be 0</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"><a-p>  * PRESSURING &lt;-&gt; PRESSURED: the pressuring player has landed a grab in neutral or on defense, or the pressured player is in shield stun</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"><a-p>  * PUNISHING &lt;-&gt; PUNISHED: the player being punished has been in hitstun at least twice in a short period without landing a hit</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"><a-p>  * SHARKING &lt;-&gt; GROUNDING: the grounding player has not touched the ground since last entering hitstun</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"><a-p>  * TECHCHASING &lt;-&gt; ESCAPING: the techchasing player landed a grab while on offense, or the escaping player is in a tech or missed-tech state</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"><a-p>  * EDGEGUARDING &lt;-&gt; RECOVERING: the recovering player has recently been in hitstun while off stage and has not since landed or grabbed ledge</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"><a-p>## </a-p><a-tt>Future Plans</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text"><a-p>  * Compile to an actual library so the parser can be used by other programs</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"><a-p>  * Make analyzer more robust (meta-analysis for multiple replays, full support for Ice Climbers, analyzing games with more than 2 players, etc.)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"><a-p>## </a-p><a-tt>Credits</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"><a-p>  * [Fizzi](https://github.com/JLaferri), for creating Slippi in the first place and for writing the node.js code as a reference for how to parse and analyze the .slp files</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"><a-p>  * [Nikki](https://github.com/NikhilNarayana), for substantial work on Slippi and help answering several questions related to the Slippi code base</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"><a-p>  * [Andrew Epstein](https://github.com/andrew-epstein), for helping debug and fix a number of crashes</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"><a-p>  * [melkor](https://github.com/hohav), for the original idea to shift replays to a columnar representation for better compression</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"><a-p>  * [b3nd3r-ssbm](https://github.com/b3nd3r-ssbm), for code contributions to make sure things work on Windows</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"><a-p>  * [cbartsch](https://github.com/cbartsch), for miscellaneous code fixes</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"><a-p>## </a-p><a-tt>References</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"><a-p>  * [Project Slippi&#39;s main GitHub page](https://github.com/project-slippi/project-slippi)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"><a-p>  * [Fizzi&#39;s .slp replay file specifications](https://github.com/project-slippi/slippi-wiki/blob/master/SPEC.md)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"><a-p>  * </a-p>[SSBM 1.02 data sheet](https://docs.google.com/spreadsheets/d/1JX2w-r2fuvWuNgGb6D3Cs4wHQKLFegZe2jhbBuIhCG8/edit) (contains state info, internal game IDs, and other Melee stuff)</span></span></pre></div></div>
</main>
</body>
</html>
