Revert "Revert "chore: Bump to 5.50 for next development cycle""

This reverts commit db1f8ccda4.

.github/ISSUE_TEMPLATE/bug.md

@@ -1,37 +1,51 @@
+# Bug report
+
 ## Summary
+
 <!--- Provide a general summary of the issue in the Title above -->
 
 ## Expected behavior
+
 <!--- Tell us what should happen -->
 
 ## Current behavior
+
 <!--- Tell us what happens instead of the expected behavior -->
 
 ## Detailed Description
+
 <!--- Provide a detailed description of the issue. Include links to screenshots or videos if
 necessary -->
 
 ## Steps to reproduce
+
 <!-- Try running the game with a default configuration as well. If that also causes issues, please point that out here in the report. This might speed up the debugging process.-->
 
 <!--- Provide a detailed step by step description how to reproduce this issue -->
+
+1.
+1.
+1.
 1.
-2.
-3.
-4.
 
 ## Possible solution
+
 <!--- Not obligatory, but suggest a fix/reason for the bug, -->
 
 ## Context (Environment)
+
 ### Bemanitools version(s) affected
-* <!--- Add one or multiple versions as a bullet list -->
+
+- <!--- Add one or multiple versions as a bullet list -->
 
 ### Game(s) and version(s) affected
-* <!--- Add one or multiple game versions as a bullet list -->
+
+- <!--- Add one or multiple game versions as a bullet list -->
 
 ### Log output
+
 See attachment.
+
 <!---
 Provide FULL log output, e.g. inject.log or launcher.log. Please do not guess which things
 are relevant or not. Without knowing, you might leave out things that are relevant for the developers. You have to enable log output explicitly if not done already. 
@@ -50,7 +64,9 @@ Use the search and replace feature of any kind of text editor.
 -->
 
 ### Configuration files
+
 See attachment.
+
 <!--- Provide any configuration files that you used, e.g. iidxhook-XX.conf. This file is located in
 the same directory as launcher.exe or inject.exe. 
 
@@ -66,18 +82,22 @@ Use the search and replace feature of any kind of text editor.
 -->
 
 ### Command line arguments
+
 <!--- Provide how you run the game from the command line, e.g. which gamestart.bat you used and any
 additional arguments that you provided to it. Also provide the contents of the gamestart.bat you
 used if you altered it. -->
 
 ### APIs used
-* <!--- List all APIs you used as a bullet list, e.g. iidxio-keyboard, eamio-keyboard -->
+
+- <!--- List all APIs you used as a bullet list, e.g. iidxio-keyboard, eamio-keyboard -->
 
 ### OS version
+
 <!--- Provide the version of Windows you used with whatever update/build identifier -->
 
 ### Hardware specs
-* CPU: <!--- Insert, e.g. Core i7 2600k 3.20ghz -->
-* RAM: <!--- Insert, e.g. 16 GB -->
-* GPU: <!--- Insert, e.g. Nvidia GeForce GTX 970, 4GB -->
-* Controllers/IO: <!--- Insert, e.g. DJ Dao RE over USB -->
+
+- CPU: <!--- Insert, e.g. Core i7 2600k 3.20ghz -->
+- RAM: <!--- Insert, e.g. 16 GB -->
+- GPU: <!--- Insert, e.g. Nvidia GeForce GTX 970, 4GB -->
+- Controllers/IO: <!--- Insert, e.g. DJ Dao RE over USB -->

.github/ISSUE_TEMPLATE/feature.md

@@ -1,14 +1,21 @@
+# Feature request
+
 ## Summary
+
 <!--- Provide a general summary of your changes in the Title above -->
 
 ## Detailed description
+
 <!--- Describe your feature in detail -->
 
 ## Benefits
+
 <!--- Describe the value/benefits of the feature in detail -->
 
 ## Drawbacks
+
 <!--- Describe any drawbacks that might be introduced with this feature -->
 
 ## Current blockers
-<!--- Describe any blockers that need to be resolved before implementing this feature -->
+
+<!--- Describe any blockers that need to be resolved before implementing this feature -->

.github/PULL_REQUEST_TEMPLATE/pull-request.md

@@ -1,27 +1,41 @@
+# Pull request
+
 ## Summary
+
 <!--- Provide a general summary of your changes in the Title above -->
 
 ## Description
+
 <!--- Describe your changes in detail -->
 
 ## Related Issue
+
 <!--- This project only accepts pull requests related to open issues -->
+
 <!--- If suggesting a new feature or change, please discuss it in an issue first -->
+
 <!--- If fixing a bug, there should be an issue describing it with steps to reproduce -->
+
 <!--- Please link to the issue here: -->
 
 ## How Has This Been Tested?
+
 <!--- Please describe in detail how you tested your changes. -->
+
 <!--- Include details of your testing environment, and the tests you ran to -->
+
 <!--- see how your change affects other areas of the code, etc. -->
 
 ## Checklist
+
 <!-- Make sure you covered all items, which apply, of the checklist below. -->
+
 <!-- Strikethrough items that do not apply and provide a brief description why. -->
-* [ ] Implemented (unit) test(s) which prove that the introduced changes are working as expected.
-* Tested with the following games:
-    * [ ] ... <!-- insert game name 1-->
-    * [ ] ... <!-- insert game name 2--->
-* [ ] Followed the developer (style) guidelines.
-* [ ] Updated existing doc of or add new doc to README file(s).
-* [ ] Updated development documentation.
+
+- \[ \] Implemented (unit) test(s) which prove that the introduced changes are working as expected.
+- Tested with the following games:
+  - \[ \] ... <!-- insert game name 1-->
+  - \[ \] ... \<!-- insert game name 2--->
+- \[ \] Followed the developer (style) guidelines.
+- \[ \] Updated existing doc of or add new doc to README file(s).
+- \[ \] Updated development documentation.

.github/workflows/build-master.yaml

@@ -0,0 +1,39 @@
+name: "Build bemanitools"
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: "ubuntu-22.04"
+    steps:
+      - name: "Checkout repository"
+        uses: "actions/checkout@v2"
+
+      - name: "Install prerequisites"
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y runc containerd docker.io
+
+      - name: "Build"
+        run: |
+          make build-docker
+
+      # Do some unpacking of the dist zip. Artifact upload repackages stuff
+      - name: "Prepare artifact package"
+        run: |
+          mkdir artifact
+          cd artifact
+          unzip ../build/bemanitools.zip
+          cd ..
+
+      - name: "Upload artifact"
+        uses: "actions/upload-artifact@v4"
+        with:
+          name: bemanitools-${{ github.sha }}
+          retention-days: 90
+          if-no-files-found: "error"
+          path: |
+            artifact/**

.github/workflows/build-tag.yaml

@@ -0,0 +1,75 @@
+name: "Build bemanitools and publish release"
+
+permissions:
+  contents: write
+  packages: write
+
+on:
+  push:
+    tags:
+      - "*.*"
+
+jobs:
+  build:
+    runs-on: "ubuntu-22.04"
+    steps:
+      - name: "Checkout repository"
+        uses: "actions/checkout@v2"
+
+      # Building bootstrapped using docker containers
+      - name: "Install prerequisites"
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y runc containerd docker.io
+      
+      - name: "Build"
+        run: |
+          make build-docker
+
+      # Do some unpacking of the dist zip. Artifact upload repackages stuff
+      - name: "Prepare artifact package"
+        run: |
+          mkdir artifact
+          cd artifact
+          unzip ../build/bemanitools.zip
+          cd ..
+
+      - name: "Upload artifact"
+        uses: "actions/upload-artifact@v4"
+        with:
+          name: bemanitools-${{ github.sha }}
+          retention-days: 90
+          if-no-files-found: "error"
+          path: |
+            artifact/**
+
+  publish-release:
+    needs: "build"
+    runs-on: "ubuntu-22.04"
+    steps:
+      # This already extracts the contents of the artifact
+      - name: "Download artifact"
+        uses: "actions/download-artifact@v4"
+        with:
+          name: bemanitools-${{ github.sha }}
+
+      - name: "Get the version"
+        id: get_version
+        run: |
+          echo ::set-output name=VERSION::$(echo $GITHUB_REF | cut -d / -f 3)
+
+      # The publish release action does not package the artifact *sigh*
+      - name: "Create release package"
+        run: |
+          zip bemanitools-${{ steps.get_version.outputs.VERSION }}.zip *
+
+      - name: "Publish release"
+        uses: "marvinpinto/action-automatic-releases@v1.2.1"
+        with:
+          repo_token: "${{ secrets.GITHUB_TOKEN }}"
+          automatic_release_tag: "latest"
+          draft: false
+          prerelease: true
+          title: ${{ steps.get_version.outputs.VERSION }}
+          files: |
+            bemanitools-${{ steps.get_version.outputs.VERSION }}.zip

.gitignore

@@ -3,4 +3,5 @@ build/
 .idea
 .vscode
 .vs
-version
+version
+.DS_Store

.gitlab-ci.yml

@@ -1,136 +0,0 @@
-#
-# This pipeline requires packages to be switched on under the repository settings. Otherwise, you will 403s when
-# uploading to the package repo is triggered.
-#
-# Variables to setup in GitLab CI/CD settings of the project
-# 
-# The variables with BASE64 postfixes need to contain the base64 encoded data. Otherwise, masking
-# in GitLab won't work due to not matching their pre-defined regex 
-#
-# CI_PIGSTALL_DATA_PREFIX_BASE64
-# CI_PIGSTALL_LINK_BASE64
-# CI_PIGSTALL_PHP_SESSION_ID
-# CI_PIGSTALL_SESSION_BASE64
-# 
-# CI_TOOLS_UPLOAD_KEY
-# CI_TOOLS_UPLOAD_URL
-# CI_TOOLS_URL
-
-image: docker:stable
-
-variables:
-    DOCKER_TLS_CERTDIR: "/certs"
-    DIST_PACKAGE_RELATIVE_PATH: "build/docker/bemanitools.zip"
-    PACKAGE_REGISTRY_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/bemanitools"
-
-services:
-  - docker:19.03.8-dind
-
-stages:
-  - build
-  - upload
-  - release
-
-build:
-  stage: build
-  only:
-    refs:
-      - master
-      - tags
-  before_script:
-    - apk update && apk add make > /dev/null
-  script:
-    - make build-docker
-  artifacts:
-    paths:
-      - build
-    expire_in: 1 week
-
-upload-package-registry:
-  stage: upload
-  image: curlimages/curl:latest
-  only:
-    refs:
-      - master
-      - tags
-  dependencies:
-    - build
-  script:
-    - |
-      if [ "${CI_COMMIT_TAG}" ]; then
-        version="${CI_COMMIT_TAG}"
-      else
-        version="${CI_COMMIT_SHORT_SHA}"
-      fi
-    - |
-      curl \
-        --silent \
-        --fail \
-        --show-error \
-        --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
-        --upload-file "${DIST_PACKAGE_RELATIVE_PATH}" \
-        $PACKAGE_REGISTRY_URL/${version}/bemanitools.zip
-
-upload-tools-page:
-  stage: upload
-  image: curlimages/curl:latest
-  only:
-    refs:
-      - tags
-  dependencies:
-    - build
-  script:
-    - |
-      curl \
-        --silent \
-        --fail \
-        --show-error \
-        --connect-timeout 5 \
-        --max-time 10 \
-        --retry 5 \
-        -F "key=${CI_TOOLS_UPLOAD_KEY}" \
-        -F "filename=${CI_PROJECT_NAME}-v${CI_COMMIT_TAG}.zip" \
-        -F "file=@${DIST_PACKAGE_RELATIVE_PATH}" \
-        ${CI_TOOLS_UPLOAD_URL}
-
-release-gitlab:
-  stage: release
-  image: registry.gitlab.com/gitlab-org/release-cli:v0.8.0
-  only:
-    refs:
-      - tags
-  script:
-    - version="$CI_COMMIT_TAG"
-    - release_message="$(scripts/ci/create-release-message.sh "${version}" < CHANGELOG.md)"
-    - |
-      release-cli create \
-        --name "bemanitools ${version}" \
-        --description="${release_message}" \
-        --tag-name ${version} \
-        --assets-link "{\"name\":\"Distribution binaries\",\"url\":\"${PACKAGE_REGISTRY_URL}/${version}/bemanitools.zip\"}"
-
-release-pigstall:
-  stage: release
-  image: curlimages/curl:latest
-  only:
-    refs:
-      - tags
-  script:
-    - version="${CI_COMMIT_TAG}"
-    - changelog_excerpt="$(scripts/ci/create-release-message.sh "${version}" < CHANGELOG.md)"
-    - release_message="$(printf "bemanitools ${version} released\n${CI_TOOLS_URL}/bemanitools-v${version}.zip\n${changelog_excerpt}")"
-    - session="$(echo "$CI_PIGSTALL_SESSION_BASE64" | base64 -d)"
-    - data_prefix="$(echo "$CI_PIGSTALL_DATA_PREFIX_BASE64" | base64 -d)"
-    - link="$(echo "$CI_PIGSTALL_LINK_BASE64" | base64 -d)"
-    - |
-      curl \
-        --silent \
-        --fail \
-        --connect-timeout 5 \
-        --max-time 10 \
-        --retry 5 \
-        --show-error \
-        -H 'Content-Type: application/x-www-form-urlencoded' \
-        -H "Cookie: PHPSESSID=$CI_PIGSTALL_PHP_SESSION_ID; session=${session}" \
-        --data-raw "${data_prefix}&body=${release_message}" \
-        "${link}"

.gitlab/merge_request_templates/Bugfix.md

@@ -1,27 +0,0 @@
-## Summary
-<!--- Provide a general summary of your changes in the Title above -->
-
-## Description
-<!--- Describe your changes in detail -->
-
-## Related Issue
-<!--- This project only accepts pull requests related to open issues -->
-<!--- If suggesting a new feature or change, please discuss it in an issue first -->
-<!--- If fixing a bug, there should be an issue describing it with steps to reproduce -->
-<!--- Please link to the issue here: -->
-
-## How Has This Been Tested?
-<!--- Please describe in detail how you tested your changes. -->
-<!--- Include details of your testing environment, and the tests you ran to -->
-<!--- see how your change affects other areas of the code, etc. -->
-
-## Checklist
-<!-- Make sure you covered all items, which apply, of the checklist below. -->
-<!-- Strikethrough items that do not apply and provide a brief description why. -->
-* [ ] Implemented (unit) test(s) which prove that the introduced changes are working as expected.
-* Tested with the following games:
-    * [ ] ... <!-- insert game name 1-->
-    * [ ] ... <!-- insert game name 2--->
-* [ ] Followed the developer (style) guidelines.
-* [ ] Updated existing doc of or add new doc to README file(s).
-* [ ] Updated development documentation.

CHANGELOG.md

@@ -1,287 +1,445 @@
 # Release history
+
 Note for CI/CD: Ensure the version formatting in the sections is kept identical to the versions
 given in tags. The pipeline will pick this up and cuts out the relevant section for release notes.
 
+## 5.50
+
+### Features
+
+### Fixes
+
+## 5.49
+
+### Features
+
+- Major overhaul of [IIDX sync and performance settings](doc/iidxhook/iidx-syncbook.md)
+  documentation. Supports users in configuring their systems to run any IIDX version with proper
+  display timings, smooth frame rates and sync game-play
+- Add `iidxio-async.dll` wrapper/shim library to drive another iidxio in a dedicated IO thread, see
+  [documentation](doc/iidxhook/iidxio-async.md) for details 
+- Add `nvgpu` tool to configure NVIDIA GPUs and create a custom timing profile, see
+  [documentation](doc/tools/nvgpu.md) for details
+- Add `d3d9-frame-graph-hook.dll` that can be added as a hook to
+  either `launcher.exe` or `inject.exe` to display a graph of the frame times of the game's render
+  for debugging and performance analysis
+- feat: Add `d3d9-monitor-check` tool to run different music game relevant monitor tests including
+  a re-implementation of the infamous IIDX “monitor check” as a separate tool for testing and
+  debugging. See [documentation](doc/tools/d3d9-monitor-check.md) for details
+
+### Fixes
+
+- iidxhook9: Work around reverb issue from Windows 26100.3476
+- iidxhook9: fix camhook for new style camera detection
+  - `cam.port_layout` added to .conf files of iidx 27 to 30
+- In general, a lot of internal cleanup
+
+## 5.48
+
+### Features
+
+- feat(config): Add invert analog input option. Remark: The old configuration file format is
+  upgraded but downgrading is not possible anymore. The new saves are using a new filename and it
+  doesn't delete the old files, see `C:\Users\<YOUR_USERNAME>\AppData\Roaming\DJHACKERS`
+
+### Fixes
+
+## 5.47
+
+### Features
+
+N/A
+
+### Fixes
+
+- fix(ddr/p3ioemu): Handle unknown 2B command to fix DDR X IO errors
+- fix(ddr/p3io): Crash on all supported DDR games due to incorrect p3io message size validation
+- fix(geninput): Sony DualShock 4 not working
+
+## 5.46
+
+### Features
+
+- feat(ddrio): Wrapper/shim library to drive another ddrio in a dedicated IO thread. Improves
+  performance for highly IO bound ddrio implementations, e.g. ddrio-p3io
+- feat(iidxiotest): bi2a-iidx support
+
+### Fixes
+
+- fix(jb03/04): Missing XML in gamestart script
+- fix(jbhook1): Rotate error message box when screen is rotated
+- fix(jbhook1): Improve/fix automatic config/nvram fs initialization
+
+## 5.45
+
+### Features
+
+- feat(iidx 30): Added support
+- feat(ddr): Add ddrio implementation with P3IO driver backend
+- feat(ddr): Add p3io-ddr-tool for testing/debugging real P3IO devices with EXTIO
+- feat(ddr): Add testing tool for real EXTIO devices
+- feat(ddr): Add extio driver
+- feat(ddr): Add p3io driver
+- feat(iidx 20-26): New/fixed gfx up-/downscaling feature, old one was broken
+- feat(ddr): Vigem driver for ddrio
+- feat(iidx 25-30): The user can now set a custom camera device override of "SKIP" to leave that
+  camera unassigned
+
+### Fixes
+
+- fix(iidx 09/10): Fix stretched BGAs on 1st and 3rd style videos
+
+## 5.44
+
+### Features
+
+- feat(doc): ezusb dev journal entry, 10th style ezusb boot up and security setup
+- feat(iidx 09/10): ezusb API call monitoring module and configuration flag
+- feat(iidx 19): Add back btools monitor check for iidxhook5
+- feat(iidx 9-19): Add configurable settings path hook. Redirect settings paths, i.e. `d/`, `e/` and
+  `f/` drive "folders" to an arbitrary path on any partition, e.g. writable partition
+- feat(iidx 9/10): Improve commandline script for irbeat-patch 09 and 10, add interactive mode
+
+### Fixes
+
+- fix(iidx 10): SQ-INIT error caused by incorrect security configuration
+- fix(iidx 9-24): Wire up coin input in ezusb1/2 IO emulation layer
+- fix(pnm 15-18): Fix IO buffer inconsistency causing random input misfiring
+- fix(jb 1-8): Fix IO buffer inconsistency causing random input misfiring
+- fix(iidx 9-24): Fix IO buffer inconsistency causing random input misfiring
+- fix(iidx 19): imagefs override strategy with local file redir. Required to enable monitor-check on
+  all chart files
+- fix(iidx 9-19): Code synchronization issue causing deadlock resulting in game hang/stuck on boot
+- fix(iidx 9-19): Fix broken settings path handling with mixed / and \\
+- fix(iidx 27): Align disabled cam connection config defaults with 28/29
+- fix(inject): Fix missing forwarding of exit code
+- fix(inject): Getting stuck when game exits cleanly due to locked up debugger thread.
+- fix(iidx 18/19 CN): gamestart.bat creating dev/nvram and dev/raw folders
+
+## 5.43
+
+- iidx29: (Officially) support IIDX CASTHOUR
+- Code structure maintenance
+- Various documentation improvements
+
 ## 5.42
-* Bugfix: Fix diagonal texture tearing on IIDX 18 and 19 based games
-* Feature: Add support for IIDX Resort Anthem CN using iidxhook4-cn 
-* Feature/bugfix: Enable "nvidia fix" for iidxhook4, 5 and 5-cn. Should fix crashing on some/all
+
+- Bugfix: Fix diagonal texture tearing on IIDX 18 and 19 based games
+- Feature: Add support for IIDX Resort Anthem CN using iidxhook4-cn
+- Feature/bugfix: Enable "nvidia fix" for iidxhook4, 5 and 5-cn. Should fix crashing on some/all
   nvidia cards
-* Various minor fixes
+- Various minor fixes
 
 ## 5.41
-* Feature: Support pop'n music 15-18 using popnhook1
-* Feature: Support IIDX tricoro CN using iidxhook5-cn
-* Various documentation improvements
+
+- Feature: Support pop'n music 15-18 using popnhook1
+- Feature: Support IIDX tricoro CN using iidxhook5-cn
+- Various documentation improvements
 
 ## 5.40
-* Feature: Support DDR X and X2 US/EU using ddrhook1 including memory card emulation
-* Fix: sdvxhook2 crashing on some OS versions
-* Feature: Support sdvx generator lights in sdvxio
+
+- Feature: Support DDR X and X2 US/EU using ddrhook1 including memory card emulation
+- Fix: sdvxhook2 crashing on some OS versions
+- Feature: Support sdvx generator lights in sdvxio
 
 ## 5.39
-* jbhook3: Fix window mode, remove window frame option, add show cursor on window option
-* Code simplification and cleanup round plug modules
-* Code structure improvements p3io jubeat
+
+- jbhook3: Fix window mode, remove window frame option, add show cursor on window option
+- Code simplification and cleanup round plug modules
+- Code structure improvements p3io jubeat
 
 ## 5.38
-* sdvxhook2: Support sound voltex exceed gear
+
+- sdvxhook2: Support sound voltex exceed gear
 
 ## 5.37
-* jbhook1: Support jubeat (1) and ripples
-* jbhook2: Support jubeat knit and copious
-* jbhook3: Support jubeat saucer, prop, qubell, clan and festo
+
+- jbhook1: Support jubeat (1) and ripples
+- jbhook2: Support jubeat knit and copious
+- jbhook3: Support jubeat saucer, prop, qubell, clan and festo
 
 ## 5.36
-* iidxhook9: Support for IIDX28
-* Various bugfixes
+
+- iidxhook9: Support for IIDX28
+- Various bugfixes
 
 ## 5.35
-* Jubeat: Add jbio-p4io
-* Nostalgia: Add nostio-panb
-* Misc: Add wavepass support to aciodrv-icca (and eamio-icca)
-* Misc: Refactor aciodrv to support multiple devices using the same port (with aciomgr)
-* Misc: Fix d3d9ex windowed hook not behaving correctly (size/framed)
-* Misc: Fix docs not being included with release
-* Various bugfixes
+
+- Jubeat: Add jbio-p4io
+- Nostalgia: Add nostio-panb
+- Misc: Add wavepass support to aciodrv-icca (and eamio-icca)
+- Misc: Refactor aciodrv to support multiple devices using the same port (with aciomgr)
+- Misc: Fix d3d9ex windowed hook not behaving correctly (size/framed)
+- Misc: Fix docs not being included with release
+- Various bugfixes
 
 ## 5.34
-* IIDX: Support IO and card reader feature switches to disable emulation in iidxhook4-7
-* Jubeat: jbio implementation for magicbox hardware
-* Misc: Various documentation improvements
-* IIDX: Turntable multiplier (can also be used as inverted) for iidxhook9
-* IIDX: iidxhook9, add force screen resolution option to fix sometimes wrong auto res detection by
-iidx27 causing inaccurate/wrong refresh rates on monitor check
-* IIDX: iidxio BIO2 implementation -> Use BIO2 hardware with any iidxhook or other software
-supporting BT5's iidxio interface
-* IIDX: BIO2 exit hook, exit the game pressing Start P1 + Start P2, Effect and VEFX
-* launcher: Allow overriding service URL from command line
-* IIDX: vigem-iidxio, tool to allow using iidxio (ezusb, ezusb2 or bio2) to emulate XBOX controllers
-to play other non arcade games that support xinput, e.g. Lunatic Rave (note: Infinitas does not
-work with this since it only supports direct input)
+
+- IIDX: Support IO and card reader feature switches to disable emulation in iidxhook4-7
+- Jubeat: jbio implementation for magicbox hardware
+- Misc: Various documentation improvements
+- IIDX: Turntable multiplier (can also be used as inverted) for iidxhook9
+- IIDX: iidxhook9, add force screen resolution option to fix sometimes wrong auto res detection by
+  iidx27 causing inaccurate/wrong refresh rates on monitor check
+- IIDX: iidxio BIO2 implementation -> Use BIO2 hardware with any iidxhook or other software
+  supporting BT5's iidxio interface
+- IIDX: BIO2 exit hook, exit the game pressing Start P1 + Start P2, Effect and VEFX
+- launcher: Allow overriding service URL from command line
+- IIDX: vigem-iidxio, tool to allow using iidxio (ezusb, ezusb2 or bio2) to emulate XBOX controllers
+  to play other non arcade games that support xinput, e.g. Lunatic Rave (note: Infinitas does not
+  work with this since it only supports direct input)
 
 ## 5.33
-* iidxhook9: Support for IIDX27 
-* sdvxio-bio2: Driver for real sdvx5 cabinet IO hardware
-* vigem-sdvxio: Tool to allow using sdvxio (kfca or bio2) to emulate an xbox controller
-* Various bugfixes and refactoring for inject and launcher
+
+- iidxhook9: Support for IIDX27
+- sdvxio-bio2: Driver for real sdvx5 cabinet IO hardware
+- vigem-sdvxio: Tool to allow using sdvxio (kfca or bio2) to emulate an xbox controller
+- Various bugfixes and refactoring for inject and launcher
 
 ## 5.32
-* Various bugfixes
+
+- Various bugfixes
 
 ## 5.31
-* DDR: Fix p3io and extio lights not working / being swapped when using geninput
-* DDR: Add HDXS light support
-* DDR: Add 64 bit support
-* DDR: Add option to use COM4 as the p3io rs232 port instead of emulating (for use with acrealio etc.)
-* Jubeat: Add network adapter hook
-* Misc: Fix aciodrv sometimes hanging on boot (eamio-icca and sdvxio-kfca) 
+
+- DDR: Fix p3io and extio lights not working / being swapped when using geninput
+- DDR: Add HDXS light support
+- DDR: Add 64 bit support
+- DDR: Add option to use COM4 as the p3io rs232 port instead of emulating (for use with acrealio
+  etc.)
+- Jubeat: Add network adapter hook
+- Misc: Fix aciodrv sometimes hanging on boot (eamio-icca and sdvxio-kfca)
 
 ## 5.30
-* SDVX: sdvxhook2 headphone force and cursor confining config options
-* DDR: Add light support for SMX gen 4 pads
+
+- SDVX: sdvxhook2 headphone force and cursor confining config options
+- DDR: Add light support for SMX gen 4 pads
 
 ## 5.29
-* SDVX: Add option for monitor rotation
-* SDVX: Add option to allow overriding network adapter IP
-* IIDX: Add force display adapter and refresh rate configuration
-* SDVX: Allow specifying display adapter to open for d3d9ex hook
-* IIDX/SDVX camerahooks bugfix: Camera sometimes not detected on some older machines
+
+- SDVX: Add option for monitor rotation
+- SDVX: Add option to allow overriding network adapter IP
+- IIDX: Add force display adapter and refresh rate configuration
+- SDVX: Allow specifying display adapter to open for d3d9ex hook
+- IIDX/SDVX camerahooks bugfix: Camera sometimes not detected on some older machines
 
 ## 5.28
-* Improve documentation in various places
-* Automatic code formatting in build pipeline
-* Bugfix: Recursive config.bat script
-* Enable automatic building on pushes to master
-* Bugfix: Stop SDVX hanging on thankyou for playing
-* sdvx2: Support for Vivid Wave using sdvxhook2
-* sdvxio-kfca: Driver for real sdvx cabinet IO hardware
+
+- Improve documentation in various places
+- Automatic code formatting in build pipeline
+- Bugfix: Recursive config.bat script
+- Enable automatic building on pushes to master
+- Bugfix: Stop SDVX hanging on thankyou for playing
+- sdvx2: Support for Vivid Wave using sdvxhook2
+- sdvxio-kfca: Driver for real sdvx cabinet IO hardware
 
 ## 5.27
-* Various documentation updates regarding development and how to contribute
-* KFCA emulation accuracy fixes
-* Fix passthrough of serial calls when using real hardware (e.g. card reader passthrough IIDX25+/SDVX5+)
-* Add sdvxio-kfca driver to talk to real SDVX hardware
-* Refactor d3d9 hook module to improve maintainability. Also fixes upscaling not working on IIDX20+.
-* Remove d3d8 hook module to improve maintainability. Make old d3d8 based games, e.g. iidxhook1/2, use d3d9 instead.
-Requires usage of d3d8to9 wrapper library to use gfx patching features.
-* Add dev doc about IIDX rendering loops
-* Add an initial draft of an architecture document (will be worked on in iterations)
-* Refactor BIO2 emulation to make it re-usable by other games
+
+- Various documentation updates regarding development and how to contribute
+- KFCA emulation accuracy fixes
+- Fix passthrough of serial calls when using real hardware (e.g. card reader passthrough
+  IIDX25+/SDVX5+)
+- Add sdvxio-kfca driver to talk to real SDVX hardware
+- Refactor d3d9 hook module to improve maintainability. Also fixes upscaling not working on IIDX20+.
+- Remove d3d8 hook module to improve maintainability. Make old d3d8 based games, e.g. iidxhook1/2,
+  use d3d9 instead. Requires usage of d3d8to9 wrapper library to use gfx patching features.
+- Add dev doc about IIDX rendering loops
+- Add an initial draft of an architecture document (will be worked on in iterations)
+- Refactor BIO2 emulation to make it re-usable by other games
 
 ## 5.26
-* iidxio-ezusb: Reduce sleep time to Sleep(1) to avoid framerate issues on some versions of iidx.
-* Bugfix: iidx d3d9 games, mainly the newer ones iidx 20-25, freezing. Happened on boot, during song selection or during the song.
-* Bugfix: log_server_init deadlock on iidxhook4-7. This caused games like iidx24 to hang before even showing a render window.
-* iidxhook: Add feature to allow GPU based up-/downscaling of rendered frame. This gives
-you the possibility to upscale the resolution of old SD (640x480) games to your monitor's/TV's
-native resolution which can have a few advantages: better image quality if the monitor's upscaler
-is not doing a good job, especially on resolutions that are not a multiple of its native resolution;
-Reduce display latency if the upscaler is slow, avoid over-/underscan which cannot always be fixed
-entirely or at all (depending on your GPU and monitor model). See the iidxhook configuration file
-for the new parameters available.
-* Major readme cleanup. Add development documentation like style guide, guidelines, development setup.
+
+- iidxio-ezusb: Reduce sleep time to Sleep(1) to avoid framerate issues on some versions of iidx.
+- Bugfix: iidx d3d9 games, mainly the newer ones iidx 20-25, freezing. Happened on boot, during song
+  selection or during the song.
+- Bugfix: log_server_init deadlock on iidxhook4-7. This caused games like iidx24 to hang before even
+  showing a render window.
+- iidxhook: Add feature to allow GPU based up-/downscaling of rendered frame. This gives you the
+  possibility to upscale the resolution of old SD (640x480) games to your monitor's/TV's native
+  resolution which can have a few advantages: better image quality if the monitor's upscaler is not
+  doing a good job, especially on resolutions that are not a multiple of its native resolution;
+  Reduce display latency if the upscaler is slow, avoid over-/underscan which cannot always be fixed
+  entirely or at all (depending on your GPU and monitor model). See the iidxhook configuration file
+  for the new parameters available.
+- Major readme cleanup. Add development documentation like style guide, guidelines, development
+  setup.
 
 ## 5.25
-* Bugfix: iidx14 and 15 crashing on Windows 10
-* Bugfix: IO2 driver not using correct package sizes on reads/write -> iidxio-ezusb2.dll now working
-* Improve ezusb2-boot.bat script to handle flashing of IO2 firmware
-* Remove broken x64 builds of ezusb1/2 tools -> Just use the x86 tool versions instead
-(use the x64 versions of iidxio-ezusb.dll and iidxio-ezusb2.dll with iidx25)
-* iidxhook1-8: Allow floating point values for frame rate limiting, e.g. 59.95 (hz).
-* Improve timing with ezusb (C02) driver
+
+- Bugfix: iidx14 and 15 crashing on Windows 10
+- Bugfix: IO2 driver not using correct package sizes on reads/write -> iidxio-ezusb2.dll now working
+- Improve ezusb2-boot.bat script to handle flashing of IO2 firmware
+- Remove broken x64 builds of ezusb1/2 tools -> Just use the x86 tool versions instead (use the x64
+  versions of iidxio-ezusb.dll and iidxio-ezusb2.dll with iidx25)
+- iidxhook1-8: Allow floating point values for frame rate limiting, e.g. 59.95 (hz).
+- Improve timing with ezusb (C02) driver
 
 ## v5.24
-* Bugfix: iidxhook8 hangs very early on startup (race condition in log-server module)
+
+- Bugfix: iidxhook8 hangs very early on startup (race condition in log-server module)
 
 ## v5.23
-* Refactored configurion (file) handling for iidxhooks, RE-READ THE DOCUMENTATION.
-This gets rid of the "short cmd parameters", e.g. -w for windowed mode, and replaces
-them with full name parameters, e.g. -p gfx.windowed=true, which improves handling
-of configuration files/values. 
-* Add a lot of unit tests to the codebase
-* Refactored round plug security infrastructure, shared with IIDX and jubeat (1)
-* Move shared utility modules between iidxhook modules to a separate utilty module 'iidxhook-util'
-* Add experimental jubeat (1) support (buggy IO emulation) 
-* Various fixes to improve all iidxhooks when running on Windows 10
-* Bugfix: iidxio-ezusb getting stuck on newer Windows platforms
-* Update iidxhook docs, e.g. how to get old IIDX versions sync on Windows 10
-* Various documentation updates
-* Various code cleanup
-* Various other minor bugfixes
+
+- Refactored configurion (file) handling for iidxhooks, RE-READ THE DOCUMENTATION. This gets rid of
+  the "short cmd parameters", e.g. -w for windowed mode, and replaces them with full name
+  parameters, e.g. -p gfx.windowed=true, which improves handling of configuration files/values.
+- Add a lot of unit tests to the codebase
+- Refactored round plug security infrastructure, shared with IIDX and jubeat (1)
+- Move shared utility modules between iidxhook modules to a separate utilty module 'iidxhook-util'
+- Add experimental jubeat (1) support (buggy IO emulation)
+- Various fixes to improve all iidxhooks when running on Windows 10
+- Bugfix: iidxio-ezusb getting stuck on newer Windows platforms
+- Update iidxhook docs, e.g. how to get old IIDX versions sync on Windows 10
+- Various documentation updates
+- Various code cleanup
+- Various other minor bugfixes
 
 ## v5.22
-* Added a lot of documentation and readme stuff (READ IT!!11)
-* Re-numbering iidxhook implementations to make room for missing games
-* Support for IIDX 18 -> iidxhook4
-* Support for IIDX 19 -> iidxhook5
-* Support for IIDX 20 -> iidxhook6
-* A lot of code refactoring and cleanup
-* Refactor p3io emulation
-* Remove obsolete BT4 DDR stuff
-* iidxhook: Refactored software monitor check and bugfixes. You can use the
-auto monitor check to determine your machine's refresh rate or (new) set the
-refresh rate yourself in the configuration file, e.g. when you already have
-determined it using one of the newer IIDX games and want to skip that monitor
-check or if BT5's software monitor check doesn't work properly (e.g. on Win 7).
-* iidxhook1-3: Check if eamuse server is reachable and log a warning otherwise.
-This should make debugging invalid URLs or connection issues easier.
-* iidxhook: Revised ezusb and ezusb2 emulation layer. Translucent support
-removed, all IO emulation goes through BT5's iidxio interface.
-* iidxio: Add implementations for ezusb (C02 IO) and ezusb2 (IO2) hardware. This
-allows you to run _ANY_ IIDX game supported by BT5 either with real C02 or IO2
-hardware.
-* iidxhook: Remove translucent card reader feature. Again, to create a unified
-interface for _ALL_ versions, use the eamio-icca.dll if you want to run on 
-real ICCA (slotted or wavepass) readers. 
-* Various other bugfixes
 
-Again, read the various markdown (.md) readme files. We tried to document
-everything to the best of our knowledge. If you are missing something, please
-contribute by adding that information and submitting a patch to us.
+- Added a lot of documentation and readme stuff (READ IT!!11)
+- Re-numbering iidxhook implementations to make room for missing games
+- Support for IIDX 18 -> iidxhook4
+- Support for IIDX 19 -> iidxhook5
+- Support for IIDX 20 -> iidxhook6
+- A lot of code refactoring and cleanup
+- Refactor p3io emulation
+- Remove obsolete BT4 DDR stuff
+- iidxhook: Refactored software monitor check and bugfixes. You can use the auto monitor check to
+  determine your machine's refresh rate or (new) set the refresh rate yourself in the configuration
+  file, e.g. when you already have determined it using one of the newer IIDX games and want to skip
+  that monitor check or if BT5's software monitor check doesn't work properly (e.g. on Win 7).
+- iidxhook1-3: Check if eamuse server is reachable and log a warning otherwise. This should make
+  debugging invalid URLs or connection issues easier.
+- iidxhook: Revised ezusb and ezusb2 emulation layer. Translucent support removed, all IO emulation
+  goes through BT5's iidxio interface.
+- iidxio: Add implementations for ezusb (C02 IO) and ezusb2 (IO2) hardware. This allows you to run
+  _ANY_ IIDX game supported by BT5 either with real C02 or IO2 hardware.
+- iidxhook: Remove translucent card reader feature. Again, to create a unified interface for _ALL_
+  versions, use the eamio-icca.dll if you want to run on real ICCA (slotted or wavepass) readers.
+- Various other bugfixes
+
+Again, read the various markdown (.md) readme files. We tried to document everything to the best of
+our knowledge. If you are missing something, please contribute by adding that information and
+submitting a patch to us.
 
 ## v5.21
-* Camera hook for IIDX 25 (use any UVC webcam in-game), by Xyen
-* *deep breath* Source code release
+
+- Camera hook for IIDX 25 (use any UVC webcam in-game), by Xyen
+- *deep breath* Source code release
 
 ## v5.20
-* Support for the new IIDX 25 IO board (xyen)
-* New IO hook system with better multi-threading behavior
-* Add a replaceable "vefxio" backend dll for IIDX (xyen)
-* Card reader emulation can now be disabled in iidxhook (xyen)
-* Add jbhook (xyen, mon)
-* Add ddrhook (ported from Bemanitools 4 by mon)
-* Various ICCA emulation improvements (xyen, mon)
-* QoL improvements to config.exe (xyen, mon)
-* Other bug fixes (various contributors)
+
+- Support for the new IIDX 25 IO board (xyen)
+- New IO hook system with better multi-threading behavior
+- Add a replaceable "vefxio" backend dll for IIDX (xyen)
+- Card reader emulation can now be disabled in iidxhook (xyen)
+- Add jbhook (xyen, mon)
+- Add ddrhook (ported from Bemanitools 4 by mon)
+- Various ICCA emulation improvements (xyen, mon)
+- QoL improvements to config.exe (xyen, mon)
+- Other bug fixes (various contributors)
 
 ## a19
-* iidx 17 support
-* Bugfix: forums.php?action=viewthread&threadid=51257&postid=1425861#post1425861
-* iidx 14-17: Improved monitor check and new monitor check screen which shows 
-the current frame rate instead of just a white screen
-* iidx 09-13: Improved monitor check (but still white screen when in progress. 
-d3d8 doesn't offer any text render out of the box)
-* iidxfx(2)-exit-hook: Switch off lights on shutdown
-* Various other bugfixes
+
+- iidx 17 support
+- Bugfix: forums.php?action=viewthread&threadid=51257&postid=1425861#post1425861
+- iidx 14-17: Improved monitor check and new monitor check screen which shows the current frame rate
+  instead of just a white screen
+- iidx 09-13: Improved monitor check (but still white screen when in progress. d3d8 doesn't offer
+  any text render out of the box)
+- iidxfx(2)-exit-hook: Switch off lights on shutdown
+- Various other bugfixes
 
 ## a18
-* Bugfix: forums.php?action=viewthread&threadid=51063
-* Various other bugfixes
+
+- Bugfix: forums.php?action=viewthread&threadid=51063
+- Various other bugfixes
 
 ## a17
-* IIDX 16 support
-* Fix broken debug output to file (for iidxhook1-3 and all games using launcher)
-* Improve debug output
-* Various minor bugfixes
+
+- IIDX 16 support
+- Fix broken debug output to file (for iidxhook1-3 and all games using launcher)
+- Improve debug output
+- Various minor bugfixes
 
 ## a16
-* Add tools.zip which contains various tools for development: ezusb IO related, 
-bemanitools API testing, acio related
-* Add documentation (.md files) for tools
-* Add iidxfx(2)-exit-hook.dll: Hook this using either inject or launcher 
-(depending on the game version) and exit the game by pressing Start P1 + Start 
-P2 + VEFX + Effect simultaneously
-* Bugfix iidxio API: 16seg not working on IIDX games with FX2 emulation
-* Bugfix iidxio API: return value of init call not getting checked in hook 
-libraries
-* SDVX input emulation fixes
-* Various other bugfixes
+
+- Add tools.zip which contains various tools for development: ezusb IO related, bemanitools API
+  testing, acio related
+- Add documentation (.md files) for tools
+- Add iidxfx(2)-exit-hook.dll: Hook this using either inject or launcher (depending on the game
+  version) and exit the game by pressing Start P1 + Start P2 + VEFX + Effect simultaneously
+- Bugfix iidxio API: 16seg not working on IIDX games with FX2 emulation
+- Bugfix iidxio API: return value of init call not getting checked in hook libraries
+- SDVX input emulation fixes
+- Various other bugfixes
 
 ## a15
-* Select best network adapter if having multiple
-* Add Felica card detection
-* Fix SDVX HID lighting
-* Fix IIDX FX2 deck lighting
+
+- Select best network adapter if having multiple
+- Add Felica card detection
+- Fix SDVX HID lighting
+- Fix IIDX FX2 deck lighting
 
 ## a13
-* iidx 15 (DJ Troopers) support
-* Fix BG video triangle seam on old games
-* New options handling: cmd args and options file
+
+- iidx 15 (DJ Troopers) support
+- Fix BG video triangle seam on old games
+- New options handling: cmd args and options file
 
 ## a11
-* Fix nVidia crash on GOLD
+
+- Fix nVidia crash on GOLD
 
 ## a10
-* Adds IO2 emulation for Gold
-* Add IO2 translucent mode for Gold ONLY atm (untested due to lack of hardware)
-* Random input bug resolved (also kinda untested, so maybe?)
+
+- Adds IO2 emulation for Gold
+- Add IO2 translucent mode for Gold ONLY atm (untested due to lack of hardware)
+- Random input bug resolved (also kinda untested, so maybe?)
 
 ## a09
-* Add IIDX 14 support
+
+- Add IIDX 14 support
 
 ## a08
-* Add experimental KFCA (SDVX PCB) support
-* Add Sound Voltex and BeatStream builds
+
+- Add experimental KFCA (SDVX PCB) support
+- Add Sound Voltex and BeatStream builds
 
 ## a07
-* Add IIDX 13 DistorteD support
-* Add option to use real card readers with IIDX 13
+
+- Add IIDX 13 DistorteD support
+- Add option to use real card readers with IIDX 13
 
 ## a06
-* Fixes bug in chart data loader interception code
+
+- Fixes bug in chart data loader interception code
 
 ## a05
-* Fix broken card reader emulation on Copula
-* Add monitor check/auto timebase for old IIDX games (9-12) -> refer to the 
-readme file on how to use it
+
+- Fix broken card reader emulation on Copula
+- Add monitor check/auto timebase for old IIDX games (9-12) -> refer to the readme file on how to
+  use it
 
 ## a04
-* Add software frame rate limiter for all D3D8 based games (-g option).
+
+- Add software frame rate limiter for all D3D8 based games (-g option).
 
 ## a03
-* Add support for IIDX 9-12
-* Translucent mode: Use real C02 EZUSB IO hardware
-* eamio-real.dll: Use real slotted or wave pass card readers
-* Setup guide, advanced features and FAQ: see readme file iidxhook1.md
+
+- Add support for IIDX 9-12
+- Translucent mode: Use real C02 EZUSB IO hardware
+- eamio-real.dll: Use real slotted or wave pass card readers
+- Setup guide, advanced features and FAQ: see readme file iidxhook1.md
 
 ## a02
-* Fonts are always correct irrespective of system locale! (Make sure you 
-install East Asian fonts tho)
-* No longer crashes shitty gaming mice that don't follow the USB spec! (will 
-backport this to bt4)
-* launcher.exe now has a UAC manifest! (because 2006 called and told me to get 
-with the fucking program)
+
+- Fonts are always correct irrespective of system locale! (Make sure you install East Asian fonts
+  tho)
+- No longer crashes shitty gaming mice that don't follow the USB spec! (will backport this to bt4)
+- launcher.exe now has a UAC manifest! (because 2006 called and told me to get with the fucking
+  program)
 
 ## a01
-* Initial Alpha, only supports IIDX 21 and 22 for now.
+
+- Initial Alpha, only supports IIDX 21 and 22 for now.

CONTRIBUTING.md

@@ -1,36 +1,39 @@
 # Contributing
+
 This document outlines different types of contributions and how YOU can help us to improve the
 project. Read it, as it provides guidelines that are there to help you and the maintainers.
 
 ## Reporting and discussions: Issues section on gitlab
+
 In order to avoid having to manage ongoing discussions and bug reports on different communication
-channels, e.g. forums, messangers or other closed groups, we ask everyone to treat the issue
-section on gitlab as the place to open their relevant discussions and bug reports regarding the
-project.
+channels, e.g. forums, messangers or other closed groups, we ask everyone to treat the issue section
+on gitlab as the place to open their relevant discussions and bug reports regarding the project.
 
 The maintainers of the project do not have the time nor motivation to micromanage on the various
-channels and enter all data here to have it collected. This is a simple task that *ANYONE* can do 
+channels and enter all data here to have it collected. This is a simple task that *ANYONE* can do
 allowing the maintainers and developers to spend their time on the codebase.
 
 ## Bug reports
+
 Follow these steps when reporting bugs to ensure you provide all information we *always* need and
 make your report valuable and actionable.
 
 1. On the bemanitools repository, go `Issues` on the left-hand sidebar.
 1. Use the search function to check if there is an already open issue regarding what you want to
-report
-    1. If that applies, read the open issue to check what's already covered regarding the bug
-    1. Provide additional information or things that are missing. Upload your log files,
-    screenshots, videos etc. Be careful to remove sensitive information like PCBIDs
-    1. Give a thumbs up to the issue to show you are interested/affected as well
+   report
+   1. If that applies, read the open issue to check what's already covered regarding the bug
+   1. Provide additional information or things that are missing. Upload your log files, screenshots,
+      videos etc. Be careful to remove sensitive information like PCBIDs
+   1. Give a thumbs up to the issue to show you are interested/affected as well
 1. If no existing issue avilable, create a new one
 1. Come up with a descriptive title
 1. **USE OUR BUG REPORTING TEMPLATE**: Pick it by selecting `Bug` on the `Description` section
 1. Follow the sections and their instructions provided by the template and fill them in. All fields
-are mandatory to provide a comprehensive report if not stated otherwise
+   are mandatory to provide a comprehensive report if not stated otherwise
 1. When finished, submit the issue
 
 ## Pull requests: bugfixes, new features or other code contributions
+
 Pull requests are welcome! May it be a merge request to an already known issue or a new feature that
 you consider as a valuable contribution, please open a MR.
 
@@ -47,37 +50,39 @@ that your contribution meets our standards. This is not meant to annoy people bu
 consistency that the project stays maintainable for everyone.
 
 Steps for contributing to the repository using a merge request:
+
 1. If you are new to git, take a bit of time to learn the basics which are very simple, e.g. Google
-for "git tutorial for non-programmers"
+   for "git tutorial for non-programmers"
 1. Fork the upstream repository (Fork button on the top right on the main page of the repository)
 1. You can start editing files like documentation easily inside gitlab which might be the prefered
-option for many non-coders
+   option for many non-coders
 1. Clone your fork to your local machine and start working on stuff
 1. Ensure you push your changes to your fork on gitlab
 1. When done, go to the `Merge Requests` section on the left sidebar of the upstream repository
 1. Hit the `New merge request` button
 1. Select the `master` branch as the source branch
 1. Select whatever branch you worked, likely `master` if you didn't change that, as the target
-branch
+   branch
 1. Hit `Compare branches and continue`
 1. Provide a descriptive title of what your change is about
 1. **USE OUR MR TEMPLATES**
-    1. If you submit a bugfix, use the `Bugfix` tempalte and fill in the sections
-    1. If you submit a new feature, use the `Feature` template and fill in the sections
+   1. If you submit a bugfix, use the `Bugfix` tempalte and fill in the sections
+   1. If you submit a new feature, use the `Feature` template and fill in the sections
 1. If you submit some minor fixes or documentation improvements, there is no template for that.
-Please provide a expressive description what you did and *why* you did that
+   Please provide a expressive description what you did and *why* you did that
 1. If any of your changes are tied to one or multiple issues, link them in the description
 1. When done, hit `Submit merge request`
 
 The maintainers will take a look at your submission and provide their feedback. The intention of
-this process is to ensure the contribution meets the quality standards. Please also see this is
-a learning opportunity, especially with your first contribution, if a lot of comments and change
+this process is to ensure the contribution meets the quality standards. Please also see this is a
+learning opportunity, especially with your first contribution, if a lot of comments and change
 requests are being made. The maintainers are open to discuss their suggestions/feedback if
 reasonable feedback is given back to them.
 
 Once all discussion is resolved and the involved maintainers approved your submission, it will be
 merged into master and also included in the next release.
 
-## Roadmap 
+## Roadmap
+
 No concrete roadmap or timeline exists. We want to continue adding support for new games as well as
-old games (some of the old games supported by BT4 are not supported, yet).
+old games (some of the old games supported by BT4 are not supported, yet).

Dockerfile

@@ -1,32 +0,0 @@
-FROM fedora:31
-
-LABEL description="Build environment for bemanitools"
-
-RUN yum -y install \
-    git \
-    make \
-    zip \
-    clang \
-    mingw64-gcc.x86_64 \
-    mingw32-gcc.x86_64 \
-    wine.x86_64
-
-RUN mkdir /bemanitools
-WORKDIR /bemanitools
-
-# Order optimized for docker layer caching
-COPY run-tests-wine.sh run-tests-wine.sh
-COPY CHANGELOG.md CHANGELOG.md
-COPY CONTRIBUTING.md CONTRIBUTING.md
-COPY LICENSE LICENSE
-COPY GNUmakefile GNUmakefile
-COPY Module.mk Module.mk
-COPY README.md README.md
-COPY doc doc
-COPY dist dist
-COPY src src
-# .git folder required or building fails when version is generated
-COPY .git .git
-
-# Building
-RUN make

Dockerfile.build

@@ -0,0 +1,21 @@
+FROM --platform=amd64 debian:11.6-slim@sha256:f7d141c1ec6af549958a7a2543365a7829c2cdc4476308ec2e182f8a7c59b519
+
+LABEL description="Build environment for bemanitools"
+
+# mingw-w64-gcc has 32-bit and 64-bit toolchains
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    mingw-w64 \
+    mingw-w64-common \
+    make \
+    zip \
+    git \
+ && rm -rf /var/lib/apt/lists/*
+
+RUN mkdir /bemanitools
+WORKDIR /bemanitools
+
+ENTRYPOINT [ \
+    "/bin/sh", \
+    "-c" , \
+    "cd /bemanitools && \
+    make" ]

Dockerfile.dev

@@ -0,0 +1,21 @@
+FROM --platform=amd64 debian:11.6-slim@sha256:f7d141c1ec6af549958a7a2543365a7829c2cdc4476308ec2e182f8a7c59b519
+
+LABEL description="Development environment for bemanitools"
+
+# mingw-w64-gcc has 32-bit and 64-bit toolchains
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    mingw-w64 \
+    mingw-w64-common \
+    make \
+    zip \
+    git \
+    clang-format \
+    python3-pip \
+ && rm -rf /var/lib/apt/lists/*
+
+RUN pip3 install mdformat
+
+RUN mkdir /bemanitools
+WORKDIR /bemanitools
+
+ENV SHELL /bin/bash

GNUmakefile

@@ -13,8 +13,10 @@ BUILDDIR        ?= build
 
 builddir_docker 	  := $(BUILDDIR)/docker
 
-docker_container_name := "bemanitools-build"
-docker_image_name     := "bemanitools:build"
+docker_build_container_name := "bemanitools-build"
+docker_build_image_name     := "bemanitools-build:latest"
+docker_dev_container_name := "bemanitools-dev"
+docker_dev_image_name     := "bemanitools-dev:latest"
 
 depdir                := $(BUILDDIR)/dep
 objdir                := $(BUILDDIR)/obj
@@ -28,7 +30,7 @@ cppflags              := -I src -I src/main -I src/test -DGITREV=$(gitrev)
 cflags                := -O2 -pipe -ffunction-sections -fdata-sections \
                           -Wall -std=c99 -DPSAPI_VERSION=1
 cflags_release        := -Werror
-ldflags		          := -Wl,--gc-sections -static-libgcc
+ldflags		          := -Wl,--gc-sections -static -static-libgcc -static-libstdc++
 
 #
 # The first target that GNU Make encounters becomes the default target.
@@ -37,19 +39,25 @@ ldflags		          := -Wl,--gc-sections -static-libgcc
 
 all: build
 
+FORCE:
+
 .PHONY: \
 build-docker \
+dev-docker \
 clean \
 code-format \
+doc-format \
 print-building \
 print-release \
 run-tests \
-version
+version \
+FORCE
 
 release: \
 print-release \
 clean \
 code-format \
+doc-format \
 all \
 run-tests
 
@@ -69,7 +77,11 @@ clean:
 
 code-format:
 	$(V)echo "Applying clang-format..."
-	$(V)find src/ -name '*.c' -o -name '*.h' | xargs clang-format -i -style=file
+	$(V)find src/main src/test -name '*.c' -o -name '*.h' | xargs clang-format -i -style=file
+
+doc-format:
+	$(V)echo "Applying mdformat on all docs..."
+	$(V)find . -name '*.md' | xargs mdformat --wrap 100
 
 run-tests:
 	$(V)echo "Running tests..."
@@ -80,14 +92,39 @@ version:
 	$(V)echo "$(gitrev)" > version
 
 build-docker:
-	$(V)docker rm -f $(docker_container_name) 2> /dev/null || true
-	$(V)docker build -t $(docker_image_name) -f Dockerfile .
-	$(V)docker create --name $(docker_container_name) $(docker_image_name)
-	$(V)rm -rf $(builddir_docker)
-	$(V)mkdir -p $(builddir_docker)
-	$(V)docker cp $(docker_container_name):/bemanitools/build $(builddir_docker)
-	$(V)mv $(builddir_docker)/build/* $(builddir_docker)
-	$(V)rm -r $(builddir_docker)/build
+	$(V)docker rm -f $(docker_build_container_name) 2> /dev/null || true
+	$(V)docker \
+		build \
+		-t $(docker_build_image_name) \
+		-f Dockerfile.build \
+		.
+	$(V)docker \
+		run \
+		--volume $(shell pwd):/bemanitools \
+		--name $(docker_build_container_name) \
+		$(docker_build_image_name)
+
+dev-docker:
+	$(V)docker rm -f $(docker_dev_container_name) 2> /dev/null || true
+	$(V)docker \
+		build \
+		-t $(docker_dev_image_name) \
+		-f Dockerfile.dev \
+		.
+	$(V)docker \
+		run \
+		--interactive \
+		--tty \
+		--volume $(shell pwd):/bemanitools \
+		--name $(docker_dev_container_name) \
+		$(docker_dev_image_name)
+
+clean-docker:
+	$(V)docker rm -f $(docker_dev_container_name) || true
+	$(V)docker image rm -f $(docker_dev_image_name) || true
+	$(V)docker rm -f $(docker_build_container_name) || true
+	$(V)docker image rm -f $(docker_build_image_name) || true
+	$(V)rm -rf $(BUILDDIR)
 
 #
 # Pull in module definitions
@@ -119,8 +156,10 @@ modules		:= $(dlls) $(exes) $(libs) $(avsdlls) $(avsexes) $(testdlls) $(testexes
 define t_moddefs
 
 cppflags_$3	+= $(cppflags) -DBUILD_MODULE=$3
+cxxflags_$3	+= $(cxxflags)  # Add C++-specific flags
 cflags_$3	+= $(cflags)
 release: cflags_$3	+= $(cflags_release)
+release: cxxflags_$3	+= $(cxxflags_release)  # Add C++-specific release flags
 ldflags_$3	+= $(ldflags)
 srcdir_$3	?= src/main/$3
 
@@ -175,9 +214,11 @@ abslib_$1_$2_$3	:= $$(libs_$3:%=$$(bindir_$1_indep)/lib%.a)
 absdpl_$1_$2_$3	:= $$(deplibs_$3:%=$$(bindir_$1_$2)/lib%.a)
 objdir_$1_$2_$3	:= $(objdir)/$$(subdir_$1_$2)/$3
 obj_$1_$2_$3	:=	$$(src_$3:%.c=$$(objdir_$1_$2_$3)/%.o) \
+			$$(cppsrc_$3:%.cpp=$$(objdir_$1_$2_$3)/%.o) \
 			$$(rc_$3:%.rc=$$(objdir_$1_$2_$3)/%_rc.o)
 
-deps		+= $$(src_$3:%.c=$$(depdir_$1_$2_$3)/%.d)
+deps		+= $$(src_$3:%.c=$$(depdir_$1_$2_$3)/%.d) \
+		   $$(cppsrc_$3:%.cpp=$$(depdir_$1_$2_$3)/%.d)
 
 $$(depdir_$1_$2_$3):
 	$(V)mkdir -p $$@
@@ -185,15 +226,25 @@ $$(depdir_$1_$2_$3):
 $$(objdir_$1_$2_$3):
 	$(V)mkdir -p $$@
 
+$$(volatile_$3:%.c=$$(objdir_$1_$2_$3)/%.o): FORCE
+$$(volatile_cpp_$3:%.cpp=$$(objdir_$1_$2_$3)/%.o): FORCE
+
 $$(objdir_$1_$2_$3)/%.o: $$(srcdir_$3)/%.c \
 		| $$(depdir_$1_$2_$3) $$(objdir_$1_$2_$3)
-	$(V)echo ... $$@
+	$(V)echo \(.c\) ... $$@
 	$(V)$$(toolchain_$1)gcc $$(cflags_$3) $$(cppflags_$3) \
 		-MMD -MF $$(depdir_$1_$2_$3)/$$*.d -MT $$@ -MP \
 		-DAVS_VERSION=$2 -c -o $$@ $$<
 
+$$(objdir_$1_$2_$3)/%.o: $$(srcdir_$3)/%.cpp \
+		| $$(depdir_$1_$2_$3) $$(objdir_$1_$2_$3)
+	$(V)echo \(.cpp\) ... $$@
+	$(V)$$(toolchain_$1)g++ $$(cxxflags_$3) $$(cppflags_$3) \
+		-MMD -MF $$(depdir_$1_$2_$3)/$$*.d -MT $$@ -MP \
+		-DAVS_VERSION=$2 -c -o $$@ $$<
+
 $$(objdir_$1_$2_$3)/%_rc.o: $$(srcdir_$3)/%.rc
-	$(V)echo ... $$@ [windres]
+	$(V)echo \(.rc\) ... $$@ [windres]
 	$(V)$$(toolchain_$1)windres $$(cppflags_$3) $$< $$@
 
 endef
@@ -205,7 +256,7 @@ define t_archive
 $(t_compile)
 
 $$(bindir_$1_$2)/lib$3.a: $$(obj_$1_$2_$3) | $$(bindir_$1_$2)
-	$(V)echo ... $$@
+	$(V)echo \(.a\) ... $$@
 	$(V)$$(toolchain_$1)ar r $$@ $$^ 2> /dev/null
 	$(V)$$(toolchain_$1)ranlib $$@
 
@@ -223,8 +274,8 @@ implib_$1_$2_$3	:= $$(bindir_$1_$2)/lib$3.a
 $$(dll_$1_$2_$3) $$(implib_$1_$2_$3):	$$(obj_$1_$2_$3) $$(abslib_$1_$2_$3) \
 					$$(absdpl_$1_$2_$3) \
 					$$(srcdir_$3)/$3.def | $$(bindir_$1_$2)
-	$(V)echo ... $$(dll_$1_$2_$3)
-	$(V)$$(toolchain_$1)gcc -shared \
+	$(V)echo \(.dll\) ... $$(dll_$1_$2_$3)
+	$(V)$$(toolchain_$1)g++ -shared \
 		-o $$(dll_$1_$2_$3) -Wl,--out-implib,$$(implib_$1_$2_$3) \
 		-Wl,--start-group $$^ -Wl,--end-group $$(ldflags_$3)
 	$(V)$$(toolchain_$1)strip $$(dll_$1_$2_$3)
@@ -242,8 +293,8 @@ exe_$1_$2_$3	:= $$(bindir_$1_$2)/$3.exe
 
 $$(exe_$1_$2_$3): $$(obj_$1_$2_$3) $$(abslib_$1_$2_$3) $$(absdpl_$1_$2_$3) \
 		| $$(bindir_$1_$2)
-	$(V)echo ... $$@
-	$(V)$$(toolchain_$1)gcc -o $$@ $$^ $$(ldflags_$3)
+	$(V)echo \(.exe\) ... $$@
+	$(V)$$(toolchain_$1)g++ -o $$@ $$^ $$(ldflags_$3)
 	$(V)$$(toolchain_$1)strip $$@
 
 endef
@@ -255,7 +306,7 @@ define t_import
 impdef_$1_$2_$3	?= src/imports/import_$1_$2_$3.def
 
 $$(bindir_$1_$2)/lib$3.a: $$(impdef_$1_$2_$3) | $$(bindir_$1_$2)
-	$(V)echo ... $$@ [dlltool]
+	$(V)echo \(.a\) ... $$@ [dlltool]
 	$(V)$$(toolchain_$1)dlltool --kill-at -l $$@ -d $$<
 
 endef

Module.mk

@@ -57,6 +57,7 @@
 #                   beatmania IIDX 22 PENDUAL
 #					beatmania IIDX 23 copula
 #                   beatmania IIDX 24 SINOBUZ
+#       Patch 3:    DanceDanceRevoluion A20+ (64-bit)
 #     "Patch" 3:    Silent Scope Bone Eater (compatible with p7)
 #	  "Patch" 7:    Steel Chronicle VicTroopers (not a Bemani, w/e)
 #
@@ -79,7 +80,7 @@ cflags          += \
 # Each AVS-dependent project should consume the earliest AVS import definition
 # that is still ABI-compatible with the real build its target links against.
 
-avsvers_32      := 1700 1603 1601 1508 1403 1304 1101 1002 803 0
+avsvers_32      := 1700 1603 1601 1508 1403 1306 1304 1101 1002 803 0
 avsvers_64      := 1700 1603 1601 1509 1508
 
 imps            += avs avs-ea3
@@ -90,6 +91,7 @@ include src/main/acioemu/Module.mk
 include src/main/aciomgr/Module.mk
 include src/main/aciotest/Module.mk
 include src/main/asio/Module.mk
+include src/main/avs-util/Module.mk
 include src/main/bio2drv/Module.mk
 include src/main/bio2emu-iidx/Module.mk
 include src/main/bio2emu/Module.mk
@@ -98,18 +100,28 @@ include src/main/bstio/Module.mk
 include src/main/camhook/Module.mk
 include src/main/cconfig/Module.mk
 include src/main/config/Module.mk
+include src/main/d3d9-frame-graph-hook/Module.mk
+include src/main/d3d9-monitor-check/Module.mk
+include src/main/d3d9-util/Module.mk
 include src/main/d3d9exhook/Module.mk
 include src/main/ddrhook-util/Module.mk
 include src/main/ddrhook1/Module.mk
 include src/main/ddrhook2/Module.mk
+include src/main/ddrio-async/Module.mk
+include src/main/ddrio-p3io/Module.mk
 include src/main/ddrio-mm/Module.mk
 include src/main/ddrio-smx/Module.mk
+include src/main/ddriotest/Module.mk
 include src/main/ddrio/Module.mk
 include src/main/dinput/Module.mk
 include src/main/eamio-icca/Module.mk
 include src/main/eamio/Module.mk
 include src/main/eamiotest/Module.mk
+include src/main/extio/Module.mk
+include src/main/extiodrv/Module.mk
+include src/main/extiotest/Module.mk
 include src/main/ezusb-emu/Module.mk
+include src/main/ezusb-iidx-16seg-emu/Module.mk
 include src/main/ezusb-iidx-emu/Module.mk
 include src/main/ezusb-iidx-fpga-flash/Module.mk
 include src/main/ezusb-iidx-sram-flash/Module.mk
@@ -131,6 +143,7 @@ include src/main/iidx-bio2-exit-hook/Module.mk
 include src/main/iidx-ezusb-exit-hook/Module.mk
 include src/main/iidx-ezusb2-exit-hook/Module.mk
 include src/main/iidx-irbeat-patch/Module.mk
+include src/main/iidxhook-d3d9/Module.mk
 include src/main/iidxhook-util/Module.mk
 include src/main/iidxhook1/Module.mk
 include src/main/iidxhook2/Module.mk
@@ -143,11 +156,15 @@ include src/main/iidxhook6/Module.mk
 include src/main/iidxhook7/Module.mk
 include src/main/iidxhook8/Module.mk
 include src/main/iidxhook9/Module.mk
+include src/main/iidxio-async/Module.mk
 include src/main/iidxio-bio2/Module.mk
 include src/main/iidxio-ezusb/Module.mk
 include src/main/iidxio-ezusb2/Module.mk
 include src/main/iidxio/Module.mk
 include src/main/iidxiotest/Module.mk
+include src/main/imgui/Module.mk
+include src/main/imgui-bt/Module.mk
+include src/main/imgui-debug/Module.mk
 include src/main/inject/Module.mk
 include src/main/jbio-magicbox/Module.mk
 include src/main/jbio-p4io/Module.mk
@@ -161,8 +178,12 @@ include src/main/jbhook3/Module.mk
 include src/main/launcher/Module.mk
 include src/main/mempatch-hook/Module.mk
 include src/main/mm/Module.mk
+include src/main/nv/Module.mk
+include src/main/nvgpu/Module.mk
 include src/main/p3io/Module.mk
+include src/main/p3iodrv/Module.mk
 include src/main/p3ioemu/Module.mk
+include src/main/p3io-ddr-tool/Module.mk
 include src/main/p4iodrv/Module.mk
 include src/main/p4ioemu/Module.mk
 include src/main/popnhook-util/Module.mk
@@ -181,6 +202,7 @@ include src/main/util/Module.mk
 include src/main/vefxio/Module.mk
 include src/main/vigem-iidxio/Module.mk
 include src/main/vigem-sdvxio/Module.mk
+include src/main/vigem-ddrio/Module.mk
 include src/main/vigemstub/Module.mk
 
 include src/test/cconfig/Module.mk
@@ -202,6 +224,7 @@ $(zipdir)/:
 
 $(zipdir)/tools.zip: \
 		build/bin/indep-32/aciotest.exe \
+		build/bin/indep-32/ddriotest.exe \
 		build/bin/indep-32/eamiotest.exe \
 		build/bin/indep-32/ezusb-iidx-fpga-flash.exe \
 		build/bin/indep-32/ezusb-iidx-sram-flash.exe \
@@ -217,12 +240,16 @@ $(zipdir)/tools.zip: \
 		build/bin/indep-32/ezusb2-dbg-hook.dll \
 		build/bin/indep-32/ezusb2-tool.exe \
 		build/bin/indep-32/ezusb-tool.exe \
+		build/bin/indep-32/nvgpu.exe \
+		build/bin/indep-32/d3d9-frame-graph-hook.dll \
+		build/bin/indep-32/d3d9-monitor-check.exe \
 		| $(zipdir)/
 	$(V)echo ... $@
 	$(V)zip -j $@ $^
 
 $(zipdir)/tools-x64.zip: \
 		build/bin/indep-64/aciotest.exe \
+		build/bin/indep-64/ddriotest.exe \
 		build/bin/indep-64/eamiotest.exe \
 		build/bin/indep-64/iidxiotest.exe \
 		build/bin/indep-64/iidx-bio2-exit-hook.dll \
@@ -230,6 +257,9 @@ $(zipdir)/tools-x64.zip: \
 		build/bin/indep-64/iidx-ezusb2-exit-hook.dll \
 		build/bin/indep-64/jbiotest.exe \
 		build/bin/indep-64/mempatch-hook.dll \
+		build/bin/indep-64/nvgpu.exe \
+		build/bin/indep-64/d3d9-frame-graph-hook.dll \
+		build/bin/indep-64/d3d9-monitor-check.exe \
 		| $(zipdir)/
 	$(V)echo ... $@
 	$(V)zip -j $@ $^
@@ -276,7 +306,7 @@ $(zipdir)/iidx-13.zip: \
 	$(V)zip -j $@ $^
 
 $(zipdir)/iidx-14-to-17.zip: \
-		build/bin/avs2_0-32/iidxhook3.dll \
+		build/bin/avs2_803-32/iidxhook3.dll \
 		build/bin/indep-32/config.exe \
 		build/bin/indep-32/eamio.dll \
 		build/bin/indep-32/geninput.dll \
@@ -415,7 +445,7 @@ $(zipdir)/iidx-25-to-26.zip: \
 	$(V)echo ... $@
 	$(V)zip -j $@ $^
 
-$(zipdir)/iidx-27-to-28.zip: \
+$(zipdir)/iidx-27-to-31.zip: \
 		build/bin/avs2_1700-64/iidxhook9.dll \
 		build/bin/avs2_1700-64/launcher.exe \
 		build/bin/indep-64/config.exe \
@@ -426,8 +456,14 @@ $(zipdir)/iidx-27-to-28.zip: \
 		dist/iidx/config.bat \
 		dist/iidx/gamestart-27.bat \
 		dist/iidx/gamestart-28.bat \
+		dist/iidx/gamestart-29.bat \
+		dist/iidx/gamestart-30.bat \
+		dist/iidx/gamestart-31.bat \
 		dist/iidx/iidxhook-27.conf \
 		dist/iidx/iidxhook-28.conf \
+		dist/iidx/iidxhook-29.conf \
+		dist/iidx/iidxhook-30.conf \
+		dist/iidx/iidxhook-31.conf \
 		dist/iidx/vefx.txt \
 		| $(zipdir)/
 	$(V)echo ... $@
@@ -436,6 +472,7 @@ $(zipdir)/iidx-27-to-28.zip: \
 $(zipdir)/iidx-hwio-x86.zip: \
 		build/bin/indep-32/aciomgr.dll \
 		build/bin/indep-32/eamio-icca.dll \
+		build/bin/indep-32/iidxio-async.dll \
 		build/bin/indep-32/iidxio-bio2.dll \
 		build/bin/indep-32/iidxio-ezusb.dll \
 		build/bin/indep-32/iidxio-ezusb2.dll \
@@ -449,6 +486,7 @@ $(zipdir)/iidx-hwio-x86.zip: \
 $(zipdir)/iidx-hwio-x64.zip: \
 		build/bin/indep-64/aciomgr.dll \
 		build/bin/indep-64/eamio-icca.dll \
+		build/bin/indep-64/iidxio-async.dll \
 		build/bin/indep-64/iidxio-bio2.dll \
 		build/bin/indep-64/iidxio-ezusb.dll \
 		build/bin/indep-64/iidxio-ezusb2.dll \
@@ -666,9 +704,9 @@ $(zipdir)/ddr-12.zip: \
 	$(V)zip -j $@ $^
 
 $(zipdir)/ddr-13.zip: \
-		build/bin/avs2_1304-32/launcher.exe \
-		build/bin/avs2_1304-32/ddrhook2.dll \
-		build/bin/avs2_1304-32/unicorntail.dll \
+		build/bin/avs2_1306-32/launcher.exe \
+		build/bin/avs2_1306-32/ddrhook2.dll \
+		build/bin/avs2_1306-32/unicorntail.dll \
 		build/bin/indep-32/config.exe \
 		build/bin/indep-32/ddrio.dll \
 		build/bin/indep-32/ddrio-mm.dll \
@@ -681,36 +719,64 @@ $(zipdir)/ddr-13.zip: \
 	$(V)echo ... $@
 	$(V)zip -j $@ $^
 
-$(zipdir)/ddr-14-to-16.zip: \
+$(zipdir)/ddr-14-to-18.zip: \
 		build/bin/avs2_1508-32/launcher.exe \
 		build/bin/avs2_1508-32/ddrhook2.dll \
 		build/bin/avs2_1508-32/unicorntail.dll \
 		build/bin/indep-32/config.exe \
 		build/bin/indep-32/ddrio.dll \
-		build/bin/indep-32/ddrio-mm.dll \
-		build/bin/indep-32/ddrio-smx.dll \
 		build/bin/indep-32/eamio.dll \
 		build/bin/indep-32/geninput.dll \
 		dist/ddr/config.bat \
+		dist/ddr/gamestart-17.bat \
+		dist/ddr/gamestart-18.bat \
 		dist/ddr/gamestart-14.bat \
 		dist/ddr/gamestart-15.bat \
 		dist/ddr/gamestart-16.bat \
+		dist/ddr/gamestart-17.bat \
+		dist/ddr/gamestart-18.bat \
 		| $(zipdir)/
 	$(V)echo ... $@
 	$(V)zip -j $@ $^
 
-$(zipdir)/ddr-16-x64.zip: \
+$(zipdir)/ddr-16-to-18-x64.zip: \
 		build/bin/avs2_1603-64/launcher.exe \
 		build/bin/avs2_1603-64/ddrhook2.dll \
 		build/bin/avs2_1603-64/unicorntail.dll \
 		build/bin/indep-64/config.exe \
 		build/bin/indep-64/ddrio.dll \
-		build/bin/indep-64/ddrio-mm.dll \
-		build/bin/indep-64/ddrio-smx.dll \
 		build/bin/indep-64/eamio.dll \
 		build/bin/indep-64/geninput.dll \
 		dist/ddr/config.bat \
+		dist/ddr/gamestart-17.bat \
+		dist/ddr/gamestart-18.bat \
 		dist/ddr/gamestart-16.bat \
+		dist/ddr/gamestart-17.bat \
+		dist/ddr/gamestart-18.bat \
+		| $(zipdir)/
+	$(V)echo ... $@
+	$(V)zip -j $@ $^
+
+$(zipdir)/ddr-hwio-x86.zip: \
+		build/bin/indep-32/ddrio-async.dll \
+		build/bin/indep-32/ddrio-p3io.dll \
+		build/bin/indep-32/ddrio-mm.dll \
+		build/bin/indep-32/ddrio-smx.dll \
+		build/bin/indep-32/extiotest.exe \
+		build/bin/indep-32/p3io-ddr-tool.exe \
+		build/bin/indep-32/vigem-ddrio.exe \
+		| $(zipdir)/
+	$(V)echo ... $@
+	$(V)zip -j $@ $^
+
+$(zipdir)/ddr-hwio-x64.zip: \
+		build/bin/indep-64/ddrio-async.dll \
+		build/bin/indep-64/ddrio-p3io.dll \
+		build/bin/indep-64/ddrio-mm.dll \
+		build/bin/indep-64/ddrio-smx.dll \
+		build/bin/indep-64/extiotest.exe \
+		build/bin/indep-64/p3io-ddr-tool.exe \
+		build/bin/indep-64/vigem-ddrio.exe \
 		| $(zipdir)/
 	$(V)echo ... $@
 	$(V)zip -j $@ $^
@@ -788,8 +854,10 @@ $(BUILDDIR)/bemanitools.zip: \
 		$(zipdir)/ddr-12.zip \
 		$(zipdir)/ddr-12-us.zip \
 		$(zipdir)/ddr-13.zip \
-		$(zipdir)/ddr-14-to-16.zip \
-		$(zipdir)/ddr-16-x64.zip \
+		$(zipdir)/ddr-14-to-18.zip \
+		$(zipdir)/ddr-16-to-18-x64.zip \
+		$(zipdir)/ddr-hwio-x86.zip \
+		$(zipdir)/ddr-hwio-x64.zip \
 		$(zipdir)/doc.zip \
 		$(zipdir)/iidx-09-to-12.zip \
 		$(zipdir)/iidx-13.zip \
@@ -801,7 +869,7 @@ $(BUILDDIR)/bemanitools.zip: \
 		$(zipdir)/iidx-20-cn.zip \
 		$(zipdir)/iidx-21-to-24.zip \
 		$(zipdir)/iidx-25-to-26.zip \
-		$(zipdir)/iidx-27-to-28.zip \
+		$(zipdir)/iidx-27-to-31.zip \
 		$(zipdir)/iidx-hwio-x86.zip \
 		$(zipdir)/iidx-hwio-x64.zip \
 		$(zipdir)/jb-01.zip \

README.md

@@ -1,164 +1,193 @@
 # Bemanitools 5
-[![pipeline status](https://dev.s-ul.net/djhackers/bemanitools/badges/master/pipeline.svg)](https://dev.s-ul.net/djhackers/bemanitools/commits/master)
 
-Version: 5.42
+Version: `5.50`
 
-[Release history](CHANGELOG.md)
+[Changelog](CHANGELOG.md)
 
-A collection of tools to run [various Bemani arcade games](#list-of-supported-games).
+A collection of tools to run [various Bemani arcade games](#supported-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.
+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](doc/README.md) 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](CONTRIBUTING.md).
 
 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](CONTRIBUTING.md#reporting-and-discussions-issues-section-on-github)
-* [ALWAYS report bugs as issues and ALWAYS use the available bug template](CONTRIBUTING.md#bug-reports)
-* [Everyone is allowed to submit changes which are not just limited to code by opening merge requests](CONTRIBUTING.md#pull-requests-bugfixes-new-features-or-other-code-contributions)
-* [Documentation improvements can and even should be contributed by non developers](CONTRIBUTING.md#pull-requests-bugfixes-new-features-or-other-code-contributions)
+
+- **EVERYONE** can contribute, this is **NOT** limited to people coding
+- [Open an issue on gitlab for discussions, feature requests and bug reports](CONTRIBUTING.md#reporting-and-discussions-issues-section-on-github)
+- [ALWAYS report bugs as issues and ALWAYS use the available bug template](CONTRIBUTING.md#bug-reports)
+- [Everyone is allowed to submit changes which are not just limited to code by opening merge requests](CONTRIBUTING.md#pull-requests-bugfixes-new-features-or-other-code-contributions)
+- [Documentation improvements can and even should be contributed by non developers](CONTRIBUTING.md#pull-requests-bugfixes-new-features-or-other-code-contributions)
 
 ## Supported games
+
 The following games are supported with their corresponding hook-libraries.
 
-* BeatStream
-    * BeatStream (`bst.zip`): bsthook
-    * BeatStream アニムトライヴ (`bst.zip`): bsthook
-* [Dance Dance Revolution](doc/ddrhook/README.md)
-    * Dance Dance Revolution X (`ddr-11.zip`): [ddrhook1](doc/ddrhook/ddrhook1.md)
-    * Dance Dance Revolution X2 (US/EU regions) (`ddr-12-us.zip`): [ddrhook1](doc/ddrhook/ddrhook1.md)
-    * Dance Dance Revolution X2 (JP region) (`ddr-12.zip`): [ddrhook2](doc/ddrhook/ddrhook2.md)
-    * Dance Dance Revolution 2013 (`ddr-14-to-16.zip`): [ddrhook2](doc/ddrhook/ddrhook2.md)
-    * Dance Dance Revolution 2014 (`ddr-14-to-16.zip`): [ddrhook2](doc/ddrhook/ddrhook2.md)
-    * Dance Dance Revolution A (`ddr-14-to-16.zip`): [ddrhook2](doc/ddrhook/ddrhook2.md)
-* [Beatmania IIDX](doc/iidxhook/README.md)
-    * Beatmania IIDX 9th Style (`iidx-09-to-12.zip`): [iidxhook1](doc/iidxhook/iidxhook1.md)
-    * Beatmania IIDX 10th Style (`iidx-09-to-12.zip`): [iidxhook1](doc/iidxhook/iidxhook1.md)
-    * Beatmania IIDX 11 IIDX RED (`iidx-09-to-12.zip`): [iidxhook1](doc/iidxhook/iidxhook1.md)
-    * Beatmania IIDX 12 HAPPY SKY (`iidx-09-to-12.zip`): [iidxhook1](doc/iidxhook/iidxhook1.md)
-    * Beatmania IIDX 13 DistorteD (`iidx-13.zip`): [iidxhook2](doc/iidxhook/iidxhook2.md)
-    * Beatmania IIDX 14 GOLD (`iidx-14-to-17.zip`): [iidxhook3](doc/iidxhook/iidxhook3.md)
-    * Beatmania IIDX 15 DJ TROOPERS (`iidx-14-to-17.zip`): [iidxhook3](doc/iidxhook/iidxhook3.md)
-    * Beatmania IIDX 16 EMPRESS (`iidx-14-to-17.zip`): [iidxhook3](doc/iidxhook/iidxhook3.md)
-    * Beatmania IIDX 17 SIRIUS (`iidx-14-to-17.zip`): [iidxhook3](doc/iidxhook/iidxhook3.md)
-    * Beatmania IIDX 18 Resort Anthem (`iidx-18.zip`): [iidxhook4](doc/iidxhook/iidxhook4.md)
-    * Beatmania IIDX 19 Lincle (`iidx-19.zip`): [iidxhook5](doc/iidxhook/iidxhook5.md)
-    * Beatmania IIDX tricoro CN (狂热节拍 IIDX 2) (`iidx-20-cn.zip`): [iidxhook5-cn](doc/iidxhook/iidxhook5-cn.md)
-    * Beatmania IIDX 20 Tricoro (`iidx-20.zip`): [iidxhook6](doc/iidxhook/iidxhook6.md)
-    * Beatmania IIDX 21 SPADA (`iidx-21-to-24.zip`): [iidxhook7](doc/iidxhook/iidxhook7.md)
-    * Beatmania IIDX 22 PENDUAL (`iidx-21-to-24.zip`): [iidxhook7](doc/iidxhook/iidxhook7.md)
-    * Beatmania IIDX 23 copula (`iidx-21-to-24.zip`): [iidxhook7](doc/iidxhook/iidxhook7.md)
-    * Beatmania IIDX 24 SINOBUZ (`iidx-21-to-24.zip`): [iidxhook7](doc/iidxhook/iidxhook7.md)
-    * Beatmania IIDX 25 CANNON BALLERS (`iidx-25-to-26.zip`): [iidxhook8](doc/iidxhook/iidxhook8.md)
-    * Beatmania IIDX 26 Rootage (`iidx-25-to-26.zip`): [iidxhook8](doc/iidxhook/iidxhook8.md)
-    * Beatmania IIDX 27 Heroic Verse (`iidx-27-to-28.zip`): [iidxhook9](doc/iidxhook/iidxhook9.md)
-    * Beatmania IIDX 28 BISTROVER (`iidx-27-to-28.zip`): [iidxhook9](doc/iidxhook/iidxhook9.md)
-* [jubeat](doc/jbhook/README.md)
-    * jubeat (`jb-01.zip`): [jbhook1](doc/jbhook/jbhook1.md)
-    * jubeat ripples (`jb-02.zip`): [jbhook1](doc/jbhook/jbhook1.md)
-    * jubeat knit (`jb-03.zip`): [jbhook2](doc/jbhook/jbhook2.md)
-    * jubeat copious (`jb-04.zip`): [jbhook2](doc/jbhook/jbhook2.md)
-    * jubeat saucer (fulfill) (`jb-05-to-07.zip`): [jbhook3](doc/jbhook/jbhook3.md)
-    * jubeat prop (`jb-05-to-07.zip`): [jbhook3](doc/jbhook/jbhook3.md)
-    * jubeat qubell (`jb-05-to-07.zip`): [jbhook3](doc/jbhook/jbhook3.md)
-    * jubeat clan (`jb-08.zip`): [jbhook3](doc/jbhook/jbhook3.md)
-    * jubeat festo (`jb-08.zip`): [jbhook3](doc/jbhook/jbhook3.md)
-* [pop'n music](doc/popnhook/README.md)
-    * pop'n music 15 ADVENTURE (`popn-15-to-18.zip`) using [popnhook1](doc/popnhook/popnhook1.md)
-    * pop'n music 16 PARTY♪ (`popn-15-to-18.zip`) using [popnhook1](doc/popnhook/popnhook1.md)
-    * pop'n music 17 THE MOVIE (`popn-15-to-18.zip`) using [popnhook1](doc/popnhook/popnhook1.md)
-    * pop'n music 18 せんごく列伝 (`popn-15-to-18.zip`) using [popnhook1](doc/popnhook/popnhook1.md)
-* SOUND VOLTEX
-    * SOUND VOLTEX BOOTH (`sdvx-01-to-04.zip`): sdvxhook
-    * SOUND VOLTEX II -infinite infection- (`sdvx-01-to-04.zip`): sdvxhook
-    * SOUND VOLTEX III GRAVITY WARS (`sdvx-01-to-04.zip`): sdvxhook
-    * SOUND VOLTEX IV HEAVENLY HAVEN (`sdvx-01-to-04.zip`): sdvxhook
-    * SOUND VOLTEX Vivid Wave (`sdvx-05-to-06`): sdvxhook2
-    * SOUND VOLTEX EXCEED GEAR (`sdvx-05-to-06`): sdvxhook2
+- BeatStream
+  - BeatStream (`bst.zip`): bsthook
+  - BeatStream アニムトライヴ (`bst.zip`): bsthook
+- [Dance Dance Revolution](doc/ddrhook/README.md)
+  - Dance Dance Revolution X (`ddr-11.zip`): [ddrhook1](doc/ddrhook/ddrhook1.md)
+  - Dance Dance Revolution X2 (US/EU regions) (`ddr-12-us.zip`): [ddrhook1](doc/ddrhook/ddrhook1.md)
+  - Dance Dance Revolution X2 (JP region) (`ddr-12.zip`): [ddrhook2](doc/ddrhook/ddrhook2.md)
+  - Dance Dance Revolution X3 vs. 2ndMIX (`ddr-13.zip`): [ddrhook2](doc/ddrhook/ddrhook2.md)
+  - Dance Dance Revolution 2013 (`ddr-14-to-18.zip`): [ddrhook2](doc/ddrhook/ddrhook2.md)
+  - Dance Dance Revolution 2014 (`ddr-14-to-18.zip`): [ddrhook2](doc/ddrhook/ddrhook2.md)
+  - Dance Dance Revolution A (`ddr-14-to-18.zip`): [ddrhook2](doc/ddrhook/ddrhook2.md)
+  - Dance Dance Revolution A20 (`ddr-14-to-18.zip`): [ddrhook2](doc/ddrhook/ddrhook2.md)
+  - Dance Dance Revolution A20+ (`ddr-14-to-18.zip`): [ddrhook2](doc/ddrhook/ddrhook2.md)
+- [Beatmania IIDX](doc/iidxhook/README.md)
+  - Beatmania IIDX 9th Style (`iidx-09-to-12.zip`): [iidxhook1](doc/iidxhook/iidxhook1.md)
+  - Beatmania IIDX 10th Style (`iidx-09-to-12.zip`): [iidxhook1](doc/iidxhook/iidxhook1.md)
+  - Beatmania IIDX 11 IIDX RED (`iidx-09-to-12.zip`): [iidxhook1](doc/iidxhook/iidxhook1.md)
+  - Beatmania IIDX 12 HAPPY SKY (`iidx-09-to-12.zip`): [iidxhook1](doc/iidxhook/iidxhook1.md)
+  - Beatmania IIDX 13 DistorteD (`iidx-13.zip`): [iidxhook2](doc/iidxhook/iidxhook2.md)
+  - Beatmania IIDX 14 GOLD (`iidx-14-to-17.zip`): [iidxhook3](doc/iidxhook/iidxhook3.md)
+  - Beatmania IIDX 15 DJ TROOPERS (`iidx-14-to-17.zip`): [iidxhook3](doc/iidxhook/iidxhook3.md)
+  - Beatmania IIDX 16 EMPRESS (`iidx-14-to-17.zip`): [iidxhook3](doc/iidxhook/iidxhook3.md)
+  - Beatmania IIDX 17 SIRIUS (`iidx-14-to-17.zip`): [iidxhook3](doc/iidxhook/iidxhook3.md)
+  - Beatmania IIDX 18 Resort Anthem (`iidx-18.zip`): [iidxhook4](doc/iidxhook/iidxhook4.md)
+  - Beatmania IIDX 19 Lincle (`iidx-19.zip`): [iidxhook5](doc/iidxhook/iidxhook5.md)
+  - Beatmania IIDX tricoro CN (狂热节拍 IIDX 2) (`iidx-20-cn.zip`):
+    [iidxhook5-cn](doc/iidxhook/iidxhook5-cn.md)
+  - Beatmania IIDX 20 Tricoro (`iidx-20.zip`): [iidxhook6](doc/iidxhook/iidxhook6.md)
+  - Beatmania IIDX 21 SPADA (`iidx-21-to-24.zip`): [iidxhook7](doc/iidxhook/iidxhook7.md)
+  - Beatmania IIDX 22 PENDUAL (`iidx-21-to-24.zip`): [iidxhook7](doc/iidxhook/iidxhook7.md)
+  - Beatmania IIDX 23 copula (`iidx-21-to-24.zip`): [iidxhook7](doc/iidxhook/iidxhook7.md)
+  - Beatmania IIDX 24 SINOBUZ (`iidx-21-to-24.zip`): [iidxhook7](doc/iidxhook/iidxhook7.md)
+  - Beatmania IIDX 25 CANNON BALLERS (`iidx-25-to-26.zip`): [iidxhook8](doc/iidxhook/iidxhook8.md)
+  - Beatmania IIDX 26 Rootage (`iidx-25-to-26.zip`): [iidxhook8](doc/iidxhook/iidxhook8.md)
+  - Beatmania IIDX 27 Heroic Verse (`iidx-27-to-30.zip`): [iidxhook9](doc/iidxhook/iidxhook9.md)
+  - Beatmania IIDX 28 BISTROVER (`iidx-27-to-30.zip`): [iidxhook9](doc/iidxhook/iidxhook9.md)
+  - Beatmania IIDX 29 CASTHOUR (`iidx-27-to-30.zip`): [iidxhook9](doc/iidxhook/iidxhook9.md)
+  - Beatmania IIDX 30 RESIDENT (`iidx-27-to-30.zip`): [iidxhook9](doc/iidxhook/iidxhook9.md)
+  - Beatmania IIDX 31 EPOLIS (`iidx-27-to-31.zip`): [iidxhook9](doc/iidxhook/iidxhook9.md)
+- [jubeat](doc/jbhook/README.md)
+  - jubeat (`jb-01.zip`): [jbhook1](doc/jbhook/jbhook1.md)
+  - jubeat ripples (`jb-02.zip`): [jbhook1](doc/jbhook/jbhook1.md)
+  - jubeat knit (`jb-03.zip`): [jbhook2](doc/jbhook/jbhook2.md)
+  - jubeat copious (`jb-04.zip`): [jbhook2](doc/jbhook/jbhook2.md)
+  - jubeat saucer (fulfill) (`jb-05-to-07.zip`): [jbhook3](doc/jbhook/jbhook3.md)
+  - jubeat prop (`jb-05-to-07.zip`): [jbhook3](doc/jbhook/jbhook3.md)
+  - jubeat qubell (`jb-05-to-07.zip`): [jbhook3](doc/jbhook/jbhook3.md)
+  - jubeat clan (`jb-08.zip`): [jbhook3](doc/jbhook/jbhook3.md)
+  - jubeat festo (`jb-08.zip`): [jbhook3](doc/jbhook/jbhook3.md)
+- [pop'n music](doc/popnhook/README.md)
+  - pop'n music 15 ADVENTURE (`popn-15-to-18.zip`) using [popnhook1](doc/popnhook/popnhook1.md)
+  - pop'n music 16 PARTY♪ (`popn-15-to-18.zip`) using [popnhook1](doc/popnhook/popnhook1.md)
+  - pop'n music 17 THE MOVIE (`popn-15-to-18.zip`) using [popnhook1](doc/popnhook/popnhook1.md)
+  - pop'n music 18 せんごく列伝 (`popn-15-to-18.zip`) using [popnhook1](doc/popnhook/popnhook1.md)
+- SOUND VOLTEX
+  - SOUND VOLTEX BOOTH (`sdvx-01-to-04.zip`): sdvxhook
+  - SOUND VOLTEX II -infinite infection- (`sdvx-01-to-04.zip`): sdvxhook
+  - SOUND VOLTEX III GRAVITY WARS (`sdvx-01-to-04.zip`): sdvxhook
+  - SOUND VOLTEX IV HEAVENLY HAVEN (`sdvx-01-to-04.zip`): sdvxhook
+  - SOUND VOLTEX Vivid Wave (`sdvx-05-to-06`): sdvxhook2
+  - SOUND VOLTEX EXCEED GEAR (`sdvx-05-to-06`): 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.
+## Auxiliary tooling
 
-See the dedicated [readme](doc/vigem/README.md) for details.
+- Bootstrapping
+  - [inject](doc/inject.md): Inject arbitrary hooking libraries into a target application process.
+  - [launcher](doc/launcher.md): Bootstrap Konami's AVS environment and launch a target application
+    with arbitrary injected hooking libraries.
+- Beatmnia IIDX Ezusb IO board
+  - [ezusb-iidx-fpga-flash](doc/tools/ezusb-iidx-fpga-flash.md): Flash a binary blob with FPGA
+    firmware to a target ezusb FX IO board
+  - [ezusb-iidx-sram-flash](doc/tools/ezusb-iidx-sram-flash.md): Flash a binary blob with SRAM
+    contents to a target ezusb FX2 IO board
+- Exit hooks: Exit the game with a button combination using native cabinet inputs
+  - [iidx-ezusb-exit-hook](doc/tools/iidx-ezusb-exit-hook.md): For IIDX with ezusb IO
+  - [iidx-bio2-exit-hook](doc/tools/iidx-bio2-exit-hook.md): For IIDX with BIO2 IO
+  - [iidx-ezusb2-exit-hook](doc/tools/iidx-ezusb-exit-hook.md): For IIDX with ezusb FX2 IO
+- Bemanitools API testing: Tools for testing bemanitools API implementations
+  - [ddriotest](doc/tools/ddriotest.md): For [ddrio API](doc/api.md#io-boards)
+  - [eamiotest](doc/tools/eamiotest.md): For [eamio API](doc/api.md#eamuse-readers)
+  - [iidxiotest](doc/tools/iidxiotest.md): For [iidxio API](doc/api.md#io-boards)
+  - [jbiotest](doc/tools/jbiotest.md): For [jbio API](doc/api.md#io-boards)
+- DDR IO testing: Tools for testing hardware of a real DDR cabinet
+  - [p3io-ddr-tool](doc/tools/p3io-ddr-tool.md)
+  - [extiotest](doc/tools/extiotest.md)
+- [aciotest](doc/tools/aciotest.md): Command line tool to quickly test ACIO devices
+- config: UI input/output configuration tool when using the default bemanitools API (geninput)
+- [d3d9-monitor-check](doc/tools/d3d9-monitor-check.md): Command line tool to check the monitor refresh rate of the
+  current GPU + monitor configuration
+- ir-beat-patch-9/10: Patch the IR beat phase on IIDX 9 and 10
+- [mempatch-hook](doc/tools/mempatch-hook.md): Patch raw memory locations in the target process
+  based on the provided configuration
+- [nvgpu](doc/tools/nvgpu.md): Command line tool to configure and tweak the NVIDIA GPU driver
+- [pcbidgen](doc/tools/pcbidgen.md): Konami PCBID generator tool
+- [ViGEm clients](doc/vigem/README.md): Expose BT5 APIs as XBOX game controllers to play any games
+  with real cabinet hardware.
 
-## 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.
+## Pre-requisites
 
-## Distribution contents
-Check the [list of supported games](#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).
+### Supported platforms
 
-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.
+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](#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
 
-## 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
+
+- The 32-bit (x86) version of
+  [Microsoft Visual C++ 2010 Service Pack 1 Redistributable Package MFC Security Update](https://www.microsoft.com/en-sg/download/details.aspx?id=26999)
+- The 32-bit (x86) and 64-bit (x64) versions of
+  [Microsoft Visual C++ Redistributable Packages for Visual Studio 2013](https://www.microsoft.com/en-sg/download/details.aspx?id=40784)
+- The
+  [DirectX 9 End-User Runtimes (June 2010)](https://www.microsoft.com/en-us/download/details.aspx?id=8109)
+
+See also [bemanitools-supplement](https://www.github.com/djhackersdev/bemanitools-supplement/) for
+files.
 
 ## Development
+
 ### Building
+
 See the [development document](doc/development.md).
 
 ### Architecture
-A dedicate [architecture document](doc/architecture.md) outlines the architecture of Bemanitools and points out the most
-important aspects you should know before you get started with development.
+
+A dedicate [architecture document](doc/architecture.md) 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](doc/api.md).
 
 ## Release process
-Steps for the release process:
-1. Update the corresponding section in the [changelog](CHANGELOG.md) with bullet points reflecting
-major features merged into master since the previous release
-1. Make sure you have the latest `master` state pulled to your local copy
-1. Tag the release with the next release number which also be found at the
-[top of the readme](#bemanitools-5) as it always reflects the current version beinged worked on
-on the `master` branch , e.g. 5.35: `git tag 5.35`
-1. Push the tag to upstream: `git push origin 5.35`
-1. The [build pipeline](https://dev.s-ul.net/djhackers/bemanitools/-/pipelines) should start
-automatically once the tag is pushed including the steps `build` and `upload-release`
-1. Once completed successfully, the release is uploaded
-1. 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>
-        ```
-    1. Update the OP title by bumping the version number in it
-    1. Update the OP post by extending it accordingly (see previous entries)
-
-1. Bump the version number at the [top of this readme](#bemanitools-5) and add a new empty section
-in the [changelog](CHANGELOG.md) with the new version number as title. Commit changes and push to
-`master` branch
-1. Continue developing and merging MRs until you decide its time for another release
+Please refer to the [dedicated documentation](doc/release-process.md).
 
 ## 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](LICENSE) included with the source code.
-
-
-
-
-
 
+Source code license is the Unlicense; you are permitted to do with this as thou wilt. For details,
+please refer to the [LICENSE file](LICENSE) included with the source code.

dist/ddr/gamestart-17.bat

@@ -0,0 +1,15 @@
+@echo off
+
+cd /d %~dp0
+
+if not exist conf\nvram mkdir conf\nvram
+if not exist conf\nvram\ea3-config.xml copy prop\eamuse-config.xml conf\nvram\ea3-config.xml
+if not exist conf\nvram\coin.xml copy prop\coin.xml conf\nvram\coin.xml
+if not exist conf\nvram\eacoin.xml copy prop\eacoin.xml conf\nvram\eacoin.xml
+if not exist conf\nvram\testmode-v.xml copy prop\testmode-v.xml conf\nvram\testmode-v.xml
+if not exist conf\raw mkdir conf\raw
+
+regsvr32 /s com\k-clvsd.dll
+regsvr32 /s com\xactengine2_10.dll
+
+.\launcher.exe -H 33554432 -K .\ddrhook2.dll .\arkmdxp3.dll %*

dist/ddr/gamestart-18.bat

@@ -0,0 +1,15 @@
+@echo off
+
+cd /d %~dp0
+
+if not exist conf\nvram mkdir conf\nvram
+if not exist conf\nvram\ea3-config.xml copy prop\eamuse-config.xml conf\nvram\ea3-config.xml
+if not exist conf\nvram\coin.xml copy prop\coin.xml conf\nvram\coin.xml
+if not exist conf\nvram\eacoin.xml copy prop\eacoin.xml conf\nvram\eacoin.xml
+if not exist conf\nvram\testmode-v.xml copy prop\testmode-v.xml conf\nvram\testmode-v.xml
+if not exist conf\raw mkdir conf\raw
+
+regsvr32 /s com\k-clvsd.dll
+regsvr32 /s com\xactengine2_10.dll
+
+.\launcher.exe -H 33554432 -K .\ddrhook2.dll .\arkmdxp3.dll %*

dist/iidx/gamestart-18-cn.bat

@@ -11,4 +11,7 @@ if not exist e\avs_conf\CONF mkdir e\avs_conf\CONF
 if not exist e\avs_conf\CONF\NVRAM mkdir e\avs_conf\CONF\NVRAM
 if not exist e\avs_conf\CONF\RAW mkdir e\avs_conf\CONF\RAW
 
+if not exist dev\nvram mkdir dev\nvram
+if not exist dev\raw mkdir dev\raw
+
 inject iidxhook4-cn.dll bm2dx.exe -D --config iidxhook-18-cn.conf %*

dist/iidx/gamestart-20-cn.bat

@@ -11,4 +11,7 @@ if not exist e\avs_conf\CONF mkdir e\avs_conf\CONF
 if not exist e\avs_conf\CONF\NVRAM mkdir e\avs_conf\CONF\NVRAM
 if not exist e\avs_conf\CONF\RAW mkdir e\avs_conf\CONF\RAW
 
+if not exist dev\nvram mkdir dev\nvram
+if not exist dev\raw mkdir dev\raw
+
 inject iidxhook5-cn.dll bm2dx.exe -D --config iidxhook-20-cn.conf %*

dist/iidx/gamestart-29.bat

@@ -0,0 +1,16 @@
+@echo off
+cd /d %~dp0
+
+if not exist dev mkdir dev
+if not exist dev\e mkdir dev\e
+if not exist dev\g mkdir dev\g
+if not exist dev\nvram mkdir dev\nvram
+if not exist dev\raw mkdir dev\raw
+if not exist dev\raw\log mkdir dev\raw\log
+if not exist dev\raw\fscache mkdir dev\raw\fscache
+
+for /R prop\defaults %%D in (*.*) do (
+    if not exist dev\nvram\%%~nxD copy /y prop\defaults\%%~nxD dev\nvram
+)
+
+launcher -H 134217728 -B iidxhook9.dll bm2dx.dll --config iidxhook-29.conf %*

dist/iidx/gamestart-30.bat

@@ -0,0 +1,16 @@
+@echo off
+cd /d %~dp0
+
+if not exist dev mkdir dev
+if not exist dev\e mkdir dev\e
+if not exist dev\g mkdir dev\g
+if not exist dev\nvram mkdir dev\nvram
+if not exist dev\raw mkdir dev\raw
+if not exist dev\raw\log mkdir dev\raw\log
+if not exist dev\raw\fscache mkdir dev\raw\fscache
+
+for /R prop\defaults %%D in (*.*) do (
+    if not exist dev\nvram\%%~nxD copy /y prop\defaults\%%~nxD dev\nvram
+)
+
+modules\launcher -H 134217728 -B iidxhook9.dll bm2dx.dll --config iidxhook-30.conf %*

dist/iidx/gamestart-31.bat

@@ -0,0 +1,16 @@
+@echo off
+cd /d %~dp0
+
+if not exist dev mkdir dev
+if not exist dev\e mkdir dev\e
+if not exist dev\g mkdir dev\g
+if not exist dev\nvram mkdir dev\nvram
+if not exist dev\raw mkdir dev\raw
+if not exist dev\raw\log mkdir dev\raw\log
+if not exist dev\raw\fscache mkdir dev\raw\fscache
+
+for /R prop\defaults %%D in (*.*) do (
+    if not exist dev\nvram\%%~nxD copy /y prop\defaults\%%~nxD dev\nvram
+)
+
+modules\launcher -H 134217728 -B iidxhook9.dll bm2dx.dll --config iidxhook-31.conf %*

dist/iidx/iidx-irbeat-patch-09.bat

@@ -1,12 +1,45 @@
 @echo off
+cd /d %~dp0
 
-IF "%1"=="" GOTO USAGE
+REM Open menu if no arguments specified
+if "%~1" == "" goto menu
 
-iidx-irbeat-patch.exe 9 %1 e\\settings.bin.0
-iidx-irbeat-patch.exe 9 %1 f\\settings.bin.1
-GOTO END
+if "%~1" gtr "3" goto badbeat
+if "%~1" == "0" goto badbeat
 
-:USAGE
-	ECHO "Usage: iidx-irbeat-patch.bat <beat phase>"
+set beat = "%~1" - 1
+iidx-irbeat-patch.exe 9 %beat% e\\settings.bin.0
+iidx-irbeat-patch.exe 9 %beat% f\\settings.bin.1
+
+if not errorlevel 0 goto error
+echo Beat phase patched sucessfully
+exit /b
+
+:menu
+echo Select beat phase:
+echo 1 - beat#1
+echo 2 - beat#2
+echo 3 - beat#3
+
+choice /n /c:123
+set /a beat = %errorlevel% - 1
+
+echo.
+iidx-irbeat-patch.exe 9 %beat% e\\settings.bin.0
+iidx-irbeat-patch.exe 9 %beat% f\\settings.bin.1
+echo.
+
+if not errorlevel 0 goto error
+echo Beat phase patched sucessfully
+timeout 5
+exit /b
+
+:error
+echo Something has gone wrong with the patching process, have you run the game at least once?
+pause
+exit /b
+
+:badbeat
+echo Invalid beat phase specified, values are 1 to 3.
+exit /b
 
-:END

dist/iidx/iidx-irbeat-patch-10.bat

@@ -1,12 +1,45 @@
 @echo off
+cd /d %~dp0
 
-IF "%1"=="" GOTO USAGE
+REM Open menu if no arguments specified
+if "%~1" == "" goto menu
 
-iidx-irbeat-patch.exe 10 %1 e\\settings.bin.0
-iidx-irbeat-patch.exe 10 %1 f\\settings.bin.1
-GOTO END
+if %~1 gtr 3 goto badbeat
+if %~1 == 0 goto badbeat
 
-:USAGE
-	ECHO "Usage: iidx-irbeat-patch.bat <beat phase>"
+set /a beat = %~1 - 1
+iidx-irbeat-patch.exe 9 %beat% e\\settings.bin.0
+iidx-irbeat-patch.exe 9 %beat% f\\settings.bin.1
+
+if not errorlevel 0 goto error
+echo Beat phase patched sucessfully
+exit /b
+
+:menu
+echo Select beat phase:
+echo 1 - beat#1
+echo 2 - beat#2
+echo 3 - beat#3
+
+choice /n /c:123
+set /a beat = %errorlevel% - 1
+
+echo.
+iidx-irbeat-patch.exe 10 %beat% e\\settings.bin.0
+iidx-irbeat-patch.exe 10 %beat% f\\settings.bin.1
+echo.
+
+if not errorlevel 0 goto error
+echo Beat phase patched sucessfully
+timeout 5
+exit /b
+
+:error
+echo Something has gone wrong with the patching process, have you run the game at least once?
+pause
+exit /b
+
+:badbeat
+echo Invalid beat phase specified, values are 1 to 3.
+exit /b
 
-:END

dist/iidx/iidxhook-09.conf

@@ -10,7 +10,7 @@ eamuse.pcbid=0101020304050607086F
 # EAMID
 eamuse.eamid=0101020304050607086F
 
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
+# Fix stretched BG videos on newer GPUs. Might appear on SIRIUS and older. On 9th and 10th style this issue may only affect older BGAs (from 1st-3rd style)
 gfx.bgvideo_uv_fix=false
 
 # Run the game in a framed window (requires windowed option)
@@ -46,17 +46,26 @@ gfx.forced_refresh_rate=-1
 # D3D9 device adapter (monitor), -1 to use default, 0, 1, 2 etc. to use specified adapter
 gfx.device_adapter=-1
 
+# Enable monitoring of ezusb.dll calls by logging call traces. Only works on 9th and 10th style!
+ezusb.api_call_monitoring=false
+
+# Set the type of ezusb IO board. 0 = C02, 1 = D01. Note: Impacts security settings!
+ezusb.io_board_type=0
+
 # Disable operator clock setting system clock time
 misc.disable_clock_set=false
 
 # Stub calls to rteffect.dll (10th to DistorteD)
 misc.rteffect_stub=false
 
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\
+
 # Security boot version (e.g. GEC02).
 sec.boot_version=GEC02   
 
 # Security boot seeds for ezusb, format: X:X:X where X is a number of 0-9 (e.g. 0:0:0).
 sec.boot_seeds=0:0:0
 
-# Security black plug mcode id string (e.g. GQC02JAA).
-sec.black_plug_mcode=GQC02JAA
+# Security black plug mcode id string (e.g. GEC02JAA).
+sec.black_plug_mcode=GEC02JAA

dist/iidx/iidxhook-10.conf

@@ -10,7 +10,7 @@ eamuse.pcbid=0101020304050607086F
 # EAMID
 eamuse.eamid=0101020304050607086F
 
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
+# Fix stretched BG videos on newer GPUs. Might appear on SIRIUS and older. On 9th and 10th style this issue may only affect older BGAs (from 1st-3rd style)
 gfx.bgvideo_uv_fix=false
 
 # Run the game in a framed window (requires windowed option)
@@ -46,12 +46,21 @@ gfx.forced_refresh_rate=-1
 # D3D9 device adapter (monitor), -1 to use default, 0, 1, 2 etc. to use specified adapter
 gfx.device_adapter=-1
 
+# Enable monitoring of ezusb.dll calls by logging call traces. Only works on 9th and 10th style!
+ezusb.api_call_monitoring=false
+
+# Set the type of ezusb IO board. 0 = C02, 1 = D01. Note: Impacts security settings!
+ezusb.io_board_type=1
+
 # Disable operator clock setting system clock time
 misc.disable_clock_set=false
 
 # Stub calls to rteffect.dll (10th to DistorteD)
 misc.rteffect_stub=false
 
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\
+
 # Security boot version (e.g. GEC02).
 sec.boot_version=GEC02   
 

dist/iidx/iidxhook-11.conf

@@ -10,7 +10,7 @@ eamuse.pcbid=0101020304050607086F
 # EAMID
 eamuse.eamid=0101020304050607086F
 
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
+# Fix stretched BG videos on newer GPUs. Might appear on SIRIUS and older. On 9th and 10th style this issue may only affect older BGAs (from 1st-3rd style)
 gfx.bgvideo_uv_fix=false
 
 # Run the game in a framed window (requires windowed option)
@@ -46,12 +46,21 @@ gfx.forced_refresh_rate=-1
 # D3D9 device adapter (monitor), -1 to use default, 0, 1, 2 etc. to use specified adapter
 gfx.device_adapter=-1
 
+# Enable monitoring of ezusb.dll calls by logging call traces. Only works on 9th and 10th style!
+ezusb.api_call_monitoring=false
+
+# Set the type of ezusb IO board. 0 = C02, 1 = D01. Note: Impacts security settings!
+ezusb.io_board_type=1
+
 # Disable operator clock setting system clock time
 misc.disable_clock_set=false
 
 # Stub calls to rteffect.dll (10th to DistorteD)
 misc.rteffect_stub=false
 
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\
+
 # Security boot version (e.g. GEC02).
 sec.boot_version=GEC02   
 

dist/iidx/iidxhook-12.conf

@@ -10,7 +10,7 @@ eamuse.pcbid=0101020304050607086F
 # EAMID
 eamuse.eamid=0101020304050607086F
 
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
+# Fix stretched BG videos on newer GPUs. Might appear on SIRIUS and older. On 9th and 10th style this issue may only affect older BGAs (from 1st-3rd style)
 gfx.bgvideo_uv_fix=false
 
 # Run the game in a framed window (requires windowed option)
@@ -46,6 +46,12 @@ gfx.forced_refresh_rate=-1
 # D3D9 device adapter (monitor), -1 to use default, 0, 1, 2 etc. to use specified adapter
 gfx.device_adapter=-1
 
+# Enable monitoring of ezusb.dll calls by logging call traces. Only works on 9th and 10th style!
+ezusb.api_call_monitoring=false
+
+# Set the type of ezusb IO board. 0 = C02, 1 = D01. Note: Impacts security settings!
+ezusb.io_board_type=1
+
 # Fix broken 3D background on Happy Sky's music select (if appearing completely white)
 misc.happy_sky_ms_bg_fix=false
 
@@ -55,6 +61,9 @@ misc.disable_clock_set=false
 # Stub calls to rteffect.dll (10th to DistorteD)
 misc.rteffect_stub=false
 
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\
+
 # Security boot version (e.g. GEC02).
 sec.boot_version=GEC02   
 

dist/iidx/iidxhook-13.conf

@@ -10,7 +10,7 @@ eamuse.pcbid=0101020304050607086F
 # EAMID
 eamuse.eamid=0101020304050607086F
 
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
+# Fix stretched BG videos on newer GPUs. Might appear on SIRIUS and older. On 9th and 10th style this issue may only affect older BGAs (from 1st-3rd style)
 gfx.bgvideo_uv_fix=false
 
 # Run the game in a framed window (requires windowed option)
@@ -46,6 +46,12 @@ gfx.forced_refresh_rate=-1
 # D3D9 device adapter (monitor), -1 to use default, 0, 1, 2 etc. to use specified adapter
 gfx.device_adapter=-1
 
+# Enable monitoring of ezusb.dll calls by logging call traces. Only works on 9th and 10th style!
+ezusb.api_call_monitoring=false
+
+# Set the type of ezusb IO board. 0 = C02, 1 = D01. Note: Impacts security settings!
+ezusb.io_board_type=1
+
 # Fix broken 3D background on DistorteD's music select (if appearing completely black)
 misc.distorted_ms_bg_fix=false
 
@@ -55,6 +61,9 @@ misc.disable_clock_set=false
 # Stub calls to rteffect.dll (10th to DistorteD)
 misc.rteffect_stub=false
 
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\
+
 # Security boot version (e.g. GEC02).
 sec.boot_version=GEC02   
 

dist/iidx/iidxhook-14.conf

@@ -7,7 +7,7 @@ eamuse.pcbid=0101020304050607086F
 # EAMID
 eamuse.eamid=0101020304050607086F
 
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
+# Fix stretched BG videos on newer GPUs. Might appear on SIRIUS and older. On 9th and 10th style this issue may only affect older BGAs (from 1st-3rd style)
 gfx.bgvideo_uv_fix=false
 
 # Run the game in a framed window (requires windowed option)
@@ -46,5 +46,8 @@ gfx.device_adapter=-1
 # Disable operator clock setting system clock time
 misc.disable_clock_set=false
 
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\
+
 # Security black plug mcode id string (e.g. GQC02JAA).
 sec.black_plug_mcode=GQGLDJAA

dist/iidx/iidxhook-15.conf

@@ -7,7 +7,7 @@ eamuse.pcbid=0101020304050607086F
 # EAMID
 eamuse.eamid=0101020304050607086F
 
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
+# Fix stretched BG videos on newer GPUs. Might appear on SIRIUS and older. On 9th and 10th style this issue may only affect older BGAs (from 1st-3rd style)
 gfx.bgvideo_uv_fix=false
 
 # Run the game in a framed window (requires windowed option)
@@ -46,5 +46,8 @@ gfx.device_adapter=-1
 # Disable operator clock setting system clock time
 misc.disable_clock_set=false
 
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\
+
 # Security black plug mcode id string (e.g. GQC02JAA).
 sec.black_plug_mcode=GQHDDJAA

dist/iidx/iidxhook-16.conf

@@ -7,7 +7,7 @@ eamuse.pcbid=0101020304050607086F
 # EAMID
 eamuse.eamid=0101020304050607086F
 
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
+# Fix stretched BG videos on newer GPUs. Might appear on SIRIUS and older. On 9th and 10th style this issue may only affect older BGAs (from 1st-3rd style)
 gfx.bgvideo_uv_fix=false
 
 # Run the game in a framed window (requires windowed option)
@@ -49,5 +49,8 @@ gfx.device_adapter=-1
 # Disable operator clock setting system clock time
 misc.disable_clock_set=false
 
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\
+
 # Security black plug mcode id string (e.g. GQC02JAA).
 sec.black_plug_mcode=GQI00JAA

dist/iidx/iidxhook-17.conf

@@ -7,7 +7,7 @@ eamuse.pcbid=0101020304050607086F
 # EAMID
 eamuse.eamid=0101020304050607086F
 
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
+# Fix stretched BG videos on newer GPUs. Might appear on SIRIUS and older. On 9th and 10th style this issue may only affect older BGAs (from 1st-3rd style)
 gfx.bgvideo_uv_fix=false
 
 # Run the game in a framed window (requires windowed option)
@@ -49,5 +49,8 @@ gfx.device_adapter=-1
 # Disable operator clock setting system clock time
 misc.disable_clock_set=false
 
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\
+
 # Security black plug mcode id string (e.g. GQC02JAA).
 sec.black_plug_mcode=GCJDJJAA

dist/iidx/iidxhook-18-cn.conf

@@ -1,9 +1,6 @@
 # PCBID
 eamuse.pcbid=0101020304050607086F
 
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
-gfx.bgvideo_uv_fix=false
-
 # Run the game in a framed window (requires windowed option)
 gfx.framed=false
 
@@ -46,5 +43,8 @@ gfx.diagonal_tearing_fix=false
 # Disable ezusb IO emulation and enable usage of real ezusb1/2 IO hardware
 io.disable_io_emu=false
 
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\
+
 # Security black plug mcode id string (e.g. GQC02JAA).
 sec.black_plug_mcode=GKJDZCAA

dist/iidx/iidxhook-18.conf

@@ -1,6 +1,3 @@
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
-gfx.bgvideo_uv_fix=false
-
 # Run the game in a framed window (requires windowed option)
 gfx.framed=false
 
@@ -44,4 +41,7 @@ gfx.diagonal_tearing_fix=false
 io.disable_card_reader_emu=false
 
 # Disable ezusb IO emulation and enable usage of real ezusb1/2 IO hardware
-io.disable_io_emu=false
+io.disable_io_emu=false
+
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\

dist/iidx/iidxhook-19.conf

@@ -1,12 +1,12 @@
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
-gfx.bgvideo_uv_fix=false
-
 # Run the game in a framed window (requires windowed option)
 gfx.framed=false
 
 # Software limit the frame rate of the rendering loop in hz, e.g. 60 or 59.95 (0.0 = no software limit)
 gfx.frame_rate_limit=0.0
 
+# Enable/disable software monitor check/auto timebase or set a pre-determined refresh value. -1 disables this feature. 0 enables auto detecting the current refresh rate on startup. Setting any positive value > 0 allows you to set a pre-determined refresh rate (e.g. retrieved from the monitor check on newer IIDX games). Either the auto detected value or pre-determined value is used to patch any chart files in-memory to fix song synchronization issues. Requires constant refresh rate!!!
+gfx.monitor_check=-1.000000
+
 # Patch the GPU device ID detection (leave empty to disable), format XXXX:YYYY, two 4 digit hex numbers (vid:pid). Examples: 1002:7146 (RV515, Radeon X1300), 1002:95C5 (RV620 LE, Radeon HD3450)
 gfx.pci_id=1002:7146
 
@@ -41,4 +41,7 @@ gfx.diagonal_tearing_fix=false
 io.disable_card_reader_emu=false
 
 # Disable ezusb IO emulation and enable usage of real ezusb1/2 IO hardware
-io.disable_io_emu=false
+io.disable_io_emu=false
+
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\

dist/iidx/iidxhook-20-cn.conf

@@ -1,9 +1,6 @@
 # PCBID
 eamuse.pcbid=0101020304050607086F
 
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
-gfx.bgvideo_uv_fix=false
-
 # Run the game in a framed window (requires windowed option)
 gfx.framed=false
 
@@ -43,5 +40,8 @@ gfx.diagonal_tearing_fix=false
 # Disable ezusb IO emulation and enable usage of real ezusb1/2 IO hardware
 io.disable_io_emu=false
 
+# Path to store the settings, e.g. bookkeeping, operator settings. d:, e: and f: drive configuration/settings data
+misc.settings_path=.\
+
 # Security black plug mcode id string (e.g. GQC02JAA).
 sec.black_plug_mcode=GKJDZCAA

dist/iidx/iidxhook-20.conf

@@ -1,6 +1,3 @@
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
-gfx.bgvideo_uv_fix=false
-
 # Run the game in a framed window (requires windowed option)
 gfx.framed=false
 

dist/iidx/iidxhook-21.conf

@@ -1,6 +1,3 @@
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
-gfx.bgvideo_uv_fix=false
-
 # Run the game in a framed window (requires windowed option)
 gfx.framed=false
 

dist/iidx/iidxhook-22.conf

@@ -1,6 +1,3 @@
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
-gfx.bgvideo_uv_fix=false
-
 # Run the game in a framed window (requires windowed option)
 gfx.framed=false
 

dist/iidx/iidxhook-23.conf

@@ -1,6 +1,3 @@
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
-gfx.bgvideo_uv_fix=false
-
 # Run the game in a framed window (requires windowed option)
 gfx.framed=false
 

dist/iidx/iidxhook-24.conf

@@ -1,6 +1,3 @@
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
-gfx.bgvideo_uv_fix=false
-
 # Run the game in a framed window (requires windowed option)
 gfx.framed=false
 

dist/iidx/iidxhook-25.conf

@@ -1,6 +1,3 @@
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
-gfx.bgvideo_uv_fix=false
-
 # Run the game in a framed window (requires windowed option)
 gfx.framed=false
 
@@ -37,17 +34,23 @@ gfx.device_adapter=-1
 # Disables the camera emulation
 cam.disable_emu=false
 
-# Override camera device ID 1 detection (copy from device manager, do not escape)
+# Disable camera 1. Use, i.e., if you only have one camera and want it to be mapped to camera 2 ingame.
+cam.disable_camera1=false
+
+# Disable camera 2. Use, i.e., if you have more than one camera but only want to map camera 1 ingame.
+cam.disable_camera2=false
+
+# Override camera device ID 1 detection (copy from device manager, do not escape) Leave blank to automatically detect
 cam.device_id1=
 
-# Override camera device ID 2 detection (copy from device manager, do not escape)
+# Override camera device ID 2 detection (copy from device manager, do not escape) Leave blank to automatically detect
 cam.device_id2=
 
-# Disable card reader emulation and enable usage of real card reader hardware on COM0 (for games supporting slotted readers)
+# Disable card reader emulation and enable usage of real card reader hardware on COM1 (for games supporting slotted readers)
 io.disable_card_reader_emu=false
 
 # Disable BIO2 emulation and enable usage of real BIO2 hardware
 io.disable_bio2_emu=false
 
 # Disables the poll limiter, warning very high CPU usage may arise
-io.disable_poll_limiter=false
+io.disable_poll_limiter=false

dist/iidx/iidxhook-26.conf

@@ -1,6 +1,3 @@
-# Fix stretched BG videos on newer GPUs. Might appear on Red and newer
-gfx.bgvideo_uv_fix=false
-
 # Run the game in a framed window (requires windowed option)
 gfx.framed=false
 
@@ -37,17 +34,23 @@ gfx.device_adapter=-1
 # Disables the camera emulation
 cam.disable_emu=false
 
-# Override camera device ID 1 detection (copy from device manager, do not escape)
+# Disable camera 1. Use, i.e., if you only have one camera and want it to be mapped to camera 2 ingame.
+cam.disable_camera1=false
+
+# Disable camera 2. Use, i.e., if you have more than one camera but only want to map camera 1 ingame.
+cam.disable_camera2=false
+
+# Override camera device ID 1 detection (copy from device manager, do not escape) Leave blank to automatically detect
 cam.device_id1=
 
-# Override camera device ID 2 detection (copy from device manager, do not escape)
+# Override camera device ID 2 detection (copy from device manager, do not escape) Leave blank to automatically detect
 cam.device_id2=
 
-# Disable card reader emulation and enable usage of real card reader hardware on COM0 (for games supporting slotted readers)
+# Disable card reader emulation and enable usage of real card reader hardware on COM1 (for games supporting slotted readers)
 io.disable_card_reader_emu=false
 
 # Disable BIO2 emulation and enable usage of real BIO2 hardware
 io.disable_bio2_emu=false
 
 # Disables the poll limiter, warning very high CPU usage may arise
-io.disable_poll_limiter=false
+io.disable_poll_limiter=false

dist/iidx/iidxhook-27.conf

@@ -1,4 +1,4 @@
-# Disable card reader emulation and enable usage of real card reader hardware on COM0 (for games supporting slotted readers)
+# Disable card reader emulation and enable usage of real card reader hardware on COM1 (for games supporting slotted readers)
 io.disable_card_reader_emu=false
 
 # Disable BIO2 emulation and enable usage of real BIO2 hardware
@@ -11,7 +11,7 @@ io.disable_poll_limiter=false
 io.lightning_mode=false
 
 # Disable camera connection
-io.disable_cams=false
+io.disable_cams=true
 
 # Disables the built in file hooks, requiring manual file creation
 io.disable_file_hooks=false
@@ -20,7 +20,16 @@ io.disable_file_hooks=false
 io.tt_multiplier=1.0
 
 # Disables the camera emulation
-cam.disable_emu=false
+cam.disable_emu=true
+
+# Camera port layout (0 = LDJ, 1 = CLDJ/TDJ-JA, 2 = TDJ-JB)
+cam.port_layout=1
+
+# Disable camera 1. Use, i.e., if you only have one camera and want it to be mapped to camera 2 ingame.
+cam.disable_camera1=false
+
+# Disable camera 2. Use, i.e., if you have more than one camera but only want to map camera 1 ingame.
+cam.disable_camera2=false
 
 # Override camera device ID detection (copy from device manager, do not escape)
 cam.device_id1=

dist/iidx/iidxhook-28.conf

@@ -1,4 +1,4 @@
-# Disable card reader emulation and enable usage of real card reader hardware on COM0 (for games supporting slotted readers)
+# Disable card reader emulation and enable usage of real card reader hardware on COM1 (for games supporting slotted readers)
 io.disable_card_reader_emu=false
 
 # Disable BIO2 emulation and enable usage of real BIO2 hardware
@@ -22,6 +22,15 @@ io.tt_multiplier=1.0
 # Disables the camera emulation
 cam.disable_emu=true
 
+# Camera port layout (0 = LDJ, 1 = CLDJ/TDJ-JA, 2 = TDJ-JB)
+cam.port_layout=1
+
+# Disable camera 1. Use, i.e., if you only have one camera and want it to be mapped to camera 2 ingame.
+cam.disable_camera1=false
+
+# Disable camera 2. Use, i.e., if you have more than one camera but only want to map camera 1 ingame.
+cam.disable_camera2=false
+
 # Override camera device ID detection (copy from device manager, do not escape)
 cam.device_id1=
 

dist/iidx/iidxhook-29.conf

@@ -0,0 +1,87 @@
+# Disable card reader emulation and enable usage of real card reader hardware on COM1 (for games supporting slotted readers)
+io.disable_card_reader_emu=false
+
+# Disable BIO2 emulation and enable usage of real BIO2 hardware
+io.disable_bio2_emu=false
+
+# Disables the poll limiter, warning very high CPU usage may arise
+io.disable_poll_limiter=false
+
+# Lightning cab mode (requires additional IO emulation)
+io.lightning_mode=false
+
+# Disable camera connection
+io.disable_cams=true
+
+# Disables the built in file hooks, requiring manual file creation
+io.disable_file_hooks=false
+
+# Turntable sensitivity multiplier (1.0 is default)
+io.tt_multiplier=1.0
+
+# Disables the camera emulation
+cam.disable_emu=true
+
+# Camera port layout (0 = LDJ, 1 = CLDJ/TDJ-JA, 2 = TDJ-JB)
+cam.port_layout=1
+
+# Disable camera 1. Use, i.e., if you only have one camera and want it to be mapped to camera 2 ingame.
+cam.disable_camera1=true
+
+# Disable camera 2. Use, i.e., if you have more than one camera but only want to map camera 1 ingame.
+cam.disable_camera2=false
+
+# Override camera device ID detection (copy from device manager, do not escape)
+cam.device_id1=
+
+# Override camera device ID detection (copy from device manager, do not escape)
+cam.device_id2=
+
+# Run the game in a framed window (requires windowed option)
+gfx.framed=true
+
+# Run the game windowed
+gfx.windowed=false
+
+# Confine mouse cursor to window
+gfx.confined=false
+
+# Windowed width, -1 for default size
+gfx.window_width=-1
+
+# Windowed height, -1 for default size
+gfx.window_height=-1
+
+# Windowed X, -1 for default X position
+gfx.window_x=-1
+
+# Windowed Y, -1 for default Y position
+gfx.window_y=-1
+
+# Forced refresh rate, -1 to not force any (try 59 or 60 if monitor check fails to lock on high refresh rate monitors)
+gfx.forced_refresh_rate=-1
+
+# D3D9ex device adapter (monitor), -1 to use default, 0, 1, 2 etc. to use specified adapter
+gfx.device_adapter=-1
+
+# Orientation to force monitor into, -1 to use default, 0, 1, 2, 3 to do 0, 90, 180, 270 degrees
+gfx.force_orientation=-1
+
+# Force a screen resolution (width), -1 to disable. Use this if the game does not auto detect your monitor's resolution properly, e.g. 1368x768 instead of 1280x720.
+gfx.force_screen_res.width=-1
+
+# Force a screen resolution (height), -1 to disable. Use this if the game does not auto detect your monitor's resolution properly, e.g. 1368x768 instead of 1280x720.
+gfx.force_screen_res.height=-1
+
+# IP of adapter to force override with
+adapter.override_ip=
+
+# Force ASIO audio mode/device (if applicable / TDJ default)
+asio.force_asio=false
+
+# Force WASAPI audio mode (if applicable / LDJ default)
+asio.force_wasapi=true
+
+# The ASIO device name to use
+asio.device_name=XONAR SOUND CARD(64)
+

dist/iidx/iidxhook-30.conf

@@ -0,0 +1,87 @@
+# Disable card reader emulation and enable usage of real card reader hardware on COM1 (for games supporting slotted readers)
+io.disable_card_reader_emu=false
+
+# Disable BIO2 emulation and enable usage of real BIO2 hardware
+io.disable_bio2_emu=false
+
+# Disables the poll limiter, warning very high CPU usage may arise
+io.disable_poll_limiter=false
+
+# Lightning cab mode (requires additional IO emulation)
+io.lightning_mode=false
+
+# Disable camera connection
+io.disable_cams=true
+
+# Disables the built in file hooks, requiring manual file creation
+io.disable_file_hooks=false
+
+# Turntable sensitivity multiplier (1.0 is default)
+io.tt_multiplier=1.0
+
+# Disables the camera emulation
+cam.disable_emu=true
+
+# Camera port layout (0 = LDJ, 1 = CLDJ/TDJ-JA, 2 = TDJ-JB)
+cam.port_layout=1
+
+# Disable camera 1. Use, i.e., if you only have one camera and want it to be mapped to camera 2 ingame.
+cam.disable_camera1=true
+
+# Disable camera 2. Use, i.e., if you have more than one camera but only want to map camera 1 ingame.
+cam.disable_camera2=false
+
+# Override camera device ID detection (copy from device manager, do not escape)
+cam.device_id1=
+
+# Override camera device ID detection (copy from device manager, do not escape)
+cam.device_id2=
+
+# Run the game in a framed window (requires windowed option)
+gfx.framed=true
+
+# Run the game windowed
+gfx.windowed=false
+
+# Confine mouse cursor to window
+gfx.confined=false
+
+# Windowed width, -1 for default size
+gfx.window_width=-1
+
+# Windowed height, -1 for default size
+gfx.window_height=-1
+
+# Windowed X, -1 for default X position
+gfx.window_x=-1
+
+# Windowed Y, -1 for default Y position
+gfx.window_y=-1
+
+# Forced refresh rate, -1 to not force any (try 59 or 60 if monitor check fails to lock on high refresh rate monitors)
+gfx.forced_refresh_rate=-1
+
+# D3D9ex device adapter (monitor), -1 to use default, 0, 1, 2 etc. to use specified adapter
+gfx.device_adapter=-1
+
+# Orientation to force monitor into, -1 to use default, 0, 1, 2, 3 to do 0, 90, 180, 270 degrees
+gfx.force_orientation=-1
+
+# Force a screen resolution (width), -1 to disable. Use this if the game does not auto detect your monitor's resolution properly, e.g. 1368x768 instead of 1280x720.
+gfx.force_screen_res.width=-1
+
+# Force a screen resolution (height), -1 to disable. Use this if the game does not auto detect your monitor's resolution properly, e.g. 1368x768 instead of 1280x720.
+gfx.force_screen_res.height=-1
+
+# IP of adapter to force override with
+adapter.override_ip=
+
+# Force ASIO audio mode/device (if applicable / TDJ default)
+asio.force_asio=false
+
+# Force WASAPI audio mode (if applicable / LDJ default)
+asio.force_wasapi=true
+
+# The ASIO device name to use
+asio.device_name=XONAR SOUND CARD(64)
+

dist/iidx/iidxhook-31.conf

@@ -0,0 +1,84 @@
+# Disable card reader emulation and enable usage of real card reader hardware on COM1 (for games supporting slotted readers)
+io.disable_card_reader_emu=false
+
+# Disable BIO2 emulation and enable usage of real BIO2 hardware
+io.disable_bio2_emu=false
+
+# Disables the poll limiter, warning very high CPU usage may arise
+io.disable_poll_limiter=false
+
+# Lightning cab mode (requires additional IO emulation)
+io.lightning_mode=false
+
+# Disable camera connection
+io.disable_cams=true
+
+# Disables the built in file hooks, requiring manual file creation
+io.disable_file_hooks=false
+
+# Turntable sensitivity multiplier (1.0 is default)
+io.tt_multiplier=1.0
+
+# Disables the camera emulation
+cam.disable_emu=true
+
+# Disable camera 1. Use, i.e., if you only have one camera and want it to be mapped to camera 2 ingame.
+cam.disable_camera1=true
+
+# Disable camera 2. Use, i.e., if you have more than one camera but only want to map camera 1 ingame.
+cam.disable_camera2=false
+
+# Override camera device ID detection (copy from device manager, do not escape)
+cam.device_id1=
+
+# Override camera device ID detection (copy from device manager, do not escape)
+cam.device_id2=
+
+# Run the game in a framed window (requires windowed option)
+gfx.framed=true
+
+# Run the game windowed
+gfx.windowed=false
+
+# Confine mouse cursor to window
+gfx.confined=false
+
+# Windowed width, -1 for default size
+gfx.window_width=-1
+
+# Windowed height, -1 for default size
+gfx.window_height=-1
+
+# Windowed X, -1 for default X position
+gfx.window_x=-1
+
+# Windowed Y, -1 for default Y position
+gfx.window_y=-1
+
+# Forced refresh rate, -1 to not force any (try 59 or 60 if monitor check fails to lock on high refresh rate monitors)
+gfx.forced_refresh_rate=-1
+
+# D3D9ex device adapter (monitor), -1 to use default, 0, 1, 2 etc. to use specified adapter
+gfx.device_adapter=-1
+
+# Orientation to force monitor into, -1 to use default, 0, 1, 2, 3 to do 0, 90, 180, 270 degrees
+gfx.force_orientation=-1
+
+# Force a screen resolution (width), -1 to disable. Use this if the game does not auto detect your monitor's resolution properly, e.g. 1368x768 instead of 1280x720.
+gfx.force_screen_res.width=-1
+
+# Force a screen resolution (height), -1 to disable. Use this if the game does not auto detect your monitor's resolution properly, e.g. 1368x768 instead of 1280x720.
+gfx.force_screen_res.height=-1
+
+# IP of adapter to force override with
+adapter.override_ip=
+
+# Force ASIO audio mode/device (if applicable / TDJ default)
+asio.force_asio=false
+
+# Force WASAPI audio mode (if applicable / LDJ default)
+asio.force_wasapi=true
+
+# The ASIO device name to use
+asio.device_name=XONAR SOUND CARD(64)
+

dist/jb/gamestart-03.bat

@@ -3,6 +3,7 @@
 cd /d %~dp0
 
 if not exist dev\nvram mkdir dev\nvram
+if not exist dev\nvram\ea3-config.xml copy prop\ea3-config.xml dev\nvram\ea3-config.xml
 if not exist dev\nvram\coin.xml copy prop\defaults\coin.xml dev\nvram\coin.xml
 if not exist dev\nvram\eacoin.xml copy prop\defaults\eacoin.xml dev\nvram\eacoin.xml
 if not exist dev\raw mkdir dev\raw

dist/jb/gamestart-04.bat

@@ -3,6 +3,7 @@
 cd /d %~dp0
 
 if not exist dev\nvram mkdir dev\nvram
+if not exist dev\nvram\ea3-config.xml copy prop\ea3-config.xml dev\nvram\ea3-config.xml
 if not exist dev\nvram\coin.xml copy prop\defaults\coin.xml dev\nvram\coin.xml
 if not exist dev\nvram\eacoin.xml copy prop\defaults\eacoin.xml dev\nvram\eacoin.xml
 if not exist dev\raw mkdir dev\raw

doc/README.md

@@ -4,30 +4,31 @@ This folder contains various types of documentation.
 
 Table of contents:
 
-* Game
-  * [Error codes](game-error-codes.md): List of bemani game specific error codes that you might
+- Game
+  - [Error codes](game-error-codes.md): List of bemani game specific error codes that you might
     encounter during boot or gameplay with troubleshooting information
-* Key tools
-  * [Inject](inject.md): Readme for one of BT5's key applications, `inject.exe`
-  * [Launcher](launcher.md): Readme for another one of BT5's key applications, `launcher.exe`
-  * [Tools](tools/README.md): Documentation for additional user and development tooling
-* Game hooks
-  * [ddrhook](ddrhook/README.md): Documentation relevant to `ddrhook` implementations
-  * [iidxhook](iidxhook/README.md): Documentation relevant to `iidxhook` implementations
-  * [jbhook](jbhook/README.md): Documentation relevant to `jbhook` implementations
-  * [popnhook](popnhook/README.md): Documentation relevant to `popnhook` implementations
-  * [sdvxhook](sdvxhook/README.md): Documentation relevant to `sdvxhook` implementations
-* Development
-  * [API](api.md): Available APIs for BT5 and instructions how to use them
-  * [Architecture](architecture.md): Outline of BT5's architecture, how things are designed and why
-  * [Development](development.md): Development environment, building, releasing, etc.
-  * [Developer documentation](dev/README.md): Various lose documentation/notes by developers
-  * [Tools](tools/README.md): Documentation for additional user and development tooling
+- Key tools
+  - [Inject](inject.md): Readme for one of BT5's key applications, `inject.exe`
+  - [Launcher](launcher.md): Readme for another one of BT5's key applications, `launcher.exe`
+  - [Tools](tools/README.md): Documentation for additional user and development tooling
+- Game hooks
+  - [ddrhook](ddrhook/README.md): Documentation relevant to `ddrhook` implementations
+  - [iidxhook](iidxhook/README.md): Documentation relevant to `iidxhook` implementations
+  - [jbhook](jbhook/README.md): Documentation relevant to `jbhook` implementations
+  - [popnhook](popnhook/README.md): Documentation relevant to `popnhook` implementations
+  - [sdvxhook](sdvxhook/README.md): Documentation relevant to `sdvxhook` implementations
+- Development
+  - [API](api.md): Available APIs and IO (hardware) implementations for BT5 and instructions how to
+    use them
+  - [Architecture](architecture.md): Outline of BT5's architecture, how things are designed and why
+  - [Development](development.md): Development environment, building, releasing, etc.
+  - [Developer documentation](dev/README.md): Various lose documentation/notes by developers
+  - [Tools](tools/README.md): Documentation for additional user and development tooling
 
 ## Further external documentation
 
-A list of external documentation that can be useful when dealing with bemanitools,
-supported data and hardware.
+A list of external documentation that can be useful when dealing with bemanitools, supported data
+and hardware.
 
-* [arcade-docs](https://github.com/Shizmob/arcade-docs): An open (to read and contribute) repository
+- [arcade-docs](https://github.com/Shizmob/arcade-docs): An open (to read and contribute) repository
   of arcade hardware and software documentation

doc/api.md

@@ -1,48 +1,81 @@
 # Bemanitools API
-Bemanitools introduces interfaces abstracting the IO hardware of many games. This is used to implement support for
-non-intended IO devices from simple keyboard support, standard gamecontrollers to custom IO boards or using real
-hardware with the games (e.g. support for real legacy hardware).
+
+Bemanitools introduces interfaces abstracting the IO hardware of many games. This is used to
+implement support for non-intended IO devices from simple keyboard support, standard gamecontrollers
+to custom IO boards or using real hardware with the games (e.g. support for real legacy hardware).
 
 For a list of already supported and included hardware by game, see the next section.
 
-The BT5 API separates main game IO hardware like buttons, turn tables, spinners, lights etc. (bstio, iidxio, ...) from
-eamuse hardware like 10-key pads and card readers (eamio).
+The BT5 API separates main game IO hardware like buttons, turn tables, spinners, lights etc. (bstio,
+iidxio, ...) from eamuse hardware like 10-key pads and card readers (eamio).
 
-If you want to write an implementation for your own custom piece of hardware, check out the SDK (*bemanitools*
-sub-folder) in the source code (src.zip).
+If you want to write an implementation for your own custom piece of hardware, check out the SDK
+(*bemanitools* sub-folder) in the source code (src.zip).
 
 ## Implementations
+
+### IO boards
+
 The following implementations are already shipped with BT5.
 
-* BeatStream
-    * bstio.dll (default): Keyboard, joystick and mouse input
-* Dance Dance Revolution
-    * ddrio.dll (default): Keyboard, joystick and mouse input
-    * ddrio-mm.dll: Minimaid hardware
-    * ddrio-smx.dll: StepManiaX platforms
-* Beatmania IIDX
-    * iidxio.dll (default): Keyboard, joystick and mouse input
-    * [iidxio-bio2.dll](iidxhook/iidxio-bio2.md): BIO2 driver
-    * [iidxio-ezusb.dll](iidxhook/iidxio-ezusb.md): Ezusb (C02 IO) driver
-    * [iidxio-ezusb2.dll](iidxhook/iidxio-ezusb2.md): Ezusb FX2 (IO2) driver
-* jubeat
-    * jbio.dll (default): Keyboard, joystick and mouse input
-* pop'n music
-    * popnio.dll (default): Keyboard, joystick and mouse input
-* SOUND VOLTEX
-    * sdvxio.dll (default): Keyboard, joystick and mouse input
-    * [sdvxio-bio2.dll](sdvxhook/sdvxio-bio2.md): BIO2 driver
-    * [sdvxio-kfca.dll](sdvxhook/sdvxio-kfca.md): KFCA IO board driver
+- BeatStream
+  - bstio.dll (default): Keyboard, joystick and mouse input
+- Dance Dance Revolution
+  - ddrio.dll (default): Keyboard, joystick and mouse input
+  - [ddrio-p3io.dll](ddrhook/ddrio-p3io.md): DDR P3IO (Dragon PCB) + EXTIO hardware
+  - ddrio-mm.dll: Minimaid hardware
+  - [ddrio-smx.dll](ddrhook/ddrio-smx.md): StepManiaX platforms
+  - [ddrio-async](ddrhook/ddrio-async.md): Wrapper/shim library to drive another ddrio in a
+    dedicated IO thread
+- Beatmania IIDX
+  - iidxio.dll (default): Keyboard, joystick and mouse input
+  - [iidxio-bio2.dll](iidxhook/iidxio-bio2.md): BIO2 driver
+  - [iidxio-ezusb.dll](iidxhook/iidxio-ezusb.md): Ezusb (C02 IO) driver
+  - [iidxio-ezusb2.dll](iidxhook/iidxio-ezusb2.md): Ezusb FX2 (IO2) driver
+- jubeat
+  - jbio.dll (default): Keyboard, joystick and mouse input
+- pop'n music
+  - popnio.dll (default): Keyboard, joystick and mouse input
+- SOUND VOLTEX
+  - sdvxio.dll (default): Keyboard, joystick and mouse input
+  - [sdvxio-bio2.dll](sdvxhook/sdvxio-bio2.md): BIO2 driver
+  - [sdvxio-kfca.dll](sdvxhook/sdvxio-kfca.md): KFCA IO board driver
+
+### Eamuse readers
 
 Eamuse hardware support is implemented separately:
-* eamio.dll (default): Keyboard and joystick input
+
+- eamio.dll (default): Keyboard and joystick input
+- eamio-icca.dll: Slotted/wave pass readers, required for old games with magnetic stripe cards
+
+#### ICCA readers for IIDX and port config in device manager
+
+The COM port for the card readers needs to be configured correctly in device manager. Otherwise,
+communication with the readers will fail if the settings do not align with how the game or
+bemanitools wants to operate them.
+
+Use built-in ports on your mainboard if available but an external USB to serial port dongle also
+works.
+
+- Assign `COM1` to the COM port the card readers are connected to.
+- Ensure that the following settings for the COM port you are going to use are set
+  - BAUD rate 57600
+  - Data bits 8
+  - Parity None
+  - Stop bits 1
+  - Flow control None.
 
 ## Development notes
-A DEF file for geninput.dll is included. To convert the DEF into an import library suitable for use with Visual C++, run
+
+A DEF file for geninput.dll is included. To convert the DEF into an import library suitable for use
+with Visual C++, run
+
 ```
 lib /machine:i386 /def:geninput.def
 ```
+
 from the Visual C++ command line. If you're using mingw then use dlltool:
+
 ```
 dlltool -d geninput.def -l geninput.a
-```
+```

doc/architecture.md

@@ -1,203 +1,239 @@
 # Bemanitools architecture
-This document gives you an overview of the architecture of Bemanitools (5). Why do we need this? This helps document the
-various design decisions and how everything comes together, in the end. At some point when things are evolving and other
-developers want to pick up the project, this might give them answers to why some things were done well or not so well.
-This allows them to iterate on the current design (document) to analyze if a change they want to apply might work out
-or not.
 
-Anway, enough preface...I guess you got the idea. This document will be split into several sections which address
-different aspects of the architecture.
+This document gives you an overview of the architecture of Bemanitools (5). Why do we need this?
+This helps document the various design decisions and how everything comes together, in the end. At
+some point when things are evolving and other developers want to pick up the project, this might
+give them answers to why some things were done well or not so well. This allows them to iterate on
+the current design (document) to analyze if a change they want to apply might work out or not.
+
+Anway, enough preface...I guess you got the idea. This document will be split into several sections
+which address different aspects of the architecture.
 
 ## The big picture
+
 TODO create a graphic that presents the key modules and ideas.
 
 ## Detouring library functions, IAT hooking
-One of Bemanitools's goals is to avoid patching of executables, libraries or any game data and instead rely on
-intercepting calls to libraries to patch bugs or introduce new features. To support a game on a non native platform
-transparently, e.g. your home desktop, this allows us to intercept I/O communication to emulate hardware or
-files/filesystem features the game expects to be available.
 
-We create a so called "hook library/hook.dll" which gets injected to the target process (the game) before the game
-runs any of its application code. This is well known by the terms of dll injection and will not be further discussed
-here (google it). The injected dll will replace the function addresses in the IATs to detour any calls to our own
-handler functions before, eventually, calling the real function. This way, we can intercept the call and do cool things.
+One of Bemanitools's goals is to avoid patching of executables, libraries or any game data and
+instead rely on intercepting calls to libraries to patch bugs or introduce new features. To support
+a game on a non native platform transparently, e.g. your home desktop, this allows us to intercept
+I/O communication to emulate hardware or files/filesystem features the game expects to be available.
+
+We create a so called "hook library/hook.dll" which gets injected to the target process (the game)
+before the game runs any of its application code. This is well known by the terms of dll injection
+and will not be further discussed here (google it). The injected dll will replace the function
+addresses in the IATs to detour any calls to our own handler functions before, eventually, calling
+the real function. This way, we can intercept the call and do cool things.
 
 These features are covered by the modules in the following subfolders in src/main:
-* hook: Essentially, this is capnhook: https://github.com/decafcode/capnhook. General tools for hooking Win32 API calls.
-* hooklib: Some additional helper modules to take care of specific issues in Bemanitools, e.g. rs232 related stuff for
-ACIO.
+
+- hook: Essentially, this is capnhook: https://github.com/decafcode/capnhook. General tools for
+  hooking Win32 API calls.
+- hooklib: Some additional helper modules to take care of specific issues in Bemanitools, e.g. rs232
+  related stuff for ACIO.
 
 Check the modules for details.
 
 ## Hooking and IRP
-IRP stands for "I/O request packet" and is a kernel mode structure used in Windows drivers for communication with the
-OS. The data structure describes an I/O request with parameters for that request avoiding function calls with large
-number of arguments to a driver.
 
-We make use of that "IRP pattern" by creating a flexible and maintainable abstraction layer for the following hooking
-modules:
-* iohook: Hook I/O (e.g. file) related calls
-* d3d9: Hook d3d9 graphics API calls
+IRP stands for "I/O request packet" and is a kernel mode structure used in Windows drivers for
+communication with the OS. The data structure describes an I/O request with parameters for that
+request avoiding function calls with large number of arguments to a driver.
 
-An IRP handler is implemented to handle selected IRP calls based on the specified operation type. IRP handlers can be
-chained which allows splitting up different features/interceptors to different functions and modules allowing you to
-create a clear structure. At the end of the forwarding chain, you the real API function that maps to the abstracted
-operation is called. However, a handler can decide at any time to not forward calls which allows you to implement
-emulation of access to selected files or I/O devices.
+We make use of that "IRP pattern" by creating a flexible and maintainable abstraction layer for the
+following hooking modules:
+
+- iohook: Hook I/O (e.g. file) related calls
+- d3d9: Hook d3d9 graphics API calls
+
+An IRP handler is implemented to handle selected IRP calls based on the specified operation type.
+IRP handlers can be chained which allows splitting up different features/interceptors to different
+functions and modules allowing you to create a clear structure. At the end of the forwarding chain,
+you the real API function that maps to the abstracted operation is called. However, a handler can
+decide at any time to not forward calls which allows you to implement emulation of access to
+selected files or I/O devices.
 
 Modules that make use of this:
-* iidxhook-util/d3d9
-* ezusb-emu/device
-* ezusb2-emu/device
-* acioemu/emu
+
+- iidxhook-util/d3d9
+- ezusb-emu/device
+- ezusb2-emu/device
+- acioemu/emu
 
 ## Bemanitools's hook libraries, let's glue everything together
-Bemanitools dlls to be injected into target game processes are refered to as "hook dlls" and come in different flavours
-targetting different games and often different versions of the same game (series), for example:
-* ddrhook: Hook dll for Dance Dance Revolution games
-* iidxhook1-8: Hook dlls for Beatmania IIDX, we are currently at 8 different implementations due to the various
-iterations the game went through, related to software and hardware.
-* sdvxhook: Hook dll for SoundVoltex series
 
-The following sub-sections will give you some brief insights on each hook implementation and what modules were used.
+Bemanitools dlls to be injected into target game processes are refered to as "hook dlls" and come in
+different flavours targetting different games and often different versions of the same game
+(series), for example:
+
+- ddrhook: Hook dll for Dance Dance Revolution games
+- iidxhook1-8: Hook dlls for Beatmania IIDX, we are currently at 8 different implementations due to
+  the various iterations the game went through, related to software and hardware.
+- sdvxhook: Hook dll for SoundVoltex series
+
+The following sub-sections will give you some brief insights on each hook implementation and what
+modules were used.
 
 ### bsthook
+
 TODO
 
 ### ddrhook
+
 TODO
 
 ### iidxhook
-IIDX went through so many hard- and software iterations, it's actually amazing that the development team(s) refactored
-and improved parts of the game and hardware with each iteration. However, when facing emulation and supporting
-compatibility to legacy OS platforms, it can't get any worse. On the bright side, IIDX helped shaping Bemanitools a lot
-and created a solid foundation other games can build on.
 
-Because of that, we have 8 iidxhook implementations supporting sometimes different software features/fixes and
-hardware. The following sub-sub-sections list the most relevant aspects and modules to point out common and different
-higher level features.
+IIDX went through so many hard- and software iterations, it's actually amazing that the development
+team(s) refactored and improved parts of the game and hardware with each iteration. However, when
+facing emulation and supporting compatibility to legacy OS platforms, it can't get any worse. On the
+bright side, IIDX helped shaping Bemanitools a lot and created a solid foundation other games can
+build on.
 
-Essentially, the main module file of each iidxhook implementation just glues the APIs of the modules it requires
-together. An additional configuration layer allows users to tweak some of the features.
+Because of that, we have 8 iidxhook implementations supporting sometimes different software
+features/fixes and hardware. The following sub-sub-sections list the most relevant aspects and
+modules to point out common and different higher level features.
 
-TODO go into some more detail about some differences in the hook modules, e.g. 18 to 19 look identical
--> but different AVS versions
+Essentially, the main module file of each iidxhook implementation just glues the APIs of the modules
+it requires together. An additional configuration layer allows users to tweak some of the features.
+
+TODO go into some more detail about some differences in the hook modules, e.g. 18 to 19 look
+identical -> but different AVS versions
 
 #### iidxhook1 (9-12)
-* Ezusb C02 I/O emulation
-    * Setupapi emulation
-    * Full security emulation with SRAM and round plugs
-    * Full serial emulation for magstripe card readers
-    * Full game essential I/O emulation
-* d3d8 patching and extended features (superseded by d3d9 hook module + d3d8to9 wrapper)
-* clock patching
-* Font patching for Japanese chars
-* Network related patches to enable eamuse to custom servers
-* Filesystem patches to detour E and F backup drives for settings
+
+- Ezusb C02 I/O emulation
+  - Setupapi emulation
+  - Full security emulation with SRAM and round plugs
+  - Full serial emulation for magstripe card readers
+  - Full game essential I/O emulation
+- d3d8 patching and extended features (superseded by d3d9 hook module + d3d8to9 wrapper)
+- clock patching
+- Font patching for Japanese chars
+- Network related patches to enable eamuse to custom servers
+- Filesystem patches to detour E and F backup drives for settings
 
 #### iidxhook2 (13)
-* Ezusb C02 I/O emulation
-    * Setupapi emulation
-    * Full security emulation with SRAM and round plugs
-    * Full game essential I/O emulation
-* ACIO ICCA card reader emulation, slotted readers
-* d3d8 patching and extended features (superseded by d3d9 hook module + d3d8to9 wrapper)
-* clock patching
-* Font patching for Japanese chars
-* Network related patches to enable eamuse to custom servers
-* Filesystem patches to detour E and F backup drives for settings
+
+- Ezusb C02 I/O emulation
+  - Setupapi emulation
+  - Full security emulation with SRAM and round plugs
+  - Full game essential I/O emulation
+- ACIO ICCA card reader emulation, slotted readers
+- d3d8 patching and extended features (superseded by d3d9 hook module + d3d8to9 wrapper)
+- clock patching
+- Font patching for Japanese chars
+- Network related patches to enable eamuse to custom servers
+- Filesystem patches to detour E and F backup drives for settings
 
 #### iidxhook3 (14-17)
-* Ezusb IO2 I/O emulation
-    * Setupapi emulation
-    * Full security emulation with SRAM and round plugs
-    * Full game essential I/O emulation
-* ACIO ICCA card reader emulation, slotted readers
-* d3d9 patching and extended features
-* Font patching for Japanese chars
-* Network related patches to enable eamuse to custom servers
-* Filesystem patches to detour E and F backup drives for settings
+
+- Ezusb IO2 I/O emulation
+  - Setupapi emulation
+  - Full security emulation with SRAM and round plugs
+  - Full game essential I/O emulation
+- ACIO ICCA card reader emulation, slotted readers
+- d3d9 patching and extended features
+- Font patching for Japanese chars
+- Network related patches to enable eamuse to custom servers
+- Filesystem patches to detour E and F backup drives for settings
 
 #### iidxhook4 (18)
-* Ezusb IO2 I/O emulation
-    * Setupapi emulation
-    * Full game essential I/O emulation
-* ACIO ICCA card reader emulation, slotted readers
-* d3d9 patching and extended features
-* Font patching for Japanese chars
-* Filesystem patches to detour E and F backup drives for settings
+
+- Ezusb IO2 I/O emulation
+  - Setupapi emulation
+  - Full game essential I/O emulation
+- ACIO ICCA card reader emulation, slotted readers
+- d3d9 patching and extended features
+- Font patching for Japanese chars
+- Filesystem patches to detour E and F backup drives for settings
 
 #### iidxhook4-cn (18 CN)
-* Ezusb IO2 I/O emulation
-  * Setupapi emulation
-  * Full security emulation with SRAM and round plugs
-  * Full game essential I/O emulation
-* d3d9 patching and extended features
-* Font patching for Japanese chars
-* Filesystem patches to detour E and F backup drives for settings
+
+- Ezusb IO2 I/O emulation
+  - Setupapi emulation
+  - Full security emulation with SRAM and round plugs
+  - Full game essential I/O emulation
+- d3d9 patching and extended features
+- Font patching for Japanese chars
+- Filesystem patches to detour E and F backup drives for settings
 
 #### iidxhook5 (19)
-* Ezusb IO2 I/O emulation
-    * Setupapi emulation
-    * Full game essential I/O emulation
-* ACIO ICCA card reader emulation, wave pass readers
-* d3d9 patching and extended features
-* Font patching for Japanese chars
-* Filesystem patches to detour E and F backup drives for settings
+
+- Ezusb IO2 I/O emulation
+  - Setupapi emulation
+  - Full game essential I/O emulation
+- ACIO ICCA card reader emulation, wave pass readers
+- d3d9 patching and extended features
+- Font patching for Japanese chars
+- Filesystem patches to detour E and F backup drives for settings
 
 #### iidxhook5-cn (20 CN)
-* Ezusb IO2 I/O emulation
-  * Setupapi emulation
-  * Full security emulation with SRAM and round plugs
-  * Full game essential I/O emulation
-* d3d9 patching and extended features
-* Font patching for Japanese chars
-* Filesystem patches to detour E and F backup drives for settings
+
+- Ezusb IO2 I/O emulation
+  - Setupapi emulation
+  - Full security emulation with SRAM and round plugs
+  - Full game essential I/O emulation
+- d3d9 patching and extended features
+- Font patching for Japanese chars
+- Filesystem patches to detour E and F backup drives for settings
 
 #### iidxhook6 (20)
-* Ezusb IO2 I/O emulation
-    * Setupapi emulation
-    * Full game essential I/O emulation
-* ACIO ICCA card reader emulation, wave pass readers
-* d3d9 patching and extended features
-* Font patching for Japanese chars
+
+- Ezusb IO2 I/O emulation
+  - Setupapi emulation
+  - Full game essential I/O emulation
+- ACIO ICCA card reader emulation, wave pass readers
+- d3d9 patching and extended features
+- Font patching for Japanese chars
 
 #### iidxhook7 (21-24)
-* Ezusb IO2 I/O emulation
-    * Setupapi emulation
-    * Full game essential I/O emulation
-* ACIO ICCA card reader emulation, wave pass readers
-* d3d9 patching and extended features
-* Font patching for Japanese chars
+
+- Ezusb IO2 I/O emulation
+  - Setupapi emulation
+  - Full game essential I/O emulation
+- ACIO ICCA card reader emulation, wave pass readers
+- d3d9 patching and extended features
+- Font patching for Japanese chars
 
 #### iidxhook8 (25-26)
-* ACIO BIO2 I/O emulation
-    * Setupapi emulation
-    * Full game essential I/O emulation
-* ACIO ICCA card reader emulation, wave pass readers
-* d3d9 patching and extended features
-* Font patching for Japanese chars
+
+- ACIO BIO2 I/O emulation
+  - Setupapi emulation
+  - Full game essential I/O emulation
+- ACIO ICCA card reader emulation, wave pass readers
+- d3d9 patching and extended features
+- Font patching for Japanese chars
 
 ### jbhook
+
 TODO
 
 ### popnhook
+
 TODO
 
 ### sdvxhook
+
 TODO
 
 ## The ezusb (emulation) stack
+
 TODO
 
 ## The ACIO (emulation) stack
+
 TODO
 
 ## BT5 API
+
 TODO
 
 ## AVS and launcher
+
 TODO
 
 ## Inject
-TODO
+
+TODO

doc/ddrhook/README.md

@@ -1,49 +1,50 @@
 # ddrhook
 
-ddrhook is a collection of hook libraries for "Dance Dance Revoluion" providing
-emulation and various patches to run these games on non BemaniPC hardware and
-newer Windows versions.
+ddrhook is a collection of hook libraries for "Dance Dance Revoluion" providing emulation and
+various patches to run these games on non BemaniPC hardware and newer Windows versions.
 
 The hook libraries must be bootstrapped either using [inject](../inject.md) or
-[launcher](../launcher.md) depending on the version you want to run. Further
-instructions are given in dedicated readme files for each ddrhook version
-(see below).
+[launcher](../launcher.md) depending on the version you want to run. Further instructions are given
+in dedicated readme files for each ddrhook version (see below).
 
 ## Versions
 
-ddrhook comes in a few different flavors. The game and its engine changed over
-the years. Some game versions might require patches/parameters enabled which
-others don't need or have different AVS versions. Here is the list of supported 
-games:
+ddrhook comes in a few different flavors. The game and its engine changed over the years. Some game
+versions might require patches/parameters enabled which others don't need or have different AVS
+versions. Here is the list of supported games:
 
-* [ddrhook1](ddrhook1.md): X, X2 (US/EU regions)
-* [ddrhook2](ddrhook2.md): X2 (JP region), X3 vs. 2ndMIX, 2013, 2014, A
+- [ddrhook1](ddrhook1.md): X, X2 (US/EU regions)
+- [ddrhook2](ddrhook2.md): X2 (JP region), X3 vs. 2ndMIX, 2013, 2014, A
 
-When building bemanitools, independent packages are created for each set of games
-which are ready to be dropped on top of vanilla AC data dumps. We recommend
-using pristine dumps to avoid any conflicts with other hardcoded hacks or
-binary patches.
+When building bemanitools, independent packages are created for each set of games which are ready to
+be dropped on top of vanilla AC data dumps. We recommend using pristine dumps to avoid any conflicts
+with other hardcoded hacks or binary patches.
 
 ## How to run
 
-To run your game with ddrhook, you have to use the inject tool to inject the
-DLL to the game process. `dist/ddr` contains bat scripts with all the
-important parameters configured. Further parameters can be added but might not
-be required to run the game with default settings.
-Further information on how to setup the data for each specific version are
-elaborated in their dedicated readme files.
+To run your game with ddrhook, you have to use the inject tool to inject the DLL to the game
+process. `dist/ddr` contains bat scripts with all the important parameters configured. Further
+parameters can be added but might not be required to run the game with default settings. Further
+information on how to setup the data for each specific version are elaborated in their dedicated
+readme files.
 
 ## Command line options
 
-Add the argument *-h* when running inject with ddrhook to print help/usage
-information with a list of parameters you can apply to tweak various things.
+Add the argument *-h* when running inject with ddrhook to print help/usage information with a list
+of parameters you can apply to tweak various things.
 
 ## ddrio API
 
-Available implementations that can be swapped out depending on which kind of
-IO hardware you want to use:
+Available implementations that can be swapped out depending on which kind of IO hardware you want to
+use:
 
-* `ddrio`: Default implementation supporting keyboard, mouse and USB
-game controllers
-* ddrio-mm: Support Minimaid custom interface
-* [ddrio-smx](ddrhook/ddrio-smx.md): Support for StepManiaX dance platforms
+- `ddrio`: Default implementation supporting keyboard, mouse and USB game controllers
+- ddrio-mm: Support Minimaid custom interface
+- [ddrio-smx](ddrio-smx.md): Support for StepManiaX dance platforms
+- [ddrio-p3io](ddrio-p3io.md): P3IO + EXTIO driver implementation
+- [ddrio-async](ddrio-async.md): Wrapper/shim library to drive another ddrio in a dedicated IO
+  thread
+
+## Unicorntail
+
+[Instructions how to run on Chimera PCBs](unicorntail.md).

doc/ddrhook/ddrhook1.md

@@ -4,8 +4,8 @@
 
 The following games are supported with this hook library:
 
-* Dance Dance Revolution X
-* Dance Dance Revolution X2 (US/EU regions)
+- Dance Dance Revolution X
+- Dance Dance Revolution X2 (US/EU regions)
 
 The games must be bootstrapped using [inject](../inject.md).
 
@@ -13,90 +13,84 @@ The games must be bootstrapped using [inject](../inject.md).
 
 Ensure your folder with your unpacked data looks like this:
 
-* `conf`
-* `data`
-* `ddr`
-* `ddr_YYYYMMDDRR` where `YYYYMMDDRR` corresponds to different datecodes of
-  different versions. Multiple folders of these possible
+- `conf`
+- `data`
+- `ddr`
+- `ddr_YYYYMMDDRR` where `YYYYMMDDRR` corresponds to different datecodes of different versions.
+  Multiple folders of these possible
 
 `DDR.exe` files should be in `ddr` and `ddr_YYYYMMDDRR` folders.
 
-Unpack the distribution package `ddr-11.zip` into one of the folders containing
-a `DDR.exe` file. We recommend using the one with the latest datecode which
-denotes the latest version of the game including bugfixes etc.
+Unpack the distribution package `ddr-11.zip` into one of the folders containing a `DDR.exe` file. We
+recommend using the one with the latest datecode which denotes the latest version of the game
+including bugfixes etc.
 
-`gamestart-11.bat` as well as `ddrhook1.dll` are now expected to be located
-in the same folder as (one) `DDR.exe` file.
+`gamestart-11.bat` as well as `ddrhook1.dll` are now expected to be located in the same folder as
+(one) `DDR.exe` file.
 
 ## Running
 
-Run `gamestart-11.bat` as administrator. For the US version of the game, run
-`gamestart-11-us.bat` instead. This can be done by either by double
-clicking or running it from `cmd.exe`. The latter is recommended to have
-any debug output kept on screen after closing the game.
+Run `gamestart-11.bat` as administrator. For the US version of the game, run `gamestart-11-us.bat`
+instead. This can be done by either by double clicking or running it from `cmd.exe`. The latter is
+recommended to have any debug output kept on screen after closing the game.
 
-This will run [inject](../inject.md) with the `ddrhook1.dll`. On first run,
-if you don't have a conguration file, e.g. `ddr-11.conf`, available in the
-same folder, a default one will be created and the game exits. Simply re-run
-`gamestart-11.bat` again.
+This will run [inject](../inject.md) with the `ddrhook1.dll`. On first run, if you don't have a
+conguration file, e.g. `ddr-11.conf`, available in the same folder, a default one will be created
+and the game exits. Simply re-run `gamestart-11.bat` again.
 
 ## Configuration ddrhook
 
-The hook library can be configured via cmd arguments or a configuration file.
-The latter is generated (*ddr-11.conf* in the same directory) on the first 
-start of the game using the gamestart-XX.bat file. It contains default values
-for all available parameters and comments explaining each parameter. Please
-follow the comments when configuring your setup.
+The hook library can be configured via cmd arguments or a configuration file. The latter is
+generated (*ddr-11.conf* in the same directory) on the first start of the game using the
+gamestart-XX.bat file. It contains default values for all available parameters and comments
+explaining each parameter. Please follow the comments when configuring your setup.
 
-Add the argument *-h* when running gamestart-XX.bat 
-(e.g. *gamestart-XX.bat -h*) to print help/usage information with a list of 
-all available parameters. Every parameter can be either set as command line
-argument or using a configuration file.
+Add the argument *-h* when running gamestart-XX.bat (e.g. *gamestart-XX.bat -h*) to print help/usage
+information with a list of all available parameters. Every parameter can be either set as command
+line argument or using a configuration file.
 
-To set a parameter from the command line, just add it as an argument after
-the bat file like this
+To set a parameter from the command line, just add it as an argument after the bat file like this
 
 ```
 gamestart-11.bat -p gfx.windowed=true
 ```
 
-The syntax for the "key=value" is the same as in the config file. Make sure
-to have a pre-ceeding "-p" for every parameter added.
+The syntax for the "key=value" is the same as in the config file. Make sure to have a pre-ceeding
+"-p" for every parameter added.
 
-However, if a parameter is specifed in the configuration file and as a command
-line argument, the command line argument overrides the config file's value.
+However, if a parameter is specifed in the configuration file and as a command line argument, the
+command line argument overrides the config file's value.
 
 ## Configure USB memory cards and edit data
 
-You can setup actual USB thumb drives mapped to a drive letter, e.g. `E:\` for
-player 1 and `F:\` for player 2, or just have them point to any local directory,
-e.g. `usbmem_p1` and `usbmem_p2`.
+You can setup actual USB thumb drives mapped to a drive letter, e.g. `E:\` for player 1 and `F:\`
+for player 2, or just have them point to any local directory, e.g. `usbmem_p1` and `usbmem_p2`.
 
-Set-up your folder mappings in the
-[conf file or via command line args](#configuration-ddrhook) like follows:
+Set-up your folder mappings in the [conf file or via command line args](#configuration-ddrhook) like
+follows:
 
-* Enable USB memory data emulation: `ddrhook1.usbmem_enabled=true`
-* Set P1 USB memory data path pointing to local folder `usbmem_p1` next to `DDR.EXE`:
+- Enable USB memory data emulation: `ddrhook1.usbmem_enabled=true`
+- Set P1 USB memory data path pointing to local folder `usbmem_p1` next to `DDR.EXE`:
   `ddrhook1.usbmem_path_p1=usbmem_p1`
-* Set P1 USB memory data path pointing to local folder `usbmem_p2` next to `DDR.EXE`:
+- Set P1 USB memory data path pointing to local folder `usbmem_p2` next to `DDR.EXE`:
   `ddrhook1.usbmem_path_p1=usbmem_p2`
-* Have/create a subfolder called `DDR_EDIT` on any location/USB drive you want to use
-* Name your edit data file either `DDR_EDIT_J.DAT` (for JP version) or `DDR_EDIT_U.DAT`
-  (for US version) and place it in the `DDR_EDIT` directory.
+- Have/create a subfolder called `DDR_EDIT` on any location/USB drive you want to use
+- Name your edit data file either `DDR_EDIT_J.DAT` (for JP version) or `DDR_EDIT_U.DAT` (for US
+  version) and place it in the `DDR_EDIT` directory.
 
 For the example setup above, the full relative path of the edit file should be
 `usbmem_p1\DDR_EDIT\DDR_EDIT_J.DAT` for player 1.
 
-Note that USB memory cards are not detected by the game and the game stays
-silent about that if they do not contain edit data, your path mapping does not resolve
-or you misplaced or named your edit data file incorrectly.
+Note that USB memory cards are not detected by the game and the game stays silent about that if they
+do not contain edit data, your path mapping does not resolve or you misplaced or named your edit
+data file incorrectly.
 
 ## Grey and glitchy arrows
 
 This is a known issue with many GPUs, typically non-Radeon GPUs.
 
-There is currently not patch available in Bemanitools for that. We assume this is an
-issue with incompatible shader code.
+There is currently not patch available in Bemanitools for that. We assume this is an issue with
+incompatible shader code.
 
 There are solutions to hard-patch the code available elsewhere.
 
@@ -106,34 +100,32 @@ There are solutions to hard-patch the code available elsewhere.
 
 The game expects you have the `CLVSD.ax` file registered for decoding videos.
 
-Grab the `CLVSD.ax` file and go to *Start* > *Run* > enter `regsvr32 clvsd.ax` and
-execute. Make sure to run as Administrator, otherwise you will get errors due to
-invalid permissions.
+Grab the `CLVSD.ax` file and go to *Start* > *Run* > enter `regsvr32 clvsd.ax` and execute. Make
+sure to run as Administrator, otherwise you will get errors due to invalid permissions.
 
 ### Game crashes during boot
 
-If you have played a newer version of DDR, e.g. DDR 2014+, you might have the
-`k-clvsd.dll` codec registered which crashes DDR X and likely X2 (EU/US) as well.
+If you have played a newer version of DDR, e.g. DDR 2014+, you might have the `k-clvsd.dll` codec
+registered which crashes DDR X and likely X2 (EU/US) as well.
 
 Unregister `k-clvsd.dll`, e.g. `regsvr32 /u k-clvsd.dll`, and
 [registering `CLVSD.ax`](#issues-with-background-videos-not-working).
 
-Note that `CLVSD.ax` will likely hang any newer/more recent DDR versions on startup
-and require you to use the `k-clvsd.dll` that came with the respective version
-instead. See [this section](ddrhook2.md#video-codecs-for-background-videos) for
-further details.
+Note that `CLVSD.ax` will likely hang any newer/more recent DDR versions on startup and require you
+to use the `k-clvsd.dll` that came with the respective version instead. See
+[this section](ddrhook2.md#video-codecs-for-background-videos) for further details.
 
 ### Black screen/render window without a response
 
 This symptom might have many causes, here is a list of known issues and what can be done:
 
-* If not done already, try installing
+- If not done already, try installing
   [DirectX Redist (June 2010)](https://www.microsoft.com/en-us/download/details.aspx?id=8109)
-* If you have an integrated/second GPU, ensure it is disabled
-* External (USB) audio devices could cause issues. Ensure you are running on on-board/integrated
+- If you have an integrated/second GPU, ensure it is disabled
+- External (USB) audio devices could cause issues. Ensure you are running on on-board/integrated
   sound cards and unplug any external audio devices.
-* [Disable fullscreen optimizations](https://devblogs.microsoft.com/directx/demystifying-full-screen-optimizations/):
+- [Disable fullscreen optimizations](https://devblogs.microsoft.com/directx/demystifying-full-screen-optimizations/):
   Right click on `DDR.exe`, *Properties* > *Compatibility* > *Disable fullscreen optimizations*
-* Check if you can run `DDR.exe` without Bemanitools by simply launching it. It should at least
-  boot into a startup screen. If that isn't even possible, then it's likely not an issue with
+- Check if you can run `DDR.exe` without Bemanitools by simply launching it. It should at least boot
+  into a startup screen. If that isn't even possible, then it's likely not an issue with
   Bemanitools. Note that your data path needs to be `D:\HDX` for that to work though.

doc/ddrhook/ddrhook2.md

@@ -4,77 +4,145 @@
 
 The following games are supported by this hook library:
 
-* Dance Dance Revolution X2 (JP region)
-* Dance Dance Revolution X3 vs. 2ndMIX
-* Dance Dance Revolution 2013
-* Dance Dance Revolution 2014
-* Dance Dance Revolution A
+- Dance Dance Revolution X2 (JP region)
+- Dance Dance Revolution X3 vs. 2ndMIX
+- Dance Dance Revolution 2013
+- Dance Dance Revolution 2014
+- Dance Dance Revolution A
+- Dance Dance Revolution A20
+- Dance Dance Revolution A20+
 
-Note that different builds of the same hook library are required to run the
-different versions. See different distribution packages, e.g. `ddr-12.zip`,
-`ddr-13.zip` etc.
+Note that different builds of the same hook library are required to run the different versions. See
+different distribution packages, e.g. `ddr-12.zip`, `ddr-13.zip` etc.
 
-Depending on the game version, earlier versions are bootstrapped using
-[inject](../inject.md) while later versions require [launcher](../launcher.md).
+Depending on the game version, earlier versions are bootstrapped using [inject](../inject.md) while
+later versions require [launcher](../launcher.md).
+
+## Setup A20+
+
+### Data and folder structure
+
+The following assumes you are using vanilla and unpacked/decrypted data. Copy/unpack the data to a
+destination of your choice. Expect to have the following root folder structure:
+
+```
+arkdata
+com
+data
+dev
+modules
+prop
+```
+
+- Copy the contents of `modules` to the root folder that the dll-files are next to the folders
+  `arkdata`, `com`, etc.
+- Unpack the contents of `ddr-14-to-16.zip` to the root folder. `luncher.exe` should be located next
+  to `arkdata`, `com` and all the dll-files
+
+#### Configuring eamuse settings
+
+You need to create a `prop/ea3-config.xml` configuration file which provides properties for
+connecting to a network of your choice (and allows the game to boot).
+
+Take the `prop/eamuse.xml` as a base and make a copy of it called `prop/ea3-config.xml`.
+
+Add the software identifier as a child to the `<ea3>` parent node:
+
+```xml
+<soft>
+  <model __type="str">MDX</model>
+  <dest __type="str">J</dest>
+  <spec __type="str">A</spec>
+  <rev __type="str">A</rev>
+  <ext __type="str">2022020200</ext>
+</soft>
+```
+
+Replace the identifiers according to the version you are using.
+
+Add your PCBID as a child to the `<ea3>` parent node:
+
+```xml
+<id>
+  <pcbid __type="str">00010203040506070809</pcbid>
+  <hardid __type="str">00010203040506070809</hardid>
+</id>
+```
+
+Replace the values accordingly with your actual PCBID registered with your target network.
+
+Add network settings (note this might already exist, replace existing or delete old one) as a child
+to the `<ea3>` parent node:
+
+```xml
+<network>
+  <sz_xrpc_buf __type="u32">102400</sz_xrpc_buf>
+  <ssl __type="bool">0</ssl>
+  <services>http://eamuse.konami.fun/service/services/services/</services>
+</network>
+```
+
+Replace the properties accordingly with the settings provided by your network provider, e.g. the
+URL, further settings like ssl etc.
 
 ## Running
 
-Run `gamestart-XX.bat`, where `XX` corresponds to the version of the game you
-want to run, as administrator. For the US version of X2, run
-`gamestart-12-us.bat` instead. This can be done by either by double
-clicking or running it from `cmd.exe`. The latter is recommended to have
-any debug output kept on screen after closing the game.
+Run `gamestart-XX.bat`, where `XX` corresponds to the version of the game you want to run, as
+administrator. For the US version of X2, run `gamestart-12-us.bat` instead. This can be done by
+either by double clicking or running it from `cmd.exe`. The latter is recommended to have any debug
+output kept on screen after closing the game.
 
-This will run [inject](../inject.md) or [launcher](../launcher.md), depending
-on the version of the game, with the `ddrhook2.dll`. On first run, if you don't
-have a conguration file, e.g. `ddr-12.conf`, available in the same folder, a
-default one will be created and the game exits. Simply re-run `gamestart-XX.bat`
-again.
+This will run [inject](../inject.md) or [launcher](../launcher.md), depending on the version of the
+game, with the `ddrhook2.dll`. On first run, if you don't have a conguration file, e.g.
+`ddr-12.conf`, available in the same folder, a default one will be created and the game exits.
+Simply re-run `gamestart-XX.bat` again.
 
 ## Configure USB memory cards and edit data (DDR X2)
 
-You can setup actual USB thumb drives mapped to a drive letter, e.g. `E:\` for
-player 1 and `F:\` for player 2, or just have them point to any local directory,
-e.g. `usbmem_p1` and `usbmem_p2`.
+You can setup actual USB thumb drives mapped to a drive letter, e.g. `E:\` for player 1 and `F:\`
+for player 2, or just have them point to any local directory, e.g. `usbmem_p1` and `usbmem_p2`.
 
-Set-up your folder mappings in the
-[conf file or via command line args](#configuration-ddrhook) like follows:
+Set-up your folder mappings in the [conf file or via command line args](#configuration-ddrhook) like
+follows:
 
-* Enable USB memory data emulation: `ddrhook1.usbmem_enabled=true`
-* Set P1 USB memory data path pointing to local folder `usbmem_p1` next to `DDR.EXE`:
+- Enable USB memory data emulation: `ddrhook1.usbmem_enabled=true`
+- Set P1 USB memory data path pointing to local folder `usbmem_p1` next to `DDR.EXE`:
   `ddrhook1.usbmem_path_p1=usbmem_p1`
-* Set P1 USB memory data path pointing to local folder `usbmem_p2` next to `DDR.EXE`:
+- Set P1 USB memory data path pointing to local folder `usbmem_p2` next to `DDR.EXE`:
   `ddrhook1.usbmem_path_p1=usbmem_p2`
-* Have/create a subfolder called `DDR_EDIT` on any location/USB drive you want to use
-* Name your edit data file either `DDR_EDIT_J.DAT` (for JP version) or `DDR_EDIT_US.DAT`
-  (for US version) and place it in the `DDR_EDIT` directory.
+- Have/create a subfolder called `DDR_EDIT` on any location/USB drive you want to use
+- Name your edit data file either `DDR_EDIT_J.DAT` (for JP version) or `DDR_EDIT_US.DAT` (for US
+  version) and place it in the `DDR_EDIT` directory.
 
 For the example setup above, the full relative path of the edit file should be
 `usbmem_p1\DDR_EDIT\DDR_EDIT_J.DAT` for player 1.
 
-Note that USB memory cards are not detected by the game and the game stays
-silent about that if they do not contain edit data, your path mapping does not resolve
-or you misplaced or named your edit data file incorrectly.
+Note that USB memory cards are not detected by the game and the game stays silent about that if they
+do not contain edit data, your path mapping does not resolve or you misplaced or named your edit
+data file incorrectly.
 
 ## Troubleshooting and FAQ
 
 ### Video codecs for background videos
 
 For DDR 2014 and newer (maybe also earlier?), you need to register `k-clvsd.dll` and
-`xactengine2_10.dll` to make background videos work. These files are included with
-respective versions of the games.
+`xactengine2_10.dll` to make background videos work. These files are included with respective
+versions of the games.
 
-Run the following commands either from a command line (`cmd.exe`) or from 
-*Start* > *Run*. Adjust the path to files accordingly pointing to the correct files.
+Run the following commands either from a command line (`cmd.exe`) or from *Start* > *Run*. Adjust
+the path to files accordingly pointing to the correct files.
 
-* Register `regsvr32 D:\MDX\contents\k-clvsd.dll`
-* Register `regsvr32 D:\MDX\contents\xactengine2_10.dll`
+- Register `regsvr32 D:\MDX\contents\k-clvsd.dll`
+- Register `regsvr32 D:\MDX\contents\xactengine2_10.dll`
 
-Note: The one that comes with IIDX will hang DDR at startup. The opposite is not true:
-IIDX works just fine with this CLVSD.
+The `gamestart-XX.bat` scripts should already take care of this by executing the listed commands
+when launched.
+
+Note: The one that comes with IIDX will hang DDR at startup. The opposite is not true: IIDX works
+just fine with this CLVSD.
 
 ### Laggy audio
 
-If you're running on Windows XP, go to the sound devices control panel, select your
-sound card, click Advanced Options and turn Hardware Acceleration down to basic. This
-will make the audio much less laggy..
+If you're running on Windows XP, go to the sound devices control panel, select your sound card,
+click Advanced Options and turn Hardware Acceleration down to basic. This will make the audio much
+less laggy..

doc/ddrhook/ddrio-async.md

@@ -0,0 +1,33 @@
+# Asynchronous proxy wrapper for other ddrio implementations
+
+This implementation of the Bemanitools API is not implementing support for any specific IO hardware.
+It is a proxy/shim library that loads another ddrio library, e.g. ddrio-p3io, and drives the entire
+backend in a dedicated IO thread. By implementing this behind the ddrio API, it is fully transparent
+to any existing application using it.
+
+The main benefit is the improved IO polling performance depending on how expensive the synchronous
+calls of the actual hardware are. For example, *ddrio-p3io* has very expensive write calls with ~12
+ms duration while read calls take ~4 ms. Therefore, a full update cycle is already about as costly
+as rendering an entire frame (at 60 fps).
+
+## Setup
+
+For hook libraries, i.e. ddrhookX, but likely applicable to 3rd party applications (consolidate
+their manuals).
+
+- Have `ddrio-async.dll` in the same folder as your `ddrhookX.dll`
+- Rename `ddrio-async.dll` to `ddrio.dll`
+- Pick another ddrio library as the backend of your choice, e.g. `ddrio-p3io.dl` and put it next to
+  the async `ddrio.dll`
+- Rename it to `ddrio-async-child.dll`, ddrio-async is looking for that filename in the same folder
+- Ensure that your `gamestart.bat` actually injects the appropriate `ddrhook.dll`, for example:
+
+```bat
+inject ddrhook1.dll ddr.exe ...*
+```
+
+or
+
+```bat
+launcher -K ddrhook2.dll arkmdxp3.dll ...*
+```

doc/ddrhook/ddrio-p3io.md

@@ -0,0 +1,29 @@
+# ddrio API implementation with DDR P3IO (Dragon) and EXTIO
+
+This implementation of BT5's ddrio API allows you to use the native DDR P3IO of a "Dragon PCB" plus
+the EXTIO with anything the ddrio API supports.
+
+This is not required to run the actual games supporting the hardware natively. However, there are
+various 3rd party applications using the ddrio API where you might benefit from using actual SD
+cabinet hardware, e.g. [vigem-ddrio](../vigem/README.md).
+
+## Setup
+
+For hooks, but likely applicable to 3rd party applications (consolidate their manuals).
+
+- Driver: You must have the P3IO driver intalled on your system
+  - Driver from
+    [bemanitools-supplements](https://github.com/djhackersdev/bemanitools-supplement/blob/master/ddr/p3io/README.md)
+- Have `ddrio-p3io.dll` in the same folder as your `ddrhookX.dll`
+- Rename `ddrio-p3io.dll` to `ddrio.dll`
+- Ensure that your `gamestart.bat` actually injects the appropriate ddrhook dll, for example:
+
+```bat
+inject ddrhook1.dll ddr.exe ...*
+```
+
+or
+
+```bat
+launcher -K ddrhook2.dll arkmdxp3.dll ...*
+```

doc/ddrhook/ddrio-smx.md

@@ -1,14 +1,30 @@
 # Using SMX pads with BemaniTools (DDR Ace and higher)
-If you are looking to use StepManiaX pads with DDR, these are supported **natively** for Gen 1 through Gen 5.(And theoretically beyond!) Steps and info below
+
+If you are looking to use StepManiaX pads with DDR, these are supported **natively** for Gen 1
+through Gen 5.(And theoretically beyond!) Steps and info below
 
 ## Step-by-Step
-1. Ensure that you have the latest `SMX.dll` copied to your contents folder. The easiest way to get this is to download and install the latest SMX Config program on [StepManiaX.com](https://data.stepmaniax.com/docs/SMXConfigInstaller-2020-04-03-01.exe). `SMX.dll`'s default install location is `C:\Program Files (x86)\SMXConfig`
-2. After bemanitools has been copied to your contents folder, rename the regular `ddrio.dll` to something like `ddrio-orig.dll`.
-3. Rename `ddrio-smx.dll` to `ddrio.dll`.
-4. Use the config tool to set up the usual stuff.(cards, network, etc.) Be sure to map menu, test, service, and start buttons to your keyboard or other controllers. You **cannot** map SMX panels as joystick inputs.
-5. Start the game. If everything works properly, the game will boot and your panels will light up when stepped on during gameplay and song selection.
+
+1. Ensure that you have the latest `SMX.dll` copied to your contents folder. The easiest way to get
+   this is to download and install the latest SMX Config program on
+   [StepManiaX.com](https://data.stepmaniax.com/docs/SMXConfigInstaller-2020-04-03-01.exe).
+   `SMX.dll`'s default install location is `C:\Program Files (x86)\SMXConfig`
+1. After bemanitools has been copied to your contents folder, rename the regular `ddrio.dll` to
+   something like `ddrio-orig.dll`.
+1. Rename `ddrio-smx.dll` to `ddrio.dll`.
+1. Use the config tool to set up the usual stuff.(cards, network, etc.) Be sure to map menu, test,
+   service, and start buttons to your keyboard or other controllers. You **cannot** map SMX panels
+   as joystick inputs.
+1. Start the game. If everything works properly, the game will boot and your panels will light up
+   when stepped on during gameplay and song selection.
 
 ## Important Things
-* Pad panel inputs (UDLR on P1 and P2) are mapped automatically. If you've purchased a single pad from StepManiaX, this jumper is installed and will set your pad to P2 by default. If you want to change to P1, you'll need to open up your pads and remove this jumper in the [MCU box](https://data.stepmaniax.com/docs/Stage%20-%20Gen%205%20Manual%20Rev1.pdf).
-* Panel colors set in the SMX config tool are not used. Colors are set internally by Bemanitools.
-* If you get a warning about setlights2 when starting the game, your `SMX.dll` is likely out of date. Make sure you've downloaded the latest version of the StepManiaX config tool from stepmaniax.com and have copied the `SMX.dll` to your contents folder.
+
+- Pad panel inputs (UDLR on P1 and P2) are mapped automatically. If you've purchased a single pad
+  from StepManiaX, this jumper is installed and will set your pad to P2 by default. If you want to
+  change to P1, you'll need to open up your pads and remove this jumper in the
+  [MCU box](https://data.stepmaniax.com/docs/Stage%20-%20Gen%205%20Manual%20Rev1.pdf).
+- Panel colors set in the SMX config tool are not used. Colors are set internally by Bemanitools.
+- If you get a warning about setlights2 when starting the game, your `SMX.dll` is likely out of
+  date. Make sure you've downloaded the latest version of the StepManiaX config tool from
+  stepmaniax.com and have copied the `SMX.dll` to your contents folder.

doc/ddrhook/unicorntail.md

@@ -0,0 +1,55 @@
+# Unicorntail
+
+Unicorntail is a hook library to run the DDR games on a hybrid type of hardware referred to as a
+"Chimera" or "Unicorn". Compared to a "Dragon", which refers to the official stock hardware by
+Konami, a Chimera mixes the P3IO board from a PCB used with GF&DM V4-V8, Jubeat, Jubeat Ripples or
+Jubeat Knit with the motherboard from a GF&DM XG, XG2 or XG3 PCB, or a Reflec Beat PCB.
+
+Actual build instructions for such hardware are out of scope here.
+
+## Context
+
+Dragon PCBs are hard to come by compared to finding the parts for a Chimera PCB.
+
+A Chimera PCB however is different in many aspects to the Dragon PCB and requires the use of the
+`unicorntail.dll` hook library.
+
+The Dragon's P3IO has two serial ports that the regular P3IOs do not, and one of these serial ports
+is used to communicate with the card readers. Note that these are actual serial ports driven
+directly by the P3IO microcontroller, these are NOT just passed through to the motherboard like the
+proprietary COM1 and COM2 connectors.
+
+Unicorn Tail intercepts serial port IO commands being sent to the P3IO and redirects them to a COM4
+in Windows instead, where two readers can be connected via the motherboard's RS232 port or a usb
+RS232 adapter.
+
+## Drivers
+
+You need the P3IO driver installed on your target system. These can be acquired from an actual stock
+HDD or grabbed from
+[bemanitools-supplements](https://dev.s-ul.net/djhackers/bemanitools-supplement/-/blob/master/gfdm/p3io/README.md).
+
+## COM Port Setup
+
+Using Device Manager in Windows, ensure the following COM ports are connected and setup.
+
+COM1: EXTIO COM4: Two readers
+
+Windows is often poor about saving the COM port number, so ewf commit (if applicable) and reboot
+after saving this setting to ensure it sticks.
+
+## Setup and run
+
+Edit the `gamestart.bat` file that you are using and append `unicorntail.dll` to the list of hooks,
+e.g.:
+
+```shell
+launcher.exe -H 33554432 -K unicorntail.dll arkmdxp3.dll %*
+```
+
+If you want to use any ddrhook library in addition, you have to have the hooks in the right order to
+make everything work correctly, e.g.:
+
+```shell
+launcher.exe -H 33554432 -K unicorntail.dll -K ddrhook2.dll arkmdxp3.dll %*
+```

doc/dev/README.md

@@ -1,3 +1,4 @@
 # Development documentation and notes
+
 This folder contains various lose documentation snippets created by the developers. These can be
-helpful as future reference.
+helpful as future reference.

doc/dev/c02-driver-on-w7-crash.md

@@ -1,103 +0,0 @@
-# Follow-up (14th August 2019)
-After publishing this post-mortem, I got messaged by a user on sows who was able to shed some more light on this issue.
-The user was experiencing the same symptoms on a Win7 setup: blue screen once the firmware was flashed to the C02 IO.
-This user's solutions was to use the USB2 ports on the PC instead of the USB3 ones. This is good to know and kinda
-aligns with the weird things happening in the driver (see below).
-
-# Post-mortem: C02 IO kernel module crash on Windows 7 (29th July 2019) by icex2
-## Background
-The original ezusbsys.sys kernel module, which is required to run the C02 IO, was compiled for Windows XP 32-bit, only.
-There is a newer driver by Cypress, cyusb3.sys, which could be used to IO2 boards on newer Windows platforms, but does
-not work with the C02 IO in combination with Konami's propriatery firmware. Thus, it was not possible to run the C02 IO
-on anything than Windows XP 32-bit. But, with newer IIDX games running on Windows 7 64-bit, the C02 IO wasn't usable
-anymore. Leaving aside, that the newer games actually require a BIO2 board and do not support C02 nor IO2 boards
-anymore.
-
-## The goal
-I still wanted to use my cabinet with a C02 board on newer games which is possible with BT5 adding an emulation layer
-and an interface (iidxio). This IO interface can be used to implement a driver that talks to a real IO again. Thus,
-implementing a ezusb iidxio driver library, we can run newer games with an C02 IO as well.
-
-However, there was no ezusbsys.sys driver that works on newer platforms required to run the newer games. But, Cypress
-was nice and included the source code of the ezusbsys kernel module. With a few tweaks and a very recent version of
-visual studio, it was quite easy to build this driver for newer platforms, including Windows 7, 8 and 10 in both
-32-bit and 64-bit variants.
-
-## The problem
-But, when using this driver on certain combinations of newer hardware (max. 1-2 years old) and Windows 7, the kernel
-module might crash after the Konami C02 firmware got flashed to the ezusb board. The result was a bluescreen and reboot.
-
-However, the hardware was fine and the kernel module worked fine on another piece of hardware, the stock PC that was 
-used with iidx 20 to 24. However, this hardware is not powerful enough to run iidx 25 and newer without stuttering
-issues.
-
-## The analysis/debugging
-Note: The full source code can be found in the bemanitools-supplement package.
-
-Setup:
-* Native hardware with Windows 7 that was crashing
-* Vmware with Windows 10 and Visual Studio 2019 to compile the kernel module. Target platform Windows 7 64-bit
-* Booting Windows 7 in test mode to allow unsigned kernel modules to run and with debug output turned on
-* dbgview on Windows 7 machine to get local kernel dbg output
-
-Because I wanted to stick to Windows 7 in the beginning (refer to the solution section), I started debugging the kernel
-module by enabling the debug message output that was already available in the code. However, since kernel debug message
-printing can be very delayed, the kernel could not print various messages before the kernel crashed.
-
-Thus, I started stripping the kernel module step by step to narrow down the possible spots causing the crash. After a
-few hours, I got the (first) issue tracked down:
-
-After the firmware was flashed, the device had to re-enumerate. When this happens, the function *Ezusb_PnPAddDevice*
-is called to create a new instance of the device. Since this kernel module is acting as a filter driver, it has to
-trap this call, and add a filter device before the real device in the device stack. Thus, each call to the ezusb device
-hits the filter device first and the filter device calls the real device after doing some magic.
-
-*Ezusb_PnPAddDevice* calls *Ezusb_CreateDeviceObject*. Afterwards, it checks the status of the call to 
-*Ezusb_CreateDeviceObject* and if successful, it tries attaching the device to the device stack. However, instead of
-using *IoAttachDeviceToDeviceStackSafe* it uses the unsafe variant *IoAttachDeviceToDeviceStack* which can lead to a
-race condition on newer Windows Systems. Furthermore, all initialization of further variables of the *deviceObject*
-needs to happen BEFORE doing that. Again, this is a race condition.
-
-Next issue: Once the kernel calls *Ezusb_StartDevice* -> *Ezusb_ConfigureDevice* -> *Ezusb_SelectInterfaces*, it tries
-to use *USBD_ParseConfigurationDescriptorEx* to get the interface from the configuration descriptor. However, that
-fails for some unknown reason. I checked the data structure and it is perfectly fine and everything is there. Thus,
-I wrote my own version *Ezusb_GetInterfaceFromConfigurationDescriptor* which does all the magic required to get this
-part fixed:
-```
-PUSB_INTERFACE_DESCRIPTOR Ezusb_GetInterfaceFromConfigurationDescriptor(
-	IN PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor
-	)
-{
-	if (!ConfigurationDescriptor) {
-		Ezusb_KdPrint(("ERROR Ezusb_GetInterfaceFromConfigurationDescriptor NULL configuration desc"));
-		return NULL;
-	}
-
-	if (ConfigurationDescriptor->wTotalLength < sizeof(USB_CONFIGURATION_DESCRIPTOR) + sizeof(USB_CONFIGURATION_DESCRIPTOR)) {
-		Ezusb_KdPrint(("ERROR Ezusb_GetInterfaceFromConfigurationDescriptor configuration descriptor too small to have space for interface descriptor"));
-		return NULL;
-	}
-
-	// hardcoding this to a single interface because we only care about the ezusb used with IIDX (C02 IO)
-	if (ConfigurationDescriptor->bNumInterfaces < 1) {
-		Ezusb_KdPrint(("ERROR Ezusb_GetInterfaceFromConfigurationDescriptor num interfaces 0"));
-		return NULL;
-	}
-
-	// when retrieving the configuration descriptor from the usb device, the interface is located right next to it
-	return (PUSB_INTERFACE_DESCRIPTOR) (((unsigned char*) ConfigurationDescriptor) + sizeof(USB_CONFIGURATION_DESCRIPTOR));
-}
-```
-
-And next issue is just up ahead: Following the above, we have to call *Ezusb_USBD_CreateConfigurationRequestEx* to
-create a USB configuration request to set the interface we want to use. This is executed with a *Ezusb_CallUSBD* call
-which sends request to the real hardware. However, this request always fails. The call *IoCallDriver* inside 
-*Ezusb_CallUSBD* always returns an NTSTATUS code that is not documented anywhere (can't find the exact status code
-anymore, but once you get it, try to find it in the header file).
-
-At this point, I had to give up. I already wasted too many hours and this is clearly a dead end.
-
-## The solution
-Once I realized that I got stuck with Windows 7 and I didn't want to buy (more) new hardware, I gave Windows 10 a try.
-Surprisingly, this solved all the issues and the kernel module runs fine. The C02 board is flashable without crashing
-and works with newer IIDX games.

doc/dev/device-list.md

@@ -6,21 +6,20 @@
 
 Separate boxed unit containing with one card reader slot and pin key pad
 
-- BeatmaniaIIDX DistorteD to Lincle: grey slotted readers hanging below the
-side speakers next to the monitor
-- DDR SN 1/2: slotted readers red/black supernova cover mounted to the side of
-the cabinet next to the monitor (left and right)
+- BeatmaniaIIDX DistorteD to Lincle: grey slotted readers hanging below the side speakers next to
+  the monitor
+- DDR SN 1/2: slotted readers red/black supernova cover mounted to the side of the cabinet next to
+  the monitor (left and right)
 
 # ICCB
 
-Single card reader slot (no separate pin pad) built into the cabinet.
-Pin entry using game controls.
+Single card reader slot (no separate pin pad) built into the cabinet. Pin entry using game controls.
 
 - (First gen) Jubeat cabinets before replaced with wave pass readers
 
 # ICCC
 
-Single card reader wave pass unit without separate pin pad. Pin entry using
-game controls. Still supported by newer versions.
+Single card reader wave pass unit without separate pin pad. Pin entry using game controls. Still
+supported by newer versions.
 
-- (Second gen) Jubeat cabinets with wave pass readers
+- (Second gen) Jubeat cabinets with wave pass readers

doc/dev/journal/2018-02-10-logging-breakdown-avs.md

@@ -0,0 +1,117 @@
+Copy/pasted from chat with tau (2018/02/10):
+
+alright then. so for modern iidx.
+
+we want to do logging inside iidxhook and we also want to pass AVS-style log functions to iidxio
+which in turn passes them on to geninput in order for those to do logging too
+
+so iidxhook connects to the AVS log API: log_body_misc and friends, which I assume are invoked using
+a log_misc() macro in Konami's source code that adds some sort of module tag.
+
+anyway yeah this we already know.
+
+libutil has four function ptrs: log_impl_misc and co. These are static variables which are
+statically initialized to some no-op functions. Except log_impl_fatal, whose implementation just
+calls libc abort()
+
+at startup you call log_to_external(), supplying four function ptrs to wire these up to. As the name
+suggests, this causes Bemanitools libutil to talk to something that is compatible with the AVS log
+sink API.
+
+alternatively you can log_to_writer(), which initializes Bemanitools to use its own, internal
+logging system, and you give it a log writer function that takes strings and writes them somewhere.
+
+So you have log sinks and you have log writers. The path is \[application code\] -> \[log sink\] ->
+\[logging engine\] -> \[log writer\] 19:29
+
+inside config.exe (or generally outside of modern AVS games) this path looks like \[bemanitools
+application code\] -> \[log sinks passed across dlls\] -> \[bemanitools logging engine\] ->
+\[bemanitools log writer\]
+
+inside modern AVS game the path looks like \[bt hook dll / bt iodev dll\] -> \[avs log_body_whatever
+log sinks\] -> \[avs logging engine\] -> \[launcher.exe log writer\]
+
+note that I tried to keep the log writer API consistent with the AVS log writer API but then Konami
+went and broke it repeatedly so now Bemanitools has its own stable log writer API. Launcher tracks
+the AVS log writer API, which breaks constantly, so that's not the same thing.
+
+anyway that's the background story. Now for the details about IIDX in particular.
+
+up until about iidx19 we did things the obvious way: iidxhook would log_to_external() to hook into
+the AVS log sinks and then call those directly and all was well. Then one fine day I was given a
+IIDX19 data dump and tried running iidxhook and it crashed with a stack overflow. hmm.
+
+the problem boils down to this: iidx19 AVS added those log timestamps. And for for whatever reason
+the AVS logging engine needs to access some mutexes and condition variables to make this work
+properly
+
+but AVS of course in grand Konami tradition has its own threading and concurrency primitive API
+which wraps the Win32 API. tbf this is kind of understandable in some sense, because win32 actually
+did not have condition variables until Windows Vista! in 2006! seriously, I'm not kidding.
+
+there's all sorts of articles out there describing in fine detail how to use Win32's event objects
+to implement your own condition variables and the multitudinous pitfalls that this entails
+
+but anyway one fun thing about the AVS concurrency API is that you can't actually use concurrency
+primitives unless you're calling that API from a thread launched using the AVS threading API
+
+and that's a problem in the case of iidxhook, because iidx is old as balls relatively speaking and
+its EZUSB driver code has I think two worker threads, which it launches using the MS libc's
+\_beginthreadex() function
+
+this in turn is a wrapper around the win32 CreateThread function, but it also boots up stdio on
+whatever new thread gets launched and basically is responsible for guaranteeing that the libc will
+operate correctly on the newly launched thread
+
+so yeah when you do windows programming, never call CreateThread, always call \_beginthreadex.
+otherwise stuff will break. maybe.
+
+point is, IIDX predates modern AVS so it just uses Windows threading directly. So, IIDX worker
+thread starts up, iidxhook does its thing, writes a log message, calls into AVS logging, which in
+turn grabs an AVS mutex, the implementation of which says "omg this isn't an AVS thread aaaaaa" and
+... attempts to call back into the logging system to log this fact. whereupon a stack overflow
+condition proceeds in a predictable manner.
+
+so, there are a few ways to deal with this problem. bemanitools 4 dealt with it in a fairly stupid
+way.
+
+and very elaborate way too
+
+bt4 intercepted IIDX's calls to create Windows threads and then redirected those calls to go via the
+AVS threading API
+
+so now the worker threads are AVS threads and logging works as expected
+
+which is all well and good but the problem is that these threads are quite timing critical. it
+probably worked fine, but i didn't want to risk affecting those threads in a weird way and
+introducing latency and jitter. i wanted to keep the threading pristine and not mess with it just
+for the sake of diagnostic messages
+
+so bemanitools 5 uses the log server approach
+
+at an appropriate time, it creates its own AVS thread, the logging server. Since it is an AVS
+thread, it can call the AVS logging API
+
+and then we have log_post_misc() and friends, implemented in log-server.c
+
+we initialize the Bemanitools logging system to log "externally" to those funcs and we also
+propagate those to iidxio.dll and eamio.dll which in turn pass them to geninput.dll
+
+so what do log_post_misc and friends do
+
+they lock a "mailbox" using the win32 concurrency primitives and write the log severity and a
+pointer to the string to be logged into the mailbox, then signal the log server thread, again using
+win32 concurrency primitives
+
+then they do a synchronous wait for an acknowledgement from the logging server: since we're holding
+a string pointer, we cannot return until that string pointer has been consumed or it may be
+concurrently invalidated
+
+so the log server wakes up, locks the mailbox, calls AVS log_body_misc() to write the log message,
+then once that returns it asserts a signal in the mailbox (again, win32 event object because lol
+what are condition variables) and releases the lock.
+
+the caller gets the signal, wakes up, and returns to whatever Bemanitools code is running on the
+IIDX IO worker thread that wanted to write a log message.
+
+end of essay.

doc/dev/journal/2019-07-29-c02-driver-on-w7-crash.md

@@ -0,0 +1,123 @@
+# Follow-up (14th August 2019)
+
+After publishing this post-mortem, I got messaged by a user on sows who was able to shed some more
+light on this issue. The user was experiencing the same symptoms on a Win7 setup: blue screen once
+the firmware was flashed to the C02 IO. This user's solutions was to use the USB2 ports on the PC
+instead of the USB3 ones. This is good to know and kinda aligns with the weird things happening in
+the driver (see below).
+
+# Post-mortem: C02 IO kernel module crash on Windows 7 (29th July 2019) by icex2
+
+## Background
+
+The original ezusbsys.sys kernel module, which is required to run the C02 IO, was compiled for
+Windows XP 32-bit, only. There is a newer driver by Cypress, cyusb3.sys, which could be used to IO2
+boards on newer Windows platforms, but does not work with the C02 IO in combination with Konami's
+propriatery firmware. Thus, it was not possible to run the C02 IO on anything than Windows XP
+32-bit. But, with newer IIDX games running on Windows 7 64-bit, the C02 IO wasn't usable anymore.
+Leaving aside, that the newer games actually require a BIO2 board and do not support C02 nor IO2
+boards anymore.
+
+## The goal
+
+I still wanted to use my cabinet with a C02 board on newer games which is possible with BT5 adding
+an emulation layer and an interface (iidxio). This IO interface can be used to implement a driver
+that talks to a real IO again. Thus, implementing a ezusb iidxio driver library, we can run newer
+games with an C02 IO as well.
+
+However, there was no ezusbsys.sys driver that works on newer platforms required to run the newer
+games. But, Cypress was nice and included the source code of the ezusbsys kernel module. With a few
+tweaks and a very recent version of visual studio, it was quite easy to build this driver for newer
+platforms, including Windows 7, 8 and 10 in both 32-bit and 64-bit variants.
+
+## The problem
+
+But, when using this driver on certain combinations of newer hardware (max. 1-2 years old) and
+Windows 7, the kernel module might crash after the Konami C02 firmware got flashed to the ezusb
+board. The result was a bluescreen and reboot.
+
+However, the hardware was fine and the kernel module worked fine on another piece of hardware, the
+stock PC that was used with iidx 20 to 24. However, this hardware is not powerful enough to run iidx
+25 and newer without stuttering issues.
+
+## The analysis/debugging
+
+Note: The full source code can be found in the bemanitools-supplement package.
+
+Setup:
+
+- Native hardware with Windows 7 that was crashing
+- Vmware with Windows 10 and Visual Studio 2019 to compile the kernel module. Target platform
+  Windows 7 64-bit
+- Booting Windows 7 in test mode to allow unsigned kernel modules to run and with debug output
+  turned on
+- dbgview on Windows 7 machine to get local kernel dbg output
+
+Because I wanted to stick to Windows 7 in the beginning (refer to the solution section), I started
+debugging the kernel module by enabling the debug message output that was already available in the
+code. However, since kernel debug message printing can be very delayed, the kernel could not print
+various messages before the kernel crashed.
+
+Thus, I started stripping the kernel module step by step to narrow down the possible spots causing
+the crash. After a few hours, I got the (first) issue tracked down:
+
+After the firmware was flashed, the device had to re-enumerate. When this happens, the function
+*Ezusb_PnPAddDevice* is called to create a new instance of the device. Since this kernel module is
+acting as a filter driver, it has to trap this call, and add a filter device before the real device
+in the device stack. Thus, each call to the ezusb device hits the filter device first and the filter
+device calls the real device after doing some magic.
+
+*Ezusb_PnPAddDevice* calls *Ezusb_CreateDeviceObject*. Afterwards, it checks the status of the call
+to *Ezusb_CreateDeviceObject* and if successful, it tries attaching the device to the device stack.
+However, instead of using *IoAttachDeviceToDeviceStackSafe* it uses the unsafe variant
+*IoAttachDeviceToDeviceStack* which can lead to a race condition on newer Windows Systems.
+Furthermore, all initialization of further variables of the *deviceObject* needs to happen BEFORE
+doing that. Again, this is a race condition.
+
+Next issue: Once the kernel calls *Ezusb_StartDevice* -> *Ezusb_ConfigureDevice* ->
+*Ezusb_SelectInterfaces*, it tries to use *USBD_ParseConfigurationDescriptorEx* to get the interface
+from the configuration descriptor. However, that fails for some unknown reason. I checked the data
+structure and it is perfectly fine and everything is there. Thus, I wrote my own version
+*Ezusb_GetInterfaceFromConfigurationDescriptor* which does all the magic required to get this part
+fixed:
+
+```
+PUSB_INTERFACE_DESCRIPTOR Ezusb_GetInterfaceFromConfigurationDescriptor(
+	IN PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor
+	)
+{
+	if (!ConfigurationDescriptor) {
+		Ezusb_KdPrint(("ERROR Ezusb_GetInterfaceFromConfigurationDescriptor NULL configuration desc"));
+		return NULL;
+	}
+
+	if (ConfigurationDescriptor->wTotalLength < sizeof(USB_CONFIGURATION_DESCRIPTOR) + sizeof(USB_CONFIGURATION_DESCRIPTOR)) {
+		Ezusb_KdPrint(("ERROR Ezusb_GetInterfaceFromConfigurationDescriptor configuration descriptor too small to have space for interface descriptor"));
+		return NULL;
+	}
+
+	// hardcoding this to a single interface because we only care about the ezusb used with IIDX (C02 IO)
+	if (ConfigurationDescriptor->bNumInterfaces < 1) {
+		Ezusb_KdPrint(("ERROR Ezusb_GetInterfaceFromConfigurationDescriptor num interfaces 0"));
+		return NULL;
+	}
+
+	// when retrieving the configuration descriptor from the usb device, the interface is located right next to it
+	return (PUSB_INTERFACE_DESCRIPTOR) (((unsigned char*) ConfigurationDescriptor) + sizeof(USB_CONFIGURATION_DESCRIPTOR));
+}
+```
+
+And next issue is just up ahead: Following the above, we have to call
+*Ezusb_USBD_CreateConfigurationRequestEx* to create a USB configuration request to set the interface
+we want to use. This is executed with a *Ezusb_CallUSBD* call which sends request to the real
+hardware. However, this request always fails. The call *IoCallDriver* inside *Ezusb_CallUSBD* always
+returns an NTSTATUS code that is not documented anywhere (can't find the exact status code anymore,
+but once you get it, try to find it in the header file).
+
+At this point, I had to give up. I already wasted too many hours and this is clearly a dead end.
+
+## The solution
+
+Once I realized that I got stuck with Windows 7 and I didn't want to buy (more) new hardware, I gave
+Windows 10 a try. Surprisingly, this solved all the issues and the kernel module runs fine. The C02
+board is flashable without crashing and works with newer IIDX games.

doc/dev/journal/2019-10-07-iidx-gfx-rendering-loops.md

@@ -1,25 +1,31 @@
 # Notes outlining some aspects of the DirectX calls which were required to know to implement a up-/downscaling feature
-As the title says, this outlines some aspects I needed to figure out in order to implement a up-/downscaling feature
-within the d3d9 hook module that works on all currently available IIDX versions (9 to 26).
 
-To analyze the rendering loops, I have used a tool called apitrace which traces the calls of many graphic APIs:
-https://github.com/apitrace/apitrace
+As the title says, this outlines some aspects I needed to figure out in order to implement a
+up-/downscaling feature within the d3d9 hook module that works on all currently available IIDX
+versions (9 to 26).
 
-Defintely recommended to quickly figure out what is going on regarding rendering. It also allows you to let you render
-parts of a scene after the application exited because it records all API calls and data passed to them.
+To analyze the rendering loops, I have used a tool called apitrace which traces the calls of many
+graphic APIs: https://github.com/apitrace/apitrace
 
-Anyway, considering the various iterations in (GPU) hardware the game had to undergo combined with weird quirks and
-"fixes" Bemanitools is undoing, I wouldn't have guessed that their rendering engine was nearly the same until IIDX 20.
-That's when they introduced SD/HD mode.
+Defintely recommended to quickly figure out what is going on regarding rendering. It also allows you
+to let you render parts of a scene after the application exited because it records all API calls and
+data passed to them.
 
-In this case, that's great news because I had to craft a solution that allows up-/downscaling the final frame to
-different resolutions (see the iidxhook-util/d3d9 module for more details about the feature).
+Anyway, considering the various iterations in (GPU) hardware the game had to undergo combined with
+weird quirks and "fixes" Bemanitools is undoing, I wouldn't have guessed that their rendering engine
+was nearly the same until IIDX 20. That's when they introduced SD/HD mode.
+
+In this case, that's great news because I had to craft a solution that allows up-/downscaling the
+final frame to different resolutions (see the iidxhook-util/d3d9 module for more details about the
+feature).
 
 But first, we need a breakdown of the render loop's most relevant parts for this:
 
 ## IIDX pre 20
-Using apitrace, we can see the following outline of a frame (not counting the first one that does a lot of setup in
-the beginning):
+
+Using apitrace, we can see the following outline of a frame (not counting the first one that does a
+lot of setup in the beginning):
+
 ```
 BeginScene
 Clear
@@ -31,12 +37,14 @@ Present
 
 No render target switching, simply render everything to the back buffer...plain and simple.
 
-Note: The viewport size is determined by the size returned by GetClientRect, wtf.
-Welp, no official Konmai seal of approval without that. ¯\_(ツ)_/¯
+Note: The viewport size is determined by the size returned by GetClientRect, wtf. Welp, no official
+Konmai seal of approval without that. ¯\_(ツ)\_/¯
 
 ## IIDX 20+
-Using apitrace, we can see the following outline of a frame (not counting the first one that does a lot of setup in
-the beginning):
+
+Using apitrace, we can see the following outline of a frame (not counting the first one that does a
+lot of setup in the beginning):
+
 ```
 BeginScene
 // tex1 is a render target texture with size 1280x720 (also in SD mode)
@@ -63,26 +71,30 @@ EndScene -> ErrInvalidCall return code
 Present
 ```
 
-This is quite a different flow to implement HD and SD mode but the solution to solve that particular problem is straight
-forward and easy to understand. This means that the game will always render in HD mode and only downscale the final
-frame to SD resolution for 640x480 output.
+This is quite a different flow to implement HD and SD mode but the solution to solve that particular
+problem is straight forward and easy to understand. This means that the game will always render in
+HD mode and only downscale the final frame to SD resolution for 640x480 output.
 
-Also, why the fuck do they call BeginScene and EndScene twice? Looks like they wanted to do this in two separate scenes
-for some reason. Checking the return values would have revealed to them that something's not right...lucky them that
-this code works nevertheless.
-Another Konmai seal of approval, a job well done. ¯\_(ツ)_/¯
+Also, why the fuck do they call BeginScene and EndScene twice? Looks like they wanted to do this in
+two separate scenes for some reason. Checking the return values would have revealed to them that
+something's not right...lucky them that this code works nevertheless. Another Konmai seal of
+approval, a job well done. ¯\_(ツ)\_/¯
 
 ## iidxhook's up-/downscaling solution
-The initial solution simply hooked into BeginScene and EndScene and let the game render to an intermediate render
-target texture. The texture was scaled according to the actual target frame buffer size before getting presented. This
-solution worked fine for pre IIDX 20 games but created a black screen on IIDX 20+.
 
-In order to avoid two different scaling flows, the final solution that works for both does the following:
-* Create a render target texture with native resolution and let the game render to it
-* Set the render target to that intermediate render target texture on BeginScene
-* Before Present
-    * Scale the intermediate render target texture to the back buffer
-    * Set the back buffer as the render target
-* Present frame
+The initial solution simply hooked into BeginScene and EndScene and let the game render to an
+intermediate render target texture. The texture was scaled according to the actual target frame
+buffer size before getting presented. This solution worked fine for pre IIDX 20 games but created a
+black screen on IIDX 20+.
 
-Just an outline which follows the actual implementation that you can find in the iidxhook-util/d3d9.
+In order to avoid two different scaling flows, the final solution that works for both does the
+following:
+
+- Create a render target texture with native resolution and let the game render to it
+- Set the render target to that intermediate render target texture on BeginScene
+- Before Present
+  - Scale the intermediate render target texture to the back buffer
+  - Set the back buffer as the render target
+- Present frame
+
+Just an outline which follows the actual implementation that you can find in the iidxhook-util/d3d9.

doc/dev/journal/2020-12-16-acio-bio2-iidx-package-dump.md

@@ -1,21 +1,25 @@
 # ACIO BIO2 IIDX package dump
-Package dump excerpt of the init sequence of a original Konami IIDX BIO2 with sub IO connected.
-This was used to identify a missing piece of information that needs to be communicated to the BIO2
-for IIDX to initialize the sub IO correctly.
+
+Package dump excerpt of the init sequence of a original Konami IIDX BIO2 with sub IO connected. This
+was used to identify a missing piece of information that needs to be communicated to the BIO2 for
+IIDX to initialize the sub IO correctly.
 
 The dump was cut off after two polls as the sequence just keeps on repeating from that point on.
 
 ## Findings for problem to solve
-With the previous implemention of the BIO2 driver, which was created off references of SDVX KFCA,
-a BIO2 used with IIDX and the sub IO (to upgrade older C02, IO2 cabinets) connected didn't
-initialize properly. This resulted in no inputs/outputs other than 14 keys working.
+
+With the previous implemention of the BIO2 driver, which was created off references of SDVX KFCA, a
+BIO2 used with IIDX and the sub IO (to upgrade older C02, IO2 cabinets) connected didn't initialize
+properly. This resulted in no inputs/outputs other than 14 keys working.
 
 The problem identified was a different byte, exact meaning not known, that is sent in
 [exchange 4](#exchange-4-ac-io-cmd-clear). Instead of `0x3B` from the SDVX KFCA based
 implementation, it needs to be set to `0x2D`.
 
 ## Exchange 1: AC_IO_CMD_ASSIGN_ADDRS
+
 ### Write
+
 ```text
 AA 00 00 01 00 01 00 02
 
@@ -29,6 +33,7 @@ data: 00
 ```
 
 ### Read
+
 ```
 AA AA 00 00 01 00 01 01 03
 
@@ -43,7 +48,9 @@ AA: SOF
 ```
 
 ## Exchange 2: AC_IO_CMD_GET_VERSION
+
 ### Write
+
 ```
 AA 01 00 02 00 00 03
 
@@ -56,6 +63,7 @@ AA: SOF
 ```
 
 ### Read
+
 ```
 AA AA 81 00 02 00 2C 0D 06 00 00 ...
 
@@ -70,7 +78,9 @@ XX: checksum
 ```
 
 ## Exchange 3: AC_IO_CMD_START_UP
+
 ### Write
+
 ```
 AA 01 00 03 00 00 04
 
@@ -83,6 +93,7 @@ AA: SOF
 ```
 
 ### Read
+
 ```
 AA AA 81 00 03 00 01 00 85
 
@@ -97,7 +108,9 @@ AA: SOF
 ```
 
 ## Exchange 4: AC_IO_CMD_CLEAR
+
 ### Write
+
 ```
 AA 01 01 00 00 01 2D 30
 
@@ -111,6 +124,7 @@ AA: SOF
 ```
 
 ### Read
+
 ```
 AA AA 81 01 00 00 01 00 83
 
@@ -125,7 +139,9 @@ AA: SOF
 ```
 
 ## Exchange 5: BIO2_BI2A_CMD_WATCHDOG
+
 ### Write
+
 ```
 AA 01 01 20 00 02 00 00 24
 
@@ -139,6 +155,7 @@ AA: SOF
 ```
 
 ### Read
+
 ```
 AA AA 81 01 20 00 01 00 A3
 
@@ -153,7 +170,9 @@ A3: checksum
 ```
 
 ## Exchange 6: BIO2_BI2A_CMD_POLL
+
 ### Write
+
 ```
 AA 01 01 52 00 30 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 84
 
@@ -167,6 +186,7 @@ AA: SOF
 ```
 
 ### Read
+
 ```
 AA AA 81 01 52 00 2E 00 00 B0 00 F0 00 F0 F0 00 00 00 00 00 02 00 5F 11 FF 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 F3
 
@@ -181,12 +201,15 @@ F3: checksum
 ```
 
 ## Exchange 7: BIO2_BI2A_CMD_POLL
+
 ### Write
+
 ```
 AA 01 01 52 00 30 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 84
 ```
 
 ### Read
+
 ```
 AA AA 81 01 52 00 2E 00 00 B0 00 F0 00 F0 F0 00 00 00 00 00 02 00 64 11 FF 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 F8
-```
+```

doc/dev/journal/2023-04-03-d01-ezusb-io-boot-security.md

@@ -0,0 +1,288 @@
+# Beatmania IIDX 10th Style - D01 IO boot code and security init
+
+Date: 2023-04-03 Author: icex2
+
+Documenting decompiled and reverse engineered code snippets from the D01 JAE `bm2dx.exe`. These
+helped me figuring out the two different security boot modes the game supports.
+
+In summary, it supports booting with the C02 IO with a C02 black dongle and a D01 IO board with a
+D01 dongle. No other combination is valid because they didn't make sense back then. You either had
+an upgraded old style/twinkle cabinet to C02 (GEC02) or you bought a new dedicated cabinet (GQD01).
+With 10th style supporting the old C02 dongle, it appears that all owners of a C02 cabinet with IO
+board and C02 dongle received a free software update/HDD. This might make sense considering the
+short life span of C02 and the game being super buggy, especially in earlier/initial revisions.
+
+The game expects the following "configurations" from bemanitools:
+
+- Booting as upgraded C02 with free D01 upgrade
+  - `sec.boot_version=GEC02   `
+  - `sec.boot_seeds=0:0:1`
+  - `sec.black_plug_mcode=GEC02JAA`
+  - "D01 IO pin" on IO board not active
+- Booting as dedicated
+  - `sec.boot_version=GEC02   `
+  - `sec.boot_seeds=0:1:1`
+  - `sec.black_plug_mcode=GQD01JAA`
+  - "D01 IO pin" on IO board ACTIVE
+
+All the above was derived from reading and understanding the documented code excerpts below.
+
+## io_boot - sub_402700
+
+Called as the first step in the boot statemachine by the "boot" function `sub_40F9C0`.
+
+```c
+// sub_402700
+int __stdcall io_boot(int a1)
+{
+  DWORD (__stdcall *timeGetTime)(); // esi
+  int usb_boot_security_res; // ebp
+  DWORD time_start; // ebx
+  int io_boot_state; // edi
+  DWORD now; // esi
+  BOOL is_d01_boot_mode; // esi
+  BOOL v7; // esi
+  int result; // eax
+  int v9; // [esp+10h] [ebp-2Ch]
+  int firmware_version; // [esp+14h] [ebp-28h]
+  int io_pad_read; // [esp+18h] [ebp-24h] BYREF
+  char v12[32]; // [esp+1Ch] [ebp-20h] BYREF
+
+  dword_4D0768 = 0;
+  strcpy(byte_4D076C, &byte_4D0858);
+  timeGetTime = ::timeGetTime;
+  v9 = 0;
+  usb_boot_security_res = io_pad_read;
+  time_start = ::timeGetTime();
+  io_boot_state = 0;
+  while ( 2 )
+  {
+    switch ( io_boot_state )
+    {
+      case 0:                                   // "start io", firmware download and wait for reconnect
+        if ( usbStart(0) )
+        {
+          if ( time_exceeded(time_start, 20000) )
+            set_io_error_type(1, aErrorUsbioStar);// ERROR(USBIO START)
+        }
+        else
+        {
+          io_boot_state = 1;
+        }
+        goto reset_io_boot_state_label;
+      case 1:                                   // check firmware
+        firmware_version = usbFirmResult();
+        if ( firmware_version == 96 )
+        {
+          if ( time_exceeded(time_start, 25000) )
+            set_io_error_type(1, aErrorFm);     // ERROR(FM), FM = firmware
+        }
+        else
+        {
+          io_boot_state = 2;
+        }
+        goto reset_io_boot_state_label;
+      case 2:
+        if ( !firmware_version )
+        {
+          usbMute(1);
+          time_start = timeGetTime();
+          now = timeGetTime();
+          io_input_is_d01_ezusb = 0;
+          do
+          {
+            usbPadRead(&io_pad_read);
+            if ( (io_pad_read & 0x10) != 0 )
+              io_input_is_d01_ezusb = 1;
+          }
+          while ( !time_exceeded(now, 2000) );
+          io_boot_state = 3;
+reset_io_boot_state_label:
+          timeGetTime = ::timeGetTime;
+          if ( io_boot_state != v9 )
+          {
+            v9 = io_boot_state;
+            time_start = ::timeGetTime();
+          }
+          continue;                             // retry
+        }
+        if ( firmware_version > 128 )
+        {
+          if ( firmware_version == 254 )
+          {
+            set_io_error_type(1, aErrorFmTrnsOut);// ERROR(FM TRNS-OUT)
+            return 1;
+          }
+          if ( firmware_version == 255 )
+          {
+            set_io_error_type(1, aErrorFmTimeOut);// ERROR(FM TIME-OUT)
+            return 1;
+          }
+        }
+        else
+        {
+          switch ( firmware_version )
+          {
+            case 128:
+              set_io_error_type(1, aErrorFmReadErr);// ERROR(FM READ-ERR)
+              return 1;
+            case -113:
+              set_io_error_type(1, aErrorFmDlErr);// ERROR(FM DL-ERR)
+              return 1;
+            case -33:
+              set_io_error_type(1, aErrorFmCmprReq);// ERROR(FM CMPR-REQ)
+              return 1;
+          }
+        }
+UNKNOWN_ERROR_LABEL:
+        set_io_error_type(1, aErrorUnknown);    // ERROR(UNKNOWN)
+        return 1;
+      case 3:
+        if ( io_init_security() )
+        {
+          set_io_error_type(1, aErrorSqInit);   // ERROR(SQ-INIT)
+          return 1;
+        }
+        io_boot_state = 4;
+        goto reset_io_boot_state_label;
+      case 4:
+        is_d01_boot_mode = io_input_is_d01_ezusb != 0;
+        if ( !strncmp(black_dongle_mcode, MCODE_GED01, 5u) )
+          is_d01_boot_mode = 1;
+        usb_boot_security_res = usbBootSecurity(aGec02, 0, is_d01_boot_mode, 1);
+        if ( usb_boot_security_res == 96 )
+        {
+          if ( time_exceeded(time_start, 20000) )
+            set_io_error_type(1, aErrorBtSqInit);// ERROR(BT-SQ-INIT)'
+        }
+        else
+        {
+          io_boot_state = 5;
+        }
+        goto reset_io_boot_state_label;
+      case 5:
+        if ( usb_boot_security_res )
+        {
+          switch ( usb_boot_security_res )
+          {
+            case 0xFFFFFE9F:
+              set_io_error_type(1, aErrorSecurityE);// ERROR(SECURITY EEP)
+              result = 1;
+              break;
+            case 0xFFFFFECF:
+            case 0xFFFFFEDF:
+              set_io_error_type(1, aErrorSecurityI);// ERROR(SECURITY ID or EEP)
+              result = 1;
+              break;
+            case 0xFFFFFEEF:
+              set_io_error_type(1, aErrorSecurityN);// 'ERROR(SECURITY No Match)'
+              result = 1;
+              break;
+            case 0xFFFFFEFF:
+              io_boot_state = 6;
+              goto reset_io_boot_state_label;
+            default:
+              goto UNKNOWN_ERROR_LABEL;
+          }
+        }
+        else
+        {
+          Sleep(0x3E8u);
+          result = 0;
+        }
+        return result;
+      case 6:                                   // security conversion/upgrading security dongles
+        v7 = io_input_is_d01_ezusb != 0;
+        if ( !usbGetSecurityKey(v12) )
+        {
+          if ( usbSetupSecurityComplete(v12, 0, v7, 1) )
+            set_io_error_type(1, aErrorSecurityC);// ERROR(SECURITY CONVERSION FAILED)
+          return 1;
+        }
+        set_io_error_type(1, aErrorSecurityC);  // ERROR(SECURITY CONVERSION FAILED)
+        goto reset_io_boot_state_label;
+      default:
+        goto UNKNOWN_ERROR_LABEL;
+    }
+  }
+}
+```
+
+## io_init_security - sub_402BB0
+
+Sub-function of the [io_boot](#io_boot---sub_402700) function.
+
+```c
+// sub_402BB0
+int io_init_security()
+{
+  int v0; // esi
+  int v2; // esi
+  int mcode_mismatch_cnt; // esi
+  char white_dongle_data_maybe[10]; // [esp+Ch] [ebp-20h] BYREF
+
+  usbSecurityInit();
+  v0 = 0;
+  while ( usbSecurityInitDone() )
+  {
+    if ( v0 > 1200 )
+    {
+      set_io_error_type(-1, aNgSi);
+      return -1;
+    }
+    ++v0;
+    Sleep(16u);
+  }
+  pcbid = 0;
+  dword_4D0754 = 0;
+  word_4D0758 = 0;
+  while ( usbGetPCBID(&pcbid) )
+    Sleep(1u);
+  *(_DWORD *)black_dongle_mcode = 0;
+  v2 = 0;
+  *(_DWORD *)&black_dongle_mcode[4] = 0;
+  while ( usbGetSecurity(black_dongle_mcode) )  // black_dongle_mcode = GQD01JAA
+  {
+    if ( v2 > 1200 )
+    {
+      set_io_error_type(-1, aNgPd);
+      return -1;
+    }
+    ++v2;
+    Sleep(16u);
+  }
+  set_cabinet_type(black_dongle_mcode[6]);
+  mcode_mismatch_cnt = black_dongle_mcode[0] != 'G';
+  if ( io_input_is_d01_ezusb || !strncmp(black_dongle_mcode, MCODE_GED01, 5u) )// Path for using the D01 dongle with D01 IO board
+  {
+    if ( (unsigned __int8)black_dongle_mcode[2] != (char)MCODE_D01 )
+      ++mcode_mismatch_cnt;
+    if ( (unsigned __int8)black_dongle_mcode[3] != SBYTE1(MCODE_D01) )
+      ++mcode_mismatch_cnt;
+    if ( (unsigned __int8)black_dongle_mcode[4] != SBYTE2(MCODE_D01) )
+      ++mcode_mismatch_cnt;
+  }
+  else                                          // Path for using the C02 dongle with C02 IO board
+  {
+    if ( (unsigned __int8)black_dongle_mcode[2] != MCODE_C02[0] )
+      ++mcode_mismatch_cnt;
+    if ( (unsigned __int8)black_dongle_mcode[3] != MCODE_C02[1] )
+      ++mcode_mismatch_cnt;
+    if ( (unsigned __int8)black_dongle_mcode[4] != MCODE_C02[2] )
+      ++mcode_mismatch_cnt;
+    if ( !usbGetSecurityKey(white_dongle_data_maybe) )
+    {
+      black_dongle_mcode[6] = white_dongle_data_maybe[6];
+      set_cabinet_type(white_dongle_data_maybe[6]);
+    }
+  }
+  if ( black_dongle_mcode[5] != 'J' )
+    ++mcode_mismatch_cnt;
+  if ( black_dongle_mcode[6] != 'A' && black_dongle_mcode[6] != 'B' && black_dongle_mcode[6] != 'C' )
+    ++mcode_mismatch_cnt;
+  if ( !mcode_mismatch_cnt )
+    return 0;
+  set_io_error_type(-1, aNgSecurity);
+  return -1;
+}
+```

doc/dev/journal/2023-04-13-iidx-24-gfx-upscaling.md

@@ -0,0 +1,56 @@
+# IIDX 24 GFX upscaling notes
+
+Date: 2023-04-15 Author: icex2
+
+Notes about my work on fixing the upscaling/downscaling feature of bemanitools for IIDX 20 to 26. I
+realized that the render backend changed significantly that the old method that worked fine doesn't
+work anymore.
+
+The tool used in the screenshots is [apitrace](https://github.com/apitrace/apitrace).
+
+## IIDX 24
+
+The GFX engine in IIDX from 20 to 26 has a changed render loop that includes built-in scaling to
+implement the SD and HD/HD\* screen settings that are selectable in the operator menu
+
+### Frame 0 - GFX init part
+
+Setting up the context and device, as well as the frame buffer. This also creates the intermediate
+texture that is configured as the render target once it begins drawing the scene.
+
+![](2023-04-13-iidx-24-gfx-upscaling/init.png)
+
+### Frame 1 - A clean main render path
+
+Start the scene and set the render target to the intermediate texture.
+
+![](2023-04-13-iidx-24-gfx-upscaling/beginscene.png)
+
+After done drawing the scene, the intermediate texture is blended to the framebuffer. With a target
+2D plane having the size of the target resolution, the blending applies linear scaling to either up-
+or downscale the final image.
+
+![](2023-04-13-iidx-24-gfx-upscaling/scaling.png)
+
+## IIDX 10
+
+A recap of the old stuff, see also [my previous notes](2019-10-07-iidx-gfx-rendering-loops.md), as I
+had to look at everything again to properly understand the differences.
+
+### Frame 0 - GFX init part
+
+Setting up the context and device, as well as the frame buffer. Renders directly to the frame
+buffer.
+
+![](2023-04-13-iidx-24-gfx-upscaling/init10.png)
+
+### Frame 1 - A clean main render path
+
+Beginning the scene excerpt. The viewport needs to match the target resolution to display the final
+image correctly.
+
+![](2023-04-13-iidx-24-gfx-upscaling/beginscene10.png)
+
+Ending the scene excerpt, nothing fancy here, just swapping the back buffer.
+
+![](2023-04-13-iidx-24-gfx-upscaling/endscene10.png)

doc/dev/journal/2023-05-28-ddr-p3io-driver-work.md

@@ -0,0 +1,195 @@
+# DDR p3io driver work, various notes
+
+Date: 2023-05-28 Author: icex2
+
+Notes about my work on writing a DDR P3io driver.
+
+## Python IO board hardware breakout interface
+
+PCB breakout interfaces/connectors on the side of the boards.
+
+### P2IO DDR
+
+Descriptions assume cabinet hardware of an upgraded DDR "black SD cabinet"
+
+- `LINE OUT 1`: Primary audio out to amplifier
+- `LINE OUT 2`: N.C.
+- `RGB`: Video out to monitor, supports 15khz/31khz based on hardware switch for video freq/mode
+  selection
+- `COM1`: Virtual com port that connects to the EXTIO
+- `COM2`: Virtual com port that connects to a pair of ICCA card readers
+- `LAN`: Network connection
+- `PWR`: 100V power in
+- `ANALOG`: N.C.
+- `PORT 1`: Lights output for cabinet lights, e.g. menu button lights, top header lights
+- `PORT 2`: N.C.
+- `DIPSW`
+  - `1`: ???
+  - `2`: On = force all sensor polling mode and allow running the game without an EXTIO
+  - `3`: ???
+  - `4`: On = force 15 khz monitor output
+- `PLUG 1`: Black dongle
+- `PLUG 2`: White dongle
+
+### P3IO GF/DM
+
+Descriptions assume usage of a P3IO from a GF/DM in a "chimera style PCB build" on an upgraded DDR
+"black SD cabinet"
+
+- `PWR`: 100V power in
+- `12V-OUT`: +12V out for external devices
+- `PORT 1`: Lights output for cabinet lights, e.g. menu button lights, top header lights
+- `PORT 2`: N.C.
+- `COM1`: To EXTIO
+- `COM2`: To card readers
+- `RGB`: Video out to monitor, supports 15khz/31khz based on hardware switch for video freq/mode
+  selection
+- `LINE OUT 1`: Primary audio out to amplifier
+- `LINE OUT 2`: N.C.
+- `DIPSW`
+  - `1`:
+  - `2`:
+  - `3`:
+  - `4`: On = force 15 khz monitor output
+- `PLUG 1`: Roundplug black dongle
+- `PLUG 2`: Roundplug white dongle
+
+### P3IO DDR(X)
+
+Descriptions assume cabinet hardware of an upgraded DDR "black SD cabinet"
+
+- `PWR`: 100V power in
+- `USB`: USB memory card readers on cabinet
+- `PORT 1`: Lights output for cabinet lights, e.g. menu button lights, top header lights
+- `COM3-4`: Virtual COM ports
+  - COM3 (VCOM1): Pins 1,3,5 on connector -> To card readers
+  - COM4 (VCOM0): Pins 2,4,6 on connector -> N.C.
+- `PLUG`: Breakout to security round plugs (black and white dongles)
+- `COM1`: To EXTIO
+  - Pinout (pins left to right)
+    - 1: TXD1
+    - 2: RXD1
+    - 3: N.C.
+    - 4: N.C.
+    - 5: GND
+- `COM2`: N/A (light spires on black HD cabinet)
+  - Pinout (pins left to right)
+    - 1: TXD2
+    - 2: RXD2
+    - 3: GND
+- `RGB`: Video out to monitor, supports 15khz/31khz based on hardware switch for video freq/mode
+  selection
+- `LINE OUT1`: Primary audio out to amplifier
+- `LINE OUT2`: N.C.
+- `LAN`: Network
+- `DIP SW`
+  - `1`:
+  - `2`:
+  - `3`:
+  - `4`: On = force 15 khz monitor output
+
+## Python IO boards and differences
+
+### P3IO DDR(X)
+
+- Connects to USB and actually enumerates as a USB device and not a virtual COM port
+- COM ports 1-4 on breakout of the PCB are being passed through as actual COM ports to the operating
+  system
+
+### P3IO GF/DM
+
+- Connects to USB and actually enumerates as a USB device and not a virtual COM port
+- COM ports 1-2 on breakout of the PCB are just virtual COM ports
+- These do not show up as COM ports on the operating system
+- The game drives the COM ports through the main P3IO protocol with additional P3IO commands to
+  open, read, write and close these virtual COM ports
+
+### P2IO DDR
+
+- Connects to USB and actually enumerates as a USB device and not a virtual COM port
+- COM ports 1-2 on breakout of the PCB are just virtual COM ports
+- These do not show up as COM ports on the operating system
+- The game drives the COM ports through the main P3IO protocol with additional P3IO commands to
+  open, read, write and close these virtual COM ports
+
+## Pinout card reader P1 -> P2 mini din8 male to mini din8 male
+
+Port 1 2 and 3:
+
+- Pin 3: TX
+- Pin 4: GND
+- Pin 5 : RX
+
+Pin 3 and 5 need to be reversed inbetween readers They are all the same, so your cable needs to
+bridge them over. A standard male to male mini din 8 cable does not do that.
+
+### Pinout card reader stock cable s-sub9 to round pin9
+
+```text
+dsub-9 female -> mini-din8 male
+2 (TXD) -> 3
+3 (RXD) -> 5
+5 (GND) -> 4
+```
+
+## ADE board and com port assignments
+
+Default or incorrectly configured?
+
+- `COM1` -> on mainboard
+- `COM2` -> COM2 on P3IO breakout
+- `COM3` -> ???
+- `COM4` -> COM1 on P3IO breakout
+
+## P3IO command init sequence on DDR 18
+
+From the ddrio-python23 library
+
+````text
+.data:1002D5D0 g_init_pakets   db 0AAh, 2, 0, 1, 29h dup(0); field_0.field_0
+.data:1002D5D0                                         ; DATA XREF: initialize_and_send_pakets+5↑o
+.data:1002D5D0                 db 0AAh, 2, 0, 2Fh, 29h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 3, 1, 27h, 1, 28h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2 dup(2), 31h, 29h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2, 3, 1, 29h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 3, 4, 27h, 29h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2Bh, 5, 25h, 10h, 28h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2Bh, 6, 25h, 10h, 28h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2Bh, 7, 25h, 10h, 28h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2Bh, 8, 25h, 10h, 28h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2Bh, 9, 25h, 10h, 28h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2Bh, 0Ah, 25h, 29h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2Bh, 0Bh, 25h, 29h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2Bh, 0Ch, 25h, 29h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2Bh, 0Dh, 25h, 29h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2Bh, 0Eh, 25h, 29h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 3, 0Fh, 5, 29h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 3, 0, 2Bh, 1, 28h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 3, 1, 29h, 5, 28h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 3, 2, 5, 30h, 28h dup(0); field_0.field_0
+.data:1002D5D0                 db 0AAh, 2 dup(3), 27h, 29h dup(0); field_0.field_0
+``
+
+```text
+// 01: get version <- this is part of a "flush" of old data?
+// 2F: set mode
+// 27: get cab type or dispsw
+// 31: get coinstock
+// 1: get version
+// 27: get cab type or dipsw
+// 25: read plug
+// 25: read plug
+// 25: read plug
+// 25: read plug
+// 25: read plug
+// 25: read plug
+// 25: read plug
+// 25: read plug
+// 25: read plug
+// 25: read plug
+// 5: set watchdog
+// 2b: unknown
+// 29: get video freq
+// 5: set watchdog
+// 27: get cab type or dipsw
+````

doc/dev/journal/2025-02-09-iidx-engine.md

@@ -0,0 +1,319 @@
+# IIDX engine overview and how game-play is impacted by hardware and software
+
+Date: 2025-02-09 Author: icex2
+
+This document provides information and explains the following:
+
+* A sort-of taxonomy of the different major IIDX game engine versions
+* How the core game-play part of the engine works regarding
+  * Threading model
+  * Main render loop
+  * Timing and synchronization
+
+The goal is to capture key knowledge about how the game's engine works to enable a better
+understanding for developing bemanitools and how certain features can impact performance and
+synchronization during game-play.
+
+This document is not claiming to be complete or 100% accurate. It is based on my own personal
+research and understanding of the IIDX game engine. It is very likely that some of the information
+is wrong or misunderstood. Feel free to raise any questions or concerns in an issue as I want
+this document to be as accurate as possible.
+
+## Taxonomy of IIDX game engine versions
+
+With every version, there have been numerous changes and improvements to the game engine. The
+following is a rough taxonomy that is focused on cabinet and hardware changes. As these are likely
+the main driver for key changes to the software and game engine, they create fairly distinct
+stages throughout the different versions of the game. The key attributes to be considered here are:
+
+* Main PCB
+* IO board
+* Monitor
+
+All of these had significant impact on key software features appearing or changing.
+
+### Twinkle hardware era: 1st Style to 8th Style
+
+* [Twinkle PCB](https://github.com/shizmob/arcade-docs/blob/main/konami/boards.md#twinkle)
+* [Original rear projection monitor](https://github.com/shizmob/arcade-docs/blob/main/konami/products.md#iidx-rear-projection-monitor)
+* Homogenous hardware and software
+
+### 1st gen PC-based upgrade only: 9th Style
+
+* 9th Style came as an upgrade kit only to existing twinkle-based cabinet hardware
+* [KNM-845G3-A02 PCB](https://github.com/shizmob/arcade-docs/blob/main/konami/boards.md#knm-845g3-a02)
+* [C02 EZUSB FX USB IO board](https://github.com/shizmob/arcade-docs/blob/main/konami/io.md#gec02-pwbaa)
+* Magnetic card readers connected to ezusb IO board
+
+### 1st gen PC-based with dedicated cabinet: 10th Style to DistorteD (13)
+
+* From here on, old cabinets that received the "Twinkle hardware" upgrade kit could always receive software only
+  upgrades
+* [CRT monitor](https://github.com/shizmob/arcade-docs/blob/main/konami/products.md#iidx-crt-monitor) with new dedicated
+  cabinets
+* [D01 EZUSB FX USB IO board](https://github.com/shizmob/arcade-docs/blob/main/konami/io.md#d01-io)
+* Slotted card readers starting version 13
+
+### 2nd gen PC: GOLD (14) to Lincle (19)
+
+* [FAB-e945-KN205](https://github.com/shizmob/arcade-docs/blob/main/konami/boards.md#fab-e945-kn205)
+* All prior cabinet configurations can be upgraded with a PCB and software upgrade
+* New LCD monitor starting version 15
+  * Further variants of the LCD monitor appear starting version 18
+* [IO2 EZUSB FX2 USB IO board](https://github.com/shizmob/arcade-docs/blob/main/konami/io.md#usbio2) introduced with
+  version 14
+* Switch to wave pass readers on version 19
+
+### 3rd gen PC: Tricoro (20) to Sinobuz (24)
+
+* All prior cabinet configurations can be upgraded with a PCB and software upgrade
+* [ADE-HM65](https://github.com/shizmob/arcade-docs/blob/main/konami/boards.md#hm65)
+* Game engine supports HD mode (720p)
+* Many new LCD monitor variants appear with every new version
+
+### 4th gen PC: CANNON BALLERS (25) to RESIDENT (30)
+
+* All prior cabinet configurations can be upgraded with a PCB and software upgrade
+* [ADE-6291](https://github.com/shizmob/arcade-docs/blob/main/konami/boards.md#ade-6291)
+* [BIO2 IO board](https://github.com/shizmob/arcade-docs/blob/main/konami/boards.md#hm65)
+  * Upgrade cabinets required the [BIO2 sub-IO board](https://github.com/shizmob/arcade-docs/blob/main/konami/io.md#bio2-ldj-sub-io)
+* Drop of SD mode support starting version 27
+* Supporting 120 hz monitors starting version 27
+* Many new LCD monitor variants appear with every new version
+  * 42" 120 hz for lightning cabinets starting version 27
+  * 42" 60 hz for non-lightning cabinets starting version 25
+
+### 5th gen PC: RESIDENT (30) to EPOLIS (31)
+
+* All prior cabinet configurations can be upgraded with a PCB and software upgrade
+* [C300-xonarae](https://github.com/shizmob/arcade-docs/blob/main/konami/boards.md#c300-xonarae)
+* Game engine supports FHD mode (1080p)
+
+## Threading model and core responsibilities in PC-based games
+
+Since the early days of 9th Style to today (as of time of writing this: EPOLIS), the threading model
+hasn't changed significantly:
+
+* Main and rendering thread
+  * Runs your typical D3D9 render loop
+    * Using D3D9ex starting version 27
+  * Starting and managing other threads
+  * Any file and game asset loading
+  * Handles all the core game logic of the different screens starting from the initial boot screen
+    to the core game-play screen
+* IO thread
+  * Polls the main IO hardware and synchronizes the in-memory input and output state with the
+    hardware
+  * Executes commands issued by the main thread to the IO board such as dongle or card reader
+    commands (ezusb generation of IO only)
+* Card reader thread (not applicable to versions 9 to 12)
+  * Runs the protocol to read/write the hardware of the readers
+  * Async execution of higher level commands issued by the main thread to the card reader hardware,
+    e.g. card read, card eject etc.
+* Audio thread
+  * Streaming of audio data to the sound API
+    * DirectSound for versions 9 to 26
+    * WASAPI for versions 27 to 30 for non-lighting cabinets with ADE-6291 hardware
+    * ASIO for versions 27 and newer for lighting cabinets
+    * ASIO for version 30/31 and newer for non-lighting cabinets with C300-xonarae hardware
+  * Async execution of higher level commands issued by the main thread to the audio backend, e.g.
+    play audio, stop audio, etc.
+* Network thread
+  * Network plumbing with the xrpc protocol
+  * Async execution of request-response commands issued by the main thread
+
+## Main and rendering thread
+
+With the game having transitioning to different screens throughout it's lifecycle, the main render
+loop might contain different logic such as asset loading. The following focuses on the main
+game-play screen, only. Common rendering logic still applies to other screens.
+
+This follows your typical D3D9 single threaded rendering loop which boils down to the following:
+
+* Begin the scene (`BeginScene`)
+* Set the render target (`SetRenderTarget`)
+* Clear the back buffer (`Clear`)
+* Run engine step. This includes and is mixed with
+  * IO input evaluation
+  * Game engine state and (re-) drawing the scene
+  * Commands to the audio playback, e.g. play key sounds
+  * Setting IO outputs
+* End the scene (`EndScene`)
+* Target a minimum frame time
+  * Introduced with version 11
+  * Sleep (`Sleep` or `SleepEx`) to fill up the frame up to either 13 ms or 14 ms (depending on the
+    version)
+  * This was likely introduced to not have the game run at hundreds of FPS if v-sync was disabled
+    (probably when running in window mode for development/testing purposes)
+* Swapping the back buffers (`Present`)
+  * D3D9 is configured with v-sync enabled by default and targets 60 hz
+  * With this configuration, the call to `Present` fills up the remaining frame time to target the
+    configured 60 hz refresh rate
+
+### Rendering resolutions
+
+The game engine went through a couple of different rendering resolutions:
+
+* 640x240: version 1 to 8 (all twinkle hardware)
+* 640x480: version 9 to 19 (1st and 2nd gen PC-based)
+* 1280x720 (HD mode) and 640x480 (SD mode): version 20 to 27 (3rd and 4th gen PC-based)
+* 1280x720 (HD mode) only for version 28 to 29 (4th gen PC-based)
+* 1280x720 (HD mode) and 1920x1080 (FHD mode) for version 30 (4th gen PC-based)
+* 1920x1080 (FHD mode) only for version 30+ (5th gen PC-based)
+
+## Core engine timing and synchronization
+
+The following outlines and explains the core engine concepts related to timing and synchronization.
+
+### The origins, twinkle hardware
+
+* It appears that the game has been on the same codebase since it's inception.
+* This can be reasoned by the following observations
+  * 9th style as the first PC-based game very buggy on initial release 
+  * 9th style threading model very clunky with various thread settings showing they tried to
+    prioritize different processing on a single core CPU 
+  * Coming from twinkle hardware that is a realtime system vs. a Windows XP system
+    * Fixed playstation 1 based hardware with a refresh rate of
+      [59.8260978565 hz](https://github.com/mamedev/mame/blob/bf9df04e005697788ae988ef5aea91a1878fd631/src/devices/video/psx.cpp#L435)
+    * No need to assume getting anything else if the resource budget per frame is not exceeded
+    * All sub-systems were driven synchronously to that fixed time step
+    * No need for the engine to synchronize audio during the song. When the song is started
+      correctly, it stayed sync throughout the song
+* Observations and assumptions
+  * It appears the developers struggled a lot with the significant platform shift to PC as indicated
+    by various core engine improvements throughout the years still
+  * Switches of hardware generations further complicated the situation as these forced them to further
+    drift away from how the game engine was initially designed on the twinkle system
+
+### Frame time/timing and engine step
+
+* The game's engine step and timing is frame based
+* The main render loop defines the minimum valid timing window for the game engine to be able to
+  evaluate
+  * 60 hz/fps = 16.667 ms (rounded to three decimal places)
+  * 120 hz/fps = 8.333 ms (rounded to three decimal places), only relevant for lightning cabinets with their 120 hz
+    screen/mode
+* Depending on the GPU hardware and configuration, the GPU might drive the screen not exactly at
+  perfectly 60 hz/fps = 16.667 ms
+* As outlined in the [main render loop](#main-and-rendering-thread), the `Present` call is the
+  key function call to determine the frame time for the game engine
+* Just having v-sync enabled and telling D3D9 to **target** 60 hz, it still depends on how the GPU
+  driver is implemented and how the GPU driver's implementation of D3D9 executes on the `Present`
+  call
+* This is primarily determined by how the GPU driver is operating and driving connected display
+  hardware
+* The following factors can contribute to that either directly or indirectly
+  * Different monitor types analog vs. digital (CRT vs. LCD)
+  * Different monitor connections VGA vs. DVI/HDMI/DP
+  * Different GPU drivers
+  * Different GPU hardware and vendors
+  * Different GPU settings
+
+### Monitor check screen
+
+The monitor check screen was introduced with version 14. This was a solution to the problem of not
+guaranteeing a single fixed refresh rate throughout different GPU and monitor combinations. See
+a detailed explanation in the previous sub-subsection about
+[what influences the frame time](#frame-timetiming-and-engine-step) of the game.
+
+The goal of the monitor check is to measure the frame time of the main render loop and use the
+results for [driving the core engine step](#engine-step-and-synchronization).
+
+The monitor check evolved slightly as different GPU and monitor hardware, and GPU drivers yielded
+varying refresh rates that determined the frame times of the main game loop.
+
+Actual values are outlined further down in the [engine step time](#engine-step-time) section.
+
+There are two main versions of the monitor check, all of them have always been part of the boot
+process:
+
+* 14
+  * Measures a total of 3000 frames
+  * If total time this took < 50004 ms -> so average of 16.668 ms per frame =  59.9952 hz
+    * S-Video mode -> 59.95 hz (also shows S-VIDEO when the monitor check completes)
+    * Otherwise VGA mode -> 60.05 hz
+  * If VGA is determined, the game patches the chart event data when loading
+    * `event_timestamp * 0.99817199 + 0.40000001` 
+  * When S-Video no charts are patched and the timing data in the chart is used as is
+* 15 to 18
+  * Identical to 14 except that chart patching now happens in milliseconds instead of frames
+  * VGA mode: `16.65279`
+  * S-Video mode: `16.680567`
+  * `event_timestamp * (1.0 / frame_time) + 0.40000001)`
+* 19
+  * Identical to previous version
+  * Monitor check screen shows current FPS on the last revision of that version. However, it doesn't
+    use the value shown there by any means. Assuming this was added before the introduction of the
+    new monitor check on 20.
+* 20 to 26
+  * Runs on boot or when switching monitor modes SD vs. HD 
+  * Measures only 1200 frames
+  * Takes the average refresh rate of 1200 frames
+  * Applies the measured avg. frame time directly to the charts before song
+* 27 to 30 
+  * Frame rate measuring identical to prior versions
+  * Added additional logic after the frame time measurements for handling of 120 hz displays 
+  * Includes checking the monitor and if the framerate matches as expected
+* 30/31 LDJ-010 upgrade
+  * Added NvDisplayConfigLDJ tool which runs on system start and configures a custom timing in the
+    NVIDIA GPU driver to ensure a fixed monitor refresh rate
+* 31
+  * Same code as before
+  * Consider the first 460 frames of the measurement as warm-up frames
+  * Discard these for the actual measurement to get more stable frame times
+  * Use a base avg. value of 119.982 for the 120 hz monitors and 59.9 for 60 hz monitors. Further
+    frames measured are counted towards the average with the given base value
+
+### Engine core game-play with visual and audio synchronization
+
+#### Chart data
+
+* Chart data encodes note timing and timing window information
+* Chart data consists of *note events* encoding a timestamp and note information such as type
+  and key-sound information
+* Timing windows are defined per chart
+* Most infamous example: GAMBOL (7Key/Another)
+* Game engine timestamp evaluation and note event timestamp encoding
+  * 9 to 14: Refresh rate in hz
+  * 15 to 31: Milliseconds (equivalent to assuming 1000 fps)
+* Fundamentally, that doesn't change game play experience as it's just a different way of
+  evaluating the timestamps since refresh rate in hz/frame rate in fps can be converted lossless to
+  frame time in ms
+
+#### Engine step time
+
+The engine uses the following source for frame rate/time to drive internal logic on the following
+versions
+
+* 9 to 13: Hardcoded 59.95 hz
+* 14: Either 59.95 hz or 60.05 hz determined by which value is determined to be closer to the
+  measured one during the monitor check screen on startup
+* 15 to 19: 59.95 hz or 60.05 hz
+  * Monitor check on startup measures the frame time and picks the value closest to what's been
+    measured
+  * Monitor check result can be overridden with the *Output Type* setting in the operator menu
+    * *S-Video* to force to 59.95 hz
+    * *VGA* to force to 60.05 hz
+* 20 to 31: Monitor check on boot determines the frame time and uses the result throughout the
+  entire game session
+
+#### Engine step and synchronization
+
+Per frame engine step advancing and synchronization during game-play
+
+* Game-play needs synchronization of the following aspects
+  * Drawn content on the screen
+  * Background audio playback track
+  * Key sound effects
+* The game engine synchronizes these only at the start of a song
+  * It takes known/determined refresh rate/frame time as the fixed time for every frame cycle
+    throughout the entire song
+  * It starts playback of the background audio track together with playback of the chart data
+  * With every engine step/frame it advances internal calculations by that fixed amount of time.
+    Thus, the game engine expects this to be constant/stable throughout an entire song
+  * The chart data is advanced every frame by the engine
+  * Key sound events are turned into audio playback on command as the chart advances
+  * No re-synchronization or check-pointing between main rendering thread and audio is happening
+    throughout the song
+* Remark: The above does not consider any kind of offsetting and timing adjustments for the sake
+  of keeping this simple and focus on the absolute core concepts 

doc/dev/logging-breakdown-avs.md

@@ -1,76 +0,0 @@
-Copy/pasted from chat with tau (2018/02/10):
-
-alright then. so for modern iidx.
-
-we want to do logging inside iidxhook and we also want to pass AVS-style log functions to iidxio which in turn passes them on to geninput in order for those to do logging too
-
-so iidxhook connects to the AVS log API: log_body_misc and friends, which I assume are invoked using a log_misc() macro in Konami's source code that adds some sort of module tag.
-
-anyway yeah this we already know.
-
-libutil has four function ptrs: log_impl_misc and co. These are static variables which are statically initialized to some no-op functions. Except log_impl_fatal, whose implementation just calls libc abort()
-
-at startup you call log_to_external(), supplying four function ptrs to wire these up to. As the name suggests, this causes Bemanitools libutil to talk to something that is compatible with the AVS log sink API.
-
-alternatively you can log_to_writer(), which initializes Bemanitools to use its own, internal logging system, and you give it a log writer function that takes strings and writes them somewhere.
-
-So you have log sinks and you have log writers. The path is [application code] -> [log sink] -> [logging engine] -> [log writer]
-19:29
-
-inside config.exe (or generally outside of modern AVS games) this path looks like [bemanitools application code] -> [log sinks passed across dlls] -> [bemanitools logging engine] -> [bemanitools log writer]
-
-inside modern AVS game the path looks like [bt hook dll / bt iodev dll] -> [avs log_body_whatever log sinks] -> [avs logging engine] -> [launcher.exe log writer]
-
-note that I tried to keep the log writer API consistent with the AVS log writer API but then Konami went and broke it repeatedly so now Bemanitools has its own stable log writer API. Launcher tracks the AVS log writer API, which breaks constantly, so that's not the same thing.
-
-anyway that's the background story. Now for the details about IIDX in particular.
-
-up until about iidx19 we did things the obvious way: iidxhook would log_to_external() to hook into the AVS log sinks and then call those directly and all was well. Then one fine day I was given a IIDX19 data dump and tried running iidxhook and it crashed with a stack overflow. hmm.
-
-the problem boils down to this: iidx19 AVS added those log timestamps. And for for whatever reason the AVS logging engine needs to access some mutexes and condition variables to make this work properly
-
-but AVS of course in grand Konami tradition has its own threading and concurrency primitive API which wraps the Win32 API. tbf this is kind of understandable in some sense, because win32 actually did not have condition variables until Windows Vista! in 2006! seriously, I'm not kidding.
-
-there's all sorts of articles out there describing in fine detail how to use Win32's event objects to implement your own condition variables and the multitudinous pitfalls that this entails
-
-but anyway one fun thing about the AVS concurrency API is that you can't actually use concurrency primitives unless you're calling that API from a thread launched using the AVS threading API
-
-and that's a problem in the case of iidxhook, because iidx is old as balls relatively speaking and its EZUSB driver code has I think two worker threads, which it launches using the MS libc's _beginthreadex() function
-
-this in turn is a wrapper around the win32 CreateThread function, but it also boots up stdio on whatever new thread gets launched and basically is responsible for guaranteeing that the libc will operate correctly on the newly launched thread
-
-so yeah when you do windows programming, never call CreateThread, always call _beginthreadex. otherwise stuff will break. maybe.
-
-point is, IIDX predates modern AVS so it just uses Windows threading directly. So, IIDX worker thread starts up, iidxhook does its thing, writes a log message, calls into AVS logging, which in turn grabs an AVS mutex, the implementation of which says "omg this isn't an AVS thread aaaaaa" and ... attempts to call back into the logging system to log this fact. whereupon a stack overflow condition proceeds in a predictable manner.
-
-so, there are a few ways to deal with this problem. bemanitools 4 dealt with it in a fairly stupid way.
-
-and very elaborate way too
-
-bt4 intercepted IIDX's calls to create Windows threads and then redirected those calls to go via the AVS threading API
-
-so now the worker threads are AVS threads and logging works as expected
-
-which is all well and good but the problem is that these threads are quite timing critical. it probably worked fine, but i didn't want to risk affecting those threads in a weird way and introducing latency and jitter. i wanted to keep the threading pristine and not mess with it just for the sake of diagnostic messages
-
-so bemanitools 5 uses the log server approach
-
-at an appropriate time, it creates its own AVS thread, the logging server. Since it is an AVS thread, it can call the AVS logging API
-
-and then we have log_post_misc() and friends, implemented in log-server.c
-
-we initialize the Bemanitools logging system to log "externally" to those funcs and we also propagate those to iidxio.dll and eamio.dll which in turn pass them to geninput.dll
-
-so what do log_post_misc and friends do
-
-they lock a "mailbox" using the win32 concurrency primitives and write the log severity and a pointer to the string to be logged into the mailbox, then signal the log server thread, again using win32 concurrency primitives
-
-then they do a synchronous wait for an acknowledgement from the logging server: since we're holding a string pointer, we cannot return until that string pointer has been consumed or it may be concurrently invalidated
-
-so the log server wakes up, locks the mailbox, calls AVS log_body_misc() to write the log message, then once that returns it asserts a signal in the mailbox (again, win32 event object because lol what are condition variables) and releases the lock.
-
-the caller gets the signal, wakes up, and returns to whatever Bemanitools code is running on the IIDX IO worker thread that wanted to write a log message.
-
-end of essay.
-
-

doc/development.md

@@ -1,64 +1,83 @@
 # Development
-This document is intended for developers interested in contributing to Bemanitools. Please read this document before
-you start developing.
+
+This document is intended for developers interested in contributing to Bemanitools. Please read this
+document before you start developing.
 
 ## Goals
-We want you to understand what this project is about and its goals. The following list serves as a guidance for all
-developers to identify valuable contributions for this project. As the project evolves, these gaols might do as well.
 
-* Allow running Konami arcade rhythm games, i.e. games of the Bemani series, on arbitrary hardware.
-    * Emulate required software and hardware features.
-    * Provide means to cope with incompatibility issues resulting from using a different software platform (e.g. version
-    of Windows). 
-* Provide an API for custom interfaces and configuring fundamental application features.
+We want you to understand what this project is about and its goals. The following list serves as a
+guidance for all developers to identify valuable contributions for this project. As the project
+evolves, these gaols might do as well.
+
+- Allow running Konami arcade rhythm games, i.e. games of the Bemani series, on arbitrary hardware.
+  - Emulate required software and hardware features.
+  - Provide means to cope with incompatibility issues resulting from using a different software
+    platform (e.g. version of Windows).
+- Provide an API for custom interfaces and configuring fundamental application features.
 
 ## Development environment
+
 The following tooling is required in order to build this project.
 
 ### Tooling
+
 #### Linux / MacOSX
-* git
-* make
-* mingw-w64
-* clang-format
-* wine (optional, for running tests or some quick testing without requiring a VM)
+
+- git
+- make
+- mingw-w64
+- clang-format
+- wine (optional, for running tests or some quick testing without requiring a VM)
 
 On MacOSX, you can use homebrew or macports to install these packages.
 
 #### Windows
+
 TODO
 
 ### IDE
-Ultimately, you are free to use whatever you feel comfortable with for development. The following is our preferred
-development environment which we run on a Linux distribution of our choice:
-* Visual Studio Code with the following extensions
-    * C/C++
-    * C++ Intellisense
-    * Clang-Format
+
+Ultimately, you are free to use whatever you feel comfortable with for development. The following is
+our preferred development environment which we run on a Linux distribution of our choice:
+
+- Visual Studio Code with the following extensions
+  - C/C++
+  - C++ Intellisense
+  - Clang-Format
 
 ### Further tools for testing and debugging
-* Debugger: Can be part of your reverse engineering IDE of your choice or stand-along like
-[OllyDbg](http://www.ollydbg.de/).
-* [apitrace](https://apitrace.github.io/): Trace render calls to graphics APIs like D3D and OpenGL.
-This tool allows you to record and re-play render calls of an application with frame-by-frame 
-debugging. Very useful to analyze the render pipeline or debug graphicial glitches.
+
+- Debugger: Can be part of your reverse engineering IDE of your choice or stand-along like
+  [OllyDbg](http://www.ollydbg.de/).
+- [apitrace](https://apitrace.github.io/): Trace render calls to graphics APIs like D3D and OpenGL.
+  This tool allows you to record and re-play render calls of an application with frame-by-frame
+  debugging. Very useful to analyze the render pipeline or debug graphicial glitches.
 
 ## Building
+
 Simply run make in the root folder:
+
 ```
 make
 ```
 
 All output is located in the *build* folder including the final *bemanitools.zip* package.
 
+Note about using `-j n` option on make: This is currently considered broken/unreliable. Expect to
+run into odd issues like randomly changing unresolved dependency errors. If you attempted this, run
+a `make clean` before running `make` again.
+
 ### Release building
-A release build is a clean build including code formatting and testing. This can be executed by running the following
-command:
+
+A release build is a clean build including code formatting and testing. This can be executed by
+running the following command:
+
 ```
 make release
 ```
 
 ## Building with docker
+
 You can also build bemanitools using docker which avoids having to setup a full development
 environment if you are just interested in building binaries for the latest changes. Naturally, this
 requires you to have the docker daemon installed. Then, run the following command from the root
@@ -71,28 +90,35 @@ make build-docker
 Once completed successfully, the build output is located in the `build/docker` sub-folder.
 
 ## Creating releases
+
 For developers to create official releases with major and minor versioning:
+
 1. Ensure that all everything you want to have for this release is merged into master.
 1. Create a [changelog](CHANGELOG.md) based on aggregating and summerizing commit messages of
-whatever got added starting from the tag of the current version to the current head of master.
-Commit that changelog and push to master.
+   whatever got added starting from the tag of the current version to the current head of master.
+   Commit that changelog and push to master.
 1. Create a tag with the next version number, e.g. for 5.28:
+
 ```bash
 git tag v5.28
 ```
+
 1. Push the tag upstream:
+
 ```bash
 git push origin v5.28
 ```
+
 1. Wait for the CI pipeline to finish building the release and check if everything's ok.
 1. On GitLab, go to "Tags" in the repository, click on the commit ID below the tag in the list you
-just created.
+   just created.
 1. Click on the "Pipelines" tab and click on the download button on the right and on "Download
-release artifacts".
-1. Rename the downloaded zip to "bemanitools-v5.28.zip" and the replace v5.28 with the version
-you want to release.
+   release artifacts".
+1. Rename the downloaded zip to "bemanitools-v5.28.zip" and the replace v5.28 with the version you
+   want to release.
 1. Upload the release.
 1. For publishing the release, create a post with the following contents:
+
 ```
 v5.28
 <insert link to uploaded zip here>
@@ -104,53 +130,66 @@ Changelog copy-paste:
 ```
 
 ## Code formatting
+
 To apply our code style using clang-format, simply run the following command:
+
 ```
 make code-format
 ```
 
-Please also refer to the [section about](###Additional-code-style-guidelines) which cannot be covered using
-clang-format.
+Please also refer to the [section about](###Additional-code-style-guidelines) which cannot be
+covered using clang-format.
 
 ## Testing
-This still needs to be improved/implemented properly to run the unit-tests easily. Currently, you have to be on either
-a Linux/MacOSX system and run
+
+This still needs to be improved/implemented properly to run the unit-tests easily. Currently, you
+have to be on either a Linux/MacOSX system and run
+
 ```
 make run-tests
 ```
-This executes all currently available unit-tests and reports to the terminal any errors. This requires wine to be
-installed.
+
+This executes all currently available unit-tests and reports to the terminal any errors. This
+requires wine to be installed.
 
 ## Project structure
+
 Now that your setup is ready to go, here is brief big picture of what you find in this project.
 
-* build: This folder will be generated once you have run the build process.
-* dist: Distribution related files such as (default) configuration files, shell scripts, etc.
-* doc: Documentation for the tools and hooks as well as some development related docs.
-* src: The source code
-    * imports: Provides headers and import definitions for AVS libs and a few other dependencies.
-    * main: The main source code with game specific hook libraries, hardware emulation and application fixes.
-    * test: Unit tests for modules that are not required for hooking or the presence of a piece of hardware.
-* .clang-format: Code style for clang-format.
-* GNUmakefile: Our makefile to build this project.
-* Module.mk: Defines the various libraries and exe files to build for the distribution packages.
+- build: This folder will be generated once you have run the build process.
+- dist: Distribution related files such as (default) configuration files, shell scripts, etc.
+- doc: Documentation for the tools and hooks as well as some development related docs.
+- src: The source code
+  - imports: Provides headers and import definitions for AVS libs and a few other dependencies.
+  - main: The main source code with game specific hook libraries, hardware emulation and application
+    fixes.
+  - test: Unit tests for modules that are not required for hooking or the presence of a piece of
+    hardware.
+- .clang-format: Code style for clang-format.
+- GNUmakefile: Our makefile to build this project.
+- Module.mk: Defines the various libraries and exe files to build for the distribution packages.
 
 ## Code style and guidelines
-Please follow these guidelines to keep a consistent style for the code base. Furthermore, we provide some best practices
-that have shown to be helpful. Please read them and reach out to us if you have any concerns or valuable
-additions/changes.
+
+Please follow these guidelines to keep a consistent style for the code base. Furthermore, we provide
+some best practices that have shown to be helpful. Please read them and reach out to us if you have
+any concerns or valuable additions/changes.
 
 ### Clang-format
-The style we agreed on is provided as a clang-format file. Therefore, we use clang-format for autoformatting our code.
 
-You can use clang-format from your terminal but when using Visual Studio Code, just install the extension. Apply
-formatting manually at the end or enable the "reformat on save" feature.
+The style we agreed on is provided as a clang-format file. Therefore, we use clang-format for
+autoformatting our code.
 
-However, clang-format cannot provide guidance to cover all our style rules. Therefore, we ask you to stick to the 
-"additional" guidelines in the following sections.
+You can use clang-format from your terminal but when using Visual Studio Code, just install the
+extension. Apply formatting manually at the end or enable the "reformat on save" feature.
+
+However, clang-format cannot provide guidance to cover all our style rules. Therefore, we ask you to
+stick to the "additional" guidelines in the following sections.
 
 ### Additional code style guidelines
+
 #### No trailing comments
+
 ```
 // NOPE
 int var = 1; // this is a variable
@@ -161,11 +200,13 @@ int var = 1;
 ```
 
 #### Comment style
-* Use either // or /* ... */ for single line.
-* Use /* ... */ for multiline comments.
-* Use /* ... */ for documentation.
+
+- Use either // or /\* ... \*/ for single line.
+- Use /\* ... \*/ for multiline comments.
+- Use /\* ... \*/ for documentation.
 
 Examples:
+
 ```
 // single line comment
 int var = 1;
@@ -184,9 +225,12 @@ int func(int a, int b);
 ```
 
 #### Include guards
-Provide include guards for every header file. The naming follows the namespacing of the module and the module name.
+
+Provide include guards for every header file. The naming follows the namespacing of the module and
+the module name.
 
 Example for bsthook/acio.h file:
+
 ```
 #ifndef BSTHOOK_ACIO_H
 #define BSTHOOK_ACIO_H
@@ -197,11 +241,13 @@ Example for bsthook/acio.h file:
 ```
 
 #### Empty line before and after control blocks
+
 Control blocks include: if, if-else, for, while, do-while, switch
 
 Makes the code more readible with control blocks being easily visible.
 
 Example
+
 ```
 int var = 1;
 
@@ -213,7 +259,10 @@ printf("%d\n", var);
 ```
 
 #### Empty line at the start of blocks
-There are situations when you want to have an empty line at the start of the block to enhance readability, for example:
+
+There are situations when you want to have an empty line at the start of the block to enhance
+readability, for example:
+
 ```
 if (a && 
     b && 
@@ -223,6 +272,7 @@ if (a &&
 ```
 
 Here the assignment aligns with the conditions of the if-black making it hard to read. Better:
+
 ```
 if (a && 
     b && 
@@ -233,20 +283,22 @@ if (a &&
 ```
 
 #### Includes
-* Always keep all includes at the top of a header and source file. Exception: Documentation before include guards on
-header file.
-* Use *< >* for system-based includes, e.g. <stdio.h>.
-* Use *" "* for project-based includes, e.g. "util/log.h".
-* For project-based includes, always use the full path relative to the root folder (src/main, src/test), e.g. 
-"util/log.h" and not "log.h" when being in another module in the "util" namespace.
-* Sorting
-    * System-based includes before project-based includes
-    * Block group them by different namespaces
-    * Lex sort block groups
-    * Because windows header files are a mess, the sorting on system-based includes is not always applicable. Please add
-    a comment when applicable and apply the necessary order.
+
+- Always keep all includes at the top of a header and source file. Exception: Documentation before
+  include guards on header file.
+- Use *\< >* for system-based includes, e.g. \<stdio.h>.
+- Use *" "* for project-based includes, e.g. "util/log.h".
+- For project-based includes, always use the full path relative to the root folder (src/main,
+  src/test), e.g. "util/log.h" and not "log.h" when being in another module in the "util" namespace.
+- Sorting
+  - System-based includes before project-based includes
+  - Block group them by different namespaces
+  - Lex sort block groups
+  - Because windows header files are a mess, the sorting on system-based includes is not always
+    applicable. Please add a comment when applicable and apply the necessary order.
 
 Example for sorting
+
 ```
 #include <stdio.h>
 #include <string.h>
@@ -260,25 +312,30 @@ Example for sorting
 ```
 
 ### Documentation
-In general, add comments where required to explain a certain piece of code. If is not self-explanatory about:
-* Why is it implemented like this
-* Very important details to understand how and why it is working that only you know
-* A complex algorithm/logic
 
-Make sure to add some comments or even an extended document. Avoid comments that explain trivial and obvious things
-like "enable feature X" before an if-block with a feature switch.
+In general, add comments where required to explain a certain piece of code. If is not
+self-explanatory about:
 
-Especially if it comes to reverse-engineering efforts, comments or even a separate document is crucial to allow others
-to understand the depths you dived into.
+- Why is it implemented like this
+- Very important details to understand how and why it is working that only you know
+- A complex algorithm/logic
 
-Any extended notes about documentation some hardware, protocol, reverse-engineering a feature etc. can be stored in
-the *doc/dev* folder and stay with the repository. Make good use of that!
+Make sure to add some comments or even an extended document. Avoid comments that explain trivial and
+obvious things like "enable feature X" before an if-block with a feature switch.
+
+Especially if it comes to reverse-engineering efforts, comments or even a separate document is
+crucial to allow others to understand the depths you dived into.
+
+Any extended notes about documentation some hardware, protocol, reverse-engineering a feature etc.
+can be stored in the *doc/dev* folder and stay with the repository. Make good use of that!
 
 #### Header files
-Document any enum, struct or function exposed by a header file. Documentation of static functions or variables in
-source modules is not required. Also provide documentation for the module.
+
+Document any enum, struct or function exposed by a header file. Documentation of static functions or
+variables in source modules is not required. Also provide documentation for the module.
 
 Example for my-namespace/my-module.h
+
 ```
 /**
  * Some example module to show you where documentation is expected.
@@ -319,22 +376,28 @@ int my_namespace_my_module_func(int a, int b);
 ```
 
 ### Naming conventions
-In general, try to keep names short but don't overdo it by using abbrevations of things you created. Sometimes this is
-not possible and we accept exceptions if there are no proper alternatives.
+
+In general, try to keep names short but don't overdo it by using abbrevations of things you created.
+Sometimes this is not possible and we accept exceptions if there are no proper alternatives.
 
 #### Namespacing
+
 The folder names use lower-case names with dashes *-* as seperators, e.g. *my-namespace*.
 
 #### Modules
-Header and source files of modules use lower-case names with dashes *-* as seperators, e.g. *my-module.c*, *my-module.h.
 
-The include guards contain the name of the namespace and module, see [here](#### Include guards).
+Header and source files of modules use lower-case names with dashes *-* as seperators, e.g.
+*my-module.c*, \*my-module.h.
+
+The include guards contain the name of the namespace and module, see \[here\](#### Include guards).
 
 Variables, functions, structs, enums and macros are namespace accordingly.
 
 #### Variables
-Snake-case with proper namespacing to namespace and module. Namespacing applies to static and global variables. Local
-variables are not namespaced.
+
+Snake-case with proper namespacing to namespace and module. Namespacing applies to static and global
+variables. Local variables are not namespaced.
+
 ```
 // For namespace "ezusb", module "device", static variable in module
 static HANDLE ezusb_device_handle;
@@ -344,7 +407,10 @@ int buffer_size = 256;
 ```
 
 #### Functions
-Snake-case with proper namespacing to namespace and module for all functions that are not hook functions.
+
+Snake-case with proper namespacing to namespace and module for all functions that are not hook
+functions.
+
 ```
 // For namespace "ezusb", module "device", static variable in module, init function
 void ezusb_device_init(...);
@@ -357,7 +423,9 @@ HANDLE my_CreateFileA(...)
 ```
 
 #### Structs
+
 Snake-case with proper namespacing to namespace and module.
+
 ```
 // For namespace "ezusb", module "device" ctx struct
 struct ezusb_device_ctx {
@@ -366,7 +434,9 @@ struct ezusb_device_ctx {
 ```
 
 #### Enums
+
 Snake-case with proper namespacing to namespace and module. Upper-case for enum entries
+
 ```
 // For namespace "ezusb", module "device" state enum
 struct EZUSB_DEVICE_STATE {
@@ -377,14 +447,18 @@ struct EZUSB_DEVICE_STATE {
 ```
 
 #### Macros
+
 Upper-case with underscore as spacing, proper namespacing to namespace and module.
+
 ```
 // For namespace "ezusb", module "device" vid
 #define EZUSB_DEVICE_VID 0xFFFF
 ```
 
 #### Multiple variable declarations
+
 Only one declaration per line which also avoids various errors, for example:
+
 ```
 // Nope
 char a, b, b;
@@ -398,25 +472,31 @@ char c;
 ```
 
 ### Testing
-We advice you to write unit tests for all modules that allow proper unit testing. This applies to modules that are not
-part of the actual hooking process and do not rely on external devices to be available. Add these tests to the
-*src/test* sub-folder.
 
-This does not only speed up your own development but hardens the code base and avoids having to test these things by
-running the real applications, hence saving a lot of time and trouble.
+We advice you to write unit tests for all modules that allow proper unit testing. This applies to
+modules that are not part of the actual hooking process and do not rely on external devices to be
+available. Add these tests to the *src/test* sub-folder.
+
+This does not only speed up your own development but hardens the code base and avoids having to test
+these things by running the real applications, hence saving a lot of time and trouble.
 
 ### Further best practices
-* Avoid external dependencies like additional libraries. Bemanitools is extremely self-contained which enables high
-portability and control which is important for implementing various "hacks" to just make things work.
-* If you see some module/function lacking documentation that you have to use/understand, add documentation once you
-figured out what the function/module is doing. This does not only help your future you but others reading the code.
-* Keep documentation and readme files up-to-date. When introducing changes/adding new features, review existing
-documentation and apply necessary changes.
+
+- Avoid external dependencies like additional libraries. Bemanitools is extremely self-contained
+  which enables high portability and control which is important for implementing various "hacks" to
+  just make things work.
+- If you see some module/function lacking documentation that you have to use/understand, add
+  documentation once you figured out what the function/module is doing. This does not only help your
+  future you but others reading the code.
+- Keep documentation and readme files up-to-date. When introducing changes/adding new features,
+  review existing documentation and apply necessary changes.
 
 ## Misc
-The core API interception code was ripped out, cleaned up a tiny bit and released on GitHub. BT5 will eventually be
-ported to use this external library in order to avoid maintaining the same code in two places at once.
+
+The core API interception code was ripped out, cleaned up a tiny bit and released on GitHub. BT5
+will eventually be ported to use this external library in order to avoid maintaining the same code
+in two places at once.
 
 https://github.com/decafcode/capnhook
 
-This too is a little rudimentary; it doesn't come with any examples or even a README yet. 
+This too is a little rudimentary; it doesn't come with any examples or even a README yet.

doc/game-error-codes.md

@@ -27,9 +27,9 @@ N/A
 
 #### How to fix
 
-* Make sure your data is not set to read only, especially the dev folder.
-* Disable all network adapters other than the one used to connect to the Internet.
-* Check for hidden network adapters in Device Manager.
+- Make sure your data is not set to read only, especially the dev folder.
+- Disable all network adapters other than the one used to connect to the Internet.
+- Check for hidden network adapters in Device Manager.
 
 ## 5-1500 series errors
 
@@ -41,7 +41,7 @@ IO ERROR
 
 #### Known occurances
 
-* Pop'n Music 15
+- Pop'n Music 15
 
 #### How to fix
 
@@ -59,8 +59,8 @@ N/A
 
 #### How to fix
 
-* Check the integrity of the data you have, i.e. some files might be corrupted
-* Check your physical drive. Is it failing?
+- Check the integrity of the data you have, i.e. some files might be corrupted
+- Check your physical drive. Is it failing?
 
 ## 5-1501 series errors
 
@@ -76,9 +76,9 @@ N/A
 
 #### How to fix
 
-* Recopy Bemanitools.
-* For Reflec Beat, make sure you are not missing device.dll. (This seems to apply to some older
-version of bemanitools)
+- Recopy Bemanitools.
+- For Reflec Beat, make sure you are not missing device.dll. (This seems to apply to some older
+  version of bemanitools)
 
 ## 5-1502 series errors
 
@@ -90,13 +90,13 @@ BACKUP CHECK ERROR
 
 #### Known occurances
 
-* Pop'n'Music 21 Sunny Park
+- Pop'n'Music 21 Sunny Park
 
 #### How to fix
 
-* Give access to gamestart.bat and launcher.exe from Windows Firewall if enabled.
-* Make sure no antivirus software firewall is blocking access to those files.
-* Start gamestart.bat as Administrator.
+- Give access to gamestart.bat and launcher.exe from Windows Firewall if enabled.
+- Make sure no antivirus software firewall is blocking access to those files.
+- Start gamestart.bat as Administrator.
 
 ### 5-1502-0000
 
@@ -110,7 +110,7 @@ N/A
 
 #### How to fix
 
-* Make sure `/dev/` isn't read-only.
+- Make sure `/dev/` isn't read-only.
 
 ### 5-1502-0002
 
@@ -120,7 +120,7 @@ HDD READ ERROR
 
 #### Known occurances
 
-* GFDM V4
+- GFDM V4
 
 #### How to fix
 
@@ -132,7 +132,7 @@ Unknown
 
 #### Description
 
-USB I/O ERROR 
+USB I/O ERROR
 
 ##### FPGA WRITE ERROR
 
@@ -146,22 +146,22 @@ timeouts making this code prone to fail.
 
 #### Known occurances
 
-* IIDX
+- IIDX
 
 #### How to fix
 
 #### FPGA WRITE ERROR
 
-* Restart the game
-* Re-copy bemanitools
+- Restart the game
+- Re-copy bemanitools
 
 #### FW TRNS-OUT
 
-* Restart the game
-* Re-copy bemanitools
-* Running the process on high priority and with admin rights
-* If you attached a debugger, that might have messed with the timing and caused this. Try a
-different debugger or attach it later in the boot process
+- Restart the game
+- Re-copy bemanitools
+- Running the process on high priority and with admin rights
+- If you attached a debugger, that might have messed with the timing and caused this. Try a
+  different debugger or attach it later in the boot process
 
 ### 5-1503-0001
 
@@ -179,10 +179,10 @@ N/A
 
 #### How to fix
 
-* Check the integrity of the data you have, i.e. some files might be corrupted
-* If the data came in an archive format, try extracting it again with another application.
-* Make sure your game is up to date with the current data available.
-* Check your physical drive. Is it failing?
+- Check the integrity of the data you have, i.e. some files might be corrupted
+- If the data came in an archive format, try extracting it again with another application.
+- Make sure your game is up to date with the current data available.
+- Check your physical drive. Is it failing?
 
 ### 5-1503-0004
 
@@ -202,13 +202,13 @@ N/A
 
 Real hardware:
 
-* Check the USB cable between the PC and the IO board is okay.
-* Make sure the IO board is getting enough of a clean supply of power.
+- Check the USB cable between the PC and the IO board is okay.
+- Make sure the IO board is getting enough of a clean supply of power.
 
 Bemanitools:
 
-* Don't attempt to put your computer to sleep while playing rhythm games.
-* Change launcher.exe process priority to High when starting the game.
+- Don't attempt to put your computer to sleep while playing rhythm games.
+- Change launcher.exe process priority to High when starting the game.
 
 ### 5-1503-0006
 
@@ -222,7 +222,7 @@ N/A
 
 #### How do I fix it?
 
-* Recopy Bemanitools.
+- Recopy Bemanitools.
 
 ### 5-1503-0007
 
@@ -236,7 +236,7 @@ N/A
 
 #### How do I fix it?
 
-* Run the game using gamestart.bat, don't just drag and drop the game dll onto launcher.exe
+- Run the game using gamestart.bat, don't just drag and drop the game dll onto launcher.exe
 
 ### 5-1503-0008
 
@@ -246,7 +246,7 @@ FPGA Write error
 
 #### Known occurances
 
-* IIDX Tricoro
+- IIDX Tricoro
 
 Seen in Tricoro Omnimix RC1.
 
@@ -266,7 +266,7 @@ N/A
 
 #### How do I fix it?
 
-* Make sure your AC(real)IO board is on the correct COM port.
+- Make sure your AC(real)IO board is on the correct COM port.
 
 ## 5-1504 series errors
 
@@ -286,8 +286,8 @@ N/A
 
 Real hardware:
 
-* Make sure your readers are connected and powered on.
-* Check your serial cables are good.
+- Make sure your readers are connected and powered on.
+- Check your serial cables are good.
 
 ### 5-1504-0003
 
@@ -330,13 +330,13 @@ the game may take 1-3 minutes longer to boot as it regenerates backup data.
 
 #### Known occurances
 
-* Jubeat Ripples
+- Jubeat Ripples
 
 #### How do I fix it?
 
-* Check the integrity of the data you have, i.e. some files might be corrupted
-* If the data came in an archive format, try extracting it again with another application.
-* Check your physical drive. Is it failing?
+- Check the integrity of the data you have, i.e. some files might be corrupted
+- If the data came in an archive format, try extracting it again with another application.
+- Check your physical drive. Is it failing?
 
 ### 5-1505-0001
 
@@ -350,9 +350,9 @@ N/A
 
 #### How do I fix it?
 
-* Check the integrity of the data you have, i.e. some files might be corrupted
-* If the data came in an archive format, try extracting it again with another application.
-* Check your physical drive. Is it failing?
+- Check the integrity of the data you have, i.e. some files might be corrupted
+- If the data came in an archive format, try extracting it again with another application.
+- Check your physical drive. Is it failing?
 
 ### 5-1505-0002
 
@@ -371,9 +371,9 @@ N/A
 
 ##### Real hardware
 
-* There may be a coin stuck, check.
-* The coin mechanism may be stuck, check.
-* Don't hold down the coin line so long.
+- There may be a coin stuck, check.
+- The coin mechanism may be stuck, check.
+- Don't hold down the coin line so long.
 
 ### 5-1505-0006
 
@@ -387,9 +387,9 @@ N/A
 
 #### How do I fix it?
 
-* Check the integrity of the data you have, i.e. some files might be corrupted
-* If the data came in an archive format, try extracting it again with another application.
-* Check your physical drive. Is it failing?
+- Check the integrity of the data you have, i.e. some files might be corrupted
+- If the data came in an archive format, try extracting it again with another application.
+- Check your physical drive. Is it failing?
 
 ### 5-1505-0025
 
@@ -399,11 +399,11 @@ N/A
 
 #### Known occurances
 
-* Jubeat Saucer Fullfill
+- Jubeat Saucer Fullfill
 
 #### How do I fix it?
 
-* Disable excess network adapters
+- Disable excess network adapters
 
 ## 5-1506 series errors
 
@@ -419,7 +419,7 @@ The backup data is corrupted. Press the test button to re-initialize it.
 
 #### Known occurances
 
-* IIDX 15 (BACKUP DATA ERROR)
+- IIDX 15 (BACKUP DATA ERROR)
 
 #### How do I fix it?
 
@@ -442,7 +442,7 @@ This error may happen before the monitor check on IIDX.
 
 #### Known occurances
 
-* IIDX (version?)
+- IIDX (version?)
 
 #### How do I fix it?
 
@@ -460,8 +460,8 @@ N/A
 
 #### How do I fix it?
 
-* "Set" and save the clock date and time in the test menu
-* Recopy Bemanitools
+- "Set" and save the clock date and time in the test menu
+- Recopy Bemanitools
 
 ## 5-1507 series errors
 
@@ -509,7 +509,7 @@ LAMP CHECK ERROR
 
 #### Known occurances
 
-* Pop'n Music 20 Fantasia
+- Pop'n Music 20 Fantasia
 
 #### How do I fix it?
 
@@ -527,7 +527,7 @@ The original message in Japanese: 電源を再投入して下さい
 
 #### Known occurances
 
-* Pop'n Music 22 Lapistoria
+- Pop'n Music 22 Lapistoria
 
 #### How do I fix it?
 
@@ -551,12 +551,12 @@ N/A
 
 #### How do I fix it?
 
-* Restart your game.
-* Check if your computer is connected to the Internet at all.
-* Make sure the services URL is correct.
-* Disable all network adapters other than the one used to connect to the Internet. Alternatively,
-setting that adapter to have the highest affinity also works.
-* If none of the above work, reinstall a newer or older version of your network drivers.
+- Restart your game.
+- Check if your computer is connected to the Internet at all.
+- Make sure the services URL is correct.
+- Disable all network adapters other than the one used to connect to the Internet. Alternatively,
+  setting that adapter to have the highest affinity also works.
+- If none of the above work, reinstall a newer or older version of your network drivers.
 
 ### 5-2002-0000
 
@@ -570,7 +570,7 @@ N/A
 
 #### How do I fix it?
 
-* Make sure you're editing the right file for network configuration settings.
+- Make sure you're editing the right file for network configuration settings.
 
 ### 5-2002-0916
 
@@ -602,18 +602,18 @@ Press the service button to start the game.
 
 #### Known occurances
 
-* IIDX, probably all known versions
+- IIDX, probably all known versions
 
 #### How do I fix it?
 
 The original message is already telling you what is going on:
 
-* Check if your machine/pc has an internet connection
-* Check your firewall settings
-* Check that the server address is configured and correct in `iidxhook.conf` (old games) or
-`ea3-config.xml`
-* You can disable the network in the operator menu to just boot the game first. Note that this is
-not possible on any versions starting IIDX 20 (tricoro).
+- Check if your machine/pc has an internet connection
+- Check your firewall settings
+- Check that the server address is configured and correct in `iidxhook.conf` (old games) or
+  `ea3-config.xml`
+- You can disable the network in the operator menu to just boot the game first. Note that this is
+  not possible on any versions starting IIDX 20 (tricoro).
 
 ### 5-2002-2301
 
@@ -669,7 +669,7 @@ N/A
 
 #### How do I fix it?
 
-* Check that there is a valid PCBID in ea3-config.xml.
+- Check that there is a valid PCBID in ea3-config.xml.
 
 ### 5-2002-2400
 
@@ -698,19 +698,19 @@ N/A
 
 #### How do I fix it?
 
-* Check your services URL in `ea3-config.xml`. Make sure to remove any slash at the end of the URL
-and check for https/http.
-* If you are running Spada, ensure to use a service URL that supports that older game (check with
-your private server provider)
-* If you are running Tune Street, ensure to use a service URL that supports that older game (check
-with your private server provider)
+- Check your services URL in `ea3-config.xml`. Make sure to remove any slash at the end of the URL
+  and check for https/http.
+- If you are running Spada, ensure to use a service URL that supports that older game (check with
+  your private server provider)
+- If you are running Tune Street, ensure to use a service URL that supports that older game (check
+  with your private server provider)
 
 ### 5-2003-2404
 
 #### Description
 
-Malformed `<network>` section.  The `<network>` section in your `ea3-config.xml` file is malformed
-in some way.
+Malformed `<network>` section. The `<network>` section in your `ea3-config.xml` file is malformed in
+some way.
 
 #### Known occurances
 
@@ -758,15 +758,15 @@ N/A
 
 #### How do I fix it?
 
-Check if your `hosts` file has any DNS redirects to other private servers that might interfere
-with this
+Check if your `hosts` file has any DNS redirects to other private servers that might interfere with
+this
 
 ### 5-2016-0000
 
 #### Description
 
-"apsmanager" is a special eAM Participation system for Korean machines(XXX:K). This system
-is maybe not supported by private servers.
+"apsmanager" is a special eAM Participation system for Korean machines(XXX:K). This system is maybe
+not supported by private servers.
 
 #### Known occurances
 

doc/iidxhook/README.md

@@ -1,52 +1,55 @@
 # iidxhook
-iidxhook is a collection of hook libraries for BeatmaniaIIDX providing
-emulation and various patches to run these games on non BemaniPC hardware and
-newer Windows versions.
+
+iidxhook is a collection of hook libraries for BeatmaniaIIDX providing emulation and various patches
+to run these games on non BemaniPC hardware and newer Windows versions.
 
 The hook libraries must be bootstrapped either using [inject](../inject.md) or
-[launcher](../launcher.md) depending on the version you want to run. Further
-instructions are given in dedicated readme files for each iidxhook version
-(see below).
+[launcher](../launcher.md) depending on the version you want to run. Further instructions are given
+in dedicated readme files for each iidxhook version (see below).
 
 ## Versions
-iidxhook comes in a few different flavors. The game and its engine changed over
-the years. Some game versions might require patches/parameters enabled which
-others don't need or have different AVS versions. Here is the list of supported 
-games:
-* [iidxhook1](iidxhook1.md): 9th, 10th, RED, HAPPY SKY
-* [iidxhook2](iidxhook2.md): DistorteD
-* [iidxhook3](iidxhook3.md): GOLD, DJ TROOPERS, EMPRESS, SIRIUS
-* [iidxhook4](iidxhook4.md): Resort Anthem
-* [iidxhook4-cn](iidxhook4-cn.md): Resort Anthem CN (狂热节拍 IIDX)
-* [iidxhook5](iidxhook5.md): Lincle
-* [iidxhook5-cn](iidxhook5-cn.md): tricoro CN (狂热节拍 IIDX 2) 
-* [iidxhook6](iidxhook6.md): Tricoro
-* [iidxhook7](iidxhook7.md): SPADA, PENDUAL, copula, SINOBUZ
-* [iidxhook8](iidxhook8.md): CANNON BALLERS, Rootage
-* [iidxhook8](iidxhook9.md): Heroic Verse
 
-When building bemanitools, independent packages are created for each set of games
-which are ready to be dropped on top of vanilla AC data dumps. We recommend
-using pristine dumps to avoid any conflicts with other hardcoded hacks or
-binary patches.
+iidxhook comes in a few different flavors. The game and its engine changed over the years. Some game
+versions might require patches/parameters enabled which others don't need or have different AVS
+versions. Here is the list of supported games:
+
+- [iidxhook1](iidxhook1.md): 9th, 10th, RED, HAPPY SKY
+- [iidxhook2](iidxhook2.md): DistorteD
+- [iidxhook3](iidxhook3.md): GOLD, DJ TROOPERS, EMPRESS, SIRIUS
+- [iidxhook4](iidxhook4.md): Resort Anthem
+- [iidxhook4-cn](iidxhook4-cn.md): Resort Anthem CN (狂热节拍 IIDX)
+- [iidxhook5](iidxhook5.md): Lincle
+- [iidxhook5-cn](iidxhook5-cn.md): tricoro CN (狂热节拍 IIDX 2)
+- [iidxhook6](iidxhook6.md): Tricoro
+- [iidxhook7](iidxhook7.md): SPADA, PENDUAL, copula, SINOBUZ
+- [iidxhook8](iidxhook8.md): CANNON BALLERS, Rootage
+- [iidxhook8](iidxhook9.md): Heroic Verse
+
+When building bemanitools, independent packages are created for each set of games which are ready to
+be dropped on top of vanilla AC data dumps. We recommend using pristine dumps to avoid any conflicts
+with other hardcoded hacks or binary patches.
 
 ## How to run
-To run your game with iidxhook, you have to use the inject tool to inject the
-DLL to the game process. `dist/iidx` contains bat scripts with all the
-important parameters configured. Further parameters can be added but might not
-be required to run the game with default settings.
-Further information on how to setup the data for each specific version are
-elaborated in their dedicated readme files.
+
+To run your game with iidxhook, you have to use the inject tool to inject the DLL to the game
+process. `dist/iidx` contains bat scripts with all the important parameters configured. Further
+parameters can be added but might not be required to run the game with default settings. Further
+information on how to setup the data for each specific version are elaborated in their dedicated
+readme files.
 
 ## Command line options
-Add the argument *-h* when running inject with iidxhook to print help/usage
-information with a list of parameters you can apply to tweak various things.
+
+Add the argument *-h* when running inject with iidxhook to print help/usage information with a list
+of parameters you can apply to tweak various things.
 
 ## iidxio API
-Available implementations that can be swapped out depending on which kind of
-IO hardware you want to use:
-* `iidxio`: Default implementation supporting keyboard, mouse and USB
-game controllers
-* [iidxio-bio2](iidxhook/iidxio-bio2.md): Support BIO2 hardware
-* [iidxio-ezusb](iidxhook/iidxio-ezusb.md): Support C02 ezusb FX hardware
-* [iidxio-ezusb2](iidxhook/iidxio-ezusb2.md): Support IO2 ezusb FX2 hardware
+
+Available implementations that can be swapped out depending on which kind of IO hardware you want to
+use:
+
+- `iidxio`: Default implementation supporting keyboard, mouse and USB game controllers
+- [iidxio-async](iidxhook/iidxio-async.md): Shim implementation that runs another iidxio implementation in a dedicated
+  thread
+- [iidxio-bio2](iidxhook/iidxio-bio2.md): Support BIO2 hardware
+- [iidxio-ezusb](iidxhook/iidxio-ezusb.md): Support C02 ezusb FX hardware
+- [iidxio-ezusb2](iidxhook/iidxio-ezusb2.md): Support IO2 ezusb FX2 hardware

doc/iidxhook/iidx-syncbook.md

@@ -0,0 +1,224 @@
+# IIDX "Syncbook": A guide to ensuring sync and performant gameplay
+
+This is a guide applicable to all IIDX versions that are native Windows PC-based. The goal is to 
+enable proper configuration of those games to ensure the game engine "runs in-sync" with any of its
+IO (visual GPU/display output, audio output, user input) resulting in high and stable performance
+for smooth game-play.
+
+This document won't go into the implementation details of the game engine. Please refer to the
+[IIDX engine details journal](../dev/journal/2025-02-09-iidx-engine.md) for a more in-depth
+information.
+
+## Understanding the problems and options to address them
+
+First, let's understand what the key problems are and how they contribute to different issues
+that impact game-play.
+
+### Song de-syncing
+
+Symptom: Throughout playing a song, the audio is de-syncing even it was fine when the song started.
+
+Cause: The game engine is fundamentally designed to run on a fixed and consistent frame
+rate/time per engine step. A mismatch of expected frame time by the game engine and actually delivered
+frame time by the GPU driver. This can come either as a stable frame time that just mismatches in
+general or (highly) fluctuating frame times.
+
+* G-sync on modern displays causes known fluctuations because it adjusts dynamically the monitor
+  refresh rate
+* V-sync not correctly configured/enforced or even vsync-off override in driver is causing
+  inconsistent frame times
+* Incorrect display timings causing refresh rate fluctuations resulting in inconsistent frame times
+
+Stable frame times but not having the correct ones that the game engine expects is a different
+problem that can be addressed by:
+
+* Knowing the refresh rates expected by the game engine of the different game versions
+* Configuring your GPU driver's display timings to match the expected frame times
+* Or, patch the game's chart data with your custom display timings so the game engine gets uses
+  *your* "correct" frame times
+  * Note: Offline patching the chart data doesn't work for several game versions as the monitor
+    check does override this data, but not as flexible as required
+  * Use the chart patch feature of bemanitools instead
+
+### Micro-stuttering and non-smooth note scrolling
+
+This is a trickier problem as it can be caused by a few different things.
+
+* GPU related
+  * Fluctuating refresh rates result in fluctuating frame times in the main game loop
+  * GPU power configuration in non-performance mode (e.g. "power saving") causes processing latency
+    due to sleep states
+* Display related
+  * Display firmware buggy and/or internal scalers that expect to run at very specific refresh rates
+    and cannot adapt to any custom display timings enforced by the GPU
+  * A known example is the official
+    [PENDUAL LCD monitor](https://github.com/shizmob/arcade-docs/blob/6ac99975cdb2bf668362f65fa9fa3ffb2127308b/konami/product/GULDJ-JI.md#notes-and-known-issues) that does not v-sync correctly to any other refresh-rate than 60.000 hz
+* CPU related
+  * CPU power configuration on Windows in non-performance mode (e.g. "power saving") causes
+    processing latency due to sleep states
+  * Correct CPU C-states configuration in BIOS/UEFI
+    * These cannot be configured in Windows and are separate from Windows's power configuration
+* Other stuff running in the background of the system causing fluctuations
+  * (Synchronous) Disk I/O heavy applications stealing CPU time
+  * Or any other process creating a considerable amount of CPU or GPU load
+
+## Configuration guide for different game versions
+
+### Measuring monitor refresh rate
+
+Let's start with configuring the system to meet the game engine's expectation regarding the
+target monitor refresh rate and requiring vsync.
+
+First, use the [d3d9-monitor-check tool](../tools/d3d9-monitor-check.md) to measure the currently
+configured refresh rate of your monitor. Note that your monitor might yield different timings on
+different resolutions and different game versions run on
+[different rendering resolutions](../dev/journal/2025-02-09-iidx-engine.md#rendering-resolutions).
+
+For example, the game version is 31 with the rendering resolution of 1920x1080 in FHD mode that you
+want to target:
+
+```bat
+d3d9-monitor-check.exe cmdline refresh-rate-test 1920 1080 60
+```
+
+The test shows the current monitor refresh rate and the average refresh rate over the course of
+the test. Check that the avg. refresh rate is stable during the measuring phase (during warm-up,
+it's ok if it fluctuates).
+
+This test allows you to determine/check:
+
+* Refresh rate/frame time fluctuations: if you see (high) fluctuations on the first or second
+  decimal place
+* What's your current target refresh rate the GPU is driving your monitor at
+* If vsync isn't overridden by some other driver setting as you want to see a refresh rate around
+  the 60 hz mark
+
+### Measuring vsync issues
+
+Some displays or the GPU configuration might lead to vsync issues which can be detected with the
+`d3d9-monitor-check.exe` tool as well.
+
+```bat
+d3d9-monitor-check.exe cmdline vsync-test 1920 1080 60
+```
+
+This runs a test with a VSYNC text that alternates red and cyan colors. If the text appears grey
+all the time, everything's fine. If you spot brief red or cyan text either occasionally or
+periodically, your current configuration has vsync issues resulting in skipped frames or old
+frames displaying longer.
+
+### Configuration
+
+The following are recommended configurations for the different game versions. If any of these
+don't work as expected, you have to troubleshoot and tweak these potentially. Please refer to the
+[guidelines above](#configuration-guide-for-different-game-versions) to understand how to use
+the tooling and test your changes.
+
+#### Recommended configuration with NVIDIA GPU and driver
+
+We want to achieve the following configuration on the GPU driver:
+
+* Turn-off g-sync if you have a monitor that supports it
+* Disable power saving mode on GPU driver
+* V-sync is not forced off
+* Run the display on a target refresh rate of `59.950 hz` which has been determined to be
+  [the most compatible across all PC-based versions](../dev/journal/2025-02-09-iidx-engine.md#engine-step-time).
+
+##### Turn-off g-sync
+
+Create a new GPU profile for IIDX, if it doesn't exist yet:
+
+```bat
+nvgpu.exe profile create iidx
+```
+
+Add the application names when the profile needs to be applied:
+
+```bat
+:: For iidx versions 9 to 17
+nvgpu.exe profile application-add iidx bm2dx.exe
+:: For iidx versions 18+
+nvgpu.exe profile application-add iidx launcher.exe
+```
+
+Disable G-SYNC for the profile:
+
+```bat
+nvgpu.exe profile gsync-disable iidx
+```
+
+##### Disable power saving mode
+
+Set GPU power state to maximum for the profile (assumes you have a 
+[GPU profile called `iidx` already created](#turn-off-g-sync)):
+
+```bat
+nvgpu.exe profile gpu-power-state-max iidx
+```
+
+##### Configure and verify target refresh rate of 59.950 hz and vsync
+
+Get display ID of your primary display:
+
+```bat
+nvgpu.exe display primary-display-id
+```
+
+Copy the hex-value of the display ID and use it in the following commands.
+
+Test the custom display timing first, e.g. for versions that run in 1920x1080
+(Replace `<DISPLAY_ID> ` with the primary display ID you got):
+
+```bat
+nvgpu.exe display custom-resolution-test <DISPLAY_ID> 1920 1080 59.95 10
+```
+
+This will test it for 10 seconds and then revert. If the result looked good, i.e. the screen didn't
+go blank or the display output was garbage, apply it:
+
+```bat
+nvgpu.exe display custom-resolution-set <DISPLAY_ID> 1920 1080 59.95
+```
+
+Test and verify the configuration is applied and works correctly:
+
+```bat
+d3d9-monitor-check.exe cmdline refresh-rate-test 1920 1080 60
+```
+
+Test if the enforced refresh rate is compatible with your display and vsync is working correctly:
+
+```bat
+d3d9-monitor-check.exe cmdline vsync-test 1920 1080 60
+```
+
+##### Alternative refresh rate configuration
+
+If for some reason your display doesn't support 59.950 hz properly, i.e. display artifacts or vsync
+issues, you can use any other 60 hz compatible refresh rate, e.g. anything between 59.900 hz and
+60.100 hz that your display supports properly.
+
+Follow the same steps [as above](#configure-and-verify-target-refresh-rate-of-59950-hz-and-vsync) 
+but use a different refresh rate, e.g. 60.000 hz.
+
+Verify using the `d3d9-monitor-check.exe` with the outlined steps if you need to play around to find
+a refresh rate that works for your setup.
+
+For the game versions 9 to 19, you have to use the chart patch feature of bemanitools to patch
+the charts to your custom refresh rate. Otherwise, the game engine will run on your configured
+refresh rate, but it will take the non-matching refresh rate from the chart data which causes
+song de-syncing.
+
+For example, to configure a refresh rate of 60.000 hz in the iidxhook config file:
+
+```text
+gfx.monitor_check=60.000
+```
+
+##### ATI/AMD
+
+Currently, there is no tooling provided by bemanitools to configure the AMD GPU driver. The basic
+concepts of what needs to be configured still applies as outlined in the NVIDIA sections above
+though, e.g. through AMD's GPU control panel.
+
+Further steps and instructions TBD

doc/iidxhook/iidxhook1.md

@@ -1,244 +1,241 @@
 # Game list
 
 The following games are compatible with this version of iidxhook:
-* 9th Style
-* 10th Style
-* RED
-* HAPPY SKY
+
+- 9th Style
+- 10th Style
+- RED
+- HAPPY SKY
 
 The games must be bootstrapped using [inject](../inject.md).
 
 # Data setup and running the game
 
 Ensure your folder with your unpacked data looks like this:
+
 - JAx (Game binary revision folder where 'x' can be A, B, C, D, E, F, G)
 - data
 - sidcode.txt
 
 Any further files are optional and not required to run the game.
 
-Unpack the package containing iidxhook1 into the revision folder of your choice.
-Most likely, you want to target the latest revision you have to run the latest
-binary of the game with any bugfixes by developers.
+Unpack the package containing iidxhook1 into the revision folder of your choice. Most likely, you
+want to target the latest revision you have to run the latest binary of the game with any bugfixes
+by developers.
 
-If you don't run this on old hardware that uses an analog version of a Realtek 
-integrated sound chip, you have to replace RtEffect.dll with a stubbed/patched
-version (RtEffect_patched.dll). Otherwise, the game might crash instantly when
-trying to start it.
+If you don't run this on old hardware that uses an analog version of a Realtek integrated sound
+chip, you have to replace RtEffect.dll with a stubbed/patched version (RtEffect_patched.dll).
+Otherwise, the game might crash instantly when trying to start it.
 
-Run the appropriate gamestart-XX.bat file as admin, where XX is either 
-09, 10, 11, 12.
+Run the appropriate gamestart-XX.bat file as admin, where XX is either 09, 10, 11, 12.
 
 # Configuring iidxhook
 
-The hook library can be configured via cmd arguments or a configuration file.
-The latter is generated (*iidxhook.conf* in the same directory) on the first 
-start of the game using the gamestart-XX.bat file. It contains default values
-for all available parameters and comments explaining each parameter. Please
-follow the comments when configuring your setup.
+The hook library can be configured via cmd arguments or a configuration file. The latter is
+generated (*iidxhook.conf* in the same directory) on the first start of the game using the
+gamestart-XX.bat file. It contains default values for all available parameters and comments
+explaining each parameter. Please follow the comments when configuring your setup.
 
-Add the argument *-h* when running gamestart-XX.bat 
-(e.g. *gamestart-XX.bat -h*) to print help/usage information with a list of 
-all available parameters. Every parameter can be either set as command line
-argument or using a configuration file.
+Add the argument *-h* when running gamestart-XX.bat (e.g. *gamestart-XX.bat -h*) to print help/usage
+information with a list of all available parameters. Every parameter can be either set as command
+line argument or using a configuration file.
+
+To set a parameter from the command line, just add it as an argument after the bat file like this
 
-To set a parameter from the command line, just add it as an argument after
-the bat file like this
 ```
 gamestart-09.bat -p gfx.windowed=true -p gfx.framed=true
 ```
 
-The syntax for the "key=value" is the same as in the config file. Make sure
-to have a pre-ceeding "-p" for every parameter added.
+The syntax for the "key=value" is the same as in the config file. Make sure to have a pre-ceeding
+"-p" for every parameter added.
 
-However, if a parameter is specifed in the configuration file and as a command
-line argument, the command line argument overrides the config file's value.
+However, if a parameter is specifed in the configuration file and as a command line argument, the
+command line argument overrides the config file's value.
 
 # Use d3d8to9 wrapper
 
-In order to use the gfx feature patches, e.g. window mode, monitor check,
-frame rate locking, framebuffer up/-downscaling etc. you **must** use the
-d3d8to9 wrapper library (get it from the bemanitools-supplement package).
-Bemanitools removed the old d3d8 hooking module to provide native d3d8 hooks
-due to compatibility and maintainability reasons.
+In order to use the gfx feature patches, e.g. window mode, monitor check, frame rate locking,
+framebuffer up/-downscaling etc. you **must** use the d3d8to9 wrapper library (get it from the
+bemanitools-supplement package). Bemanitools removed the old d3d8 hooking module to provide native
+d3d8 hooks due to compatibility and maintainability reasons.
 
 # Eamuse network setup
 
-If you want to run the games online, you have to set a valid PCBID in the 
-configuration file or as a command line argument. You also have to set the url 
-of the eamuse server you want to connect to.
+If you want to run the games online, you have to set a valid PCBID in the configuration file or as a
+command line argument. You also have to set the url of the eamuse server you want to connect to.
 
-Run the game with the gamestart-XX.bat file and enable network on the operator 
-menu. When enabled, the game seems to hang and expects you to power
-cycle the machine (i.e. quit the game and restart it).
+Run the game with the gamestart-XX.bat file and enable network on the operator menu. When enabled,
+the game seems to hang and expects you to power cycle the machine (i.e. quit the game and restart
+it).
 
 # Switching beat phases 9th and 10th Style
 
-9th Style offers internet ranking phases 1 and 2, 10th Style phases 1, 2 and 3. 
-On both games, the phases are not controlled by the eamuse server the game is 
-connected to (this started with RED). Thus, the game was unlocked by binary 
-updates back then. 
-The higher the beat phase, the more expert courses and songs got unlocked. 
-Furthermore, the "real" ES and OMES are only available on beat#1.
-Use the iidx-irbeat-patch-XX.bat to patch to a different beat phase if you want 
-to play on a different beat phase. The default phase is beat#1. 
-To unlock everything, patch the game to beat#3.
+9th Style offers internet ranking phases 1 and 2, 10th Style phases 1, 2 and 3. On both games, the
+phases are not controlled by the eamuse server the game is connected to (this started with RED).
+Thus, the game was unlocked by binary updates back then. The higher the beat phase, the more expert
+courses and songs got unlocked. Furthermore, the "real" ES and OMES are only available on beat#1.
+Use the iidx-irbeat-patch-XX.bat to patch to a different beat phase if you want to play on a
+different beat phase. The default phase is beat#1. To unlock everything, patch the game to beat#3.
 Example: "iidx-irbeat-patch-10.bat 2" to patch to beat#3 on 10th Style
 
 # Real hardware support
 
 ## USB IO (ezusb)
 
-Use the specific iidxio API implementations, e.g. iidxio-ezusb.dll to use
-an old C02 EZUSB IO board, to run the game on real hardware. Thanks to a common
-abstraction layer, you can also use more modern IO, e.g. IO2 boards with
-iidxio-ezusb2.dll, even with old games that do not support them.
+Use the specific iidxio API implementations, e.g. iidxio-ezusb.dll to use an old C02 EZUSB IO board,
+to run the game on real hardware. Thanks to a common abstraction layer, you can also use more modern
+IO, e.g. IO2 boards with iidxio-ezusb2.dll, even with old games that do not support them.
 
 ## Slotted/Wave pass card readers
 
-Replace the default *eamio.dll* with the *eamio-icca.dll* and have either your
-slotted (IIDX, DDR Supernova or GF/DM type) or new wave pass card readers 
-conencted and and assigned to *COM1*.
+Replace the default *eamio.dll* with the *eamio-icca.dll* and have either your slotted (IIDX, DDR
+Supernova or GF/DM type) or new wave pass card readers conencted and and assigned to *COM1*.
 
 ### ICCA device settings (device manager)
-* Port: COM1
-* BAUD rate: 57600
-* Data bits: 8
-* Parity: None
-* Stop bits: 1
-* Flow control: None
 
-If you encounter issues after the game opened the device, e.g. application
-stuck, try a USB <-> COM dongle instead of using one of the COM ports of the
-mainboard.
+- Port: COM1
+- BAUD rate: 57600
+- Data bits: 8
+- Parity: None
+- Stop bits: 1
+- Flow control: None
+
+If you encounter issues after the game opened the device, e.g. application stuck, try a USB \<-> COM
+dongle instead of using one of the COM ports of the mainboard.
 
 # Known bugs
+
 ## avs00000.bin file on D drive
-All other settings data is remapped to the local folders d, e and f. But, for
-the avs00000.bin file that's not possible. Once the avs.dll is initialized
-(DllMain called), it creates that file if it doesn't exist. Currently, we can't
-fix this because iidxhook is injected after avs.dll is loaded and can't be
-injected before it is loaded to patch the path for the file.
+
+All other settings data is remapped to the local folders d, e and f. But, for the avs00000.bin file
+that's not possible. Once the avs.dll is initialized (DllMain called), it creates that file if it
+doesn't exist. Currently, we can't fix this because iidxhook is injected after avs.dll is loaded and
+can't be injected before it is loaded to patch the path for the file.
 
 ## USBIO (FM-DL TIMEOUT)
-IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this 
-happens, run the game again. 
+
+IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this happens, run the game
+again.
 
 # Troubleshooting and FAQ
 
 ## The game is running (very) slow in fullscreen mode but is fine in window mode
-If you are using a AMD GPU, try disabling "GPU scaling" which you can find in AMD
-settings UI under "Settings" -> "Display".
+
+If you are using a AMD GPU, try disabling "GPU scaling" which you can find in AMD settings UI under
+"Settings" -> "Display".
 
 This issue only observed on 9th Style so far.
 
 Use
-[bemanitool's built in upscaling feature](#over-underscan-bad-image-quality-or-latency-caused-by-my-monitorsTV-upscaler) if the game is not
-scaled properly in full screen.
+[bemanitool's built in upscaling feature](#over-underscan-bad-image-quality-or-latency-caused-by-my-monitorsTV-upscaler)
+if the game is not scaled properly in full screen.
 
 ## Window mode or any other gfx related options do not work when changing them in the config file or using cmd args
 
 See [this](#Use-d3d8to9-wrapper) section.
 
 ## The game does not run "well" (frame drops, drifting offsync etc)
+
 This can be related to various issues:
-* Make sure to run the game as (true) Administrator especially on Windows 7 and
-newer. This will also get rid of various other errors (see below) that are 
-related to permission issues.
-* Run the game's process with a higher priority:
+
+- Make sure to run the game as (true) Administrator especially on Windows 7 and newer. This will
+  also get rid of various other errors (see below) that are related to permission issues.
+- Run the game's process with a higher priority:
+
 ```
 start "" /relatime "gamestart.bat"
 ```
-* Enforce v-sync enabled in your GPU settings.
-* Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx)
-that is not jumping around. Use the timebase feature of one of the newer games to
-check that or enable iidxhook's timebase and check the log output for the
-determined value. Run this a few times and check if the results differ.
-* Use iidxhook's frame rate limiter feature (see further below) to software lock
-the refresh rate. This might be necessary on Windows 7 and newer for D3D8 games,
-e.g. iidx 9 to 12, which seem to ignore GPU side v-sync.
-* Use iidxhook's auto timebase feature (see further below) or set a pre-determined
-value to cut down start-up times.
+
+Also refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ### The game still stutters (randomly) and drifts off-sync
-If this concerns a d3d8 based game, i.e. IIDX 9 to 13, use the d3d8to9 wrapper from
-the bemanitools-supplement package (follow the included instructions).
+
+If this concerns a d3d8 based game, i.e. IIDX 9 to 13, use the d3d8to9 wrapper from the
+bemanitools-supplement package (follow the included instructions).
 
 ## "NETWORK WARNING" instead of "NETWORK OK"
+
 This can be caused by:
-* Invalid PCBID
-* Firewall blocking connections
-* Invalid eamuse url or port specified
-* Game is not run using the Administrator account
-Make sure to check these things first
+
+- Invalid PCBID
+- Firewall blocking connections
+- Invalid eamuse url or port specified
+- Game is not run using the Administrator account Make sure to check these things first
 
 ## My songs are offsync
-* Make sure your machine's refresh rate is stable
-* If you don't get a close to 59.94hz refresh rate, use the software monitor
-check/auto timebase that's built into iidxhook (refer to help/config file)
+
+Refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## The game crashes instantly (10th, RED, HAPPY SKY)
-Replace the original RtEffects.dll with the patched version 
-RtEffects_patched.dll from utils (for explanation see above).
+
+Replace the original RtEffects.dll with the patched version RtEffects_patched.dll from utils (for
+explanation see above).
 
 ## The game errors with "PROG CHECKSUM" on boot (10th Style only)
-10th Style does some checksum tests on boot that have to be removed in order
-to boot it with iidxhook injected. Use a patched executable that removed the
-checksum tests.
+
+10th Style does some checksum tests on boot that have to be removed in order to boot it with
+iidxhook injected. Use a patched executable that removed the checksum tests.
 
 ## My game runs too fast
+
 iidxhook can limit the frame rate for you (refer to help/config file)
 
 ## My game crashes when I try fullscreen
+
 Use dxwnd and set settings like "Acquire admin caps" and "Fullscreen only"
 
 ## 10key input (card reader keyboard) seems unresponsive
-10key pad emulation for the old magnetic card readers is quite a mess and 
-can't be refreshed very often to make it feel unresponsive. Solution:
-hit your 10key/numpad slower than normal
+
+10key pad emulation for the old magnetic card readers is quite a mess and can't be refreshed very
+often to make it feel unresponsive. Solution: hit your 10key/numpad slower than normal
 
 ## Background videos aren't working. When starting a song, windows is playing the error sound and a message box appears (RED, HAPPY SKY)
+
 If you are running in window mode, you can see an error pop-up window with the title
 `DirectShow Texture3D Sample` and error message
 `Could not create source filter to graph! hr=<some number>`.
 
-When running fullscreen, you only hear a windows error sound and the game appears to be frozen
-when trying to play a background video.
+When running fullscreen, you only hear a windows error sound and the game appears to be frozen when
+trying to play a background video.
 
-You are missing a codec to decode and play the videos. There are different 
-methods available to get background videos working. Probably, the easiest 
-solution: grab the CLVSD.ax file and go to Start -> Run -> regsvr32 clvsd.ax
-Make sure to run cmd.exe as Administrator, otherwise you will get errors caused
-by invalid permissions.
+You are missing a codec to decode and play the videos. There are different methods available to get
+background videos working. Probably, the easiest solution: grab the CLVSD.ax file and go to Start ->
+Run -> regsvr32 clvsd.ax Make sure to run cmd.exe as Administrator, otherwise you will get errors
+caused by invalid permissions.
 
 ## All background videos are looking streched (starting with HAPPY SKY)
-The game requires a hardware feature that is not present on newer GPUs.
-Refer to the help/config file and turn on the UV fix.
+
+The game requires a hardware feature that is not present on newer GPUs. Refer to the help/config
+file and turn on the UV fix.
 
 ## I installed the CLVSD.ax codec but the game crashes or displays a message box that tells me to disable my debugger
+
 If songs keep crashing upon start and you get an error message that says
+
 ```
 DirectShow Texture3D Sample
 Could not create source filter to graph! hr=0x80040266
 ```
-despite having the codec (CLVSD.ax) installed, turn off debugging output 
-(refer to the help/config file) or use a CLVSD.ax codec which has the debugger 
-checks removed.
+
+despite having the codec (CLVSD.ax) installed, turn off debugging output (refer to the help/config
+file) or use a CLVSD.ax codec which has the debugger checks removed.
 
 ## I used the auto timebase option and/or limited my refresh rate but the songs are still going offsync
-There aren't many options left. The old games were developed for specific
-hardware and are not guaranteed to work well on (especially) newer hardware.
-Multiple monitor setups can also have a bad impact on a stable refresh rate.
-Try a setup with just a single monitor you want to use for gameplay physically
-connected. Furthermore, dedicated and tested/verified hardware by other users 
-is recommended if you want to save yourself a lot of fiddling.
+
+Refer to the [iidx-syncbook](iidx-syncbook.md) if you haven't already.
+
+There aren't many options left. The old games were developed for specific hardware and are not
+guaranteed to work well on (especially) newer hardware. Multiple monitor setups can also have a bad
+impact on a stable refresh rate. Try a setup with just a single monitor you want to use for gameplay
+physically connected. Furthermore, dedicated and tested/verified hardware by other users is
+recommended if you want to save yourself a lot of fiddling.
 
 ## Over-/underscan, bad image quality or latency caused by my monitor's/TV's upscaler
-Many modern monitors/TVs cannot upscale 640x480 output properly. This can lead to
-over-/underscan, bad image quality or even latency caused by the upscaler of the device
-you are using.
-If one or multiple of these issues apply, use the built in scaling options by setting
-*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution
-to scale to. Usually, you want to set this to the monitor's native resolution, e.g.
-1920x1080 for full HD. You can play around with a few different filters using
-*gfx.scale_back_buffer_filter* which impacts image quality/blurriness on upscaling.
+
+Many modern monitors/TVs cannot upscale 640x480 output properly. This can lead to over-/underscan,
+bad image quality or even latency caused by the upscaler of the device you are using. If one or
+multiple of these issues apply, use the built in scaling options by setting
+*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution to scale to.
+Usually, you want to set this to the monitor's native resolution, e.g. 1920x1080 for full HD. You
+can play around with a few different filters using *gfx.scale_back_buffer_filter* which impacts
+image quality/blurriness on upscaling.

doc/iidxhook/iidxhook2.md

@@ -1,104 +1,101 @@
 # Game list
 
 The following games are compatible with this version of iidxhook:
-* DistorteD
+
+- DistorteD
 
 The games must be bootstrapped using [inject](../inject.md).
 
 # Data setup and running the game
 
 Ensure your folder with your unpacked data looks like this:
+
 - JAx (Game binary revision folder where 'x' can be A, B, C, D, E, F, G)
 - data
 - sidcode.txt
 
 Any further files are optional and not required to just run the game.
 
-Unpack the package containing iidxhook2 into the revision folder of your choice.
-Most likely, you want to target the latest revision you have to run the latest
-binary of the game with any bugfixes by developers.
+Unpack the package containing iidxhook2 into the revision folder of your choice. Most likely, you
+want to target the latest revision you have to run the latest binary of the game with any bugfixes
+by developers.
 
-If you don't run this on old hardware that uses an analog version of a Realtek 
-integrated sound chip, you have to replace RtEffect.dll with a stubbed/patched
-version (RtEffect_patched.dll). Otherwise, the game might crash instantly when
-trying to start it.
+If you don't run this on old hardware that uses an analog version of a Realtek integrated sound
+chip, you have to replace RtEffect.dll with a stubbed/patched version (RtEffect_patched.dll).
+Otherwise, the game might crash instantly when trying to start it.
 
 Run the gamestart-13.bat file as admin.
 
 # Configuring iidxhook
 
-The hook library can be configured via cmd arguments or a configuration file.
-The latter is generated (*iidxhook.conf* in the same directory) on the first 
-start of the game using the gamestart-13.bat file. It contains default values
-for all available parameters and comments explaining each parameter. Please
-follow the comments when configuring your setup.
+The hook library can be configured via cmd arguments or a configuration file. The latter is
+generated (*iidxhook.conf* in the same directory) on the first start of the game using the
+gamestart-13.bat file. It contains default values for all available parameters and comments
+explaining each parameter. Please follow the comments when configuring your setup.
 
-Add the argument *-h* when running gamestart-13.bat 
-(e.g. *gamestart-13.bat -h*) to print help/usage information with a list of 
-all available parameters. Every parameter can be either set as command line
-argument or using a configuration file.
+Add the argument *-h* when running gamestart-13.bat (e.g. *gamestart-13.bat -h*) to print help/usage
+information with a list of all available parameters. Every parameter can be either set as command
+line argument or using a configuration file.
+
+To set a parameter from the command line, just add it as an argument after the bat file like this
 
-To set a parameter from the command line, just add it as an argument after
-the bat file like this
 ```
 gamestart-09.bat -p gfx.windowed=true -p gfx.framed=true
 ```
 
-The syntax for the "key=value" is the same as in the config file. Make sure
-to have a pre-ceeding "-p" for every parameter added.
+The syntax for the "key=value" is the same as in the config file. Make sure to have a pre-ceeding
+"-p" for every parameter added.
 
-However, if a parameter is specifed in the configuration file and as a command
-line argument, the command line argument overrides the config file's value.
+However, if a parameter is specifed in the configuration file and as a command line argument, the
+command line argument overrides the config file's value.
 
 # Use d3d8to9 wrapper
 
-In order to use the gfx feature patches, e.g. window mode, monitor check,
-frame rate locking, framebuffer up/-downscaling etc. you **must** use the
-d3d8to9 wrapper library (get it from the bemanitools-supplement package).
-Bemanitools removed the old d3d8 hooking module to provide native d3d8 hooks
-due to compatibility and maintainability reasons.
+In order to use the gfx feature patches, e.g. window mode, monitor check, frame rate locking,
+framebuffer up/-downscaling etc. you **must** use the d3d8to9 wrapper library (get it from the
+bemanitools-supplement package). Bemanitools removed the old d3d8 hooking module to provide native
+d3d8 hooks due to compatibility and maintainability reasons.
 
 # Eamuse network setup
 
-If you want to run the games online, you have to set a valid PCBID in the 
-configuration file or as a command line argument. You also have to set the 
-url of the eamuse server you want to connect to.
+If you want to run the games online, you have to set a valid PCBID in the configuration file or as a
+command line argument. You also have to set the url of the eamuse server you want to connect to.
 
-Run the game with the gamestart-13.bat file and enable network on the operator 
-menu. When enabled, the game seems to hang and expects you to power
-cycle the machine (i.e. quit the game and restart it).
+Run the game with the gamestart-13.bat file and enable network on the operator menu. When enabled,
+the game seems to hang and expects you to power cycle the machine (i.e. quit the game and restart
+it).
 
 # Real hardware support
 
 ## USB IO (ezusb)
 
-Use the specific iidxio API implementations, e.g. iidxio-ezusb.dll to use
-an old C02 EZUSB IO board, to run the game on real hardware. Thanks to a common
-abstraction layer, you can also use more modern IO, e.g. IO2 boards with
-iidxio-ezusb2.dll, even with old games that do not support them.
+Use the specific iidxio API implementations, e.g. iidxio-ezusb.dll to use an old C02 EZUSB IO board,
+to run the game on real hardware. Thanks to a common abstraction layer, you can also use more modern
+IO, e.g. IO2 boards with iidxio-ezusb2.dll, even with old games that do not support them.
 
 ## Slotted/Wave pass card readers
 
-Replace the default *eamio.dll* with the *eamio-icca.dll* and have either your
-slotted (IIDX, DDR Supernova or GF/DM type) or new wave pass card readers 
-conencted and and assigned to *COM1*.
+Replace the default *eamio.dll* with the *eamio-icca.dll* and have either your slotted (IIDX, DDR
+Supernova or GF/DM type) or new wave pass card readers conencted and and assigned to *COM1*.
 
 ### ICCA device settings (device manager)
-* Port: COM1
-* BAUD rate: 57600
-* Data bits: 8
-* Parity: None
-* Stop bits: 1
-* Flow control: None
 
-If you encounter issues after the game opened the device, e.g. application
-stuck, try a USB <-> COM dongle instead of using one of the COM ports of the
-mainboard.
+- Port: COM1
+- BAUD rate: 57600
+- Data bits: 8
+- Parity: None
+- Stop bits: 1
+- Flow control: None
+
+If you encounter issues after the game opened the device, e.g. application stuck, try a USB \<-> COM
+dongle instead of using one of the COM ports of the mainboard.
 
 # Known bugs
+
 ## USBIO (FM-DL TIMEOUT)
-IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this 
-happens, run the game again. 
+
+IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this happens, run the game
+again.
 
 # Troubleshooting and FAQ
 
@@ -107,93 +104,97 @@ happens, run the game again.
 See [this](#Use-d3d8to9-wrapper) section.
 
 ## The game does not run "well" (frame drops, drifting offsync etc)
+
 This can be related to various issues:
-* Make sure to run the game as (true) Administrator especially on Windows 7 and
-newer. This will also get rid of various other errors (see below) that are 
-related to permission issues.
-* Run the game's process with a higher priority:
+
+- Make sure to run the game as (true) Administrator especially on Windows 7 and newer. This will
+  also get rid of various other errors (see below) that are related to permission issues.
+- Run the game's process with a higher priority:
+
 ```
 start "" /relatime "gamestart.bat"
 ```
-* Enforce v-sync enabled in your GPU settings.
-* Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx)
-that is not jumping around. Use the timebase feature of one of the newer games to
-check that or enable iidxhook's timebase and check the log output for the
-determined value. Run this a few times and check if the results differ.
-* Use iidxhook's frame rate limiter feature (see further below) to software lock
-the refresh rate. This might be necessary on Windows 7 and newer for D3D8 games,
-e.g. iidx 9 to 12, which seem to ignore GPU side v-sync.
-* Use iidxhook's auto timebase feature (see further below) or set a pre-determined
-value to cut down start-up times.
+
+Also refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ### The game still stutters (randomly) and drifts off-sync
-If this concerns a d3d8 based game, i.e. IIDX 9 to 13, use the d3d8to9 wrapper from
-the bemanitools-supplement package (follow the included instructions).
+
+If this concerns a d3d8 based game, i.e. IIDX 9 to 13, use the d3d8to9 wrapper from the
+bemanitools-supplement package (follow the included instructions).
 
 ## "NETWORK WARNING" instead of "NETWORK OK"
+
 This can be caused by:
-* Invalid PCBID
-* Firewall blocking connections
-* Invalid eamuse url or port specified
-* Game is not run using the Administrator account
-Make sure to check these things first
+
+- Invalid PCBID
+- Firewall blocking connections
+- Invalid eamuse url or port specified
+- Game is not run using the Administrator account Make sure to check these things first
 
 ## My songs are offsync
-* Make sure your machine's refresh rate is stable
-* If you don't get a close to 59.94hz refresh rate, use the software monitor
-check/auto timebase that's built into iidxhook (refer to help/config file)
+
+Refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## The game crashes instantly
-Replace the original RtEffects.dll with the patched version 
-RtEffects_patched.dll from utils (for explanation see above).
+
+Replace the original RtEffects.dll with the patched version RtEffects_patched.dll from utils (for
+explanation see above).
 
 ## My game runs too fast
+
 iidxhook can limit the frame rate for you (refer to help/config file)
 
 ## My game crashes when I try fullscreen
+
 Use dxwnd and set settings like "Acquire admin caps" and "Fullscreen only"
 
 ## Background videos aren't working. When starting a song, windows is playing the error sound and a message box appears
+
 If you are running in window mode, you can see an error pop-up window with the title
 `DirectShow Texture3D Sample` and error message
 `Could not create source filter to graph! hr=<some number>`.
 
-When running fullscreen, you only hear a windows error sound and the game appears to be frozen
-when trying to play a background video.
+When running fullscreen, you only hear a windows error sound and the game appears to be frozen when
+trying to play a background video.
 
-You are missing a codec to decode and play the videos. There are different 
-methods available to get background videos working. Probably, the easiest 
-solution: grab the CLVSD.ax file and go to Start -> Run -> regsvr32 clvsd.ax
-Make sure to run cmd.exe as Administrator, otherwise you will get errors caused
-by invalid permissions.
+You are missing a codec to decode and play the videos. There are different methods available to get
+background videos working. Probably, the easiest solution: grab the CLVSD.ax file and go to Start ->
+Run -> regsvr32 clvsd.ax Make sure to run cmd.exe as Administrator, otherwise you will get errors
+caused by invalid permissions.
 
 ## All background videos are looking streched (starting with HAPPY SKY)
-The game requires on a hardware feature that is not present on newer GPUs.
-Refer to the help/config file and turn on the UV fix.
+
+The game requires on a hardware feature that is not present on newer GPUs. Refer to the help/config
+file and turn on the UV fix.
 
 ## I installed the CLVSD.ax codec but the game crashes or displays a message box that tells me to disable my debugger
+
 If songs keep crashing upon start and you get an error message that says
+
 ```
 DirectShow Texture3D Sample
 Could not create source filter to graph! hr=0x80040266
 ```
-despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) 
-from gamestart or use a CLVSD.ax codec which has the debugger checks removed.
+
+despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) from gamestart or use a
+CLVSD.ax codec which has the debugger checks removed.
 
 ## I used the auto timebase option and/or limited my refresh rate but the songs are still going offsync
-There aren't many options left. The old games were developed for specific
-hardware and are not guaranteed to work well on (especially) newer hardware.
-Multiple monitor setups can also have a bad impact on a stable refresh rate.
-Try a setup with just a single monitor you want to use for gameplay physically
-connected. Furthermore, dedicated and tested/verified hardware by other users 
-is recommended if you want to save yourself a lot of fiddling.
+
+Refer to the [iidx-syncbook](iidx-syncbook.md) if you haven't already.
+
+There aren't many options left. The old games were developed for specific hardware and are not
+guaranteed to work well on (especially) newer hardware. Multiple monitor setups can also have a bad
+impact on a stable refresh rate. Try a setup with just a single monitor you want to use for gameplay
+physically connected. Furthermore, dedicated and tested/verified hardware by other users is
+recommended if you want to save yourself a lot of fiddling.
 
 ## Over-/underscan, bad image quality or latency caused by my monitor's/TV's upscaler
-Many modern monitors/TVs cannot upscale 640x480 output properly. This can lead to
-over-/underscan, bad image quality or even latency caused by the upscaler of the device
-you are using.
-If one or multiple of these issues apply, use the built in scaling options by setting
-*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution
-to scale to. Usually, you want to set this to the monitor's native resolution, e.g.
-1920x1080 for full HD. You can play around with a few different filters using
-*gfx.scale_back_buffer_filter* which impacts image quality/blurriness on upscaling.
+
+Many modern monitors/TVs cannot upscale 640x480 output properly. This can lead to over-/underscan,
+bad image quality or even latency caused by the upscaler of the device you are using. If one or
+multiple of these issues apply, use the built in scaling options by setting
+*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution to scale to.
+Usually, you want to set this to the monitor's native resolution, e.g. 1920x1080 for full HD. You
+can play around with a few different filters using *gfx.scale_back_buffer_filter* which impacts
+image quality/blurriness on upscaling.

doc/iidxhook/iidxhook3.md

@@ -1,216 +1,223 @@
 # Game list
 
 The following games are compatible with this version of iidxhook:
-* GOLD
-* DJ Troopers
-* EMPRESS
-* SIRIUS
+
+- GOLD
+- DJ Troopers
+- EMPRESS
+- SIRIUS
 
 The games must be bootstrapped using [inject](../inject.md).
 
 # Data setup and running the game
 
 Ensure your folder with your unpacked data looks like this:
-- yyyymmddrr (y = year digit, m = month digit, d = day digit, r = revision digit) 
-revision folder containing game binary and libraries
+
+- yyyymmddrr (y = year digit, m = month digit, d = day digit, r = revision digit) revision folder
+  containing game binary and libraries
 - data
 - sidcode.txt
 
 Any further files are optional and not required to just run the game.
 
-Unpack the package containing iidxhook3 into the revision folder of your choice.
-Most likely, you want to target the latest revision you have to run the latest
-binary of the game with any bugfixes by developers.
+Unpack the package containing iidxhook3 into the revision folder of your choice. Most likely, you
+want to target the latest revision you have to run the latest binary of the game with any bugfixes
+by developers.
 
-Run the gamestart-XX.bat file as admin where XX is the version of your choice 
-that's supported by this hook.
+Run the gamestart-XX.bat file as admin where XX is the version of your choice that's supported by
+this hook.
 
 # Configuring iidxhook
 
-The hook library can be configured via cmd arguments or a configuration file.
-The latter is generated (*iidxhook.conf* in the same directory) on the first 
-start of the game using the gamestart-XX.bat file. It contains default values
-for all available parameters and comments explaining each parameter. Please
-follow the comments when configuring your setup.
+The hook library can be configured via cmd arguments or a configuration file. The latter is
+generated (*iidxhook.conf* in the same directory) on the first start of the game using the
+gamestart-XX.bat file. It contains default values for all available parameters and comments
+explaining each parameter. Please follow the comments when configuring your setup.
 
-Add the argument *-h* when running gamestart-XX.bat 
-(e.g. *gamestart-XX.bat -h*) to print help/usage information with a list of 
-all available parameters. Every parameter can be either set as command line
-argument or using a configuration file.
+Add the argument *-h* when running gamestart-XX.bat (e.g. *gamestart-XX.bat -h*) to print help/usage
+information with a list of all available parameters. Every parameter can be either set as command
+line argument or using a configuration file.
+
+To set a parameter from the command line, just add it as an argument after the bat file like this
 
-To set a parameter from the command line, just add it as an argument after
-the bat file like this
 ```
 gamestart-09.bat -p gfx.windowed=true -p gfx.framed=true
 ```
 
-The syntax for the "key=value" is the same as in the config file. Make sure
-to have a pre-ceeding "-p" for every parameter added.
+The syntax for the "key=value" is the same as in the config file. Make sure to have a pre-ceeding
+"-p" for every parameter added.
 
-However, if a parameter is specifed in the configuration file and as a command
-line argument, the command line argument overrides the config file's value.
+However, if a parameter is specifed in the configuration file and as a command line argument, the
+command line argument overrides the config file's value.
 
 # Eamuse network setup
 
-If you want to run the games online, you have to set a valid PCBID and EAMID 
-(use the PCBID as the EAMID) in the configuration file or as a command line 
-argument. You also have to set the url of the eamuse server you want to 
-connect to.
+If you want to run the games online, you have to set a valid PCBID and EAMID (use the PCBID as the
+EAMID) in the configuration file or as a command line argument. You also have to set the url of the
+eamuse server you want to connect to.
 
-Additional note regarding EAMID: This is new compared to the prior games and
-is provided as the identifier of the "eamuse license" to the server. Depending
-on the implementation of the server, this can lead to authentication failure
-resulting in
+Additional note regarding EAMID: This is new compared to the prior games and is provided as the
+identifier of the "eamuse license" to the server. Depending on the implementation of the server,
+this can lead to authentication failure resulting in
 [a network error on boot or warning during gameplay](#network-warning-instead-of-network-ok).
 
-Run the game with the gamestart-XX.bat file and enable network on the operator 
-menu. When enabled, the game seems to hang and expects you to power
-cycle the machine (i.e. quit the game and restart it).
+Run the game with the gamestart-XX.bat file and enable network on the operator menu. When enabled,
+the game seems to hang and expects you to power cycle the machine (i.e. quit the game and restart
+it).
 
 # Real hardware support
 
 ## USB IO (ezusb)
 
-Use the specific iidxio API implementations, e.g. iidxio-ezusb2.dll to use
-the IO2 EZUSB board, to run the game on real hardware. Thanks to a common
-abstraction layer, you can also use custom IO boards or whatever Konami hardware
-is going to be available in the future. Obviously, someone has to write a
-driver, first.
+Use the specific iidxio API implementations, e.g. iidxio-ezusb2.dll to use the IO2 EZUSB board, to
+run the game on real hardware. Thanks to a common abstraction layer, you can also use custom IO
+boards or whatever Konami hardware is going to be available in the future. Obviously, someone has to
+write a driver, first.
 
 ## Slotted/Wave pass card readers
 
-Replace the default *eamio.dll* with the *eamio-icca.dll* and have either your
-slotted (IIDX, DDR Supernova or GF/DM type) or new wave pass card readers 
-conencted and and assigned to *COM1*.
+Replace the default *eamio.dll* with the *eamio-icca.dll* and have either your slotted (IIDX, DDR
+Supernova or GF/DM type) or new wave pass card readers conencted and and assigned to *COM1*.
 
 ### ICCA device settings (device manager)
-* Port: COM1
-* BAUD rate: 57600
-* Data bits: 8
-* Parity: None
-* Stop bits: 1
-* Flow control: None
 
-If you encounter issues after the game opened the device, e.g. application
-stuck, try a USB <-> COM dongle instead of using one of the COM ports of the
-mainboard.
+- Port: COM1
+- BAUD rate: 57600
+- Data bits: 8
+- Parity: None
+- Stop bits: 1
+- Flow control: None
+
+If you encounter issues after the game opened the device, e.g. application stuck, try a USB \<-> COM
+dongle instead of using one of the COM ports of the mainboard.
 
 # Known bugs
+
 ## USBIO (FM-DL TIMEOUT)
-IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this 
-happens, run the game again. 
+
+IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this happens, run the game
+again.
 
 # Troubleshooting and FAQ
+
 ## The game does not start at all
-If you try to run iidx16 or iidx17 and you see one of the following outputs when
-running the gamestart-XX.bat script:
+
+If you try to run iidx16 or iidx17 and you see one of the following outputs when running the
+gamestart-XX.bat script:
+
 ```
 Failed to launch hook EXE: 00000002
 ```
+
 or
+
 ```
 Injecting: iidxhook3.dll
 Debug active process
 Resuming remote process...
 ```
 
-Make sure to check if you are using non htpac'd executables on iidx16 and iidx17
-and also non htpac'd libraries/dll files on iidx17. These won't work with BT
-and injecting the hook libraries.
+Make sure to check if you are using non htpac'd executables on iidx16 and iidx17 and also non
+htpac'd libraries/dll files on iidx17. These won't work with BT and injecting the hook libraries.
 
 ## The game does not run "well" (frame drops, drifting offsync etc)
+
 This can be related to various issues:
-* Make sure to run the game as (true) Administrator especially on Windows 7 and
-newer. This will also get rid of various other errors (see below) that are 
-related to permission issues.
-* Run the game's process with a higher priority:
+
+- Make sure to run the game as (true) Administrator especially on Windows 7 and newer. This will
+  also get rid of various other errors (see below) that are related to permission issues.
+- Run the game's process with a higher priority:
+
 ```
 start "" /relatime "gamestart.bat"
 ```
-* Enforce v-sync enabled in your GPU settings.
-* Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx)
-that is not jumping around. Use the timebase feature of one of the newer games to
-check that or enable iidxhook's timebase and check the log output for the
-determined value. Run this a few times and check if the results differ.
-* Use iidxhook's frame rate limiter feature (see further below) to software lock
-the refresh rate. This might be necessary on Windows 7 and newer for D3D8 games,
-e.g. iidx 9 to 12, which seem to ignore GPU side v-sync.
-* Use iidxhook's auto timebase feature (see further below) or set a pre-determined
-value to cut down start-up times.
+
+Also refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## "NETWORK WARNING" instead of "NETWORK OK"
+
 This can be caused by:
-* Invalid PCBID/EAMID: Ensure both are [set to the same ID](#eamuse-network-setup)
-* Firewall blocking connections
-* Invalid eamuse url or port specified
-* Game is not run using the Administrator account
-Make sure to check these things first
+
+- Invalid PCBID/EAMID: Ensure both are [set to the same ID](#eamuse-network-setup)
+- Firewall blocking connections
+- Invalid eamuse url or port specified
+- Game is not run using the Administrator account Make sure to check these things first
 
 ## My songs are offsync
-The built-in monitor check just determines if the game should sync to either
-59.94 hz (S-Video setting) or 60.04 hz (VGA setting). If you don't have a setup
-that runs on (as close as possible) these values: 
-* Make sure your machine's refresh rate is stable, e.g. 60.00x hz.
-* If you don't get a close to 59.94hz (S-Video setting) or 60.04 hz 
-(VGA setting) refresh rate, go an set the output mode in the operator menu
-to "VGA" to enforce the game to run chart syncing on 60.04 hz refresh
-rate (even if your setup does not have that value). Next, use the software 
-monitor check/auto timebase that's built into iidxhook (refer to cmd 
-help/configfile).
+
+Refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## My game runs too fast
+
 iidxhook can limit the frame rate for you (refer to help/config file)
 
 ## My game crashes when I try fullscreen
+
 Use dxwnd and set settings like "Acquire admin caps" and "Fullscreen only"
 
 ## Background videos aren't working. When starting a song, windows is playing the error sound and a message box appears
+
 If you are running in window mode, you can see an error pop-up window with the title
 `DirectShow Texture3D Sample` and error message
 `Could not create source filter to graph! hr=<some number>`.
 
-When running fullscreen, you only hear a windows error sound and the game appears to be frozen
-when trying to play a background video.
+When running fullscreen, you only hear a windows error sound and the game appears to be frozen when
+trying to play a background video.
 
-You are missing a codec to decode and play the videos. There are different 
-methods available to get background videos working. Probably, the easiest 
-solution: grab the CLVSD.ax file and go to Start -> Run -> regsvr32 clvsd.ax
-Make sure to run cmd.exe as Administrator, otherwise you will get errors caused
-by invalid permissions.
+You are missing a codec to decode and play the videos. There are different methods available to get
+background videos working. Probably, the easiest solution: grab the CLVSD.ax file and go to Start ->
+Run -> regsvr32 clvsd.ax Make sure to run cmd.exe as Administrator, otherwise you will get errors
+caused by invalid permissions.
 
 ## All background videos are looking streched (starting with HAPPY SKY)
-The game requires on a hardware feature that is not present on newer GPUs.
-Refer to the help/config file and turn on the UV fix.
+
+The game requires on a hardware feature that is not present on newer GPUs. Refer to the help/config
+file and turn on the UV fix.
 
 ## I installed the CLVSD.ax codec but the game crashes or displays a message box that tells me to disable my debugger
+
 If songs keep crashing upon start and you get an error message that says
+
 ```
 DirectShow Texture3D Sample
 Could not create source filter to graph! hr=0x80040266
 ```
-despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) 
-from gamestart or use a CLVSD.ax codec which has the debugger checks removed.
+
+despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) from gamestart or use a
+CLVSD.ax codec which has the debugger checks removed.
 
 ## I used the auto timebase option and/or limited my refresh rate but the songs are still going offsync
-There aren't many options left. The old games were developed for specific
-hardware and are not guaranteed to work well on (especially) newer hardware.
-Multiple monitor setups can also have a bad impact on a stable refresh rate.
-Try a setup with just a single monitor you want to use for gameplay physically
-connected. Furthermore, dedicated and tested/verified hardware by other users 
-is recommended if you want to save yourself a lot of fiddling.
+
+Refer to the [iidx-syncbook](iidx-syncbook.md) if you haven't already.
+
+There aren't many options left. The old games were developed for specific hardware and are not
+guaranteed to work well on (especially) newer hardware. Multiple monitor setups can also have a bad
+impact on a stable refresh rate. Try a setup with just a single monitor you want to use for gameplay
+physically connected. Furthermore, dedicated and tested/verified hardware by other users is
+recommended if you want to save yourself a lot of fiddling.
 
 ## I am getting a message box with a japanese error message and a black window immediately after starting the game
-The game checks the vendor and product ID of your GPU installed. If it doesn't
-match a hardcoded whitelist, the game won't boot. Use the option *gfx.pci_id*
-either in the config file or as a cmd argument to spoof these IDs. See the
-help message for instructions and possible IDs.
+
+The game checks the vendor and product ID of your GPU installed. If it doesn't match a hardcoded
+whitelist, the game won't boot. Use the option *gfx.pci_id* either in the config file or as a cmd
+argument to spoof these IDs. See the help message for instructions and possible IDs.
 
 ## Over-/underscan, bad image quality or latency caused by my monitor's/TV's upscaler
-Many modern monitors/TVs cannot upscale 640x480 output properly. This can lead to
-over-/underscan, bad image quality or even latency caused by the upscaler of the device
-you are using.
-If one or multiple of these issues apply, use the built in scaling options by setting
-*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution
-to scale to. Usually, you want to set this to the monitor's native resolution, e.g.
-1920x1080 for full HD. You can play around with a few different filters using
-*gfx.scale_back_buffer_filter* which impacts image quality/blurriness on upscaling.
+
+Many modern monitors/TVs cannot upscale 640x480 output properly. This can lead to over-/underscan,
+bad image quality or even latency caused by the upscaler of the device you are using. If one or
+multiple of these issues apply, use the built in scaling options by setting
+*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution to scale to.
+Usually, you want to set this to the monitor's native resolution, e.g. 1920x1080 for full HD. You
+can play around with a few different filters using *gfx.scale_back_buffer_filter* which impacts
+image quality/blurriness on upscaling.
+
+## DJTroopers crashes on boot
+
+The stock game is buggy and cannot create default backup data correctly. This can be fixed by using
+existing backup data from a stock drive or by using the pre-generated backup data for the `e:\` and
+`f:\` drives provided by
+[bemanitools-supplement](https://github.com/djhackersdev/bemanitools-supplement/tree/master/iidx/15#default-backup-data).
+
+Copy those files to your target location that you have configured to store this data, e.g. local
+`e\` and `f\` folders or the target `e:\` and `f:\` volumes.

doc/iidxhook/iidxhook4-cn.md

@@ -1,7 +1,8 @@
 # Game list
 
 The following games are compatible with this version of iidxhook:
-* Resort Anthem CN (狂热节拍 IIDX)
+
+- Resort Anthem CN (狂热节拍 IIDX)
 
 The games must be bootstrapped using [inject.exe](../inject.md).
 
@@ -9,5 +10,5 @@ The games must be bootstrapped using [inject.exe](../inject.md).
 
 Resort Anthem CN (狂热节拍 IIDX):
 
-* Does not have NETWORK function
-* Game doesn't used card readers
+- Does not have NETWORK function
+- Game doesn't used card readers

doc/iidxhook/iidxhook4.md

@@ -1,29 +1,33 @@
 # Game list
 
 The following games are compatible with this version of iidxhook:
-* Resort Anthem
+
+- Resort Anthem
 
 The games must be bootstrapped using [launcher](../launcher.md).
 
 # Data setup and running the game
 
-We assume that you are using a clean/vanilla data dump. Ensure your ("concents")
-folder with your unpacked data looks like this:
+We assume that you are using a clean/vanilla data dump. Ensure your ("concents") folder with your
+unpacked data looks like this:
+
 - data
 - modules
 - prop
 
-* Copy/Move all files from the *modules* directory to the root folder, so they
-are located next to the *data* and *prop* folders.
+* Copy/Move all files from the *modules* directory to the root folder, so they are located next to
+  the *data* and *prop* folders.
 * Copy all files from *prop/defaults* to the *prop* folder.
-* Create a new file *app-config.xml* in the *prop* folder with the following
-content:
+* Create a new file *app-config.xml* in the *prop* folder with the following content:
+
 ```
 <?xml version="1.0"?>
 <param></param>
 ```
-* Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by
-replacing the *<fs>*-block in that file with the following block:
+
+- Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by replacing the
+  *<fs>*-block in that file with the following block:
+
 ```
 <fs>
     <root>
@@ -41,182 +45,175 @@ replacing the *<fs>*-block in that file with the following block:
     <nr_filedesc __type="u16">256</nr_filedesc>
 </fs>
 ```
-* Unpack the package containing iidxhook4 into the root folder so iidxhook4.dll
-and all other files are located in the same folder as *data*, *prop*, 
-*bm2dx.dll*, etc.
-* Run the gamestart-18.bat file as admin.
+
+- Unpack the package containing iidxhook4 into the root folder so iidxhook4.dll and all other files
+  are located in the same folder as *data*, *prop*, *bm2dx.dll*, etc.
+- Run the gamestart-18.bat file as admin.
 
 # Configuring iidxhook
 
-The hook library can be configured via cmd arguments or a configuration file.
-The latter is generated (*iidxhook-18.conf* in the same directory) on the first 
-start of the game using the gamestart-18.bat file. It contains default values
-for all available parameters and comments explaining each parameter. Please
-follow the comments when configuring your setup.
+The hook library can be configured via cmd arguments or a configuration file. The latter is
+generated (*iidxhook-18.conf* in the same directory) on the first start of the game using the
+gamestart-18.bat file. It contains default values for all available parameters and comments
+explaining each parameter. Please follow the comments when configuring your setup.
 
-Add the argument *-h* when running gamestart-18.bat 
-(e.g. *gamestart-18.bat -h*) to print help/usage information with a list of 
-all available parameters. Every parameter can be either set as command line
-argument or using a configuration file.
+Add the argument *-h* when running gamestart-18.bat (e.g. *gamestart-18.bat -h*) to print help/usage
+information with a list of all available parameters. Every parameter can be either set as command
+line argument or using a configuration file.
+
+To set a parameter from the command line, just add it as an argument after the bat file like this
 
-To set a parameter from the command line, just add it as an argument after
-the bat file like this
 ```
 gamestart-09.bat -p gfx.windowed=true -p gfx.framed=true
 ```
 
-The syntax for the "key=value" is the same as in the config file. Make sure
-to have a pre-ceeding "-p" for every parameter added.
+The syntax for the "key=value" is the same as in the config file. Make sure to have a pre-ceeding
+"-p" for every parameter added.
 
-However, if a parameter is specifed in the configuration file and as a command
-line argument, the command line argument overrides the config file's value.
+However, if a parameter is specifed in the configuration file and as a command line argument, the
+command line argument overrides the config file's value.
 
 # Eamuse network setup
 
-If you want to run the games online, you need a valid PCBID and the service URL.
-Open *prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and
-*ea3/network/services* nodes accordingly.
+If you want to run the games online, you need a valid PCBID and the service URL. Open
+*prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and *ea3/network/services* nodes
+accordingly.
 
-Run the game with the gamestart-18.bat file and enable network on the operator 
-menu. When enabled, the game seems to hang and expects you to power
-cycle the machine (i.e. quit the game and restart it).
+Run the game with the gamestart-18.bat file and enable network on the operator menu. When enabled,
+the game seems to hang and expects you to power cycle the machine (i.e. quit the game and restart
+it).
 
 # Real hardware support
 
 ## USB IO (ezusb)
 
 You have the following options:
-* Set `io.disable_io_emu=true` in the `iidxhook.conf` file to not hook ezusb
-IO communication with an emulation layer. The game will directly talk to the IO.
-The game supports the ezusb (C02) as well as ezusb FX2 (IO2) boards. 
-* Set `io.disable_io_emu=false` in the `iidxhook.conf` file.
-Use the specific iidxio API implementations, e.g. `iidxio-ezusb2.dll` to use
-the IO2 EZUSB board. The common `iidxio` abstraction layer also allows you to
-use custom IO boards or whatever Konami hardware is going to be available in
-the future. Obviously, someone has to write an imlementation of the `iidxio`
-API, first.
+
+- Set `io.disable_io_emu=true` in the `iidxhook.conf` file to not hook ezusb IO communication with
+  an emulation layer. The game will directly talk to the IO. The game supports the ezusb (C02) as
+  well as ezusb FX2 (IO2) boards.
+- Set `io.disable_io_emu=false` in the `iidxhook.conf` file. Use the specific iidxio API
+  implementations, e.g. `iidxio-ezusb2.dll` to use the IO2 EZUSB board. The common `iidxio`
+  abstraction layer also allows you to use custom IO boards or whatever Konami hardware is going to
+  be available in the future. Obviously, someone has to write an imlementation of the `iidxio` API,
+  first.
 
 ## Slotted/Wave pass card readers
 
 You have the following options:
-* Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook
-card reader communication with an emulation layer. The game will directly talk
-to the real readers though this only supports whatever readers the game 
-directly supports (slotted readers)
-* Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file.
-Replace the default `eamio.dll` with the `eamio-icca.dll` and have either your
-slotted (IIDX, DDR Supernova or GF/DM type) or new wave pass card readers 
-conencted and and assigned to `COM1`. Other custom implementations of of the
-`eamio` API also work.
+
+- Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook card reader
+  communication with an emulation layer. The game will directly talk to the real readers though this
+  only supports whatever readers the game directly supports (slotted readers)
+- Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file. Replace the default
+  `eamio.dll` with the `eamio-icca.dll` and have either your slotted (IIDX, DDR Supernova or GF/DM
+  type) or new wave pass card readers conencted and and assigned to `COM1`. Other custom
+  implementations of of the `eamio` API also work.
 
 ### ICCA device settings (device manager)
-* Port: COM1
-* BAUD rate: 57600
-* Data bits: 8
-* Parity: None
-* Stop bits: 1
-* Flow control: None
 
-If you encounter issues after the game opened the device, e.g. application
-stuck, try a USB <-> COM dongle instead of using one of the COM ports of the
-mainboard.
+- Port: COM1
+- BAUD rate: 57600
+- Data bits: 8
+- Parity: None
+- Stop bits: 1
+- Flow control: None
+
+If you encounter issues after the game opened the device, e.g. application stuck, try a USB \<-> COM
+dongle instead of using one of the COM ports of the mainboard.
 
 # Known bugs
+
 ## USBIO (FM-DL TIMEOUT)
-IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this 
-happens, run the game again.
+
+IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this happens, run the game
+again.
 
 # Troubleshooting and FAQ
 
 ## The game does not run "well" (frame drops, drifting offsync etc)
+
 This can be related to various issues:
-* Make sure to run the game as (true) Administrator especially on Windows 7 and
-newer. This will also get rid of various other errors (see below) that are 
-related to permission issues.
-* Run the game's process with a higher priority:
+
+- Make sure to run the game as (true) Administrator especially on Windows 7 and newer. This will
+  also get rid of various other errors (see below) that are related to permission issues.
+- Run the game's process with a higher priority:
+
 ```
 start "" /relatime "gamestart.bat"
 ```
-* Enforce v-sync enabled in your GPU settings.
-* Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx)
-that is not jumping around. Use the timebase feature of one of the newer games to
-check that or enable iidxhook's timebase and check the log output for the
-determined value. Run this a few times and check if the results differ.
-* Use iidxhook's frame rate limiter feature (see further below) to software lock
-the refresh rate. This might be necessary on Windows 7 and newer for D3D8 games,
-e.g. iidx 9 to 12, which seem to ignore GPU side v-sync.
-* Use iidxhook's auto timebase feature (see further below) or set a pre-determined
-value to cut down start-up times.
+
+Also refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## "NETWORK WARNING" instead of "NETWORK OK"
+
 This can be caused by:
-* Invalid PCBID
-* Firewall blocking connections
-* Invalid eamuse url or port specified
-* Game is not run using the Administrator account
-Make sure to check these things first
+
+- Invalid PCBID
+- Firewall blocking connections
+- Invalid eamuse url or port specified
+- Game is not run using the Administrator account Make sure to check these things first
 
 ## My songs are offsync
-The built-in monitor check just determines if the game should sync to either
-59.94 hz (S-Video setting) or 60.04 hz (VGA setting). If you don't have a setup
-that runs on (as close as possible) these values: 
-* Make sure your machine's refresh rate is stable, e.g. 60.00x hz.
-* If you don't get a close to 59.94hz (S-Video setting) or 60.04 hz 
-(VGA setting) refresh rate, go an set the output mode in the operator menu
-to "VGA" to enforce the game to run chart syncing on 60.04 hz refresh
-rate (even if your setup does not have that value). Next, use the software 
-monitor check/auto timebase that's built into iidxhook (refer to cmd 
-help/configfile).
+
+Refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## My game runs too fast
+
 iidxhook can limit the frame rate for you (refer to help/config file)
 
 ## My game crashes when I try fullscreen
+
 Use dxwnd and set settings like "Acquire admin caps" and "Fullscreen only"
 
 ## Background videos aren't working. When starting a song, windows is playing the error sound and a message box appears
+
 If you are running in window mode, you can see an error pop-up window with the title
 `DirectShow Texture3D Sample` and error message
 `Could not create source filter to graph! hr=<some number>`.
 
-When running fullscreen, you only hear a windows error sound and the game appears to be frozen
-when trying to play a background video.
+When running fullscreen, you only hear a windows error sound and the game appears to be frozen when
+trying to play a background video.
 
-You are missing a codec to decode and play the videos. There are different 
-methods available to get background videos working. Probably, the easiest 
-solution: grab the CLVSD.ax file and go to Start -> Run -> regsvr32 clvsd.ax
-Make sure to run cmd.exe as Administrator, otherwise you will get errors caused
-by invalid permissions.
+You are missing a codec to decode and play the videos. There are different methods available to get
+background videos working. Probably, the easiest solution: grab the CLVSD.ax file and go to Start ->
+Run -> regsvr32 clvsd.ax Make sure to run cmd.exe as Administrator, otherwise you will get errors
+caused by invalid permissions.
 
 ## I installed the CLVSD.ax codec but the game crashes or displays a message box that tells me to disable my debugger
+
 If songs keep crashing upon start and you get an error message that says
+
 ```
 DirectShow Texture3D Sample
 Could not create source filter to graph! hr=0x80040266
 ```
-despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) 
-from gamestart or use a CLVSD.ax codec which has the debugger checks removed.
+
+despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) from gamestart or use a
+CLVSD.ax codec which has the debugger checks removed.
 
 ## I used the auto timebase option and/or limited my refresh rate but the songs are still going offsync
-There aren't many options left. The old games were developed for specific
-hardware and are not guaranteed to work well on (especially) newer hardware.
-Multiple monitor setups can also have a bad impact on a stable refresh rate.
-Try a setup with just a single monitor you want to use for gameplay physically
-connected. Furthermore, dedicated and tested/verified hardware by other users 
-is recommended if you want to save yourself a lot of fiddling.
+
+Refer to the [iidx-syncbook](iidx-syncbook.md) if you haven't already.
+
+There aren't many options left. The old games were developed for specific hardware and are not
+guaranteed to work well on (especially) newer hardware. Multiple monitor setups can also have a bad
+impact on a stable refresh rate. Try a setup with just a single monitor you want to use for gameplay
+physically connected. Furthermore, dedicated and tested/verified hardware by other users is
+recommended if you want to save yourself a lot of fiddling.
 
 ## I am getting a message box with a japanese error message and a black window immediately after starting the game
-The game checks the vendor and product ID of your GPU installed. If it doesn't
-match a hardcoded whitelist, the game won't boot. Use the option *gfx.pci_id*
-either in the config file or as a cmd argument to spoof these IDs. See the
-help message for instructions and possible IDs.
+
+The game checks the vendor and product ID of your GPU installed. If it doesn't match a hardcoded
+whitelist, the game won't boot. Use the option *gfx.pci_id* either in the config file or as a cmd
+argument to spoof these IDs. See the help message for instructions and possible IDs.
 
 ## Over-/underscan, bad image quality or latency caused by my monitor's/TV's upscaler
-Many modern monitors/TVs cannot upscale 640x480 output properly. This can lead to
-over-/underscan, bad image quality or even latency caused by the upscaler of the device
-you are using.
-If one or multiple of these issues apply, use the built in scaling options by setting
-*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution
-to scale to. Usually, you want to set this to the monitor's native resolution, e.g.
-1920x1080 for full HD. You can play around with a few different filters using
-*gfx.scale_back_buffer_filter* which impacts image quality/blurriness on upscaling.
+
+Many modern monitors/TVs cannot upscale 640x480 output properly. This can lead to over-/underscan,
+bad image quality or even latency caused by the upscaler of the device you are using. If one or
+multiple of these issues apply, use the built in scaling options by setting
+*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution to scale to.
+Usually, you want to set this to the monitor's native resolution, e.g. 1920x1080 for full HD. You
+can play around with a few different filters using *gfx.scale_back_buffer_filter* which impacts
+image quality/blurriness on upscaling.

doc/iidxhook/iidxhook5-cn.md

@@ -1,7 +1,8 @@
 # Game list
 
 The following games are compatible with this version of iidxhook:
-* tricoro CN (狂热节拍 IIDX 2)
+
+- tricoro CN (狂热节拍 IIDX 2)
 
 The games must be bootstrapped using [inject.exe](../inject.md).
 
@@ -9,7 +10,7 @@ The games must be bootstrapped using [inject.exe](../inject.md).
 
 tricoro CN (狂热节拍 IIDX 2):
 
-* Game uses Lincle engine
-* Identifier being JDZ
-* Does not have NETWORK function
-* Game doesn't used card readers
+- Game uses Lincle engine
+- Identifier being JDZ
+- Does not have NETWORK function
+- Game doesn't used card readers

doc/iidxhook/iidxhook5.md

@@ -1,29 +1,33 @@
 # Game list
 
 The following games are compatible with this version of iidxhook:
-* Lincle
+
+- Lincle
 
 The games must be bootstrapped using [launcher](../launcher.md).
 
 # Data setup and running the game
 
-We assume that you are using a clean/vanilla data dump. Ensure your ("concents")
-folder with your unpacked data looks like this:
+We assume that you are using a clean/vanilla data dump. Ensure your ("concents") folder with your
+unpacked data looks like this:
+
 - data
 - modules
 - prop
 
-* Copy/Move all files from the *modules* directory to the root folder, so they
-are located next to the *data* and *prop* folders.
+* Copy/Move all files from the *modules* directory to the root folder, so they are located next to
+  the *data* and *prop* folders.
 * Copy all files from *prop/defaults* to the *prop* folder.
-* Create a new file *app-config.xml* in the *prop* folder with the following
-content:
+* Create a new file *app-config.xml* in the *prop* folder with the following content:
+
 ```
 <?xml version="1.0"?>
 <param></param>
 ```
-* Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by
-replacing the *<fs>*-block in that file with the following block:
+
+- Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by replacing the
+  *<fs>*-block in that file with the following block:
+
 ```
 <fs>
     <root>
@@ -41,170 +45,165 @@ replacing the *<fs>*-block in that file with the following block:
     <nr_filedesc __type="u16">256</nr_filedesc>
 </fs>
 ```
-* Unpack the package containing iidxhook5 into the root folder so iidxhook5.dll
-and all other files are located in the same folder as *data*, *prop*, 
-*bm2dx.dll*, etc.
-* Run the gamestart-19.bat file as admin.
+
+- Unpack the package containing iidxhook5 into the root folder so iidxhook5.dll and all other files
+  are located in the same folder as *data*, *prop*, *bm2dx.dll*, etc.
+- Run the gamestart-19.bat file as admin.
 
 # Configuring iidxhook
 
-The hook library can be configured via cmd arguments or a configuration file.
-The latter is generated (*iidxhook-19.conf* in the same directory) on the first 
-start of the game using the gamestart-19.bat file. It contains default values
-for all available parameters and comments explaining each parameter. Please
-follow the comments when configuring your setup.
+The hook library can be configured via cmd arguments or a configuration file. The latter is
+generated (*iidxhook-19.conf* in the same directory) on the first start of the game using the
+gamestart-19.bat file. It contains default values for all available parameters and comments
+explaining each parameter. Please follow the comments when configuring your setup.
 
-Add the argument *-h* when running gamestart-19.bat 
-(e.g. *gamestart-19.bat -h*) to print help/usage information with a list of 
-all available parameters. Every parameter can be either set as command line
-argument or using a configuration file.
+Add the argument *-h* when running gamestart-19.bat (e.g. *gamestart-19.bat -h*) to print help/usage
+information with a list of all available parameters. Every parameter can be either set as command
+line argument or using a configuration file.
+
+To set a parameter from the command line, just add it as an argument after the bat file like this
 
-To set a parameter from the command line, just add it as an argument after
-the bat file like this
 ```
 gamestart-09.bat -p gfx.windowed=true -p gfx.framed=true
 ```
 
-The syntax for the "key=value" is the same as in the config file. Make sure
-to have a pre-ceeding "-p" for every parameter added.
+The syntax for the "key=value" is the same as in the config file. Make sure to have a pre-ceeding
+"-p" for every parameter added.
 
-However, if a parameter is specifed in the configuration file and as a command
-line argument, the command line argument overrides the config file's value.
+However, if a parameter is specifed in the configuration file and as a command line argument, the
+command line argument overrides the config file's value.
 
 # Eamuse network setup
 
-If you want to run the games online, you need a valid PCBID and the service URL.
-Open *prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and
-*ea3/network/services* nodes accordingly.
+If you want to run the games online, you need a valid PCBID and the service URL. Open
+*prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and *ea3/network/services* nodes
+accordingly.
 
-Run the game with the gamestart-19.bat file and enable network on the operator 
-menu. When enabled, the game seems to hang and expects you to power
-cycle the machine (i.e. quit the game and restart it).
+Run the game with the gamestart-19.bat file and enable network on the operator menu. When enabled,
+the game seems to hang and expects you to power cycle the machine (i.e. quit the game and restart
+it).
 
 # Real hardware support
 
 ## USB IO (ezusb)
 
 You have the following options:
-* Set `io.disable_io_emu=true` in the `iidxhook.conf` file to not hook ezusb
-IO communication with an emulation layer. The game will directly talk to the IO.
-The game supports the ezusb (C02) as well as ezusb FX2 (IO2) boards. 
-* Set `io.disable_io_emu=false` in the `iidxhook.conf` file.
-Use the specific iidxio API implementations, e.g. `iidxio-ezusb2.dll` to use
-the IO2 EZUSB board. The common `iidxio` abstraction layer also allows you to
-use custom IO boards or whatever Konami hardware is going to be available in
-the future. Obviously, someone has to write an imlementation of the `iidxio`
-API, first.
+
+- Set `io.disable_io_emu=true` in the `iidxhook.conf` file to not hook ezusb IO communication with
+  an emulation layer. The game will directly talk to the IO. The game supports the ezusb (C02) as
+  well as ezusb FX2 (IO2) boards.
+- Set `io.disable_io_emu=false` in the `iidxhook.conf` file. Use the specific iidxio API
+  implementations, e.g. `iidxio-ezusb2.dll` to use the IO2 EZUSB board. The common `iidxio`
+  abstraction layer also allows you to use custom IO boards or whatever Konami hardware is going to
+  be available in the future. Obviously, someone has to write an imlementation of the `iidxio` API,
+  first.
 
 ## Slotted/Wave pass card readers
 
 You have the following options:
-* Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook
-card reader communication with an emulation layer. The game will directly talk
-to the real readers though this only supports whatever readers the game 
-directly supports (wave pass readers)
-* Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file.
-Replace the default `eamio.dll` with the `eamio-icca.dll` and have either your
-slotted (IIDX, DDR Supernova or GF/DM type) or new wave pass card readers 
-conencted and and assigned to `COM1`. Other custom implementations of of the
-`eamio` API also work.
+
+- Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook card reader
+  communication with an emulation layer. The game will directly talk to the real readers though this
+  only supports whatever readers the game directly supports (wave pass readers)
+- Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file. Replace the default
+  `eamio.dll` with the `eamio-icca.dll` and have either your slotted (IIDX, DDR Supernova or GF/DM
+  type) or new wave pass card readers conencted and and assigned to `COM1`. Other custom
+  implementations of of the `eamio` API also work.
 
 ### ICCA device settings (device manager)
-* Port: COM1
-* BAUD rate: 57600
-* Data bits: 8
-* Parity: None
-* Stop bits: 1
-* Flow control: None
 
-If you encounter issues after the game opened the device, e.g. application
-stuck, try a USB <-> COM dongle instead of using one of the COM ports of the
-mainboard.
+- Port: COM1
+- BAUD rate: 57600
+- Data bits: 8
+- Parity: None
+- Stop bits: 1
+- Flow control: None
+
+If you encounter issues after the game opened the device, e.g. application stuck, try a USB \<-> COM
+dongle instead of using one of the COM ports of the mainboard.
 
 # Known bugs
+
 ## USBIO (FM-DL TIMEOUT)
-IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this 
-happens, run the game again. 
+
+IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this happens, run the game
+again.
 
 # Troubleshooting and FAQ
 
 ## The game does not run "well" (frame drops, drifting offsync etc)
+
 This can be related to various issues:
-* Make sure to run the game as (true) Administrator especially on Windows 7 and
-newer. This will also get rid of various other errors (see below) that are 
-related to permission issues.
-* Run the game's process with a higher priority:
+
+- Make sure to run the game as (true) Administrator especially on Windows 7 and newer. This will
+  also get rid of various other errors (see below) that are related to permission issues.
+- Run the game's process with a higher priority:
+
 ```
 start "" /relatime "gamestart.bat"
 ```
-* Enforce v-sync enabled in your GPU settings.
-* Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx)
-that is not jumping around. Use the timebase feature of one of the newer games to
-check that or enable iidxhook's timebase and check the log output for the
-determined value. Run this a few times and check if the results differ.
-* Use iidxhook's frame rate limiter feature (see further below) to software lock
-the refresh rate. This might be necessary on Windows 7 and newer for D3D8 games,
-e.g. iidx 9 to 12, which seem to ignore GPU side v-sync.
-* Use iidxhook's auto timebase feature (see further below) or set a pre-determined
-value to cut down start-up times.
+
+Also refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## "NETWORK WARNING" instead of "NETWORK OK"
+
 This can be caused by:
-* Invalid PCBID
-* Firewall blocking connections
-* Invalid eamuse url or port specified
-* Game is not run using the Administrator account
-Make sure to check these things first
+
+- Invalid PCBID
+- Firewall blocking connections
+- Invalid eamuse url or port specified
+- Game is not run using the Administrator account Make sure to check these things first
 
 ## My songs are offsync
-From this version onwards (if you use the very final data of Lincle), the game
-comes with a built-in auto timebase option ("monitor check" on startup) which
-dynamically, detects the refresh rate of your current setup. Thus, BT5's 
-timebase option is not included from this hook version onwards, anymore.
-Ensure that refresh rate displayed is very stable, e.g. 60.00x hz, and the
-game should be able to provide you with a smooth and sync game experience.
+
+Refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## My game runs too fast
+
 iidxhook can limit the frame rate for you (refer to help/config file)
 
 ## My game crashes when I try fullscreen
+
 Use dxwnd and set settings like "Acquire admin caps" and "Fullscreen only"
 
 ## Background videos aren't working. When starting a song, windows is playing the error sound and a message box appears
+
 If you are running in window mode, you can see an error pop-up window with the title
 `DirectShow Texture3D Sample` and error message
 `Could not create source filter to graph! hr=<some number>`.
 
-When running fullscreen, you only hear a windows error sound and the game appears to be frozen
-when trying to play a background video.
+When running fullscreen, you only hear a windows error sound and the game appears to be frozen when
+trying to play a background video.
 
-You are missing a codec to decode and play the videos. There are different 
-methods available to get background videos working. Probably, the easiest 
-solution: grab the CLVSD.ax file and go to Start -> Run -> regsvr32 clvsd.ax
-Make sure to run cmd.exe as Administrator, otherwise you will get errors caused
-by invalid permissions.
+You are missing a codec to decode and play the videos. There are different methods available to get
+background videos working. Probably, the easiest solution: grab the CLVSD.ax file and go to Start ->
+Run -> regsvr32 clvsd.ax Make sure to run cmd.exe as Administrator, otherwise you will get errors
+caused by invalid permissions.
 
 ## I installed the CLVSD.ax codec but the game crashes or displays a message box that tells me to disable my debugger
+
 If songs keep crashing upon start and you get an error message that says
+
 ```
 DirectShow Texture3D Sample
 Could not create source filter to graph! hr=0x80040266
 ```
-despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) 
-from gamestart or use a CLVSD.ax codec which has the debugger checks removed.
+
+despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) from gamestart or use a
+CLVSD.ax codec which has the debugger checks removed.
 
 ## I am getting a message box with a japanese error message and a black window immediately after starting the game
-The game checks the vendor and product ID of your GPU installed. If it doesn't
-match a hardcoded whitelist, the game won't boot. Use the option *gfx.pci_id*
-either in the config file or as a cmd argument to spoof these IDs. See the
-help message for instructions and possible IDs.
+
+The game checks the vendor and product ID of your GPU installed. If it doesn't match a hardcoded
+whitelist, the game won't boot. Use the option *gfx.pci_id* either in the config file or as a cmd
+argument to spoof these IDs. See the help message for instructions and possible IDs.
 
 ## Over-/underscan, bad image quality or latency caused by my monitor's/TV's upscaler
-Many modern monitors/TVs cannot upscale 640x480 output properly. This can lead to
-over-/underscan, bad image quality or even latency caused by the upscaler of the device
-you are using.
-If one or multiple of these issues apply, use the built in scaling options by setting
-*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution
-to scale to. Usually, you want to set this to the monitor's native resolution, e.g.
-1920x1080 for full HD. You can play around with a few different filters using
-*gfx.scale_back_buffer_filter* which impacts image quality/blurriness on upscaling.
+
+Many modern monitors/TVs cannot upscale 640x480 output properly. This can lead to over-/underscan,
+bad image quality or even latency caused by the upscaler of the device you are using. If one or
+multiple of these issues apply, use the built in scaling options by setting
+*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution to scale to.
+Usually, you want to set this to the monitor's native resolution, e.g. 1920x1080 for full HD. You
+can play around with a few different filters using *gfx.scale_back_buffer_filter* which impacts
+image quality/blurriness on upscaling.

doc/iidxhook/iidxhook6.md

@@ -1,29 +1,33 @@
 # Game list
 
 The following games are compatible with this version of iidxhook:
-* Tricoro
+
+- Tricoro
 
 The games must be bootstrapped using [launcher](../launcher.md).
 
 # Data setup and running the game
 
-We assume that you are using a clean/vanilla data dump. Ensure your ("concents")
-folder with your unpacked data looks like this:
+We assume that you are using a clean/vanilla data dump. Ensure your ("concents") folder with your
+unpacked data looks like this:
+
 - data
 - modules
 - prop
 
-* Copy/Move all files from the *modules* directory to the root folder, so they
-are located next to the *data* and *prop* folders.
+* Copy/Move all files from the *modules* directory to the root folder, so they are located next to
+  the *data* and *prop* folders.
 * Copy all files from *prop/defaults* to the *prop* folder.
-* Create a new file *app-config.xml* in the *prop* folder with the following
-content:
+* Create a new file *app-config.xml* in the *prop* folder with the following content:
+
 ```
 <?xml version="1.0"?>
 <param></param>
 ```
-* Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by
-replacing the *<fs>*-block in that file with the following block:
+
+- Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by replacing the
+  *<fs>*-block in that file with the following block:
+
 ```
 <fs>
     <root>
@@ -41,8 +45,9 @@ replacing the *<fs>*-block in that file with the following block:
     <nr_filedesc __type="u16">256</nr_filedesc>
 </fs>
 ```
-* Setup valid logger configuration by replacing the *<log>*-block in 
-*prop/avs-config.xml* with:
+
+- Setup valid logger configuration by replacing the *<log>*-block in *prop/avs-config.xml* with:
+
 ```
 <log>
     <netsci>
@@ -52,165 +57,165 @@ replacing the *<fs>*-block in that file with the following block:
     <level __type="str">misc</level>
 </log>
 ```
-* Unpack the package containing iidxhook6 into the root folder so iidxhook6.dll
-and all other files are located in the same folder as *data*, *prop*, 
-*bm2dx.dll*, etc.
-* Run the gamestart-20.bat file as admin.
+
+- Unpack the package containing iidxhook6 into the root folder so iidxhook6.dll and all other files
+  are located in the same folder as *data*, *prop*, *bm2dx.dll*, etc.
+- Run the gamestart-20.bat file as admin.
 
 # Configuring iidxhook
 
-The hook library can be configured via cmd arguments or a configuration file.
-The latter is generated (*iidxhook-20.conf* in the same directory) on the first 
-start of the game using the gamestart-20.bat file. It contains default values
-for all available parameters and comments explaining each parameter. Please
-follow the comments when configuring your setup.
+The hook library can be configured via cmd arguments or a configuration file. The latter is
+generated (*iidxhook-20.conf* in the same directory) on the first start of the game using the
+gamestart-20.bat file. It contains default values for all available parameters and comments
+explaining each parameter. Please follow the comments when configuring your setup.
 
-Add the argument *-h* when running gamestart-20.bat 
-(e.g. *gamestart-20.bat -h*) to print help/usage information with a list of 
-all available parameters. Every parameter can be either set as command line
-argument or using a configuration file.
+Add the argument *-h* when running gamestart-20.bat (e.g. *gamestart-20.bat -h*) to print help/usage
+information with a list of all available parameters. Every parameter can be either set as command
+line argument or using a configuration file.
+
+To set a parameter from the command line, just add it as an argument after the bat file like this
 
-To set a parameter from the command line, just add it as an argument after
-the bat file like this
 ```
 gamestart-09.bat -p gfx.windowed=true -p gfx.framed=true
 ```
 
-The syntax for the "key=value" is the same as in the config file. Make sure
-to have a pre-ceeding "-p" for every parameter added.
+The syntax for the "key=value" is the same as in the config file. Make sure to have a pre-ceeding
+"-p" for every parameter added.
 
-However, if a parameter is specifed in the configuration file and as a command
-line argument, the command line argument overrides the config file's value.
+However, if a parameter is specifed in the configuration file and as a command line argument, the
+command line argument overrides the config file's value.
 
 # Eamuse network setup
 
-If you want to run the games online, you need a valid PCBID and the service URL.
-Open *prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and
-*ea3/network/services* nodes accordingly.
+If you want to run the games online, you need a valid PCBID and the service URL. Open
+*prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and *ea3/network/services* nodes
+accordingly.
 
-Run the game with the gamestart-20.bat file and enable network on the operator 
-menu. When enabled, the game seems to hang and expects you to power
-cycle the machine (i.e. quit the game and restart it).
+Run the game with the gamestart-20.bat file and enable network on the operator menu. When enabled,
+the game seems to hang and expects you to power cycle the machine (i.e. quit the game and restart
+it).
 
 # Real hardware support
 
 ## USB IO (ezusb)
 
 You have the following options:
-* Set `io.disable_io_emu=true` in the `iidxhook.conf` file to not hook ezusb
-IO communication with an emulation layer. The game will directly talk to the IO.
-The game supports the ezusb (C02) as well as ezusb FX2 (IO2) boards. 
-* Set `io.disable_io_emu=false` in the `iidxhook.conf` file.
-Use the specific iidxio API implementations, e.g. `iidxio-ezusb2.dll` to use
-the IO2 EZUSB board. The common `iidxio` abstraction layer also allows you to
-use custom IO boards or whatever Konami hardware is going to be available in
-the future. Obviously, someone has to write an imlementation of the `iidxio`
-API, first.
+
+- Set `io.disable_io_emu=true` in the `iidxhook.conf` file to not hook ezusb IO communication with
+  an emulation layer. The game will directly talk to the IO. The game supports the ezusb (C02) as
+  well as ezusb FX2 (IO2) boards.
+- Set `io.disable_io_emu=false` in the `iidxhook.conf` file. Use the specific iidxio API
+  implementations, e.g. `iidxio-ezusb2.dll` to use the IO2 EZUSB board. The common `iidxio`
+  abstraction layer also allows you to use custom IO boards or whatever Konami hardware is going to
+  be available in the future. Obviously, someone has to write an imlementation of the `iidxio` API,
+  first.
 
 ## Slotted/Wave pass card readers
 
 You have the following options:
-* Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook
-card reader communication with an emulation layer. The game will directly talk
-to the real readers though this only supports whatever readers the game 
-directly supports (wave pass readers)
-* Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file.
-Replace the default `eamio.dll` with the `eamio-icca.dll` and have either your
-slotted (IIDX, DDR Supernova or GF/DM type) or new wave pass card readers 
-conencted and and assigned to `COM1`. Other custom implementations of of the
-`eamio` API also work.
+
+- Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook card reader
+  communication with an emulation layer. The game will directly talk to the real readers though this
+  only supports whatever readers the game directly supports (wave pass readers)
+- Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file. Replace the default
+  `eamio.dll` with the `eamio-icca.dll` and have either your slotted (IIDX, DDR Supernova or GF/DM
+  type) or new wave pass card readers conencted and and assigned to `COM1`. Other custom
+  implementations of of the `eamio` API also work.
 
 ### ICCA device settings (device manager)
-* Port: COM1
-* BAUD rate: 57600
-* Data bits: 8
-* Parity: None
-* Stop bits: 1
-* Flow control: None
 
-If you encounter issues after the game opened the device, e.g. application
-stuck, try a USB <-> COM dongle instead of using one of the COM ports of the
-mainboard.
+- Port: COM1
+- BAUD rate: 57600
+- Data bits: 8
+- Parity: None
+- Stop bits: 1
+- Flow control: None
+
+If you encounter issues after the game opened the device, e.g. application stuck, try a USB \<-> COM
+dongle instead of using one of the COM ports of the mainboard.
 
 # Known bugs
+
 ## USBIO (FM-DL TIMEOUT)
-IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this 
-happens, run the game again. 
+
+IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this happens, run the game
+again.
 
 # Troubleshooting and FAQ
 
 ## The game does not run "well" (frame drops, drifting offsync etc)
+
 This can be related to various issues:
-* Make sure to run the game as (true) Administrator especially on Windows 7 and
-newer. This will also get rid of various other errors (see below) that are 
-related to permission issues.
-* Run the game's process with a higher priority:
+
+- Make sure to run the game as (true) Administrator especially on Windows 7 and newer. This will
+  also get rid of various other errors (see below) that are related to permission issues.
+- Run the game's process with a higher priority:
+
 ```
 start "" /relatime "gamestart.bat"
 ```
-* Enforce v-sync enabled in your GPU settings.
-* Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx)
-that is not jumping around. Use the timebase feature of one of the newer games to
-check that or enable iidxhook's timebase and check the log output for the
-determined value. Run this a few times and check if the results differ.
+
+Also refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## "NETWORK WARNING" instead of "NETWORK OK"
+
 This can be caused by:
-* Invalid PCBID
-* Firewall blocking connections
-* Invalid eamuse url or port specified
-* Game is not run using the Administrator account
-Make sure to check these things first
+
+- Invalid PCBID
+- Firewall blocking connections
+- Invalid eamuse url or port specified
+- Game is not run using the Administrator account Make sure to check these things first
 
 ## My songs are offsync
-From this version onwards (or Lincle very final revision), the game comes with 
-a built-in auto timebase option ("monitor check" on startup) which
-dynamically, detects the refresh rate of your current setup. Thus, BT5's 
-timebase option is not included from this hook version onwards, anymore.
-Ensure that refresh rate displayed is very stable, e.g. 60.00x hz, and the
-game should be able to provide you with a smooth and sync game experience.
+
+Refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## My game runs too fast
+
 iidxhook can limit the frame rate for you (refer to help/config file)
 
 ## My game crashes when I try fullscreen
+
 Use dxwnd and set settings like "Acquire admin caps" and "Fullscreen only"
 
 ## Background videos aren't working. When starting a song, windows is playing the error sound and a message box appears
+
 If you are running in window mode, you can see an error pop-up window with the title
 `DirectShow Texture3D Sample` and error message
 `Could not create source filter to graph! hr=<some number>`.
 
-When running fullscreen, you only hear a windows error sound and the game appears to be frozen
-when trying to play a background video.
+When running fullscreen, you only hear a windows error sound and the game appears to be frozen when
+trying to play a background video.
 
-You are missing a codec to decode and play the videos. There are different 
-methods available to get background videos working. Probably, the easiest 
-solution: grab the CLVSD.ax file and go to Start -> Run -> regsvr32 clvsd.ax
-Make sure to run cmd.exe as Administrator, otherwise you will get errors caused
-by invalid permissions.
+You are missing a codec to decode and play the videos. There are different methods available to get
+background videos working. Probably, the easiest solution: grab the CLVSD.ax file and go to Start ->
+Run -> regsvr32 clvsd.ax Make sure to run cmd.exe as Administrator, otherwise you will get errors
+caused by invalid permissions.
 
 ## I installed the CLVSD.ax codec but the game crashes or displays a message box that tells me to disable my debugger
+
 If songs keep crashing upon start and you get an error message that says
+
 ```
 DirectShow Texture3D Sample
 Could not create source filter to graph! hr=0x80040266
 ```
-despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) 
-from gamestart or use a CLVSD.ax codec which has the debugger checks removed.
+
+despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) from gamestart or use a
+CLVSD.ax codec which has the debugger checks removed.
 
 ## I am getting a message box with a japanese error message and a black window immediately after starting the game
-The game checks the vendor and product ID of your GPU installed. If it doesn't
-match a hardcoded whitelist, the game won't boot. Use the option *gfx.pci_id*
-either in the config file or as a cmd argument to spoof these IDs. See the
-help message for instructions and possible IDs.
+
+The game checks the vendor and product ID of your GPU installed. If it doesn't match a hardcoded
+whitelist, the game won't boot. Use the option *gfx.pci_id* either in the config file or as a cmd
+argument to spoof these IDs. See the help message for instructions and possible IDs.
 
 ## Over-/underscan, bad image quality or latency caused by my monitor's/TV's upscaler
-Many modern monitors/TVs cannot upscale some lower resolutions, e.g. 640x480, properly.
-This can lead to over-/underscan, bad image quality or even latency caused by the upscaler
-of the device you are using.
-If one or multiple of these issues apply, use the built in scaling options by setting
-*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution
-to scale to. Usually, you want to set this to the monitor's native resolution, e.g.
-1920x1080 for full HD. You can play around with a few different filters using
-*gfx.scale_back_buffer_filter* which impacts image quality/blurriness on upscaling.
+
+Many modern monitors/TVs cannot upscale some lower resolutions, e.g. 640x480, properly. This can
+lead to over-/underscan, bad image quality or even latency caused by the upscaler of the device you
+are using. If one or multiple of these issues apply, use the built in scaling options by setting
+*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution to scale to.
+Usually, you want to set this to the monitor's native resolution, e.g. 1920x1080 for full HD. You
+can play around with a few different filters using *gfx.scale_back_buffer_filter* which impacts
+image quality/blurriness on upscaling.

doc/iidxhook/iidxhook7.md

@@ -1,32 +1,36 @@
 # Game list
 
 The following games are compatible with this version of iidxhook:
-* SPADA
-* PENDUAL
-* copula
-* SINOBUZ
+
+- SPADA
+- PENDUAL
+- copula
+- SINOBUZ
 
 The games must be bootstrapped using [launcher](../launcher.md).
 
 # Data setup and running the game
 
-We assume that you are using a clean/vanilla data dump. Ensure your ("concents")
-folder with your unpacked data looks like this:
+We assume that you are using a clean/vanilla data dump. Ensure your ("concents") folder with your
+unpacked data looks like this:
+
 - data
 - modules
 - prop
 
-* Copy/Move all files from the *modules* directory to the root folder, so they
-are located next to the *data* and *prop* folders.
+* Copy/Move all files from the *modules* directory to the root folder, so they are located next to
+  the *data* and *prop* folders.
 * Copy all files from *prop/defaults* to the *prop* folder.
-* Create a new file *app-config.xml* in the *prop* folder with the following
-content:
+* Create a new file *app-config.xml* in the *prop* folder with the following content:
+
 ```
 <?xml version="1.0"?>
 <param></param>
 ```
-* Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by
-replacing the *<fs>*-block in that file with the following block:
+
+- Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by replacing the
+  *<fs>*-block in that file with the following block:
+
 ```
 <fs>
     <root>
@@ -44,8 +48,9 @@ replacing the *<fs>*-block in that file with the following block:
     <nr_filedesc __type="u16">256</nr_filedesc>
 </fs>
 ```
-* Setup valid logger configuration by replacing the *<log>*-block in 
-*prop/avs-config.xml* with:
+
+- Setup valid logger configuration by replacing the *<log>*-block in *prop/avs-config.xml* with:
+
 ```
 <log>
     <netsci>
@@ -55,168 +60,166 @@ replacing the *<fs>*-block in that file with the following block:
     <level __type="str">misc</level>
 </log>
 ```
-* Unpack the package containing iidxhook7 into the root folder so iidxhook7.dll
-and all other files are located in the same folder as *data*, *prop*, 
-*bm2dx.dll*, etc.
-* Run the gamestart-XX.bat file as admin. Where XX matches the version you 
-want to run.
+
+- Unpack the package containing iidxhook7 into the root folder so iidxhook7.dll and all other files
+  are located in the same folder as *data*, *prop*, *bm2dx.dll*, etc.
+- Run the gamestart-XX.bat file as admin. Where XX matches the version you want to run.
 
 # Configuring iidxhook
 
-The hook library can be configured via cmd arguments or a configuration file.
-The latter is generated (*iidxhook-XX.conf* in the same directory) on the first 
-start of the game using the gamestart-XX.bat file (again, XX matches your target
-game version). It contains default values for all available parameters and 
-comments explaining each parameter. Please follow the comments when configuring 
-your setup.
+The hook library can be configured via cmd arguments or a configuration file. The latter is
+generated (*iidxhook-XX.conf* in the same directory) on the first start of the game using the
+gamestart-XX.bat file (again, XX matches your target game version). It contains default values for
+all available parameters and comments explaining each parameter. Please follow the comments when
+configuring your setup.
 
-Add the argument *-h* when running gamestart-XX.bat 
-(e.g. *gamestart-XX.bat -h*) to print help/usage information with a list of 
-all available parameters. Every parameter can be either set as command line
-argument or using a configuration file.
+Add the argument *-h* when running gamestart-XX.bat (e.g. *gamestart-XX.bat -h*) to print help/usage
+information with a list of all available parameters. Every parameter can be either set as command
+line argument or using a configuration file.
+
+To set a parameter from the command line, just add it as an argument after the bat file like this
 
-To set a parameter from the command line, just add it as an argument after
-the bat file like this
 ```
 gamestart-09.bat -p gfx.windowed=true -p gfx.framed=true
 ```
 
-The syntax for the "key=value" is the same as in the config file. Make sure
-to have a pre-ceeding "-p" for every parameter added.
+The syntax for the "key=value" is the same as in the config file. Make sure to have a pre-ceeding
+"-p" for every parameter added.
 
-However, if a parameter is specifed in the configuration file and as a command
-line argument, the command line argument overrides the config file's value.
+However, if a parameter is specifed in the configuration file and as a command line argument, the
+command line argument overrides the config file's value.
 
 # Eamuse network setup
 
-If you want to run the games online, you need a valid PCBID and the service URL.
-Open *prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and
-*ea3/network/services* nodes accordingly.
+If you want to run the games online, you need a valid PCBID and the service URL. Open
+*prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and *ea3/network/services* nodes
+accordingly.
 
-Run the game with the gamestart-XX.bat file and enable network on the operator 
-menu. When enabled, the game seems to hang and expects you to power
-cycle the machine (i.e. quit the game and restart it).
+Run the game with the gamestart-XX.bat file and enable network on the operator menu. When enabled,
+the game seems to hang and expects you to power cycle the machine (i.e. quit the game and restart
+it).
 
 # Real hardware support
 
 ## USB IO (ezusb)
 
 You have the following options:
-* Set `io.disable_io_emu=true` in the `iidxhook.conf` file to not hook ezusb
-IO communication with an emulation layer. The game will directly talk to the IO.
-The game supports the ezusb (C02) as well as ezusb FX2 (IO2) boards. 
-* Set `io.disable_io_emu=false` in the `iidxhook.conf` file.
-Use the specific iidxio API implementations, e.g. `iidxio-ezusb2.dll` to use
-the IO2 EZUSB board. The common `iidxio` abstraction layer also allows you to
-use custom IO boards or whatever Konami hardware is going to be available in
-the future. Obviously, someone has to write an imlementation of the `iidxio`
-API, first.
+
+- Set `io.disable_io_emu=true` in the `iidxhook.conf` file to not hook ezusb IO communication with
+  an emulation layer. The game will directly talk to the IO. The game supports the ezusb (C02) as
+  well as ezusb FX2 (IO2) boards.
+- Set `io.disable_io_emu=false` in the `iidxhook.conf` file. Use the specific iidxio API
+  implementations, e.g. `iidxio-ezusb2.dll` to use the IO2 EZUSB board. The common `iidxio`
+  abstraction layer also allows you to use custom IO boards or whatever Konami hardware is going to
+  be available in the future. Obviously, someone has to write an imlementation of the `iidxio` API,
+  first.
 
 ## Slotted/Wave pass card readers
 
 You have the following options:
-* Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook
-card reader communication with an emulation layer. The game will directly talk
-to the real readers though this only supports whatever readers the game 
-directly supports (wave pass readers)
-* Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file.
-Replace the default `eamio.dll` with the `eamio-icca.dll` and have either your
-slotted (IIDX, DDR Supernova or GF/DM type) or new wave pass card readers 
-conencted and and assigned to `COM1`. Other custom implementations of of the
-`eamio` API also work.
+
+- Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook card reader
+  communication with an emulation layer. The game will directly talk to the real readers though this
+  only supports whatever readers the game directly supports (wave pass readers)
+- Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file. Replace the default
+  `eamio.dll` with the `eamio-icca.dll` and have either your slotted (IIDX, DDR Supernova or GF/DM
+  type) or new wave pass card readers conencted and and assigned to `COM1`. Other custom
+  implementations of of the `eamio` API also work.
 
 ### ICCA device settings (device manager)
-* Port: COM1
-* BAUD rate: 57600
-* Data bits: 8
-* Parity: None
-* Stop bits: 1
-* Flow control: None
 
-If you encounter issues after the game opened the device, e.g. application
-stuck, try a USB <-> COM dongle instead of using one of the COM ports of the
-mainboard.
+- Port: COM1
+- BAUD rate: 57600
+- Data bits: 8
+- Parity: None
+- Stop bits: 1
+- Flow control: None
+
+If you encounter issues after the game opened the device, e.g. application stuck, try a USB \<-> COM
+dongle instead of using one of the COM ports of the mainboard.
 
 # Known bugs
+
 ## USBIO (FM-DL TIMEOUT)
-IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this 
-happens, run the game again. 
+
+IIDX occasionally fails to boot with a "USBIO (FM-DL TIMEOUT)" error. If this happens, run the game
+again.
 
 # Troubleshooting and FAQ
 
 ## The game does not run "well" (frame drops, drifting offsync etc)
+
 This can be related to various issues:
-* Make sure to run the game as (true) Administrator especially on Windows 7 and
-newer. This will also get rid of various other errors (see below) that are 
-related to permission issues.
-* Run the game's process with a higher priority:
+
+- Make sure to run the game as (true) Administrator especially on Windows 7 and newer. This will
+  also get rid of various other errors (see below) that are related to permission issues.
+- Run the game's process with a higher priority:
+
 ```
 start "" /relatime "gamestart.bat"
 ```
-* Enforce v-sync enabled in your GPU settings.
-* Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx)
-that is not jumping around. Use the timebase feature of one of the newer games to
-check that or enable iidxhook's timebase and check the log output for the
-determined value. Run this a few times and check if the results differ.
+
+Also refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## "NETWORK WARNING" instead of "NETWORK OK"
+
 This can be caused by:
-* Invalid PCBID
-* Firewall blocking connections
-* Invalid eamuse url or port specified
-* Game is not run using the Administrator account
-Make sure to check these things first
+
+- Invalid PCBID
+- Firewall blocking connections
+- Invalid eamuse url or port specified
+- Game is not run using the Administrator account Make sure to check these things first
 
 ## My songs are offsync
-From IIDX 20 (or Lincle very final revision) onwards, the game comes with 
-a built-in auto timebase option ("monitor check" on startup) which
-dynamically, detects the refresh rate of your current setup. Thus, BT5's 
-timebase option is not included from this hook version onwards, anymore.
-Ensure that refresh rate displayed is very stable, e.g. 60.00x hz, and the
-game should be able to provide you with a smooth and sync game experience.
+
+Refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## My game runs too fast
+
 iidxhook can limit the frame rate for you (refer to help/config file)
 
 ## My game crashes when I try fullscreen
+
 Use dxwnd and set settings like "Acquire admin caps" and "Fullscreen only"
 
 ## Background videos aren't working. When starting a song, windows is playing the error sound and a message box appears
+
 If you are running in window mode, you can see an error pop-up window with the title
 `DirectShow Texture3D Sample` and error message
 `Could not create source filter to graph! hr=<some number>`.
 
-When running fullscreen, you only hear a windows error sound and the game appears to be frozen
-when trying to play a background video.
+When running fullscreen, you only hear a windows error sound and the game appears to be frozen when
+trying to play a background video.
 
-You are missing a codec to decode and play the videos. There are different 
-methods available to get background videos working. Probably, the easiest 
-solution: grab the CLVSD.ax file and go to Start -> Run -> regsvr32 clvsd.ax
-Make sure to run cmd.exe as Administrator, otherwise you will get errors caused
-by invalid permissions.
+You are missing a codec to decode and play the videos. There are different methods available to get
+background videos working. Probably, the easiest solution: grab the CLVSD.ax file and go to Start ->
+Run -> regsvr32 clvsd.ax Make sure to run cmd.exe as Administrator, otherwise you will get errors
+caused by invalid permissions.
 
 ## I installed the CLVSD.ax codec but the game crashes or displays a message box that tells me to disable my debugger
+
 If songs keep crashing upon start and you get an error message that says
+
 ```
 DirectShow Texture3D Sample
 Could not create source filter to graph! hr=0x80040266
 ```
-despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) 
-from gamestart or use a CLVSD.ax codec which has the debugger checks removed.
+
+despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) from gamestart or use a
+CLVSD.ax codec which has the debugger checks removed.
 
 ## I am getting a message box with a japanese error message and a black window immediately after starting the game
-The game checks the vendor and product ID of your GPU installed. If it doesn't
-match a hardcoded whitelist, the game won't boot. Use the option *gfx.pci_id*
-either in the config file or as a cmd argument to spoof these IDs. See the
-help message for instructions and possible IDs.
+
+The game checks the vendor and product ID of your GPU installed. If it doesn't match a hardcoded
+whitelist, the game won't boot. Use the option *gfx.pci_id* either in the config file or as a cmd
+argument to spoof these IDs. See the help message for instructions and possible IDs.
 
 ## Over-/underscan, bad image quality or latency caused by my monitor's/TV's upscaler
-Many modern monitors/TVs cannot upscale some lower resolutions, e.g. 640x480, properly.
-This can lead to over-/underscan, bad image quality or even latency caused by the upscaler
-of the device you are using.
-If one or multiple of these issues apply, use the built in scaling options by setting
-*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution
-to scale to. Usually, you want to set this to the monitor's native resolution, e.g.
-1920x1080 for full HD. You can play around with a few different filters using
-*gfx.scale_back_buffer_filter* which impacts image quality/blurriness on upscaling.
 
+Many modern monitors/TVs cannot upscale some lower resolutions, e.g. 640x480, properly. This can
+lead to over-/underscan, bad image quality or even latency caused by the upscaler of the device you
+are using. If one or multiple of these issues apply, use the built in scaling options by setting
+*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution to scale to.
+Usually, you want to set this to the monitor's native resolution, e.g. 1920x1080 for full HD. You
+can play around with a few different filters using *gfx.scale_back_buffer_filter* which impacts
+image quality/blurriness on upscaling.

doc/iidxhook/iidxhook8.md

@@ -1,8 +1,9 @@
 # Game list
 
 The following games are compatible with this version of iidxhook:
-* CANNON BALLERS
-* Rootage
+
+- CANNON BALLERS
+- Rootage
 
 The games must be bootstrapped using [launcher](../launcher.md).
 
@@ -10,34 +11,37 @@ The games must be bootstrapped using [launcher](../launcher.md).
 
 ## Supported versions of Windows
 
-This version requires at least Win 7 x64 and will not run, like the
-former versions, on Win XP x86!
+This version requires at least Win 7 x64 and will not run, like the former versions, on Win XP x86!
 
 ## Dependencies
 
 Make sure to have the following dependencies installed:
-* DirectX 9
-* Visual C++ 2010 Redistributable Package (x64)
+
+- DirectX 9
+- Visual C++ 2010 Redistributable Package (x64)
 
 ## Data setup
 
-We assume that you are using a clean/vanilla data dump. Ensure your ("concents")
-folder with your unpacked data looks like this:
+We assume that you are using a clean/vanilla data dump. Ensure your ("concents") folder with your
+unpacked data looks like this:
+
 - data
 - modules
 - prop
 
-* Copy/Move all files from the *modules* directory to the root folder, so they
-are located next to the *data* and *prop* folders.
+* Copy/Move all files from the *modules* directory to the root folder, so they are located next to
+  the *data* and *prop* folders.
 * Copy all files from *prop/defaults* to the *prop* folder.
-* Create a new file *app-config.xml* in the *prop* folder with the following
-content:
+* Create a new file *app-config.xml* in the *prop* folder with the following content:
+
 ```
 <?xml version="1.0"?>
 <param></param>
 ```
-* Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by
-replacing the *<fs>*-block in that file with the following block:
+
+- Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by replacing the
+  *<fs>*-block in that file with the following block:
+
 ```
 <fs>
     <root>
@@ -51,174 +55,170 @@ replacing the *<fs>*-block in that file with the following block:
     <nr_filedesc __type="u16">256</nr_filedesc>
 </fs>
 ```
-* Unpack the package containing iidxhook8 into the root folder so iidxhook8.dll
-and all other files are located in the same folder as *data*, *prop*, 
-*bm2dx.dll*, etc.
-* Run the gamestart-XX.bat file as admin. Where XX matches the version you 
-want to run.
+
+- Unpack the package containing iidxhook8 into the root folder so iidxhook8.dll and all other files
+  are located in the same folder as *data*, *prop*, *bm2dx.dll*, etc.
+- Run the gamestart-XX.bat file as admin. Where XX matches the version you want to run.
 
 # Configuring iidxhook
 
-The hook library can be configured via cmd arguments or a configuration file.
-The latter is generated (*iidxhook-XX.conf* in the same directory) on the first 
-start of the game using the gamestart-XX.bat file (again, XX matches your target
-game version). It contains default values for all available parameters and 
-comments explaining each parameter. Please follow the comments when configuring 
-your setup.
+The hook library can be configured via cmd arguments or a configuration file. The latter is
+generated (*iidxhook-XX.conf* in the same directory) on the first start of the game using the
+gamestart-XX.bat file (again, XX matches your target game version). It contains default values for
+all available parameters and comments explaining each parameter. Please follow the comments when
+configuring your setup.
 
-Add the argument *-h* when running gamestart-XX.bat 
-(e.g. *gamestart-XX.bat -h*) to print help/usage information with a list of 
-all available parameters. Every parameter can be either set as command line
-argument or using a configuration file.
+Add the argument *-h* when running gamestart-XX.bat (e.g. *gamestart-XX.bat -h*) to print help/usage
+information with a list of all available parameters. Every parameter can be either set as command
+line argument or using a configuration file.
+
+To set a parameter from the command line, just add it as an argument after the bat file like this
 
-To set a parameter from the command line, just add it as an argument after
-the bat file like this
 ```
 gamestart-09.bat -p gfx.windowed=true -p gfx.framed=true
 ```
 
-The syntax for the "key=value" is the same as in the config file. Make sure
-to have a pre-ceeding "-p" for every parameter added.
+The syntax for the "key=value" is the same as in the config file. Make sure to have a pre-ceeding
+"-p" for every parameter added.
 
-However, if a parameter is specifed in the configuration file and as a command
-line argument, the command line argument overrides the config file's value.
+However, if a parameter is specifed in the configuration file and as a command line argument, the
+command line argument overrides the config file's value.
 
 # Eamuse network setup
 
-If you want to run the games online, you need a valid PCBID and the service URL.
-Open *prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and
-*ea3/network/services* nodes accordingly.
+If you want to run the games online, you need a valid PCBID and the service URL. Open
+*prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and *ea3/network/services* nodes
+accordingly.
 
-Run the game with the gamestart-XX.bat file and enable network on the operator 
-menu. When enabled, the game seems to hang and expects you to power
-cycle the machine (i.e. quit the game and restart it).
+Run the game with the gamestart-XX.bat file and enable network on the operator menu. When enabled,
+the game seems to hang and expects you to power cycle the machine (i.e. quit the game and restart
+it).
 
 # Real hardware support
 
 ### BIO2 hardware
 
-Set `io.disable_bio2_emu=true` in the `iidxhook.conf` file to not hook the BIO2
-communication with an emulation layer. The game will directly talk to the IO.
-In this mode, tthe game supports the BIO2 board only.
+Set `io.disable_bio2_emu=true` in the `iidxhook.conf` file to not hook the BIO2 communication with
+an emulation layer. The game will directly talk to the IO. In this mode, tthe game supports the BIO2
+board only.
 
 ### Ezusb and other
 
-Set `io.disable_bio2_emu=false` in the `iidxhook.conf` file.
-Use the specific iidxio API implementations, e.g. `iidxio-ezusb2.dll` to use
-the IO2 EZUSB board. The common `iidxio` abstraction layer also allows you to
-use custom IO boards or whatever Konami hardware is going to be available in
-the future. Obviously, someone has to write an imlementation of the `iidxio`
-API, first.
+Set `io.disable_bio2_emu=false` in the `iidxhook.conf` file. Use the specific iidxio API
+implementations, e.g. `iidxio-ezusb2.dll` to use the IO2 EZUSB board. The common `iidxio`
+abstraction layer also allows you to use custom IO boards or whatever Konami hardware is going to be
+available in the future. Obviously, someone has to write an imlementation of the `iidxio` API,
+first.
 
 ## Slotted/Wave pass card readers
 
 You have the following options:
-* Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook
-card reader communication with an emulation layer. The game will directly talk
-to the real readers though this only supports whatever readers the game 
-directly supports (wave pass readers)
-* Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file.
-Replace the default `eamio.dll` with the `eamio-icca.dll` and have either your
-slotted (IIDX, DDR Supernova or GF/DM type) or new wave pass card readers 
-conencted and and assigned to `COM1`. Other custom implementations of of the
-`eamio` API also work.
+
+- Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook card reader
+  communication with an emulation layer. The game will directly talk to the real readers though this
+  only supports whatever readers the game directly supports (wave pass readers)
+- Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file. Replace the default
+  `eamio.dll` with the `eamio-icca.dll` and have either your slotted (IIDX, DDR Supernova or GF/DM
+  type) or new wave pass card readers conencted and and assigned to `COM1`. Other custom
+  implementations of of the `eamio` API also work.
 
 ### ICCA device settings (device manager)
-* Port: COM1
-* BAUD rate: 57600
-* Data bits: 8
-* Parity: None
-* Stop bits: 1
-* Flow control: None
 
-If you encounter issues after the game opened the device, e.g. application
-stuck, try a USB <-> COM dongle instead of using one of the COM ports of the
-mainboard.
+- Port: COM1
+- BAUD rate: 57600
+- Data bits: 8
+- Parity: None
+- Stop bits: 1
+- Flow control: None
+
+If you encounter issues after the game opened the device, e.g. application stuck, try a USB \<-> COM
+dongle instead of using one of the COM ports of the mainboard.
 
 # Troubleshooting and FAQ
 
 ## The monitor check is showing high fps and I am using a monitor with high refresh rate features, e.g. 120/144hz
-Sync and timing might be screwed up since the game was never meant to run on
-such refresh rates. Try setting the option `gfx.forced_refresh_rate` to either
-`59` or `60`.
 
-Note: Your GPU driver settings must be configured to allow application overrides
-on vertical sync/refresh rate options.
+Sync and timing might be screwed up since the game was never meant to run on such refresh rates. Try
+setting the option `gfx.forced_refresh_rate` to either `59` or `60`.
+
+Note: Your GPU driver settings must be configured to allow application overrides on vertical
+sync/refresh rate options.
 
 On AMD GPUs, set the "V-Sync" option to `On, unless application specifies`.
 
 ## The game does not run "well" (frame drops, drifting offsync etc)
+
 This can be related to various issues:
-* Make sure to run the game as (true) Administrator especially on Windows 7 and
-newer. This will also get rid of various other errors (see below) that are 
-related to permission issues.
-* Run the game's process with a higher priority:
+
+- Make sure to run the game as (true) Administrator especially on Windows 7 and newer. This will
+  also get rid of various other errors (see below) that are related to permission issues.
+- Run the game's process with a higher priority:
+
 ```
 start "" /relatime "gamestart.bat"
 ```
-* Enforce v-sync enabled in your GPU settings.
-* Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx)
-that is not jumping around. Use the timebase feature of one of the newer games to
-check that or enable iidxhook's timebase and check the log output for the
-determined value. Run this a few times and check if the results differ.
+
+Also refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## "NETWORK WARNING" instead of "NETWORK OK"
+
 This can be caused by:
-* Invalid PCBID
-* Firewall blocking connections
-* Invalid eamuse url or port specified
-* Game is not run using the Administrator account
-Make sure to check these things first
+
+- Invalid PCBID
+- Firewall blocking connections
+- Invalid eamuse url or port specified
+- Game is not run using the Administrator account Make sure to check these things first
 
 ## My songs are offsync
-From IIDX 20 (or Lincle very final revision) onwards, the game comes with 
-a built-in auto timebase option ("monitor check" on startup) which
-dynamically, detects the refresh rate of your current setup. Thus, BT5's 
-timebase option is not included from this hook version onwards, anymore.
-Ensure that refresh rate displayed is very stable, e.g. 60.00x hz, and the
-game should be able to provide you with a smooth and sync game experience.
+
+Refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## My game runs too fast
+
 iidxhook can limit the frame rate for you (refer to help/config file)
 
 ## My game crashes when I try fullscreen
+
 Use dxwnd and set settings like "Acquire admin caps" and "Fullscreen only"
 
 ## Background videos aren't working. When starting a song, windows is playing the error sound and a message box appears
+
 If you are running in window mode, you can see an error pop-up window with the title
 `DirectShow Texture3D Sample` and error message
 `Could not create source filter to graph! hr=<some number>`.
 
-When running fullscreen, you only hear a windows error sound and the game appears to be frozen
-when trying to play a background video.
+When running fullscreen, you only hear a windows error sound and the game appears to be frozen when
+trying to play a background video.
 
-You are missing a codec to decode and play the videos. There are different 
-methods available to get background videos working. Probably, the easiest 
-solution: grab the CLVSD.ax file and go to Start -> Run -> regsvr32 clvsd.ax
-Make sure to run cmd.exe as Administrator, otherwise you will get errors caused
-by invalid permissions.
+You are missing a codec to decode and play the videos. There are different methods available to get
+background videos working. Probably, the easiest solution: grab the CLVSD.ax file and go to Start ->
+Run -> regsvr32 clvsd.ax Make sure to run cmd.exe as Administrator, otherwise you will get errors
+caused by invalid permissions.
 
 ## I installed the CLVSD.ax codec but the game crashes or displays a message box that tells me to disable my debugger
+
 If songs keep crashing upon start and you get an error message that says
+
 ```
 DirectShow Texture3D Sample
 Could not create source filter to graph! hr=0x80040266
 ```
-despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) 
-from gamestart or use a CLVSD.ax codec which has the debugger checks removed.
+
+despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) from gamestart or use a
+CLVSD.ax codec which has the debugger checks removed.
 
 ## I am getting a message box with a japanese error message and a black window immediately after starting the game
-The game checks the vendor and product ID of your GPU installed. If it doesn't
-match a hardcoded whitelist, the game won't boot. Use the option *gfx.pci_id*
-either in the config file or as a cmd argument to spoof these IDs. See the
-help message for instructions and possible IDs.
+
+The game checks the vendor and product ID of your GPU installed. If it doesn't match a hardcoded
+whitelist, the game won't boot. Use the option *gfx.pci_id* either in the config file or as a cmd
+argument to spoof these IDs. See the help message for instructions and possible IDs.
 
 ## Over-/underscan, bad image quality or latency caused by my monitor's/TV's upscaler
-Many modern monitors/TVs cannot upscale some lower resolutions, e.g. 640x480, properly.
-This can lead to over-/underscan, bad image quality or even latency caused by the upscaler
-of the device you are using.
-If one or multiple of these issues apply, use the built in scaling options by setting
-*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution
-to scale to. Usually, you want to set this to the monitor's native resolution, e.g.
-1920x1080 for full HD. You can play around with a few different filters using
-*gfx.scale_back_buffer_filter* which impacts image quality/blurriness on upscaling.
+
+Many modern monitors/TVs cannot upscale some lower resolutions, e.g. 640x480, properly. This can
+lead to over-/underscan, bad image quality or even latency caused by the upscaler of the device you
+are using. If one or multiple of these issues apply, use the built in scaling options by setting
+*gfx.scale_back_buffer_width* and *gfx.scale_back_buffer_height* to a target resolution to scale to.
+Usually, you want to set this to the monitor's native resolution, e.g. 1920x1080 for full HD. You
+can play around with a few different filters using *gfx.scale_back_buffer_filter* which impacts
+image quality/blurriness on upscaling.

doc/iidxhook/iidxhook9.md

@@ -1,8 +1,12 @@
 # Game list
 
 The following games are compatible with this version of iidxhook:
-* Heroic Verse
-* BISTROVER
+
+- Heroic Verse
+- BISTROVER
+- CASTHOUR
+- RESIDENT
+- EPOLIS
 
 The games must be bootstrapped using [launcher](../launcher.md).
 
@@ -10,28 +14,31 @@ The games must be bootstrapped using [launcher](../launcher.md).
 
 ## Supported versions of Windows
 
-This version requires at least Win 7 x64 and will not run, like the
-former versions, on Win XP x86!
+This version requires at least Win 7 x64 and will not run, like the former versions, on Win XP x86!
 
 ## Dependencies
 
 Make sure to have the following dependencies installed:
-* DirectX 9
-* Visual C++ 2010 Redistributable Package (x64)
+
+- DirectX 9
+- Visual C++ 2010 Redistributable Package (x64)
 
 ## Data setup
 
-We assume that you are using a clean/vanilla data dump. Ensure your ("concents")
-folder with your unpacked data looks like this:
+We assume that you are using a clean/vanilla data dump. Ensure your ("contents") folder with your
+unpacked data looks like this:
+
 - data
 - modules
 - prop
 
-* Copy/Move all files from the *modules* directory to the root folder, so they
-are located next to the *data* and *prop* folders.
+* For versions 27-29, only
+  - Copy/Move all files from the *modules* directory to the root folder, so they are located next to
+    the *data* and *prop* folders.
 * Copy all files from *prop/defaults* to the *prop* folder.
-* Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by
-replacing the *<fs>*-block in that file with the following block:
+* Setup proper paths for *dev/nvram* and *dev/raw* in *prop/avs-config.xml* by replacing the
+  *<fs>*-block in that file with the following block:
+
 ```
 <fs>
     <root>
@@ -45,200 +52,211 @@ replacing the *<fs>*-block in that file with the following block:
     <nr_filedesc __type="u16">256</nr_filedesc>
 </fs>
 ```
-* Unpack the package containing iidxhook9 into the root folder so iidxhook9.dll
-and all other files are located in the same folder as *data*, *prop*, 
-*bm2dx.dll*, etc.
-* Run the gamestart-XX.bat file as admin. Where XX matches the version you 
-want to run.
 
-* Note: if you know what you're doing and would like to keep all the dlls in the
-*modules* folder then you extract iidxhook9 into that directory, move
-gamestart-XX.bat up, and edit the paths.
+- For versions 27-29, only
+
+  - Unpack the package containing iidxhook9 into the root folder so iidxhook9.dll and all other
+    files are located in the same folder as *data*, *prop*, *bm2dx.dll*, etc.
+
+- For version 30-31
+
+  - Unpack the package containing iidxhook9 into the `modules` folder so iidxhook9.dll and all other
+    files are located in the same folder as the game's DLLs, e.g. *bm2dx.dll*, etc.
+  - Move the `gamestart-30.bat` to the root folder so it is located next to the `modules`, `data`
+    and `prop` folders
+
+- Run the gamestart-XX.bat file as admin. Where XX matches the version you want to run.
+
+- Note: if you know what you're doing and would like to keep all the dlls in the *modules* folder
+  then you extract iidxhook9 into that directory, move gamestart-XX.bat up, and edit the paths.
 
 # Configuring iidxhook
 
-The hook library can be configured via cmd arguments or a configuration file.
-The latter is generated (*iidxhook-XX.conf* in the same directory) on the first 
-start of the game using the gamestart-XX.bat file (again, XX matches your target
-game version). It contains default values for all available parameters and 
-comments explaining each parameter. Please follow the comments when configuring 
-your setup.
+The hook library can be configured via cmd arguments or a configuration file. The latter is
+generated (*iidxhook-XX.conf* in the same directory) on the first start of the game using the
+gamestart-XX.bat file (again, XX matches your target game version). It contains default values for
+all available parameters and comments explaining each parameter. Please follow the comments when
+configuring your setup.
 
-Add the argument *-h* when running gamestart-XX.bat 
-(e.g. *gamestart-XX.bat -h*) to print help/usage information with a list of 
-all available parameters. Every parameter can be either set as command line
-argument or using a configuration file.
+Add the argument *-h* when running gamestart-XX.bat (e.g. *gamestart-XX.bat -h*) to print help/usage
+information with a list of all available parameters. Every parameter can be either set as command
+line argument or using a configuration file.
+
+To set a parameter from the command line, just add it as an argument after the bat file like this
 
-To set a parameter from the command line, just add it as an argument after
-the bat file like this
 ```
 gamestart-09.bat -p gfx.windowed=true -p gfx.framed=true
 ```
 
-The syntax for the "key=value" is the same as in the config file. Make sure
-to have a pre-ceeding "-p" for every parameter added.
+The syntax for the "key=value" is the same as in the config file. Make sure to have a pre-ceeding
+"-p" for every parameter added.
 
-However, if a parameter is specifed in the configuration file and as a command
-line argument, the command line argument overrides the config file's value.
+However, if a parameter is specifed in the configuration file and as a command line argument, the
+command line argument overrides the config file's value.
+
+# Note on camhook
+
+The cammera hook (camhook) is used to allow other class compliant cameras to be used. Depending on the variant of the game, you will need to select the correct camera port layout.
+
+For original LDJ, this is always 0, for conversion kit LDJ and original TDJ-JA, this is 1, and for TDJ-JB this will be 2 (this case is rare / you will know if this is needed on your setup).
 
 # Eamuse network setup
 
-If you want to run the games online, you need a valid PCBID and the service URL.
-Open *prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and
-*ea3/network/services* nodes accordingly.
+If you want to run the games online, you need a valid PCBID and the service URL. Open
+*prop/ea3-config.xml* and set the values of the *ea3/id/pcbid* and *ea3/network/services* nodes
+accordingly.
 
-Run the game with the gamestart-XX.bat file and enable network on the operator 
-menu. When enabled, the game seems to hang and expects you to power
-cycle the machine (i.e. quit the game and restart it).
+Run the game with the gamestart-XX.bat file and enable network on the operator menu. When enabled,
+the game seems to hang and expects you to power cycle the machine (i.e. quit the game and restart
+it).
 
 # Real hardware support
 
 ## The game does not go into either 640x480 (SD) or 1280x720 (HD) as expected but rather picks a resolution like 1386x768
-The graphics backend of the game is auto detecting the resolution and refresh
-rate based on the supported specs reported by the monitor. Depending on that
-output, this can lead to the game picking some "odd" resolution like 1386x768
-even the game is set to HD mode (expecting 1280x720).
 
-Furthermore, this can lead to different refresh rate values on the automatic
-monitor check, e.g. compared to previous versions (59.94 on Rootage but 60.02
-on Heroic Verse). Ultimately, the result can be a very offsync gameplay
-experience with extremely delayed input.
+The graphics backend of the game is auto detecting the resolution and refresh rate based on the
+supported specs reported by the monitor. Depending on that output, this can lead to the game picking
+some "odd" resolution like 1386x768 even the game is set to HD mode (expecting 1280x720).
 
-If that happens, try forcing the resolution to `1280x720` when the game is
-set to HD mode in the operator menu. Note: Your monitor must also be capable
-of handling the resolution.
+Furthermore, this can lead to different refresh rate values on the automatic monitor check, e.g.
+compared to previous versions (59.94 on Rootage but 60.02 on Heroic Verse). Ultimately, the result
+can be a very offsync gameplay experience with extremely delayed input.
+
+If that happens, try forcing the resolution to `1280x720` when the game is set to HD mode in the
+operator menu. Note: Your monitor must also be capable of handling the resolution.
 
 iidxhook.conf:
+
 ```text
 gfx.force_screen_res.width=1280
 gfx.force_screen_res.height=720
 ```
 
 ## The monitor check is showing high fps and I am using a monitor with high refresh rate features, e.g. 120/144hz
-Sync and timing might be screwed up since the game was never meant to run on
-such refresh rates. Try setting the option `gfx.forced_refresh_rate` to either
-`59` or `60`.
 
-Note: Your GPU driver settings must be configured to allow application overrides
-on vertical sync/refresh rate options.
+Sync and timing might be screwed up since the game was never meant to run on such refresh rates. Try
+setting the option `gfx.forced_refresh_rate` to either `59` or `60`.
+
+Note: Your GPU driver settings must be configured to allow application overrides on vertical
+sync/refresh rate options.
 
 On AMD GPUs, set the "V-Sync" option to `On, unless application specifies`.
 
 ### BIO2 hardware
 
-Set `io.disable_bio2_emu=true` in the `iidxhook.conf` file to not hook the BIO2
-communication with an emulation layer. The game will directly talk to the IO.
-In this mode, the game supports the BIO2 board only.
+Set `io.disable_bio2_emu=true` in the `iidxhook.conf` file to not hook the BIO2 communication with
+an emulation layer. The game will directly talk to the IO. In this mode, the game supports the BIO2
+board only.
 
 ## Driver notes
-You can use the default driver that Windows (7/10) automatically installs once
-you connect the BIO2 board via USB to your host. However, these drivers will
-not allow the game to detect the board correctly, throwing an IO error.
-The drivers will work fine when using the iidxio API implementation 
+
+You can use the default driver that Windows (7/10) automatically installs once you connect the BIO2
+board via USB to your host. However, these drivers will not allow the game to detect the board
+correctly, throwing an IO error. The drivers will work fine when using the iidxio API implementation
 [iidxio-bio2](iidxio-bio2.md).
 
-If you want to use the BIO2 with the game without the emulation layer, as
-suggested above, you need to install Konami's original driver which is
-identical to the stock Windows driver except the device name is different
-(which is the crucial part for the stock game's automatic detection).
+If you want to use the BIO2 with the game without the emulation layer, as suggested above, you need
+to install Konami's original driver which is identical to the stock Windows driver except the device
+name is different (which is the crucial part for the stock game's automatic detection).
 
 The driver is available in the bemanitools-supplement repository.
 
 ### Ezusb and other
 
-Set `io.disable_bio2_emu=false` in the `iidxhook.conf` file.
-Use the specific iidxio API implementations, e.g. `iidxio-ezusb2.dll` to use
-the IO2 EZUSB board. The common `iidxio` abstraction layer also allows you to
-use custom IO boards or whatever Konami hardware is going to be available in
-the future. Obviously, someone has to write an imlementation of the `iidxio`
-API, first.
+Set `io.disable_bio2_emu=false` in the `iidxhook.conf` file. Use the specific iidxio API
+implementations, e.g. `iidxio-ezusb2.dll` to use the IO2 EZUSB board. The common `iidxio`
+abstraction layer also allows you to use custom IO boards or whatever Konami hardware is going to be
+available in the future. Obviously, someone has to write an imlementation of the `iidxio` API,
+first.
 
 ## Slotted/Wave pass card readers
 
 You have the following options:
-* Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook
-card reader communication with an emulation layer. The game will directly talk
-to the real readers though this only supports whatever readers the game 
-directly supports (wave pass readers)
-* Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file.
-Replace the default `eamio.dll` with the `eamio-icca.dll` and have either your
-slotted (IIDX, DDR Supernova or GF/DM type) or new wave pass card readers 
-conencted and and assigned to `COM1`. Other custom implementations of of the
-`eamio` API also work.
+
+- Set `io.disable_card_reader_emu=true` in the `iidxhook.conf` file to not hook card reader
+  communication with an emulation layer. The game will directly talk to the real readers though this
+  only supports whatever readers the game directly supports (wave pass readers)
+- Set `io.disable_card_reader_emu=false` in the `iidxhook.conf` file. Replace the default
+  `eamio.dll` with the `eamio-icca.dll` and have either your slotted (IIDX, DDR Supernova or GF/DM
+  type) or new wave pass card readers conencted and and assigned to `COM1`. Other custom
+  implementations of of the `eamio` API also work.
 
 ### ICCA device settings (device manager)
-* Port: COM1
-* BAUD rate: 57600
-* Data bits: 8
-* Parity: None
-* Stop bits: 1
-* Flow control: None
 
-If you encounter issues after the game opened the device, e.g. application
-stuck, try a USB <-> COM dongle instead of using one of the COM ports of the
-mainboard.
+- Port: COM1
+- BAUD rate: 57600
+- Data bits: 8
+- Parity: None
+- Stop bits: 1
+- Flow control: None
+
+If you encounter issues after the game opened the device, e.g. application stuck, try a USB \<-> COM
+dongle instead of using one of the COM ports of the mainboard.
 
 # Troubleshooting and FAQ
+
 ## The turntable input feels laggy/delayed with my BIO2 + sub IO
-See the [this readme](hardware/bio2-sub-io-turntable-bypass-cable.md) for
-information about the bypass cable.
+
+See the [this readme](hardware/bio2-sub-io-turntable-bypass-cable.md) for information about the
+bypass cable.
 
 ## The game does not run "well" (frame drops, drifting offsync etc)
+
 This can be related to various issues:
-* Make sure to run the game as (true) Administrator especially on Windows 7 and
-newer. This will also get rid of various other errors (see below) that are 
-related to permission issues.
-* Run the game's process with a higher priority:
+
+- Make sure to run the game as (true) Administrator especially on Windows 7 and newer. This will
+  also get rid of various other errors (see below) that are related to permission issues.
+- Run the game's process with a higher priority:
+
 ```
 start "" /relatime "gamestart.bat"
 ```
-* Enforce v-sync enabled in your GPU settings.
-* Ensure that you have a constant refresh rate around the 60 hz (59.9xx or 60.0xx)
-that is not jumping around. Use the timebase feature of one of the newer games to
-check that or enable iidxhook's timebase and check the log output for the
-determined value. Run this a few times and check if the results differ.
+
+Also refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## "NETWORK WARNING" instead of "NETWORK OK"
+
 This can be caused by:
-* Invalid PCBID
-* Firewall blocking connections
-* Invalid eamuse url or port specified
-* Game is not run using the Administrator account
-Make sure to check these things first
+
+- Invalid PCBID
+- Firewall blocking connections
+- Invalid eamuse url or port specified
+- Game is not run using the Administrator account Make sure to check these things first
 
 ## My songs are offsync
-From IIDX 20 (or Lincle very final revision) onwards, the game comes with 
-a built-in auto timebase option ("monitor check" on startup) which
-dynamically, detects the refresh rate of your current setup. Thus, BT5's 
-timebase option is not included from this hook version onwards, anymore.
-Ensure that refresh rate displayed is very stable, e.g. 60.00x hz, and the
-game should be able to provide you with a smooth and sync game experience.
+
+Refer to the [iidx-syncbook](iidx-syncbook.md).
 
 ## My game runs too fast
+
 iidxhook can limit the frame rate for you (refer to help/config file)
 
 ## My game crashes when I try fullscreen
+
 Use dxwnd and set settings like "Acquire admin caps" and "Fullscreen only"
 
 ## Background videos aren't working. When starting a song, windows is playing the error sound and a message box appears
+
 If you are running in window mode, you can see an error pop-up window with the title
 `DirectShow Texture3D Sample` and error message
 `Could not create source filter to graph! hr=<some number>`.
 
-When running fullscreen, you only hear a windows error sound and the game appears to be frozen
-when trying to play a background video.
+When running fullscreen, you only hear a windows error sound and the game appears to be frozen when
+trying to play a background video.
 
-You are missing a codec to decode and play the videos. There are different 
-methods available to get background videos working. Probably, the easiest 
-solution: grab the CLVSD.ax file and go to Start -> Run -> regsvr32 clvsd.ax
-Make sure to run cmd.exe as Administrator, otherwise you will get errors caused
-by invalid permissions.
+You are missing a codec to decode and play the videos. There are different methods available to get
+background videos working. Probably, the easiest solution: grab the CLVSD.ax file and go to Start ->
+Run -> regsvr32 clvsd.ax Make sure to run cmd.exe as Administrator, otherwise you will get errors
+caused by invalid permissions.
 
 ## I installed the CLVSD.ax codec but the game crashes or displays a message box that tells me to disable my debugger
+
 If songs keep crashing upon start and you get an error message that says
+
 ```
 DirectShow Texture3D Sample
 Could not create source filter to graph! hr=0x80040266
 ```
-despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) 
-from gamestart or use a CLVSD.ax codec which has the debugger checks removed.
+
+despite having the codec (CLVSD.ax) installed, remove the debug flag (*-D*) from gamestart or use a
+CLVSD.ax codec which has the debugger checks removed.

doc/iidxhook/iidxio-async.md

@@ -0,0 +1,22 @@
+# IIDXIO async API implementation
+
+This implementation of the iidxio API is a shim library that takes another iidxio library and
+runs the functions `iidx_io_ep1_send`, `iidx_io_ep2_recv` and `iidx_io_ep3_write_16seg` in a
+dedicated thread. State synchronization to the getter and setter functions is also handled
+transparently.
+
+Usage of this **may** improve performance of certain iidxio implementations or when using them
+in certain integrations, e.g. the send and receive functions of a iidxio implementation for some
+target IO hardware calls are synchronous and expensive. 
+
+This is not a fix/solution to a badly implemented iidxio library with poor performance as it cannot
+make it go faster and address potential latency issues, for example.
+
+Use with caution and know why and when you need to use it.
+
+## Setup
+
+* Add `iidxio-async.dll` in the same folder as your `iidxhookX.dll`
+* Rename your `iidxio.dll` to `iidxio-async-child.dll`
+* Rename `iidxio-async.dll` to `iidxio.dll`
+* Run the game

doc/iidxhook/iidxio-bio2.md

@@ -1,21 +1,28 @@
 # IIDXIO API implementation with BIO2 driver
+
 This implementation of BT5's iidxio API allows you to use native BIO2 hardware with anything that
 supports BT5's iidxio API, e.g. all iidxhooks of BT5. Thus, you can play your favorite old IIDX
 games with the latest generation of hardware.5.
 
 ## Setup
-* Have `iidxio-bio2.dll` in the same folder as your `iidxhookX.dll`
-* Rename `iidxio-bio2.dll` to `iidxio.dll`
-* Ensure that your `gamestart.bat` actually injects the appropriate iidxhook dll, for example:
+
+- Have `iidxio-bio2.dll` in the same folder as your `iidxhookX.dll`
+- Rename `iidxio-bio2.dll` to `iidxio.dll`
+- Ensure that your `gamestart.bat` actually injects the appropriate iidxhook dll, for example:
+
 ```bat
 inject iidxhook3.dll bm2dx.exe ...*
 ```
+
 or
+
 ```bat
 launcher -K iidxhook4.dll bm2dx.dll ...*
 ```
-* This assumes that the BIO2 is already flashed to the correct firmware. The firmware perists once
-flashed and does not need to be re-flashed after a power cycle.
+
+- This assumes that the BIO2 is already flashed to the correct firmware. The firmware perists once
+  flashed and does not need to be re-flashed after a power cycle.
 
 ## Driver notes
-See [here](iidxhook9.md#driver-notes).
+
+See [here](iidxhook9.md#driver-notes).

doc/iidxhook/iidxio-ezusb.md

@@ -1,30 +1,31 @@
-This library drives a "legacy" ezusb IO board, also known as C02/D01 IO, and 
-implements the iidxio API of BT5. Thus, it allows you to use this IO board with
-*any* version of IIDX that is supported by BT5.
+This library drives a "legacy" ezusb IO board, also known as C02/D01 IO, and implements the iidxio
+API of BT5. Thus, it allows you to use this IO board with *any* version of IIDX that is supported by
+BT5.
 
 # Setup
-* Rename iidxio-ezusb.dll to iidxio.dll.
-* Ensure that your gamestart.bat actually injects the appropriate iidxhook dll,
-for example:
+
+- Rename iidxio-ezusb.dll to iidxio.dll.
+- Ensure that your gamestart.bat actually injects the appropriate iidxhook dll, for example:
+
 ```
 *inject iidxhook3.dll bm2dx.exe ...*
 ```
+
 or
+
 ```
 launcher -K iidxhook4.dll bm2dx.dll ...*
 ```
-* Before running the game, you have to flash a set of binaries to your IO board
-(base firmware and FPGA). The iidxio-ezusb.dll does NOT take care of this and
-only drives the hardware during gameplay. The binary images required are not 
-included with BT5.
-* Use the ezusb-tool.exe binary included in the tools sub-package to flash the
-appropriate ezusb base firmware. Once the firmware is flashed successfully,
-the status LEDs on the side of the board should show a blinking pattern.
-* Use the ezusb-iidx-fpga-flash.exe binary to flash the appropriate FPGA binary
-dump to the FPGA.
-* There is a script called ezusb-boot.bat which combines the two steps above
-and can be integrated into the startup process of a dedicated setup.
-* If you are using a D01 IO board, use the `fpga-d01.bin` file instead of the
-`fpga.bin` file.
-* If you ignore these steps, you will either run into errors or parts of the
-IO board won't work (e.g. lights).
+
+- Before running the game, you have to flash a set of binaries to your IO board (base firmware and
+  FPGA). The iidxio-ezusb.dll does NOT take care of this and only drives the hardware during
+  gameplay. The binary images required are not included with BT5.
+- Use the ezusb-tool.exe binary included in the tools sub-package to flash the appropriate ezusb
+  base firmware. Once the firmware is flashed successfully, the status LEDs on the side of the board
+  should show a blinking pattern.
+- Use the ezusb-iidx-fpga-flash.exe binary to flash the appropriate FPGA binary dump to the FPGA.
+- There is a script called ezusb-boot.bat which combines the two steps above and can be integrated
+  into the startup process of a dedicated setup.
+- If you are using a D01 IO board, use the `fpga-d01.bin` file instead of the `fpga.bin` file.
+- If you ignore these steps, you will either run into errors or parts of the IO board won't work
+  (e.g. lights).

doc/iidxhook/iidxio-ezusb2.md

@@ -1,27 +1,28 @@
-This library drives the ezusb FX2 IO board, also known as IO2, and 
-implements the iidxio API of BT5. Thus, it allows you to use this IO2 board with
-*any* version of IIDX that is supported by BT5.
+This library drives the ezusb FX2 IO board, also known as IO2, and implements the iidxio API of BT5.
+Thus, it allows you to use this IO2 board with *any* version of IIDX that is supported by BT5.
 
 # Setup
-* Rename iidxio-ezusb2.dll to iidxio.dll.
-* Ensure that your gamestart.bat actually injects the appropriate iidxhook dll,
-for example:
+
+- Rename iidxio-ezusb2.dll to iidxio.dll.
+- Ensure that your gamestart.bat actually injects the appropriate iidxhook dll, for example:
+
 ```
 *inject iidxhook3.dll bm2dx.exe ...*
 ```
+
 or
+
 ```
 launcher -K iidxhook4.dll bm2dx.dll ...*
 ```
-* Before running the game, you have to flash the appropriate firmware to your 
-IO board. The iidxio-ezusb2.dll does NOT take care of this and only drives the 
-hardware during gameplay. The binary image required is not included with BT5.
-* Use the ezusb2-tool.exe binary included in the tools sub-package to first scan
-for the device path of your connected hardware. Then, use the device path to 
-flash the appropriate ezusb base firmware. Once the firmware is flashed
-successfully, the status LEDs on the side of the board should show a blinking
-pattern.
-* There is a script called ezusb2-boot.bat which combines the two steps above
-and can be integrated into the startup process of a dedicated setup.
-* If you ignore these steps, your IO board won't work with our iidxio 
-implementation.
+
+- Before running the game, you have to flash the appropriate firmware to your IO board. The
+  iidxio-ezusb2.dll does NOT take care of this and only drives the hardware during gameplay. The
+  binary image required is not included with BT5.
+- Use the ezusb2-tool.exe binary included in the tools sub-package to first scan for the device path
+  of your connected hardware. Then, use the device path to flash the appropriate ezusb base
+  firmware. Once the firmware is flashed successfully, the status LEDs on the side of the board
+  should show a blinking pattern.
+- There is a script called ezusb2-boot.bat which combines the two steps above and can be integrated
+  into the startup process of a dedicated setup.
+- If you ignore these steps, your IO board won't work with our iidxio implementation.

doc/inject.md

@@ -1,18 +1,17 @@
 # Inject
 
-Inject is a tool that creates a process for a specified application executable
-file and injects a specified list of library/dll files into the process before
-it is kicked off.
+Inject is a tool that creates a process for a specified application executable file and injects a
+specified list of library/dll files into the process before it is kicked off.
 
-Typically, the tool is run when you use one of the bat script files to start
-any of the games that require its usage, e.g. older IIDX games.
+Typically, the tool is run when you use one of the bat script files to start any of the games that
+require its usage, e.g. older IIDX games.
+
+It comes with further option switches for development, e.g. Halting until a debugger is attached,
+outputting debug output to a logfile etc. Just run the application without any parameters to get a
+usage message:
 
-It comes with further option switches for development, e.g. Halting until
-a debugger is attached, outputting debug output to a logfile etc.
-Just run the application without any parameters to get a usage message:
 ```
 inject.exe
 ```
 
-How inject.exe is used can be taken from the bat script files of various
-(typically older) games.
+How inject.exe is used can be taken from the bat script files of various (typically older) games.