Leahnaya/bemanitools
1
0
Fork 0
mirror of https://github.com/djhackersdev/bemanitools.git synced 2026-08-20 07:24:01 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

Bemanitools v5.26 release

Browse Source
This commit is contained in:
icex2
2019-09-27 22:36:50 +02:00
commit cbd7720349
718 changed files with 62731 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
doc/api.md Normal file
View File

@@ -0,0 +1,43 @@
# 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).
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).
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
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-ezusb.dll: Ezusb (C02 IO) driver
* iidxio-ezusb2.dll: Ezusb FX2 (IO2) driver
* jubeat
* jbio.dll (default): Keyboard, joystick and mouse input
* SOUND VOLTEX
* sdvxio.dll (default): Keyboard, joystick and mouse input
Eamuse hardware support is implemented separately:
* eamio.dll (default): Keyboard and joystick input
## 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
```
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
```

103
doc/dev/c02-driver-on-w7-crash.md Normal file
View File

@@ -0,0 +1,103 @@
# 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.

26
doc/dev/device-list.md Normal file
View File

@@ -0,0 +1,26 @@
# H44B
(RGB) LED output board for jubeat cabinets.
# ICCA
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)
# ICCB
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.
- (Second gen) Jubeat cabinets with wave pass readers

76
doc/dev/logging-breakdown-avs.md Normal file
View File

@@ -0,0 +1,76 @@
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.

316
doc/development.md Normal file
View File

@@ -0,0 +1,316 @@
# Development
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.
## 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)
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
## Building
Simply run make in the root folder:
```
make
```
All output is located in the *build* folder including the final *bemanitools.zip* package.
## 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 to run *run-test-wine.sh* from the root folder. 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.
## 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.
### 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.
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
// OK
// this is a variable
int var = 1;
```
#### Comment style
* Use either // or /* ... */ for single line.
* Use /* ... */ for multiline comments.
* Use /* ... */ for documentation.
Examples:
```
// single line comment
int var = 1;
/* another single line comment */
int var2 = 2;
/* multi
line
comment */
/**
* This is a function.
*/
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.
Example for bsthook/acio.h file:
```
#ifndef BSTHOOK_ACIO_H
#define BSTHOOK_ACIO_H
// ...
#endif
```
#### 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;
if (var == 2) {
// ...
}
printf("%d\n", var);
```
#### 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.
Example for sorting
```
#include <stdio.h>
#include <string.h>
#include <windows.h>
#include "iidxhook-util/acio.h"
#include "iidxhook-util/d3d9.h"
#include "util/log.h"
#include "util/mem.h"
```
### 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.
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.
Example for my-namespace/my-module.h
```
/**
* Some example module to show you where documentation is expected.
*/
#ifndef MY_NAMESPACE_MY_MODULE_H
#define MY_NAMESPACE_MY_MODULE_H
/**
* Very useful enum for things.
*/
enum my_enum {
MY_NAMESPACE_MY_MODULE_MY_ENUM_VAL_1 = 1,
MY_NAMESPACE_MY_MODULE_MY_ENUM_VAL_2 = 2,
}
/**
* Some cool data structure.
*/
struct my_struct {
int a;
float b;
};
/**
* This is my awesome function doing great things.
*
* Here are some details about it:
* - Detail 1
* - Detail 2
*
* @param a If > 0, something happens.
* @param b Only positive values valid, makes sure fancy things happen.
* @return Result of the computation X which is always > 0. -1 on error.
*/
int my_namespace_my_module_func(int a, int b);
#endif
```
### 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.
#### 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).
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.
```
// For namespace "ezusb", module "device", static variable in module
static HANDLE ezusb_device_handle;
// Local variable in some function
int buffer_size = 256;
```
#### 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(...);
// CreateFileA hook function inside module
HANDLE my_CreateFileA(...)
{
// ...
}
```
#### Structs
Snake-case with proper namespacing to namespace and module.
```
// For namespace "ezusb", module "device" ctx struct
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 {
EZUSB_DEVICE_STATE_INIT = 0,
EZUSB_DEVICE_STATE_RUNNING = 1,
// ...
}
```
#### Macros
Upper-case with underscore as spacing, proper namespacing to namespace and module.
```
// For namespace "ezusb", module "device" vid
#define EZUSB_DEVICE_VID 0xFFFF
```
### 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.
### 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.
## 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.
https://github.com/decafcode/capnhook
This too is a little rudimentary; it doesn't come with any examples or even a README yet.

39
doc/iidxhook/README.md Normal file
View File

@@ -0,0 +1,39 @@
# 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.
# 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
* [iidxhook5](iidxhook5.md): Lincle
* [iidxhook6](iidxhook6.md): Tricoro
* [iidxhook7](iidxhook7.md): SPADA, PENDUAL, copula, SINOBUZ
* [iidxhook8](../iidxhook8/iidxhook8.md): CANNON BALLERS
When building kactools, 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 prestine 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.
# 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.

216
doc/iidxhook/iidxhook1.md Normal file
View File

@@ -0,0 +1,216 @@
# Game list
The following games are compatible with this version of iidxhook:
* 9th Style
* 10th Style
* RED
* HAPPY SKY
# 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.
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.
# 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.
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
```
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.
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 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).
# 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.
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.
## 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*.
### 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.
# 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.
## USBIO (FM-DL TIMEOUT)
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:
```
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.
### 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).
## "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
## 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)
## 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).
## 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.
## 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
## Background videos aren't working. When starting a song, windows is playing the error sound and a message box appears (RED, HAPPY SKY)
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.
## 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.
## 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.
## 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.
If you want to use this with old d3d8 games (IIDX 9-13), you have to use the d3d8to9
library from bemanitools-supplement because the d3d8 hook module cannot support this
upscaling feature. Make sure to set *misc.use_d3d9_hooks=true*.

181
doc/iidxhook/iidxhook2.md Normal file
View File

@@ -0,0 +1,181 @@
# Game list
The following games are compatible with this version of iidxhook:
* DistorteD
# 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.
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.
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
```
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.
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 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).
# 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.
## 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*.
### 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.
# 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.
# 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:
```
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.
### 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).
## "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
## 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)
## The game crashes instantly
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
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.
## 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.
## 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.
## 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.
If you want to use this with old d3d8 games (IIDX 9-13), you have to use the d3d8to9
library from bemanitools-supplement because the d3d8 hook module cannot support this
upscaling feature. Make sure to set *misc.use_d3d9_hooks=true*.

185
doc/iidxhook/iidxhook3.md Normal file
View File

@@ -0,0 +1,185 @@
# Game list
The following games are compatible with this version of iidxhook:
* GOLD
* DJ Troopers
* EMPRESS
* SIRIUS
# 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
- 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.
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.
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
```
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.
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.
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.
## 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*.
### 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.
# 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.
# 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:
```
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.
## "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
## 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).
## 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
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.
## 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.
## 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.
## 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.
## 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.

201
doc/iidxhook/iidxhook4.md Normal file
View File

@@ -0,0 +1,201 @@
# Game list
The following games are compatible with this version of iidxhook:
* Resort Anthem
# 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:
- 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 all files from *prop/defaults* to the *prop* folder.
* 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:
```
<fs>
<root>
<device __type="str">.</device>
</root>
<nvram>
<device __type="str">dev/nvram</device>
<fstype __type="str">fs</fstype>
<option __type="str">posix=1</option>
</nvram>
<raw>
<device __type="str">dev/raw</device>
</raw>
<nr_mountpoint __type="u16">256</nr_mountpoint>
<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.
# 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.
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
```
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.
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.
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)
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*.
### 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.
# 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.
# 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:
```
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.
## "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
## 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).
## 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
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.
## 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.
## 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.
## 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.

189
doc/iidxhook/iidxhook5.md Normal file
View File

@@ -0,0 +1,189 @@
# Game list
The following games are compatible with this version of iidxhook:
* Lincle
# 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:
- 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 all files from *prop/defaults* to the *prop* folder.
* 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:
```
<fs>
<root>
<device __type="str">.</device>
</root>
<nvram>
<device __type="str">dev/nvram</device>
<fstype __type="str">fs</fstype>
<option __type="str">posix=1</option>
</nvram>
<raw>
<device __type="str">dev/raw</device>
</raw>
<nr_mountpoint __type="u16">256</nr_mountpoint>
<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.
# 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.
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
```
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.
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.
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)
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*.
### 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.
# 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.
# 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:
```
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.
## "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
## 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.
## 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
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.
## 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.
## 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.

195
doc/iidxhook/iidxhook6.md Normal file
View File

@@ -0,0 +1,195 @@
# Game list
The following games are compatible with this version of iidxhook:
* Tricoro
# 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:
- 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 all files from *prop/defaults* to the *prop* folder.
* 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:
```
<fs>
<root>
<device __type="str">.</device>
</root>
<nvram>
<device __type="str">dev/nvram</device>
<fstype __type="str">fs</fstype>
<option __type="str">posix=1</option>
</nvram>
<raw>
<device __type="str">dev/raw</device>
</raw>
<nr_mountpoint __type="u16">256</nr_mountpoint>
<nr_filedesc __type="u16">256</nr_filedesc>
</fs>
```
* Setup valid logger configuration by replacing the *<log>*-block in
*prop/avs-config.xml* with:
```
<log>
<netsci>
<enable __type="bool">0</enable>
</netsci>
<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.
# 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.
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
```
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.
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.
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)
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*.
### 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.
# 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.
# 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:
```
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.
## "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
## 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.
## 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
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.
## 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.
## 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.

201
doc/iidxhook/iidxhook7.md Normal file
View File

@@ -0,0 +1,201 @@
# Game list
The following games are compatible with this version of iidxhook:
* SPADA
* PENDUAL
* copula
* SINOBUZ
# 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:
- 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 all files from *prop/defaults* to the *prop* folder.
* 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:
```
<fs>
<root>
<device __type="str">.</device>
</root>
<nvram>
<device __type="str">dev/nvram</device>
<fstype __type="str">fs</fstype>
<option __type="str">posix=1</option>
</nvram>
<raw>
<device __type="str">dev/raw</device>
</raw>
<nr_mountpoint __type="u16">256</nr_mountpoint>
<nr_filedesc __type="u16">256</nr_filedesc>
</fs>
```
* Setup valid logger configuration by replacing the *<log>*-block in
*prop/avs-config.xml* with:
```
<log>
<netsci>
<enable __type="bool">0</enable>
</netsci>
<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.
# 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.
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
```
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.
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.
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.
## 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*.
### 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.
# 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.
# 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:
```
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.
## "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
## 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.
## 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
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.
## 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.
## 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.

195
doc/iidxhook/iidxhook8.md Normal file
View File

@@ -0,0 +1,195 @@
# Game list
The following games are compatible with this version of iidxhook:
* CANNON BALLERS
# Data setup and running the game
## Supported versions of Windows
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)
## Data setup
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 all files from *prop/defaults* to the *prop* folder.
* 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:
```
<fs>
<root>
<device __type="str">.</device>
</root>
<mounttable>
<vfs name="boot" fstype="fs" src="dev/raw" dst="/dev/raw" opt="vf=1,posix=1"/>
<vfs name="boot" fstype="fs" src="dev/nvram" dst="/dev/nvram" opt="vf=0,posix=1"/>
</mounttable>
<nr_mountpoint __type="u16">256</nr_mountpoint>
<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.
# 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.
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
```
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.
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.
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 the *io.disable_bio2_emu* configuration value to *1* to disable BIO2
emulation to run the game using real BIO2 hardware.
### Ezusb and other
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*.
### 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.
# 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:
```
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.
## "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
## 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.
## 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
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.
## 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.
## 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.

28
doc/iidxhook/iidxio-ezusb.md Normal file
View File

@@ -0,0 +1,28 @@
This library drives a "legacy" ezusb IO board, also known as C02 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:
```
*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 ignore these steps, you will either run into errors or parts of the
IO board won't work (e.g. lights).

27
doc/iidxhook/iidxio-ezusb2.md Normal file
View File

@@ -0,0 +1,27 @@
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:
```
*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.

31
doc/jbhook/jbhook.md Normal file
View File

@@ -0,0 +1,31 @@
# Game list
The following games are compatible with this version of jbhook:
* saucer
* prop
* qubell
# Data setup and running the game
Ensure your folder with your unpacked data looks like this:
- data
- prop
- Various dll files including jubeat.dll
Unpack the package containing jbhook into the folder containing the jubeat.dll
file.
Run the gamestart.bat file.
# Eamuse network setup
* Open the prop/ea3-config.xml
* Replace the *ea3/network/services* URL with network service URL of your
choice (for example http://my.eamuse.com)
* Edit the *ea3/id/pcbid*
# Real hardware support
Run the launcher without the hook dll: *launcher jubeat.dll*
# Troubleshooting and FAQ

2
doc/tools/aciotest.md Normal file
View File

@@ -0,0 +1,2 @@
Test your real ACIO hardware connected to your machine using this tool. Just
execute it and follow the usage instructions.

3
doc/tools/eamiotest.md Normal file
View File

@@ -0,0 +1,3 @@
Testing tool for development of eamio libraries used for emulating card reader
hardware on bemanitools. Just place eamiotest.exe and the eamio.dll your
custom eamio.dll in the same folder and run eamiotest.exe.

6
doc/tools/ezusb-iidx-fpga-flash.md Normal file
View File

@@ -0,0 +1,6 @@
Flash a binary FPGA binary (not hex) firmware image to the FPGA of a EZUSB
board. This assumes that your IO board is already flashed using a base
firmware image (either by the game itself or using the *ezusb-tool*
application). Just call the executable and follow the usage instructions.
The type *v1* refers to the first gen protocol used from iidx 9 to 13 and *v2*
to the second gen protocol used from iidx 14 onwards.

4
doc/tools/ezusb-iidx-sram-flash.md Normal file
View File

@@ -0,0 +1,4 @@
Tool to write a binary (not hex) image to the SRAM of a ezusb board.
Just run the executable and follow the usage instructions. Ensure that the
correct base firmware supporting SRAM is flashed to the board prior using this
(either by the game or using the *ezusb-tool* application).

6
doc/tools/ezusb-tool.md Normal file
View File

@@ -0,0 +1,6 @@
Tool for fundamental legacy EZUSB management tasks, e.g. scanning for connected
devices, querying basic device info (vid, pid, name) and flashing firmware.
This tool requires the "cyusb" driver to be installed and does NOT work with the
"cyusb3" driver and thus not on anything newer than WinXP.
Just run the tool without any arguments to get usage information.

22
doc/tools/ezusb2-dbg-hook.md Normal file
View File

@@ -0,0 +1,22 @@
A hook library for debugging and dumping usb requests of games that use the
ezusb IO board (IIDX C02, IIDX IO2, Pop'n Music IO2). The library creates
a log file *ezusbdbg.log* in the same directory as your library/executable
which contains data dumps of the usb device's traffic.
Example usage:
*inject iidxhook1.dll ezusbdbg-hook.dll bm2dx.exe ...*
*launcher -K ezusbdbg-hook.dll bm2dx.dll ...*
Make sure to provide the following additional arguments:
*--ezusbdbg_path <device path>*
The device path points to the path to open the device, e.g. on the old IIDX
games that was *"\\\\.\\Ezusb-0"*. If you don't know the path, you can run
the hook with dummy data, e.g. *--ezusbdbg_path asdfgqwer* and check the log
for any logged open calls with paths to find your ezusb device.
--ezusbdbg_type <1 or 2>
Specify the type of device to debug. *1* is for the legacy ezusb device, e.g.
IIDX C02, and *2* for the FX2 type device, e.g. IIDX IO2, Pop'n IO2.
Both parameters must be specified, otherwise the hook will error. Make sure
to check the logfile for any errors or warnings as well.

6
doc/tools/ezusb2-tool.md Normal file
View File

@@ -0,0 +1,6 @@
Tool for fundamental EZUSB FX2 management tasks, e.g. scanning for connected
devices, querying basic device info (vid, pid, name) and flashing firmware. This
tool requires the newer "cyusb3" driver and does NOT work with the old "ezusb"
driver.
Just run the tool without any arguments to get usage information.

12
doc/tools/iidx-ezusb-exit-hook.md Normal file
View File

@@ -0,0 +1,12 @@
A hook library that can be used with BeatmaniaIIDX games that run the old ezusb
IO board (e.g. 9-13). It allows you to exit the game by pressing Start P1 +
Start P2 + VEFX + Effect simultaneously. This is very useful if you want an
option to exit back to your desktop without having a keyboard attached.
The exit hook lib must be loaded like any other hook lib you are already
injecting to the game using *inject*. The order for the hook libs is important
as they are loaded in the order specified for the inject call. The entry in
the *gamestart.bat* file should look like this:
*inject iidxhook1.dll iidx-ezusb-exit-hook.dll bm2dx.exe ...*
Where iidxhook1 is used for version 9-12. Use iidxhook2 for version 13.

15
doc/tools/iidx-ezusb2-exit-hook.md Normal file
View File

@@ -0,0 +1,15 @@
A hook library that can be used with BeatmaniaIIDX games that run the ezusb
FX2 IO board (e.g. 14-24). It allows you to exit the game by pressing Start P1 +
Start P2 + VEFX + Effect simultaneously. This is very useful if you want an
option to exit back to your desktop without having a keyboard attached.
The exit hook lib must be loaded like any other hook lib you are already
injecting to the game using either *inject* or *launcher* (depending on the game
version). The order for the hook libs is important as they are loaded in the
order specified for the inject/launcher call. The entry in the *gamestart.bat*
file should look like this for inject:
*inject iidxhook3.dll -K iidx-ezusb2-exit-hook.dll bm2dx.exe ...*
...and for launcher:
*launcher -K iidxhook4.dll -K iidx-ezusb2-exit-hook.dll bm2dx.dll ...*
Where iidxhook3 is used for 14-15 and iidxhook4 for 20-24.

3
doc/tools/iidxiotest.md Normal file
View File

@@ -0,0 +1,3 @@
Testing tool for development of iidxio libraries used for emulating the main io
hardware on bemanitools for BeatmaniaIIDX. Just place iidxiotest.exe and your
custom iidxio.dll in the same folder and run iidxiotest.exe.

72
doc/tools/mempatch-hook.md Normal file
View File

@@ -0,0 +1,72 @@
# A simple memory patching hook
This is a hook which can be passed along with other hooks to be injected into
the target application of your choice (e.g. when using inject or launcher). It
allows you to patch raw memory contents of either the target application or
any libraries loaded with it. No static hex-edits anymore. Instead, create a
simple script file and also document your patches for others which allows them
to easily disable/enable them.
# Setup
Copy the *mempatch-hook.dll* to the target application of your choice and add
it to the list of libraries to inject:
Example when using *inject.exe*:
```
inject iidxhook3.dll mempatch-hook.dll bm2dx.exe --options iidxhook-16.conf --mempatch myPatch.mph %*
```
When using *launcher.exe*:
```
launcher -K iidxhook4.dll -K mempatch-hook.dll bm2dx.dll --options iidxhook.conf --mempatch myPatch.mph %*
```
To load a patch script, add the *--mempatch <path to patch script>* argument (as
shown above in the example). You can specify this more than once which allows
you to apply multiple scripts in order, e.g.
*--mempatch myPatch1.mph --mempatch myPatch1.mph*.
# Patch script format
A patch script is a simple list of items seperated by a newline character
(i.e. one item = one line). Example script file:
```
# This is a comment
# Use comments to document your patches and make the script useful for others
# Empty lines are allowed as well and skipped by the patcher
# All numbers specified are hex format only.
# First entry which gets processed by the patcher. One entry specifies a single
# patch to apply starting a the specified address
# The first parameter (bm2dx.exe) is the base address. Specify the exe name
# of the application for relative addreses to patch inside the exe. You can
# also specify dlls loaded by the target application (e.g. libacio.dll)
#
# The second parameter (137C4C) is the offset. The target address for this patch
# is bm2dx.exe + 137C4C (bm2dx.exe commonly resolves to 400000) -> 5137C4C
#
# The third parameter is the data to patch at the target location. This byte hex
# string can have an arbitrary even length.
#
# The fourth parameter is optional and allows you to specify the expected data
# at the target loation before patching. This gives you the chance to add some
# sort of checksum'ing for the patches if you want.
bm2dx.exe 137C4C 2121212121 4540
# The first parameter can also be - which resolves to a base memory address of
# 0 for the loaded application.
# So the target address here is 0 + 537C4C = 537C4C
#
# The fourth parameter isn't used here (optional)
- 537C4C 2222212122
# You can also set the third parameter to '-' which means no data and disables
# the patching. This allows you to use the fourth parameter and execute a
# memory check, only. This can be used for signiture checking of the target
# application
bm2dx.exe 137C4C - 4540
```

2
doc/tools/pcbidgen.md Normal file
View File

@@ -0,0 +1,2 @@
Tool to generate random and (checksum) valid PCBIDs used on various Konami
Arcade games.