Max/pumpitupdev_pumptools
1
0
Fork 0
mirror of https://github.com/pumpitupdev/pumptools.git synced 2026-10-05 13:17:55 +03:00
Code Issues Packages Projects Releases Wiki Activity

Version 1.08 with public source code release.

Browse Source
This commit is contained in:
icex2
2020-10-03 20:56:55 +02:00
parent 656148121d
commit 762bf140c0
555 changed files with 55502 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/hook/exchook.md
+54
View File
@@ -0,0 +1,54 @@
# exchook: Exceed
This readme covers any matters that are relevant for this hook, only. Anything that applies to **all** hooks is covered
in a [main hook readme file](../hook.md) including general data setup and a quick start guide.
## Additional notable features
* Full MK5IO emulation with API hook: Keyboard, MK6 PIUIO or your own custom IO
* Fixed infamous hold glitch, i.e. make the damn game playable, finally
## Versions supported
* 20040325
* 20040408
Any other version won't work, period. Pumptools has to memory patch various things like I/O because hooking them is not
possible (at least not right now).
## Dependencies
Make sure to read the different methods of dependency resolution available in the [main hook readme file](../hook.md),
first.
The following **direct** dependencies (cmd: `readelf -d piu`) are required:
* libGL.so.1
* libGLU.so.1
* libpthread.so.0
* libasound.so.2
* libz.so.1
* libpng12.so.0
* libc.so.6
* libm.so.6
* libX11.so.6
* libstdc++.so.5
Additionally, when using `piuio.so`, you need the following library as well:
* libusb-1.0.so.0
As for method 1, when using Ubuntu, the dependencies can be found in the following packages:
* libc-bin (or gcc-multilib on a 64-bit platform)
* libusb-1.0-0
* libx11-6
* zlib1g
* libasound2
## Data setup
In additional to the [general information applying to **all** hooks](../hook.md#data-setup), this game requires all
files and folders in the `game` folder to be in **UPPERCASE** on a case-sensitive file system.
## Troubleshooting and FAQ
Make sure to also check the
[troubleshooting and FAQ section of the main hook readme](../hook.md#troubleshooting-and-faq). This covers various
things that apply to **all** hooks. The following sub-sections apply mainly to this hook.
### The game crashes when using the sound device hw:0
The game's sound manager relies on hardware mixing using the same device which is not supported by newer versions of
alsa anymore. Instead, you have to use software mixing using the `dmix` device,
[see here](#the-game's-music-plays-too-fast-or-sounds-weird).
doc/hook/f2hook.md
+96
View File
@@ -0,0 +1,96 @@
# Notable features
* Runs on recent kernel versions thanks to various fixes
* Runs on 32-bit and 64-bit distros (64-bit distros require additional 32-bit libs to be installed)
* Full dongle emulation
* Remove HDD checks to run this on "non legit" drives
* Full MK6IO emulation with API hook: Keyboard or your own custom IO
* Real IO passthrough (for MK6 usb io)
# Versions supported
All known versions supported.
# Data setup
You are expected to get a clean set of data from a prestine drive. Ensure that
the game version matches one of the supported versions listed.
You need two main folders:
* data
* settings
## Data folder
Contents of the folder:
* game: The binaries of the custom "AMFS". File names must be lower case.
* lib: Put any libraries (especially older versions of libraries that can't be
installed anymore using the package manager) the game uses and aren't installed
on your system in here.
* piu: The piu executable
## Settings folder
The contents of the folder are auto generated if the files don't exist.
Otherwise, this folder contains:
* PIUFESTA2.INI
* RANK.DATA
## Executable dependencies
All dependencies must be compiled as 32-bit binaries. Here is a list of
dependencies (with versions) required to run the game:
* libGL.so.1
* libGLU.so.1
* libasound.so.2
* libusb-0.1.so.4
* libmad.so.0
* libmpeg2.so.0
* libmpeg2convert.so.0
* libftgl.so.2
* libstdc++.so.6
* libgcc_s.so.1
* libc.so.6
* libm.so.6
* libX11.so.6
* libpthread.so.0
* libdl.so.2
* librt.so.1
* libnvidia-tls.so.340.96
* libnvidia-glcore.so.340.96
* libXext.so.6
* libusb-1.0.so.0
* libfreetype.so.6
* libxcb.so.1
* libudev.so.1
* libz.so.1
* libbz2.so.1.0
* libpng16.so.16
* libharfbuzz.so.0
* libXau.so.6
* libXdmcp.so.6
* libcap.so.2
* libresolv.so.2
* libglib-2.0.so.0
* libgraphite2.so.3
* libpcre.so.1
# Hook module configuration file
Checkout the usage information of the hook and set the option values according
to your needs. Here is an example option configuration file:
```
log_file_path=/tmp/pumptools.log
log_level=3
enable_file_monitor=0
enable_io_monitor=0
piuio_emu_lib_path=/pumptools/lib/piuio-emu.so
piuio_exit_test_service=1
game_settings_path=/save/f2
sound_device=hw:0
keyboard_dev=/dev/input/by-id/usb-Logitech_USB_Receiver-if02-event-mouse
halt_on_segv=0
```
# Run the game
Ensure you are running an X screen. Otherwise, you have to start one along with the game. Various library/system-calls
require root privileges. Make sure to run the game as root or with sudo (otherwise you get various sorts of errors,
typically permission denied). Use the included *run.sh* file to start the game on a desktop environment.
# Further notes
## Vsync
The game is required to run with vsync on.
doc/hook/fexhook.md
+88
View File
@@ -0,0 +1,88 @@
# Notable features
* Runs on recent kernel versions thanks to various fixes
* Runs on 32-bit and 64-bit distros (64-bit distros require additional 32-bit libs to be installed)
* Full dongle emulation
* Remove HDD checks to run this on "non legit" drives
* Full MK6IO emulation with API hook: Keyboard or your own custom IO
* Real IO passthrough (for MK6 usb io)
# Versions supported
All known versions supported.
# Data setup
You are expected to get a clean set of data from a prestine drive. Ensure that
the game version matches one of the supported versions listed.
You need two main folders:
* data
* settings
## Data folder
Contents of the folder:
* game: The binaries of the custom "Fiesta FS". These are stored in raw areas
of the HDD and have to be extraced. File names must be lower case.
* lib: Put any libraries (especially older versions of libraries that can't be
installed anymore using the package manager) the game uses and aren't installed
on your system in here.
* piu: The piu executable
## Settings folder
The contents of the folder are auto generated if the files don't exist.
Otherwise, this folder contains:
* PIUFESTAEX.INI
* RANK.DATA
## Executable dependencies
All dependencies must be compiled as 32-bit binaries. Here is a list of
dependencies (with versions) required to run the game:
* libGL.so.1
* libGLU.so.1
* libasound.so.2
* libusb-0.1.so.4
* libmad.so.0
* libmpeg2.so.0
* libmpeg2convert.so.0
* libstdc++.so.6
* libm.so.6
* libgcc_s.so.1
* libc.so.6
* libX11.so.6
* libpthread.so.0
* libdl.so.2
* librt.so.1
* libnvidia-tls.so.340.96
* libnvidia-glcore.so.340.96
* libXext.so.6
* libusb-1.0.so.0
* libxcb.so.1
* libudev.so.1
* libXau.so.6
* libXdmcp.so.6
* libcap.so.2
* libresolv.so.2
# Hook module configuration file
Checkout the usage information of the hook and set the option values according
to your needs. Here is an example option configuration file:
```
log_file_path=/tmp/pumptools.log
log_level=3
enable_file_monitor=0
enable_io_monitor=0
piuio_emu_lib_path=/pumptools/lib/piuio-emu.so
piuio_exit_test_service=1
game_settings_path=/save/fex
sound_device=hw:0
keyboard_dev=/dev/input/by-id/usb-Logitech_USB_Receiver-if02-event-mouse
halt_on_segv=0
```
# Run the game
Ensure you are running an X screen. Otherwise, you have to start one along with the game. Various library/system-calls
require root privileges. Make sure to run the game as root or with sudo (otherwise you get various sorts of errors,
typically permission denied). Use the included *run.sh* file to start the game on a desktop environment.
# Further notes
## Vsync
The game is required to run with vsync on.
doc/hook/fsthook.md
+89
View File
@@ -0,0 +1,89 @@
# Notable features
* Runs on recent kernel versions thanks to various fixes
* Runs on 32-bit and 64-bit distros (64-bit distros require additional 32-bit libs to be installed)
* Full dongle emulation
* Remove HDD checks to run this on "non legit" drives
* Full MK6IO emulation with API hook: Keyboard or your own custom IO
* Real IO passthrough (for MK6 usb io)
# Versions supported
All known versions supported.
# Data setup
You are expected to get a clean set of data from a prestine drive. Ensure that
the game version matches one of the supported versions listed.
You need two main folders:
* data
* settings
## Data folder
Contents of the folder:
* game: The binaries of the custom "Fiesta FS". These are stored in raw areas
of the HDD and have to be extraced. File names must be lower case.
* lib: Put any libraries (especially older versions of libraries that can't be
installed anymore using the package manager) the game uses and aren't installed
on your system in here.
* piu: The piu executable
## Settings folder
The contents of the folder are auto generated if the files don't exist.
Otherwise, this folder contains:
* PIUFESTA.INI
* RANK.DATA
## Executable dependencies
All dependencies must be compiled as 32-bit binaries. Here is a list of
dependencies (with versions) required to run the game:
* libGL.so.1
* libGLU.so.1
* libasound.so.2
* libusb-0.1.so.4
* libmad.so.0
* libmpeg2.so.0
* libmpeg2convert.so.0
* libstdc++.so.6
* libm.so.6
* libgcc_s.so.1
* libc.so.6
* libX11.so.6
* libpthread.so.0
* libdl.so.2
* librt.so.1
* libnvidia-tls.so.340.96
* libnvidia-glcore.so.340.96
* libXext.so.6
* libusb-1.0.so.0
* libxcb.so.1
* libudev.so.1
* libXau.so.6
* libXdmcp.so.6
* libcap.so.2
* libresolv.so.2
# Hook module configuration file
Checkout the usage information of the hook and set the option values according
to your needs. Here is an example option configuration file:
```
log_file_path=/tmp/pumptools.log
log_level=3
enable_file_monitor=0
enable_io_monitor=0
piuio_emu_lib_path=/pumptools/lib/piuio-emu.so
piuio_exit_test_service=1
game_settings_path=/save/fst
sound_device=hw:0
keyboard_dev=/dev/input/by-id/usb-Logitech_USB_Receiver-if02-event-mouse
halt_on_segv=0
```
# Run the game
Ensure you are running an X screen. Run the game using
Ensure you are running an X screen. Otherwise, you have to start one along with the game. Various library/system-calls
require root privileges. Make sure to run the game as root or with sudo (otherwise you get various sorts of errors,
typically permission denied). Use the included *run.sh* file to start the game on a desktop environment.
# Further notes
## Vsync
The game is required to run with vsync on.
doc/hook/hook.md
+201
View File
@@ -0,0 +1,201 @@
# Pumptool's hook libraries
A collection of libraries that need to be pre-loaded when running vanilla dumps of Pump It Up games. These hooks allow
you to run any of the supported games on any* Linux distribution and hardware.
Each game might require a different hook library as the software evolved as well as the hardware and original
operating system changed a few times as well.
## General features
A few notable features:
* Run any supported gam on recent kernel versions thanks to various fixes
* Run any supported game on 32-bit and 64-bit distros (64-bit distros require additional 32-bit libs to be installed)
* Full dongle emulation
* Remove HDD checks to run this on "non legit" drives
* Full IO hardware emulation: MK6 PIUIO, Pro Button board (PIUBTN)
* Real IO passthrough
* API: Implement support for your own custom IO
## Supported games and versions
Check each of the dedicated hook readmes which games and versions are supported.
## Hardware, operating system and environment
A general outline is given by [this readme](os.md) if you want to setup something yourself. Otherwise, you should
checkout the `pumpos` project in a repository nearby which takes care of installing a fully configured OS to a physical
disk to run the games on dedicated hardware for cabinets.
## Quick start: how to run (official release)
The following steps apply to any game of the "officially" supported release data.
1. Install the required dependencies which can vary per game. Check the section "required dependencies" in the dedicated
readme files of each hook.
1. Unpack `game.zip` and `lib-local.zip` to a folder of your choice.
1. Your folder should contain the following files and folders: `game`, `lib`, `piu`, `version`
1. Unpack the hook which supports the game you have chosen, e.g. for Exceed use `exchook.zip`, from the
`pumptools-X.XX.zip` release package next to the `piu` executable
1. Unpack the `piuio.zip` from the `pumptools-X.XX.zip` release package next to the `piu` executable
1. Rename the hook library, e.g. for Exceed `exchook.so`, to `hook.so` and the hook configuration file, e.g. for
Exceed `exchook.conf`, to `hook.conf`
1. Open `hook.conf` with a text editor and set the `patch.piuio.emu_lib` property accordingly:
* For keyboard usage: `patch.piuio.emu_lib=./ptapi-io-piuio-keyboard.so` and
`patch_hook_main_loop.x11_input_handler=./ptapi-io-piuio-keyboard.so"`
* Configure your keyboard mappings using `./ptapi-io-piuio-keyboard-conf`
* For USB PIUIO usage: Do not set the `patch.piuio.emu_lib` property and have the hardware plugged in.
1. Run the game as logged in root user: `./piueb run` or if you have `sudo` installed and configured: `sudo ./piueb run`
Details to specific games are given in the hook read files dedicated to each supported version. Further general
configuration and technical details as well as troubleshooting known issues are described in following sections.
## Dependencies
A list of dependencies is provided in the dedicated hook readme files for each game. The following is a general guide
on how dependencies of the games can be resolved to run them.
Right now, there are two methods for resolving the dependencies and which dependencies to use for the game:
* __Method 1__: Install as many dependencies as possible using the package manager of your distribution. Usually, you want
to go for method 1 and if the game runs, you don't have to bother with method 2. A few less common libraries are
provided with the official data release and are loaded from the local `lib` folder instead.
* __Method 2__: Provide **all** libraries except GPU related ones and a dedicated ld-linux loader with the game
independent from your system. Theoretically, this gives you full distribution independence but it is more complicated
and comes with a few unresolved issues so far. If method 1 doesn't work for you, try this method. For details, see the
[following section](#local-data-folder).
## Data setup
You are expected to get a clean set of data from a pristine drive. Ensure that the game is supported by one of the
hook libraries coming with pumptools and the game's version is on the list supported versions.
You are not required to have the pulled data in the same locations as on the original drive as the hook library can
be configured to have everything in a single local folder. These settings can be found and tweaked in the `hook.conf`
file which is created after you started the game once.
### Local data folder
Your local data folder must contain the following folders and files:
* `game`: The `game` asset folder from the HDD. Filename casing depends on the games and is relevant on case-sensitive
file systems. Exact requirements are explained in the readme files of each hook. Otherwise, the game crashes because of
files/folders it cannot find. Furthermore, put any additional files/folders that are game assets and not located in
the original `game` folder into the `game` folder, e.g. `mission.txt`, `SCRIPT` folder etc. which are located in
the cramfs on some games.
* `lib`: Put any libraries (especially older versions of libraries that can't be installed anymore using the package
manager) the game uses and aren't installed on your system in here. Using piueb, you have two options with potential
different (in-)compatibility issues:
1. Have **all** libraries the game requires to run (except GPU driver specific libs) with compatible version in that
folder including a dedicated `ld-linux.so`. See [piueb script header documentation](../../dist/piueb).
1. Have only additional libraries that are not common/available on with your package manager **without** a dedicated
`ld-linux.so`.
* `save`: Empty folder where the the game stores configuration. These files are created by the game automatically and
contain default values if missing.
* `piu`: The Linux port `piu` executable.
## Configure IO
The hooks allow you to hook any implementation of [pumptools's API](../api/api.md) to the game to drive any type of IO
hardware. See the [dedicated readme](../api/io/piuio.md) on how to configure the PIUIO with the different types
of implementations available, e.g. keyboard, joystick, ...
## Troubleshooting and FAQ
The following sub-sections apply to all hooks.
### USB 3.0 vs 2.0 issues with USB thumb drives/profiles
This affects *ALL* games that make use of USB thumb drives for storing player profile related data.
Due to how the Linux kernel treats bus-port mappings for USB 3.0 and USB 2.0 different, it is recommended to limit the
usage of USB thumb drives either to 3.0 or 2.0 drives only after having configured the port assignment for the affected
games.
For example, you use a USB 2.0 thumb drive to assign one physical USB ports on your machine to each player side using
NX2's operator menu configuration option. However, the configured assignment is only working for USB 2.0 drives. If
you repeat this configuration step with a USB 3.0 drive (if your mainboard supports them because it has a USB 3.0
host controller), you will get different `bus:port` values shown on the configuration screen. Keep this in mind when
setting up the game, assigning the ports and using USB thumb drives with the games.
### My USB thumb drive is not detected by the game at all
Which means you cannot use it to even map the USB ports in the test menu.
Make sure to try at least another one by a different brand. There have been reports of some thumb drives simply not
working, e.g. a fairly old Kingston 1GB. In general, everything that gets detected fine by Linux should work.
### My USB thumb drive works when mapping the ports in the test menu but is not recognized on the game login screen
Might be the same issue as [here](#my-usb-thumb-drive-is-not-detected-by-the-game-at-all). Try out different USB thumb
drives. Be aware of the [USB 3.0 vs 2.0 issue](#usb-30-vs-20-issues-with-usb-thumb-drivesprofiles) as well.
### The game enters the operator menu when I start it
This is known to happen consistently on NX but was observed on other versions like Exceed 2 and Zero in the past. The
cause for this is unknown so far. Even with all usb emulation layers removed from pumptools and a real MK6 PIUIO
attached this still happens. If the game is run without the PIUIO attached, everything's fine. Therefore, we suspect
this is a bug within the game's PIUIO driver, likely some uninitialized buffers (due to the randomness of this bug
being triggered).
### How to I generate a fresh configuration file with default values
If you deleted your `hook.conf` file or you just want a clean start with default values, the hook creates a clean
`hook.conf` file if none exists once you run `piueb`.
### What are the command line arguments supported by the hook
Just run `piueb run -h` to get help output from the hook library. This also provides you with shortened command line
parameters for all options available from the configuration file.
### How do I provide command line arguments to quickly change configuration settings for the game
Just run `piueb run` with the shortened command line parameter, e.g. `piueb run -w`.
### The game's music plays too fast, too slow, or sounds weird
Depending on the game version you play, the audio subsystem is set to either render to an output device with a
frequency of 44100hz or 48000hz in SE16_LE format. Alsa needs to be configured accordingly to play back the audio
data at the right sample rate to make it sound right.
Games and audio settings required:
* 44100hz: MK3 Linux ports 1st to Prex 3, Exceed (1), Pro 1 and Pro 2
* 48000hz: Exceed 2 and newer
One possibility to fix that is change the values in your config, e.g. `/usr/share/alsa/pcm/dmix.conf` when using the
`dmix` device (the location and config can differ depending on your setup). In case you have to set them to 48000hz,
search for the following configuration values and replace them with these values:
```
format S16_LE
rate 48000
```
If the contents of the files are just variables, check `/usr/share/alsa/alsa.conf` something similar like this:
```text
defaults.pcm.dmix.rate 44100
defaults.pcm.dmix.format "S16_LE"
```
The same method applies to replacing 44100hz with 48000hz.
### How do I figure out which sound device to select
You can list the currently connected devices/sound cards using the following command:
```shell script
cat /proc/asound/cards
```
Example output:
```text
0 [PCH ]: HDA-Intel - HDA Intel PCH
HDA Intel PCH at 0xfb610000 irq 51
1 [NVidia ]: HDA-Intel - HDA NVidia
HDA NVidia at 0xfb080000 irq 52
```
You can see two audio devices available: `0` being the built-in sound chip and `1` the audio output on the installed
GPU (i.e. HDMI audio out).
To route the audio to the device of your choice, e.g. device `0`, add the number to the `hw:` path: `hw:0` for device
`0`. Set `hw:0` in the configuration file:
```text
patch.sound.device=hw:0
```
### The game plays/renders too fast
The game relies on vsync to lock to the target framerate of 60 FPS. Ensure vsync is turned on in your GPU settings.
### libGL.so.1: cannot open shared object file: No such file or directory
Install your GPU drivers. This library depends on the GPU driver and is not included with the distributed data.
### There's no sound at all, even with the correct sound device selected
On certain setups, the sound output only seems to work after already having attempted to use the sound device once.
In a shell, try running the following command twice:
```shell script
aplay -q /usr/share/sounds/alsa/Front_Center.wav
```
If after a fresh boot the sound plays after the second attempt, your setup suffers from this issue.
Simply putting the above command once in a boot script will make sure the sound device is activated.
doc/hook/mk3hook.md
+283
View File
@@ -0,0 +1,283 @@
# mk3hook: 1st to Prex 3/Premiere 3 Linux ports
This readme covers any matters that are relevant for this hook, only. Anything that applies to **all** hooks is covered
in a [main hook readme file](../hook.md) including general data setup and a quick start guide.
First and foremost, the MK3 Linux ports are runnable without this hook as well. The ports were created from the original
fully disassembled DOS binaries and reassembled for 32-bit Linux. To make the games run on modern non-MK3 hardware,
additional features were added to the disassembly:
* Software lockchip emulation
* ISA PIUIO to USB PIUIO (over libusb)
* MP3 audio decoding and playback using fmodex
* Software sound effect playback
* Software EEPROM data reading/writing
However, since modifying the (decompiled) source code is a very complex task, various additional features and fixes
are applied using a hook library. This lacks certain flexibility but is so far sufficient to fix various bugs and add
some more quality of life features.
## Additional notable features
* Audio subsystem using fmodex: Bugfixes and audio device selection
* Relocate game data to `game` sub-folder to have identical data layout to newer generation games
* Additional development/debugging features, e.g. file, io, open logging and tracing
* Hardcoded OpenGL bugfix
* Utilize pumptools configuration infrastructure to unify configuration of all games
## Versions supported
Basically, "all" versions are supported considering there was only one Linux binary per game released so far.
## Quick start: how to run (official release), additional steps
Start with the quick start guide from the [main hook readme](../hook.md#quick-start-how-to-run-official-release) and
add the additional steps at the very end:
1. **1st and 2nd only**: Open the `hook.conf` file and set the following property: `game.1st_2nd_fs=1`. For details, see
[this section](#1st-or-2nd-errors-about-failed-resource-loading)
1. **1st only**: Go straight to the operator menu by pressing `G` on your keyboard. Go to `GAME OPTION`, select and
confirm `DEFAULT SETTING` and `SAVE AND EXIT`. Next, go to `COIN OPTION`, `DEFAULT SETTING` and `SAVE AND EXIT`. See
[this section](#1st-crashes-right-after-the-andamiro-logo-or-the-intro-sequence-when-i-should-see-the-title-screen-with-a-floating-point-exception)
for details.
## Dependencies
Make sure to read the different methods of dependency resolution available in the [main hook readme file](../hook.md),
first.
The following **direct** dependencies (cmd: `readelf -d piu`) are required by all Linux ports:
* libGL.so.1
* libX11.so.6
* libXxf86vm.so.1
* libXrandr.so.2
* libpthread.so.0
* libXi.so.6
* libXcursor.so.1
* libXinerama.so.1
* libm.so.6
* libncurses.so.5
* libtinfo.so.5
* libfmodex.so
* libconfig.so.9
* libusb-0.1.so.4
* libc.so.6
As for method 1, when using Ubuntu, the dependencies can be found in the following packages:
* libc-bin (or gcc-multilib on a 64-bit platform)
* libusb-0.1-4
* libconfig++9v5
* tinfo5
* ncurses5
* libxcursor1
* libxinerama1
* libxi6
* libxrandr2
* libxxf86vm1
* libx11-6
* libasound2
## Data setup
In additional to the [general information applying to **all** hooks](../hook.md#data-setup), the following information
goes for a clean set of data from a pristine/non-bootleg CD.
If you have the official release, this might not be relevant to you as it just explains some important technical details
about the data.
In general, get a clean set of data from a pristine/non-bootleg CD.
However, 1st, 2nd and 3rd and Extra (IIRC) are the exception here. These games have their textures packed in an odd
format (IIRC something about an odd color format and/or textures being flipped) that cannot be used with the Linux port
versions. These versions require file modification and repacking to make everything look correct with the linux
binaries.
Furthermore, because the old games ran on case-insensitive file systems, everything goes with file naming depending on
the version of the game, e.g. full upper/lower-case files, folders and even mixed ones, e.g. Stage.cfg (*sigh*).
In order to make this less painful for the the hook library, some file names were modified to create some sort of
consistency.
You are not required to have the pulled data in the same location and layout as given by the original layout on the
disc as this can be configured with the hook library. Everything can be located locally in a single folder. The settings
for this can be found and tweaked in the `hook.conf` file which is created after you started the game once
([see below](#mk3hook-features)).
#### The game data subfolder
This differs slightly from newer generation games, i.e. MK6-based and newer. The hook library takes care of this by
implementing a consistent directory structure on all versions of the game. Therefore, all game data from the CD of MK3
games goes into a `game` folder as well. Example of `games` contents for Prex 3:
* `AUDIO`
* `BGA`
* `STEP`
* `TITLE`
* `PIU.BIN`
* `STAGE.CFG`
Furthermore, the game needs to have the sound effects available as files. These were stored on a ROM chip on the MK3
hardware. Luckily, newer PC-based games have these as normal files with the correct naming in the `game/WAVE` subfolder.
These also go into `game/EFFECTS`.
Some other and older versions come with different files and folders but the process is identical. The first three games,
1st, 2nd and 3rd, had their audio files stored on disc as PCM audio data next to the other game assets. These audio
files need to be ripped and provided as MP3 encoded audio files in the sub-folder `game/track`.
## Linux port features
This section covers the features that were added to the Linux ports and therefore not available on the original DOS
versions.
### Configuration file
A configuration file with different options can be provided to the game's bare executable. The configuration is provided
as a command line argument when running the game, e.g.
```
./piu ./save/config.cfg
```
Example contents:
```
fullscreen = 1;
allow_exit = 1;
save_file = "./save/EEPROM.BIN";
effect_path = "./EFFECTS/";
track_path = "./track/";
sync_offset = 115;
sync_multiplier = 4.16666666666666696272613990004;
music_volume = 1.0;
sfx_volume = 1.0;
```
Most entries are self-explanatory. However, there are two parameters that can be tweaked to control synchronisation of
the stepchart to the music.
The `sync_offset` parameter (in ms) is used to offset the stepchart to the music. However, as you might be used to such
a parameter from other music games, this offset is **NOT** entirely identical to adjusting the music to your sound
system's latency. You can use this value to shift the synchronisation point forward and backward but keep in mind that
it will not match any other offset values you determined in other games.
The `sync_multiplier` is also a variable that was depending on the sound hardware of the target platform. It was
already determined and there should be **NO** reason to change it unless you know what it does and how it is used in
synchronizing the stepchart to the song in the engine.
All these configuration values are exposed via the `hook.conf` file and hooked to the pumptools configuration
infrastructure. Usually, there is no need to deal with this directly, so this is section is mainly for documenting its
presence.
### Built-in keyboard controls
Ignore this section if you are using the `mk3hook` because it will disable this feature entirely. See
[this section](#configure-io).
The following keyboard controls are available with the Linux ports.
PIUIO hooked controls:
```
Test: Key G
Service: Key H
Clear: Key J
Coin 1: Key K
Coin 2: Key L
Pads (Player 2 on numpad):
Q E 7 9
S 5
Z C 1 3
```
Keyboard controls supported by the game engine (won't work on very early versions of the game, e.g. 1st, 2nd, 3rd):
```
Test: F1
Service: F2
Clear: F3
```
### USB PIUIO
Ignore this section if you are using the `mk3hook` because it will disable this feature entirely. See
[this section](#configure-io).
When a USB PIUIO is plugged it, the game will automatically detect and use it.
### Exit the game
Use `Test` + `Service` on the USB PIUIO (controls) to exit the game. This can also be blocked in the configuration.
## mk3hook features
Check the `hook.conf` file which is located in the same folder as the `piu` executable once you have started the game.
The available settings are explained in the `hook.conf` file.
### Configure IO
See [this section of the main hook readme](../hook.md#configure-io).
### Select another audio device
If the default sound card is not working, e.g. see [here](#no-sound-and-fmod-errors-in-log), you might want to
select another audio device/card instead.
In order to find out which cards are available and which configuration value to set, you have to run the game once.
Check the log and you will see a list of available devices printed somewhere at the beginning of the log, for example:
```
Output type: 11
Num available drivers 43
Driver 0: default
Driver 1: null
Driver 2: jack
Driver 3: sysdefault:CARD=PCH
Driver 4: front:CARD=PCH,DEV=0
...
```
By default and if you have not configured any sound device, yet, this will pick the first, usually, `default` device.
Pick another one by copying the name, e.g. `sysdefault:CARD=PCH`, and setting it in the `hook.conf` file:
```
patch.sound.device=sysdefault:CARD=PCH
```
When you restart the game, check the log if the device got picked up properly. This is indicated by a log message
right after the device list is printed.
### Debugging fmodex issues
You can also debug issues with fmodex, e.g. why
[the selected sound device does not work](#no-sound-and-fmod-errors-in-log).
You need to replace the normal `fmodex.so` library in the game local `lib` folder with a `fmodexL.so` version. Just
rename the "L"-version to `fmodex.so` and have it in the game local `lib` folder. Furthermore, you have to enable
debug output by setting the following configuration value in the `hook.conf` file:
```
patch.sound.debug_output=0
```
After that's done, you should see additional log output by fmodex on the console.
## Troubleshooting and FAQ
Make sure to also check the
[troubleshooting and FAQ section of the main hook readme](../hook.md#troubleshooting-and-faq). This covers various
things that apply to **all** hooks. The following sub-sections apply mainly to this hook.
### No sound and FMOD errors in log
If you see one or multiple of the following error messages in the log output
```
FMOD error! (60) Error initializing output device.
FMOD error! (79) This command failed because System::init or System::setDriver was not called.
FMOD error! (37) An invalid parameter was passed to this function.
```
it is very likely that fmod cannot use the default/currently selected audio device for playback. This can have various
reasons from non suitable configuration to device being used by another process and therefore blocked if not supporting
software mixing.
Choose another device for playback instead, see [this section](#select-another-audio-device), or you can enable
fmodex debug output to further debug this issue, see [this section](#debugging-fmodex-issues).
### 1st/2nd is missing the "Insert Coin" text on the title screen and several other graphics, e.g. life bar during gameplay
This is a known bug and we do not have a fix for this so far. However, this is not always triggered and if you keep
restarting the game (with a few seconds of waiting between restarts), you will start the game without this bug being
active eventually.
### 1st or 2nd errors about failed resource loading
For example:
```
FAIL: res_load( piu.dat )
```
This error indicates that one or multiple game files are not placed in the right location(s), your configured `game`
sub-directory path is not correct or you forgot to switch on the "1st/2nd filesystem" feature switch in the hook
configuration. For the latter, set the following in your `hook.conf` file:
```
game.1st_2nd_fs=1
```
### 1st crashes right after the Andamiro logo or the intro sequence when I should see the title screen with a floating point exception
1st does not detect if no EEPROM data is available and does not write defaults on first start or when you deleted the
`save/EEPROM.BIN` file. Therefore, all settings values for the game are considered "0". This is fine with all settings
except the coin settings. This causes the floating point exception though I assume it was actually caused by a division
by zero.
To fix this, go right to the operator menu when you booted up the game and are still on the Andamiro logo screen. Go
to `GAME OPTION`, select and confirm `DEFAULT SETTING` and `SAVE AND EXIT`. Next, go to `COIN OPTION`, `DEFAULT SETTING`
and `SAVE AND EXIT`. This writes a fresh `EEPROM.bin` file with all default settings and you are good to go.
doc/hook/nx2hook.md
+154
View File
@@ -0,0 +1,154 @@
# nx2hook: NX2
This readme covers any matters that are relevant for this hook, only. Anything that applies to **all** hooks is covered
in a [main hook readme file](../hook.md) including general data setup and a quick start guide.
## Additional notable features
* Removed USB flash drive vendor lock, i.e. use _ANY_ USB flash drive to store game profiles
* Auto generate new profiles if no profile is found on the connected USB flash drive
## Versions supported
All known versions supported.
## Dependencies
Make sure to read the different methods of dependency resolution available in the [main hook readme file](../hook.md),
first.
The following **direct** dependencies (cmd: `readelf -d piu`) are required:
* libfreetype.so.6
* librt.so.1
* libGL.so.1
* libGLU.so.1
* libusb-0.1.so.4
* libpthread.so.0
* libXxf86vm.so.1
* libpng12.so.0
* libasound.so.2
* libmad.so.0
* libgcc_s.so.1
* libc.so.6
* libm.so.6
* libX11.so.6
* libstdc++.so.6
* libz.so.1
As for method 1, when using Ubuntu, the dependencies can be found in the following packages:
* libc-bin (or gcc-multilib on a 64-bit platform)
* libx11-6
* zlib1g
* libusb-0.1-4
* libasound2
## Data setup
In additional to the [general information applying to **all** hooks](../hook.md#data-setup), this game requires all
files and folders from the original `game` folder to be in **UPPERCASE** on a case-sensitive file system with the
exception of `*.txt` and `*.ttf` files in the root of game. Further game asset files and folders from cramfs need to be
copied to the `game` directory. `nx.ttf`, `nxcn.ttf`, `nxpt.ttf`, `nxtw.ttf` and `mission.txt` must be **lowercase** but
`SCRIPT` and its contents must be **UPPERCASE**.
## Pumpnet setup
Instead of using plain usb profiles like on the vanilla version without pumptools (which is still possible with
pumptools), pumptools provides a patch module to upload/download usb profiles to/from a remote server over TCP IP
networks.
This feature can be enabled by setting the following configuration properties in the `hook.conf` file:
```text
patch.net_profile.server=<put the server address of the pumpnet server here>
patch.net_profile.machine_id=<put your machine id that's registered with the server here>
```
If the network offers or even requires secure communication using https, you should have received a package with a
client certificate, a client key and a certificate authority bundle. Place the files named `ca-bundle-crt.pem`,
`client-crt.pem` and `client-key.pem` in a folder, e.g. `cert` next to the `piu` executable and configure the hook
to use these for the encrypted communication by setting the property key `patch.net_profile.cert_dir_path`
accordingly, e.g. `patch.net_profile.cert_dir_path=./cert`. Note: The server URL that you set for the properties key
`patch.net_profile.server` has to be a https based URL in order to work correctly, e.g. `https://localhost`. Your
network provided of your choice should provide you the URL you have to use.
When everything's configured correctly, the log tells you so:
```text
Initialized pumpnet for game 20, serveraddr localhost:8080, main endpoint version /usbprofile/v1
Initialized: game 20, server XXXXXXX, machine id XXXXXXX
```
How you acquire an address to a remote server and a machine ID is out of this document's scope.
Once these parameters are present, pumptools is looking for a file called `pumpnet.bin` on connected usb sticks. As
long as this file is in the root directory of your usb drive, the game will ignore the the regular `nx2save.bin` and
`nx2rank.bin` files and always try to connect to the remote server. When you remove `pumpnet.bin`, it will pick up the
local profiles and not connect to the server, even if enabled.
`pumpnet.bin` contains an identifier for the player to login. This file needs to be provided by the network service
somehow. The how is out of the scope of this document.
Ensure you have mapped the usb ports in the game correctly. Go to the operator menu and the "usb drive" item. Plug
**exactly one** usb thumb drive into the usb port you want to assign as P1 and hit the test button. The menu item
should change from `---` to a numerical value, e.g. `03:00` which describes the bus and port the drive got detected on.
Repeat this for P2.
When you start the game, have your usb stick plugged in and it is recognized correctly by the game, the log output
tells you if it found the `pumpnet.bin` file and connected to the server correctly for downloading your profile data:
```text
Found pumpnet profile file /mnt/0/pumpnet.bin
Profile file player 0, file_type 0, refId XXXXXXXXXXXXXX downloading from server...
Downloading file player 0, file_type 0, refId XXXXXXXXXXXXXX successful
```
If it cannot connect to the server, the log tells you that as well and retries to connect to it a few times before
giving up:
```text
Performing curl request failed: Couldn't connect to server
Failed, http code 0, retrying (0)...
...
```
## Troubleshooting and FAQ
Make sure to also check the
[troubleshooting and FAQ section of the main hook readme](../hook.md#troubleshooting-and-faq). This covers various
things that apply to **all** hooks. The following sub-sections apply mainly to this hook.
### How do I unlock 'Tell Me' on the non korean version?
Put an empty file called `KEY.LUA` into the `game/SCRIPT` folder and change the language to korean in the operator menu.
This loads the korean version of the game (yes, that's how it actually worked originally) and 'Tell Me' will be
available.
Note: You can't switch back to English unless you delete the file `game/SCRIPT/KEY.LUA`.
### When using pumpnet, the game does not detect any usb sticks
Make sure that you have configured the usb ports in the game's operator menu `USB DRIVE` menu item. For instructions,
refer to the [above section](#pumpnet-setup).
### When using pumpnet, the game tells me to register my usb drive on login
If you see the message "Please REGISTER your USB drive at www.piugame.com prior to using the product." when logging in
with pumpnet enable, your login got rejected for one of the following reasons:
* Your machine ID is invalid or not whitelisted on the server
* Your player ID is invalid or no such player exists on the server
* No NX2 profile was created for the player ID on the server
On any of the above cases, verify that you ensured you have configured everything correctly on the user web interface
of pumpnet. Otherwise, contact the server administrator.
### When using pumpnet, the game apparently gets stuck on the usb drive login screen
This can happen if the game cannot reach the server or on some other errors that might be temporarily. Therefore, the
game retries for up to ten times currently to reach the server or complete an outstanding operation. This is also
reflected in the logs with warning messages telling you the game is retrying.
### Curl requests fail: Problem with the SSL CA cert
When you get the following error message:
```text
Performing curl request failed: Problem with the SSL CA cert (path? access rights?)
```
Make sure the path you configured for the property key `patch.net_profile.cert_dir_path` is pointing to an existing
directory containing the files `ca-bundle-crt.pem`, `client-crt.pem` and `client-key.pem` that you received from the
the network you are trying to connect to.
### Curl requests fail: SSL peer certificate or SSH remote key was not OK
When you get the following error message:
```text
Performing curl request failed: SSL peer certificate or SSH remote key was not OK
```
Make sure that you have the files `ca-bundle-crt.pem`, `client-crt.pem` and `client-key.pem` that you have received
from the network you are trying to connect to placed in a directory. The path to the **directory** needs to be set in
the hook configuration file by setting the key `patch.net_profile.cert_dir_path`, e.g.
`patch.net_profile.cert_dir_path=./cert` if the files are placed next to the `piu` exec in the folder `cert`.
doc/hook/nxahook.md
+55
View File
@@ -0,0 +1,55 @@
# nxahook: NXA
This readme covers any matters that are relevant for this hook, only. Anything that applies to **all** hooks is covered
in a [main hook readme file](../hook.md) including general data setup and a quick start guide.
## Additional notable features
* Removed USB flash drive vendor lock, i.e. use _ANY_ USB flash drive to store game profiles
* Auto generate new profiles if no profile is found on the connected USB flash drive
# Versions supported
All known versions supported.
## Dependencies
Make sure to read the different methods of dependency resolution available in the [main hook readme file](../hook.md),
first.
The following **direct** dependencies (cmd: `readelf -d piu`) are required:
* libfreetype.so.6
* librt.so.1
* libGL.so.1
* libGLU.so.1
* libusb-0.1.so.4
* libpthread.so.0
* libXxf86vm.so.1
* libpng12.so.0
* libasound.so.2
* libmad.so.0
* libboost_regex-mt.so.3
* libgcc_s.so.1
* libc.so.6
* libm.so.6
* libX11.so.6
* libdl.so.2
* libstdc++.so.6
* libz.so.1
As for method 1, when using Ubuntu, the dependencies can be found in the following packages:
* libc-bin (or gcc-multilib on a 64-bit platform)
* libx11-6
* zlib1g
* libusb-0.1-4
* libasound2
## Data setup
In additional to the [general information applying to **all** hooks](../hook.md#data-setup), this game requires all
files and folders from the original `game` folder to be in **UPPERCASE** on a case-sensitive file system. Further game
asset files and folders from cramfs need to be copied to the `game` directory. `nx.ttf`, `nxcn.ttf`, `nxpt.ttf`,
`nxtw.ttf`, `mission.txt` and `ufo.txt` must be **lowercase** but `SCRIPT` and its contents must be **UPPERCASE**.
The `config` (or `CONFIG`) folder and its contents must be available in **UPPER** _AND_ **lowercase**. The `BrainQuest`
folder name must be kept like this and its contents must be **lowercase**.
## Troubleshooting and FAQ
Make sure to also check the
[troubleshooting and FAQ section of the main hook readme](../hook.md#troubleshooting-and-faq). This covers various
things that apply to **all** hooks. The following sub-sections apply mainly to this hook.
doc/hook/nxhook.md
+52
View File
@@ -0,0 +1,52 @@
# nxhook: NX
This readme covers any matters that are relevant for this hook, only. Anything that applies to **all** hooks is covered
in a [main hook readme file](../hook.md) including general data setup and a quick start guide.
## Versions supported
All known versions supported.
## Dependencies
Make sure to read the different methods of dependency resolution available in the [main hook readme file](../hook.md),
first.
The following **direct** dependencies (cmd: `readelf -d piu`) are required:
* librt.so.1
* liblua50.so.5.0
* liblualib50.so.5.0
* libGL.so.1
* libGLU.so.1
* libusb-0.1.so.4
* libpthread.so.0
* libpng12.so.0
* libasound.so.2
* libgcc_s.so.1
* libc.so.6
* libm.so.6
* libXext.so.6
* libX11.so.6
* libstdc++.so.5
* libz.so.1
As for method 1, when using Ubuntu, the dependencies can be found in the following packages:
* libc-bin (or gcc-multilib on a 64-bit platform)
* libx11-6
* zlib1g
* libusb-0.1-4
* libasound2
## Data setup
In additional to the [general information applying to **all** hooks](../hook.md#data-setup), this game requires all
files and folders in the `game` folder to be in **UPPERCASE** on a case-sensitive file system.
## Troubleshooting and FAQ
Make sure to also check the
[troubleshooting and FAQ section of the main hook readme](../hook.md#troubleshooting-and-faq). This covers various
things that apply to **all** hooks. The following sub-sections apply mainly to this hook.
### Fully unlock the game
This hook has an option to fully unlock the game by setting the following property in the configuration file:
```text
game.force_unlock=1
```
This will unlock all missions in "World Tour" as well any locked songs in "Special Zone", and the song "FAEP 2-2".
doc/hook/os.md
+59
View File
@@ -0,0 +1,59 @@
# Hardware
Everything runs on original hardware MK6 and up. However, newer games might be slightly more demanding and will not
run smoothly on the old MK6 anymore.
As for custom hardware, everything that's at least of MK6 specs should do the job. GPU-wise you are not bound to nVidia
cards. Though, the card of your choice has to support at least the OpenGL 2.0 standard.
However, not that we have seen graphical glitches on AMD and Intel GPUs with NX2 which we haven't seen on older pump
versions. The game starts and runs but after some time you might encounter graphical glitches.
You can also run the games in a VM. Recommended settings: 2 vCPUs, 2 GB RAM, OpenGL 2.0 hardware acceleration enabled
(requires installing drivers/kernel modules on your guest).
# Operating system and environment setup
This document outlines common stuff that is required to run any of the games supported by pumptools. Make sure to follow
these properly and have your system prepared for the hooks before you continue with their dedicated readme files.
## Linux distributions supported
If you have the required knowledge, you should be able to get this to run on any distribution available. However, there
are a few things to consider:
* The game is a 32-bit binary, you need to be able to run 32-bit binaries
* Naturally, the game requires 32-bit versions of the libraries it depends on
* The game is built with glibc. You might have a hard time on distributions not shipping with them by default, e.g.
Alpine Linux
* Kernel-wise, the latest kernels and everything that's not pre 2.6 should work. Due to various hook sub-modules, many
quirks in different games have been fixed to run all games on the latest upstream kernel versions of Linux.
Recommendation: Use a 64-bit Linux distribution of your choice. You can also use a 32-bit distribution as this is the
arch these games were built for but it does not come with any benefits. Prepare yourself to upgrade to 64-bit once any
of the newer games (finally) moves to that target architecture.
## Dependencies
Each game and hook comes with a list of dependencies you might have to install. This depends on which type of dependency
resolution you pick.
When running this on a 64-bit Ubuntu, all packages must be installed as lib32 packages! When you are on Debian/Ubuntu
(based) distros and you are using apt, you have to enable multiarch support first:
```shell script
sudo dpkg --add-architecture i386
apt update
```
Then, install the 32-bit packages like this where `<pkgname>` must be replaced accordingly:
```shell script
apt install pkgname:i386
```
Note: The `:386` postfix does not apply to packages like `gccmultilib` as this already covers the i386 part.
## GPU drivers
For `libGL`, you need to install a GPU driver and have hardware acceleration enabled. The `libGL` library provided also
needs to be 32-bit compatible.
To check if everything's installed and HW acceleration is working, just run `glxgears`. If that doesn't error and you
see the rendered gears spinning, you should be fine.
## Sound drivers
Naturally, you also have to have sound stuff installed. Having alsa with its libraries available is sufficient. Pulse
and similar audio systems are not required, e.g. when running on a cabinet.
doc/hook/prihook.md
+108
View File
@@ -0,0 +1,108 @@
# Notable features
* Runs on recent kernel versions thanks to various fixes
* Runs on 32-bit and 64-bit distros (64-bit distros require additional 32-bit libs to be installed)
* Full dongle emulation
* Remove HDD checks to run this on "non legit" drives
* Full MK6IO emulation with API hook: Keyboard or your own custom IO
* Real IO passthrough (for MK6 usb io)
# Versions supported
All known versions supported.
# Data setup
You are expected to get a clean set of data from a prestine drive. Ensure that
the game version matches one of the supported versions listed.
You need two main folders:
* data
* settings
## Data folder
Contents of the folder:
* game: The binaries of the custom "AMFS". File names must be lower case.
* lib: Put any libraries (especially older versions of libraries that can't be
installed anymore using the package manager) the game uses and aren't installed
on your system in here.
* piu: The piu executable
## Settings folder
The contents of the folder are auto generated if the files don't exist.
Otherwise, this folder contains:
* PIUPRIME.INI
* RANK.DATA
## Executable dependencies
All dependencies must be compiled as 32-bit binaries. Here is a list of
dependencies (with versions) required to run the game:
* libGL.so.1
* libGLU.so.1
* libasound.so.2
* libcurl.so.4
* libsodium.so.13
* libusb-0.1.so.4
* libmad.so.0
* libmpeg2.so.0
* libmpeg2convert.so.0
* libftgl.so.2
* libstdc++.so.6
* libgcc_s.so.1
* libc.so.6
* libm.so.6
* libXext.so.6
* libX11.so.6
* libpthread.so.0
* libdl.so.2
* librt.so.1
* libnvidia-tls.so.340.96
* libnvidia-glcore.so.340.96
* libidn.so.11
* libssh2.so.1
* libssl.so.1.0.0
* libcrypto.so.1.0.0
* libgssapi_krb5.so.2
* libkrb5.so.3
* libk5crypto.so.3
* libcom_err.so.2
* libz.so.1
* libusb-1.0.so.0
* libfreetype.so.6
* libxcb.so.1
* libkrb5support.so.0
* libkeyutils.so.1
* libresolv.so.2
* libudev.so.1
* libbz2.so.1.0
* libpng16.so.16
* libharfbuzz.so.0
* libXau.so.6
* libXdmcp.so.6
* libcap.so.2
* libglib-2.0.so.0
* libgraphite2.so.3
* libpcre.so.1
# Hook module configuration file
Checkout the usage information of the hook and set the option values according
to your needs. Here is an example option configuration file:
```
log_file_path=/tmp/pumptools.log
log_level=3
enable_file_monitor=0
enable_io_monitor=0
piuio_emu_lib_path=/pumptools/lib/piuio-emu.so
piuio_exit_test_service=1
game_settings_path=/save/pri
sound_device=hw:0
keyboard_dev=/dev/input/by-id/usb-Logitech_USB_Receiver-if02-event-mouse
halt_on_segv=0
```
# Run the game
Ensure you are running an X screen. Otherwise, you have to start one along with the game. Various library/system-calls
require root privileges. Make sure to run the game as root or with sudo (otherwise you get various sorts of errors,
typically permission denied). Use the included *run.sh* file to start the game on a desktop environment.
# Further notes
## Vsync
The game is required to run with vsync on.
doc/hook/pro2hook.md
+91
View File
@@ -0,0 +1,91 @@
# Notable features
* Runs on recent kernel versions
* Runs on 32-bit and 64-bit distros (64-bit distros require additional 32-bit libs to be installed)
* Dongle stuff must be patched out
* You need decrypted data zips to run this
* Full MK6IO emulation with API hook: Keyboard or your own custom IO
* Full PIUBTN emulation with API hook: Keyboard or your own custom IO
* Real IO passthrough (for MK6 usb io and PIUBTN)
# Versions supported
Currently, only the latest revision is supported (I think that's R5?)
# Data setup
A clean set of data won't work here. Glenn protected the data with his own life
(pretty much) and made it as obnoxious as possible to unpack it. So good luck
getting the original data out of a drive image (if you didn't get it already
from somewhere).
All access to files and folders are detoured to two folders which makes setting
up everything easier.
You need one main folder:
* game/pro2 (contains all the game data, stepmania layout)
## Executable dependencies
All dependencies must be compiled as 32-bit binaries. Here is a list of
dependencies (with versions) required to run the game:
* libXtst.so.6
* libXrandr.so.2
* libGL.so.1
* libGLU.so.1
* libdl.so.2
* libavformat.so.51
* libavcodec.so.51
* libavutil.so.49
* libusb-0.1.so.4
* libpthread.so.0
* librt.so.1
* libstdc++.so.5
* libm.so.6
* libgcc_s.so.1
* libc.so.6
* libX11.so.6
* libXext.so.6
* libXi.so.6
* libXrender.so.1
* libnvidia-tls.so.340.106
* libnvidia-glcore.so.340.106
* libstdc++.so.6
* libxcb.so.1
* libXau.so.6
* libXdmcp.so.6
# Hook module configuration file
Checkout the usage information of the hook and set the option values according
to your needs. Here is an example option configuration file:
```
log_file_path=./pumptools.log
log_level=3
enable_file_monitor=0
enable_io_monitor=0
piubtn_emu_lib_path=
piubtn_real_passthrough=1
piuio_emu_lib_path=./piuio.so
piuio_real_passthrough=1
piuio_exit_test_service=1
game_data_path=./game
```
# Run the game
Ensure you are running an X screen. Run the game using
Ensure you are running an X screen. Otherwise, you have to start one along with the game. Various library/system-calls
require root privileges. Make sure to run the game as root or with sudo (otherwise you get various sorts of errors,
typically permission denied). Use the included *run.sh* file to start the game on a desktop environment.
# Further notes
## ITG2 PIUIO kernel module hack
If you don't have the original kernel module installed and you are running a
real PIUIO, you have to hook the *piuio.so* lib which implements the piuio api.
The "emulation" part which simply calls back to a real piuio driver takes
care of handling the kernel hack path then. If you run on a real IO without
hooking that module, you won't get an inputs or outputs.
## The game is crashing very early
This is probably due to not having the right IO hardware connected/emulated.
The game doesn't have any proper error handling if either the PIUIO or the
button IO is missing/not connected (or not emulated).
## Vsync
The game is required to run with vsync on.
doc/hook/prohook.md
+107
View File
@@ -0,0 +1,107 @@
# prohook: Pro (1)
This readme covers any matters that are relevant for this hook, only. Anything that applies to **all** hooks is covered
in a [main hook readme file](../hook.md) including general data setup and a quick start guide.
## Versions supported
All known versions supported if no-dongle patched at this time.
## Dependencies
Make sure to read the different methods of dependency resolution available in the [main hook readme file](../hook.md),
first.
The following **direct** dependencies (cmd: `readelf -d piu`) are required:
* libXtst.so.6
* libXrandr.so.2
* libGL.so.1
* libGLU.so.1
* libdl.so.2
* libavformat.so.51
* libavcodec.so.51
* libavutil.so.49
* libusb-0.1.so.4
* libpthread.so.0
* librt.so.1
* libstdc++.so.5
* libm.so.6
* libgcc_s.so.1
* libc.so.6
* libX11.so.6
As for method 1, when using Ubuntu, the dependencies can be found in the following packages:
* libc-bin (or gcc-multilib on a 64-bit platform)
* libx11-6
* libusb-0.1-4
* libasound2
## Data setup
A clean set of data won't work here. You need the decrypted data zip files and a patched executable that uses plain zip
files instead of encrypted ones.
All access to files and folders are detoured to two folders which makes setting up everything easier.
You need two main folders:
* `game` folder with the following contents
* All data zip files (e.g. `data0.zip`, `data1.zip`, ..., `encore.zip`)
* An empty file `FX` (if you run this on a FX or other cabinet with a widescreen monitor)
* `save ` folder. Contents are generated automatically if empty.
## USB thumb drive/profile support
Without any patches, the game's way of handling USB thumb drives is incompatible to the kernels of the last years.
This is fixed by prohook but requires some additional configuration effort.
1. Decide which physical USB ports of your machine you are going to use for the player 1 and player 2 sides.
1. Plug in *one* USB thumb drive into the player 1 port. Now you have to figure out two things:
1. The device node the drive got assigned to by the kernel, e.g. `sdb`. For example, use the command `fdisk` or
`lsblk` for this and take a note.
1. The USB bus and port number the thumb drive is plugged into. `ls -la /sys/block` shows you all currently
available block devices, including USB thumb drives. Find the thumb drive you plugged into the physical port and
check the path the symlink gets resolved to. For example:
`sdc -> ../devices/pci0000:00/0000:00:14.0/usb2/2-1/2-1:1.0/host7/target7:0:0/7:0:0:0/block/sdd`
You can identify the bus and port by taking a look at the part after the `usb2` directory here: `2-2`. The format
is `bus-port` which means that in this example the drive is plugged into port 1 of bus 2. Take a note of that.
1. Repeat the previous step for the physical port you consider using for player 2.
1. Create two folders that will serve as mount points for the two player sides in the `/mnt` directory, e.g.
`mkdir /mnt/0 && mkdir /mnt/1` (or re-using these folders if they already exist from other piu games).
1. Add the following entry to the `/etc/fstab` file on the machine you want to run the game on:
```text
/dev/sdb1 /mnt/0 auto noauto,owner 0 0
/dev/sdc1 /mnt/1 auto noauto,owner 0 0
```
Note: This does not create a fixed assignment of `/dev/sdb1` or `/dev/sdc1` to a specific physical USB port. It just
ensures that any block device that gets enumerated as `/dev/sdb` will get its first partition mounted to `/mnt/0`
(same concept applies to `/dev/sdc1/`).
1. Modify the `hook.conf` file used with `prohook.so` by inserting the device nodes and bus-port combinations into the
respective fields, for example:
```text
patch.usb_profile.p1.bus_port=2-1
patch.usb_profile.p2.bus_port=2-2
# Note: No partitions, e.g. sdb1, here
patch.usb_profile.dev_nodes=sdb,sdc
```
Once you plug-in a USB thumb drive to the configured ports, it should show up on the correct player side.
## Troubleshooting and FAQ
Make sure to also check the
[troubleshooting and FAQ section of the main hook readme](../hook.md#troubleshooting-and-faq). This covers various
things that apply to **all** hooks. The following sub-sections apply mainly to this hook.
## Enable log output from the game
If you run into any issues, consider enabling the game's log output to console which might help you figuring out
what's going on. This can be done by editing the `data.Static.ini` file in the `data0.zip` file. Go to the section
`[Options-arcade]` and change the property `ShowLogOutput=0` to `ShowLogOutput=1`.
## Switch screen aspect ratio: 4:3 and 16:9
The game supports 4:3 and 16:9 aspect ratios. To enable 16:9 mode, ensure that an empty file called `FX` is placed
next to the data zip files inside the `game` directory. For 4:3 mode, simply delete the `FX` file if it exists.
## ITG2 PIUIO kernel module hack
If you don't have the original kernel module installed and you are running a real PIUIO, you have to hook the
`ptapi-io-piuio-real.so` lib which implements the piuio api. The "emulation" part which simply calls back to a real
piuio driver takes care of handling the kernel hack path then. If you run on a real IO without hooking that module,
you won't get any inputs or outputs.
## The game is crashing very early
The log might show something about "ptrace failing" and not being able to "load libformat". However, the actual problem
is probably not having all the necessary IO hardware connected (or emulation enabled). The game doesn't have any proper
error handling if either the PIUIO or the button IO is missing/not connected (or not emulated).
doc/hook/x2hook.md
+60
View File
@@ -0,0 +1,60 @@
# x2hook: Exceed 2
This readme covers any matters that are relevant for this hook, only. Anything that applies to **all** hooks is covered
in a [main hook readme file](../hook.md) including general data setup and a quick start guide.
## Versions supported
* 102
Any other version won't work, period. The hook has to memory patch a weird bug causing the sound thread to crash.
## Dependencies
Make sure to read the different methods of dependency resolution available in the [main hook readme file](../hook.md),
first.
The following **direct** dependencies (cmd: `readelf -d piu`) are required:
* libGL.so.1
* libGLU.so.1
* libpthread.so.0
* libmad.so.0
* libasound.so.2
* libz.so.1
* libpng12.so.0
* libmpeg2.so.0
* libmpeg2convert.so.0
* libusb-0.1.so.4
* liblua50.so.5.0
* liblualib50.so.5.0
* libgcc_s.so.1
* libc.so.6
* libm.so.6
* libX11.so.6
* libstdc++.so.5
As for method 1, when using Ubuntu, the dependencies can be found in the following packages:
* libc-bin (or gcc-multilib on a 64-bit platform)
* libx11-6
* zlib1g
* libusb-0.1-4
* libasound2
## Data setup
In additional to the [general information applying to **all** hooks](../hook.md#data-setup), this game requires all
files and folders in the `game` folder to be in **UPPERCASE** on a case-sensitive file system.
## Troubleshooting and FAQ
Make sure to also check the
[troubleshooting and FAQ section of the main hook readme](../hook.md#troubleshooting-and-faq). This covers various
things that apply to **all** hooks. The following sub-sections apply mainly to this hook.
### Fully unlock the game
This hook has an option to fully unlock the game (well, unlock Canon-D Full Mix without entering the code because that's
the only permanent unlock) by setting the following property in the configuration file:
```text
game.force_unlock=1
```
### Using the unlock option to unlock Canon-D full remix does not work when enabled
When the game cannot read from an existing `PIUEXCEED.INI` file, the settings are created in-memory and written to disk.
Therefore, the unlock mechanism of the hook cannot apply this to the contents in-memory but only when the
`PIUEXCEED.INI` file is re-loaded. To achieve this, once you started the game to create a new `PIUEXCEED.INI` with
default values, simply quit the game and restart.
doc/hook/zerohook.md
+50
View File
@@ -0,0 +1,50 @@
# zerohook: Zero
This readme covers any matters that are relevant for this hook, only. Anything that applies to **all** hooks is covered
in a [main hook readme file](../hook.md) including general data setup and a quick start guide.
## Versions supported
All known versions supported.
## Dependencies
Make sure to read the different methods of dependency resolution available in the [main hook readme file](../hook.md),
first.
The following **direct** dependencies (cmd: `readelf -d piu`) are required:
* libGL.so.1
* libGLU.so.1
* libpthread.so.0
* libasound.so.2
* libz.so.1
* libpng12.so.0
* libusb-0.1.so.4
* liblua50.so.5.0
* liblualib50.so.5.0
* libgcc_s.so.1
* libc.so.6
* libm.so.6
* libX11.so.6
* libstdc++.so.5
As for method 1, when using Ubuntu, the dependencies can be found in the following packages:
* libc-bin (or gcc-multilib on a 64-bit platform)
* libx11-6
* zlib1g
* libusb-0.1-4
* libasound2
## Data setup
In additional to the [general information applying to **all** hooks](../hook.md#data-setup), this game requires all
files and folders in the `game` folder to be in **UPPERCASE** on a case-sensitive file system.
## Troubleshooting and FAQ
Make sure to also check the
[troubleshooting and FAQ section of the main hook readme](../hook.md#troubleshooting-and-faq). This covers various
things that apply to **all** hooks. The following sub-sections apply mainly to this hook.
### Fully unlock the game
This hook has an option to fully unlock the game by setting the following property in the configuration file:
```text
game.force_unlock=1
```
This will unlock all missions on mission station as well as any locked songs and stepcharts.