pumptools/README.md

# Pumptools: The ultimate toolset to run all Linux based PIU games on any* kernel and distribution

Version: 1.12

[Release history](CHANGELOG.md)

This tool-set provides hook libraries that can be pre-loaded to run vanilla dumps of all Pump It Up games running on
Linux. This also includes the only exclusive MK5 hardware based game Exceed and the MK3 Linux ports.

## Public release note

Currently, the public release contains all source code required to run all games listed
[here](#games-and-latest-versions-supported). The following games however are currently not working due to missing
dongle key tables and raw hdd areas (dummy files exist to allow full compilation of the project):

* Fiesta
* FiestaEX
* Fiesta 2
* Prime

The required assets to run these games will follow with future releases.

## Documentation

Additional documentation on different topics related to pumptools are located in the `doc` subfolder
[here](doc/README.md).

For release distribution packages, you can find a `doc.zip` file inside the `pumptools.zip` package that contains all
documentation also referenced from here:

### Developers

* [API](doc/api/api.md): Pumptools public API documentation to write your own integrations with
  pumptools, e.g. IO
* [Development](doc/development/development.md): How to develop for and with pumptools, e.g.
  development environment setup, building
* [Architecture](doc/development/architecture.md): Describes the architecture of pumptools outlining the most important
  high level aspects

### Users

* [Hook library documentation](doc/hook/hook.md): User documentation how to setup and use the hook libraries
* [Hardware docs](https://github.com/Shizmob/arcade-docs): Boards, cabinets, IOs etc.
* [Game documentation](https://github.com/pumpitupdev/piu-game-docs): General game related stuff like pad codes, unlocks
  etc

## Hook libraries

### Features

* Run all supported games on recent hardware, Linux distributions and kernel versions
* Environment sandboxing to increase compatibility and portability
* API for hardware abstraction: Write your own drivers for IO devices
* Full dongle emulation in software
* Works with **vanilla** data, no hex edits
* Various (bug)fixes and quality of live improvements for many games

### Games and latest versions supported

All hooks share a major set of features provided by pumptools. Therefore, common topics are covered in the
[main hook readme](doc/hook/hook.md). Start there when you are setting up a game with pumptools. Additionally, refer to
each dedicated hook readme for further important and required information to successfully setup and run the games.

The following games are supported and tested with the latest versions available. Earlier version might also be support
and work because of the nature the hooks are implemented.

* [MK3 Linux Ports: 1st to Prem 3/Prex 3](doc/hook/mk3hook.md): MK3 Linux ports (there is only one version officially
available per game version)
* [Exceed](doc/hook/exchook.md): 20040408
* [Exceed 2](doc/hook/x2hook.md): 102
* [Zero](doc/hook/zerohook.md): 103
* [NX](doc/hook/nxhook.md): 108
* [Pro](doc/hook/prohook.md): R5 nodongle
* [NX2](doc/hook/nx2hook.md): 154
* [Pro2](doc/hook/pro2hook.md): R5 nodongle
* [NXA](doc/hook/nxahook.md): 110

Not available, yet:

* [Fiesta](doc/hook/fsthook.md): 120
* [FiestaEX](doc/hook/fexhook.md): 151
* [Fiesta 2](doc/hook/f2hook.md): 161
* [Prime](doc/hook/prihook.md): 122

### Prepare your operating system

Before you start installing and configuring anything of pumptools, read [this readme](doc/hook/os.md) on how to prepare
your operating system and environment. Please also note that not every Linux distribution and different versions were
tested and verified working.

### Get and prepare game data

You need **vanilla**, i.e. non-tempered and non-decrypted, game assets as well as non-tempered executable binaries
which can be pulled from legit and clean physical disks or images of them.

For setting up the games, have a look at the dedicated readme files for
[each hook and game](#games-and-latest-versions-supported).

### Setup hook libraries

**READ THE WHOLE README OF THE HOOK BUILD YOU WANT TO USE FIRST BEFORE DOING ANYTHING!!!**

The readme files go into great detail how to setup things with various potential relevant aspects spread across the
document. Being aware of them will save you a lot of puzzling and time. Furthermore, read the FAQ/troubleshooting
section before as well to be aware of any known issues when you encounter them.

## Building

Make sure you have the [required tools](doc/development/development.md) installed. Once that's done, simply run

```shell script
make build
```

to build it on your current host from the root directory of this project.

The build output is located in the `build` subdirectory. The built binaries can be found in `build/bin` and a
distribution package called `pumptools.zip` can be found in the `build` subfolder.

You can also build in a docker container. The container provides the necessary build environment and also ensures 
[compatibility regarding glibc versions](doc/development/development.md#compatibility-issues-with-newer-glibc-versions).

```shell script
make build-docker
```

The build output from the docker image is located in `build/docker`.

## License

Source code license is the Unlicense; you are permitted to do with this as thou wilt. For details, please refer to the
[LICENSE file](LICENSE) included with the source code.