pumptools/doc/hook/hook.md

# 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.

## Dependencies of hook libraries
Pumptool's hook libraries aim for having no dependencies other than what is already required by the
different games to run.

Since all games available so far are compiled as 32-bit binaries, naturally, it requires you to install
the 32-bit versions of the dependencies (if you are not running a 32-bit distributed).
Note the `:i386` postfix for packages in the command further below. This is required if you are on a 64-bit
distribution.

However, there are some exceptions that require additional libraries in order to allow the following
features to work correctly:
* Hook libraries, e.g. `nx2hook` that support network features, e.g. usb profiles with pumpnet
* IO API implementations that support real devices, e.g. real PIUIO, which use libusb-1.0

Taken from [the Dockerfile for building pumptools](../../Dockerfile), the following commands install
the dependencies that you need on an Ubuntu-based system:

```bash
dpkg --add-architecture i386
apt-get update && apt-get install -y \
    g++-multilib \
    gcc-multilib \
    libc6-dev-i386 \
    libusb-1.0-0:i386 \
    libusb:i386 \
    libasound2:i386 \
    libconfig++:i386 \
    libx11:i386 \
    libcurl4-gnutls:i386
```

Further game version specific dependencies and how to set these up is outlined in
[its own section](#dependencies-of-games).

## 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.

!!!
AVOID USING `lib-ld.zip` PERIOD. THIS IS A FALLBACK OPTION IF `lib-local.zip` DOES NOT WORK!!!
!!!

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 of games
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
```

Alternative:
```shell script
aplay -l
```

Example output:

```text
**** List of PLAYBACK Hardware Devices ****
card 0: Generic [HD-Audio Generic], device 3: HDMI 0 [HDMI 0]
  Subdevices: 1/1
  Subdevice #0: subdevice #0
card 0: Generic [HD-Audio Generic], device 7: HDMI 1 [HDMI 1]
  Subdevices: 1/1
  Subdevice #0: subdevice #0
card 0: Generic [HD-Audio Generic], device 8: HDMI 2 [HDMI 2]
  Subdevices: 1/1
  Subdevice #0: subdevice #0
card 0: Generic [HD-Audio Generic], device 9: HDMI 3 [HDMI 3]
  Subdevices: 1/1
  Subdevice #0: subdevice #0
card 2: Generic_1 [HD-Audio Generic], device 0: ALC887-VD Analog [ALC887-VD Analog]
  Subdevices: 0/1
  Subdevice #0: subdevice #0
card 2: Generic_1 [HD-Audio Generic], device 1: ALC887-VD Digital [ALC887-VD Digital]
  Subdevices: 1/1
  Subdevice #0: subdevice #0
```

If you want to route the audio output to `card 0: Generic [HD-Audio Generic], device 3: HDMI`, set the following in
the `hook.conf` file:

```text
patch.sound.device=hw:CARD=Generic,DEV=3
```


### 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.

### How do I enable fullscreen/window mode?
It depends on the game. All MK3 linux ports have a window/fullscreen option that actually works. For games of the PRO
series, you have to [tweak game specific configuration files](prohook.md#windowfullscreen-mode). All other classic PIU
games depend on how you have your current Linux environment/X-server set, up. On a desktop environment, these games will
always start in window mode.

In general, there is no actual full-screen option on Linux like you have on Windows with DirectX. Fullscreen on Linux
means that you switch resolution of whatever X session you have currently running and fill the screen with the view
of your application.

The best you can do to go fullscreen on desktop is exactly the above. This can be achieved like follows:

```shell script
sudo xrandr --output HDMI-0 --mode 640x480
sudo ./piueb run
# Or whatever is your default resolution on your monitor
sudo xrandr --output HDMI-0 --mode 1024x768
```

Otherwise, it is recommended to setup a dedicated x-session using `startx`, e.g. `startx ./piueb run` and just have
only the game run in that session. A good reference for this might be the various scripts included in
[pumpos](https://dev.s-ul.net/hackitup/pumpos/-/tree/master/dist/piu/base/pumpos/data/00_bootstrap).

If you have a multi-monitor setup, things are getting quite complicated. Therefore, we are not covering this in here.

Also note that if you want the game to render at a higher resolution than its defined one, e.g. 640x480, this is not
possible right now. The output you get from the frame buffer will always be its native resolution.

### The game window is small and the 4:3 games are stretched when full screen on modern widescreen displays
On supported games, you can change the option `gfx.scaling_mode` in the `hook.conf` file to enable different pre-defined
scaling modes. Especially for the SD 640x480 4:3 games, this allows you to upscale the rendered output to a widescreen
display resolution while keeping the aspect ratio (pillarbox).

Note: This does not change the enhance the image quality. It just uses the GPU to interpolate the lower resolution
output and stretches it to the target surface area.

### The game crashes with a snd_pcm_open error
If the game crashes with the following error:

```text
[E][2021/3/28-19:38:49:778][patch-sound][sound.c:55] snd_pcm_open failed: No such file or directory
piu: pcm_params.c:2354: snd_pcm_hw_refine: Assertion `pcm && params' failed.
Aborted (core dumped)
```

Verify that you have set the `patch.sound.device=` property in the `hook.conf`. Also refer to
[this section](#how-do-i-figure-out-which-sound-device-to-select) how to configure your audio device.