{% extends "base.html" %}
{% block body %}
<h1>Benami/Konami e-Amusement API</h1>
<p>Why?</p>
<p>I was curious how these APIs work, yet could find little to nothing on Google. There are a number of
    closed-source projects, with presumably similarly closed-source internal documentation, and a scattering of
    implementations of things, yet I couldn't find a site that actually just documents how the API works. If I'm
    going to have to reverse engineer an open source project (or a closed source one, for that matter), I might as
    well just go reverse engineer an actual game (or it's stdlib, as most of my time has been spent currently).</p>
<p>For the sake of being lazy, I'll probably end up calling it eAmuse more than anything else throughout these
    pages. Other names you may come across include <code>httpac</code> and <code>xrpc</code>*. The former is the
    suite of HTTP functions used in the Bemani stdlib, and the latter then name of their communication protocol they
    implement at the application layer, but whenever someone refers to any of them in the context of a rhythm game,
    they will be referring to the things documented here.<br />
    <small style="margin-left: 8px">*I believe <code>xrpc</code> is the officialy used name for the protocol.</small>
</p>
<p>These pages are very much a work in progress, and are being written <i>as</i> I reverse engineer parts of the
    protocol. I've been asserting all my assumptions by writing my own implementation as I go, however it currently
    isn't sharable quality code and, more importantly, the purpose of these pages is to make implementation of one's
    own code hopefully trivial (teach a man to fish, and all that).</p>
<p>Sharing annotated sources for all of the games' stdlibs would be both impractical and unwise. Where relevant
    however I try to include snippets to illustrate concepts, and have included their locations in the source for if
    you feel like taking a dive too.</p>
<p>If you're here because you work on one of those aforementioned closed source projects, hello! Feel free to share
    knowledge with the rest of the world, or point out corrections. Or don't; you do you.</p>

<h3>Code snippets</h3>
<p>Across these pages there are a number of code snippets. They roughly break down into three categories:</p>
<ul>
    <li>Assembly: Directly disassembled code from game binaries</li>
    <li>C: Either raw decompilation, or slightly cleaned up decompilation</li>
    <li>Python: Snippets from my local testing implementations</li>
    <li>Pseudocode: Used to illustrate some points. Note that it probably started life as Python before being
        pseudo'd</li>
</ul>
<p>If you yoink chunks of Python code, attribution is always appreciated, but consider it under CC0 (just don't be
    that person who tries to take credit for it, yeah?).</p>
<p>Assembly and C snippets often come with an accompanying filename and address. If you're interested in learning how
    things work in more detail, I'd strongly recommend checking them out. Not all games come with the same version of
    files; the provided addresses are for build SDVX build KFC-2019020600, using the default base offset.</p>

<h2>Contents</h2>
<ol>
    <li><a href="./transport.html">Transport layer</a></li>
    <ol>
        <li><a href="./transport.html#packet">Packet structure</a></li>
        <li><a href="./transport.html#type">Types</a></li>
    </ol>
    <li><a href="./packet.html">The inner packet structure</a></li>
    <ol>
        <li><a href="./packet.html#xml">XML packets</a></li>
        <li><a href="./packet.html#binary">Binary packed packets</a></li>
        <li><a href="./packet.html#schema">Binary schemas</a></li>
        <li><a href="./packet.html#data">Binary data</a></li>
    </ol>
    <li><a href="./protocol.html">Communication protocol details</a></li>
    <ul>
        <li>There are a crazy number of sub pages here, so just go check the contents there.</li>
    </ul>
    <li><a href="./server.html">Let's write a server</a></li>
    <ol>
        <li><a href="./server.html#groundwork">Groundwork</a></li>
        <li><a href="./server.html#handlers">Implementing handlers</a></li>
        <li><a href="./server.html#extra">Extra endpoints</a></li>
    </ol>
    <li>Misc pages</li>
    <ol>
        <li><a href="./cardid.html">Parsing and converting card IDs</a></li>
    </ol>
</ol>

<h2>Getting started</h2>
<p>My aim with these pages is to cover as much as possible, so you don't need to try and figure them out yourself.
    That said, being able to follow along yourself will almost certainly help get more out of this. For following
    along with source code, you're really going to want to grab yourself a dumped copy of a game (it's going to be a
    lot easier, and cheeper, than dumping one yourself). I trust you can figure out where to find that.</p>
<p>For network related things, your options are a little broader. The ideal would be physical ownership of a
    cabinet, and a subscription to genuine e-amusement. Odds are you don't have both of those :P. A connection to an
    alternative network works just as well. In the more likely case that you don't have a physical cabinet, it's
    time to crack out that dumped copy of a game and just run it on your own PC (or a VM, if you're not on Windows)
    (odds are whatever you downloaded came with the program you'll need to start it pre-packaged. If not, it rhymes
    with rice.).</p>
<p>You will also need a local e-amusement-emulating server. By the time I'm done with these pages, there will
    hopefully be everything you need to be able to write your own. Unfortunately I'm not finished writing them;
    depending on where you acquired your game, it may have shipped with one of said servers. If it didn't, Asphyxia
    CORE will do the trick (yes, it's closed source).</p>
<p>If this all sounds like way too much work, and/or you're just here because of curiosity, I plan to prepare some
    pcaps of network traffic to play around with without needing a running copy of a game or a network tap on a cab.
</p>

<a href="./transport.html">Next page</a>
{% endblock %}