docs/templates/pages/index.html
2022-01-12 21:12:23 +00:00

92 lines
6.0 KiB
HTML

{% 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 %}