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