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