bemanitools/README.md

Bemanitools 5

Version: 5.40

Release history

A collection of tools to run various Bemani arcade games.

Bemanitools 5 (BT5) is the successor to Bemanitools 4 which introduces a big code cleanup and support for newer games. BT5 uses a cleaner approach than BT4 did; specifically, all input and lighting is handled by emulating the protocols spoken by the real IO PCBs, instead of replacing chunks of game code like BT4. The benefits of this approach are a more authentic gameplay experience, and easier support for a broader range of releases from each game series.

Documentation

Browse our documentation as it might already cover various questions and concerns you are looking for or about to ask.

Contributions and bug reporting

Read the dedicated CONTRIBUTING.md documentation.

The tl;dr version and golden rules of the sections in the document:

• EVERYONE can contribute, this is NOT limited to people coding
• Open an issue on gitlab for discussions, feature requests and bug reports
• ALWAYS report bugs as issues and ALWAYS use the available bug template
• Everyone is allowed to submit changes which are not just limited to code by opening merge requests
• Documentation improvements can and even should be contributed by non developers

List of supported games (hook libraries)

• BeatStream
  • BeatStream (bst.zip) using bsthook
  • BeatStream アニムトライヴ (bst.zip) using bsthook
• Dance Dance Revolution
  • Dance Dance Revolution X2 (ddr-12-to-16.zip) using ddrhook
  • Dance Dance Revolution X3 vs. 2ndMIX (ddr-12-to-16.zip) using ddrhook
  • Dance Dance Revolution 2013 (ddr-12-to-16.zip) using ddrhook
  • Dance Dance Revolution 2014 (ddr-12-to-16.zip) using ddrhook
  • Dance Dance Revolution A (ddr-12-to-16.zip) using ddrhook
• Beatmania IIDX
  • Beatmania IIDX 9th Style (iidx-09-to-12.zip) using iidxhook1
  • Beatmania IIDX 10th Style (iidx-09-to-12.zip) using iidxhook1
  • Beatmania IIDX 11 IIDX RED (iidx-09-to-12.zip) using iidxhook1
  • Beatmania IIDX 12 HAPPY SKY (iidx-09-to-12.zip) using iidxhook1
  • Beatmania IIDX 13 DistorteD (iidx-13.zip) using iidxhook2
  • Beatmania IIDX 14 GOLD (iidx-14-to-17.zip) using iidxhook3
  • Beatmania IIDX 15 DJ TROOPERS (iidx-14-to-17.zip) using iidxhook3
  • Beatmania IIDX 16 EMPRESS (iidx-14-to-17.zip) using iidxhook3
  • Beatmania IIDX 17 SIRIUS (iidx-14-to-17.zip) using iidxhook3
  • Beatmania IIDX 18 Resort Anthem (iidx-18.zip) using iidxhook4
  • Beatmania IIDX 19 Lincle (iidx-19.zip) using iidxhook5
  • Beatmania IIDX 20 Tricoro (iidx-20.zip) using iidxhook6
  • Beatmania IIDX 21 SPADA (iidx-21-to-24.zip) using iidxhook7
  • Beatmania IIDX 22 PENDUAL (iidx-21-to-24.zip) using iidxhook7
  • Beatmania IIDX 23 copula (iidx-21-to-24.zip) using iidxhook7
  • Beatmania IIDX 24 SINOBUZ (iidx-21-to-24.zip) using iidxhook7
  • Beatmania IIDX 25 CANNON BALLERS (iidx-25-to-26.zip) using iidxhook8
  • Beatmania IIDX 26 Rootage (iidx-25-to-26.zip) using iidxhook8
  • Beatmania IIDX 27 Heroic Verse (iidx-27-to-28.zip) using iidxhook9
  • Beatmania IIDX 28 BISTROVER (iidx-27-to-28.zip) using iidxhook9
• jubeat
  • jubeat (jb-01.zip) using jbhook1
  • jubeat ripples (jb-02.zip) using jbhook1
  • jubeat knit (jb-03.zip) using jbhook2
  • jubeat copious (jb-04.zip) using jbhook2
  • jubeat saucer (fulfill) (jb-05-to-07.zip) using jbhook3
  • jubeat prop (jb-05-to-07.zip) using jbhook3
  • jubeat qubell (jb-05-to-07.zip) using jbhook3
  • jubeat clan (jb-08.zip) using jbhook3
  • jubeat festo (jb-08.zip) using jbhook3
• SOUND VOLTEX
  • SOUND VOLTEX BOOTH (sdvx-01-to-04.zip) using sdvxhook
  • SOUND VOLTEX II -infinite infection- (sdvx-01-to-04.zip) using sdvxhook
  • SOUND VOLTEX III GRAVITY WARS (sdvx-01-to-04.zip) using sdvxhook
  • SOUND VOLTEX IV HEAVENLY HAVEN (sdvx-01-to-04.zip) using sdvxhook
  • SOUND VOLTEX Vivid Wave (sdvx-05-to-06) using sdvxhook2
  • SOUND VOLTEX EXCEED GEAR (sdvx-05-to-06) using sdvxhook2

ViGEm clients: Expose BT5 APIs as XBOX game controllers

Play your favorite non-bemani arcade games with any hardware, e.g. real cabinet hardware, that implements BT5 APIs.

See the dedicated readme for details.

Supported platforms

Our main platforms are currently Windows XP and Windows 7 which are also the target platforms on the original hardware of those games. However, as it gets more difficult to get and maintain hardware comptible with Windows XP, this might change in the future. Many games also run on very recent Windows 10 builds but bear with us that it's hard to keep up with Windows updates breaking legacy software.

Distribution contents

Check the list of supported games to grab the right files for your game. BT5 also includes a tools subpackage (tools.zip) as well as the full source code (src.zip).

You will find *.md files in various sub-packages that give you further instructions for setup, usage, error information or FAQ. We advice you to read them as your questions and concerns might already be answered by them. If not, let us know if there is any information that you consider helpful or important to know and should be added.

Setup and dependencies

Most (older generation) games were developed for Windows XP Embedded but should run fine on any consumer version of Windows XP. Newer versions of Windows, e.g. Windows 7, 8 and 10, should be fine as well. Some hooks also include fixes required to run the games on a more recent version.

Depending on the game, you also need the following dependencies installed:

• DirectX 9 runtime
• Microsoft Visual C++ Redistributables 2010 and 2013: Depends on the game and age but both should cover most if not all of the games so far

Development

Building

See the development document.

Architecture

A dedicate architecture document outlines the architecture of Bemanitools and points out the most important aspects you should know before you get started with development.

API

Please refer to the API documentation.

Release process

Steps for the release process:

1. Update the corresponding section in the changelog with bullet points reflecting major features merged into master since the previous release

2. Make sure you have the latest master state pulled to your local copy

3. Tag the release with the next release number which also be found at the top of the readme as it always reflects the current version beinged worked on on the master branch , e.g. 5.35: git tag 5.35

4. Push the tag to upstream: git push origin 5.35

5. The build pipeline should start automatically once the tag is pushed including the steps build and upload-release

6. Once completed successfully, the release is uploaded

7. Take the changelog of the published version and notify the pigs in the stall about it:

   1. New post in thread

      <insert version here> released: <direct link to published version>
      
      Changelog:
      <paste changelog here>
      

   2. Update the OP title by bumping the version number in it
   3. Update the OP post by extending it accordingly (see previous entries)

8. Bump the version number at the top of this readme and add a new empty section in the changelog with the new version number as title. Commit changes and push to master branch

9. Continue developing and merging MRs until you decide its time for another release

License

Source code license is the Unlicense; you are permitted to do with this as thou wilt. For details, please refer to the LICENSE file included with the source code.