{% extends "base.html" %} {% block body %}

Benami/Konami e-Amusement API

Why?

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).

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 httpac and xrpc*. 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.
*I believe xrpc is the officialy used name for the protocol.

These pages are very much a work in progress, and are being written as 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).

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.

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.

Code snippets

Across these pages there are a number of code snippets. They roughly break down into three categories:

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?).

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.

Contents

  1. Transport layer
    1. Packet structure
    2. Types
  2. The inner packet structure
    1. XML packets
    2. Binary packed packets
    3. Binary schemas
    4. Binary data
  3. Communication protocol details
  4. Let's write a server
    1. Groundwork
    2. Implementing handlers
    3. Extra endpoints
  5. Misc pages
    1. Parsing and converting card IDs

Getting started

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.

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.).

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).

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.

Next page {% endblock %}