mirror of
https://github.com/pumpitupdev/pumptools.git
synced 2026-10-06 21:57:56 +03:00
voidderef-agent
7a72487742
The configured PIUIO or PIUBTN library path and the mapping-file lookup are separate behaviors. This distinction was unclear, making it difficult to understand what shared installations already supported and what the lookup added by PR #86 changed. Document the per-game and shared-folder layouts, the keyboard X11 input-handler requirement, and the current search order: load the mapping beside the selected library first, then fall back to the folder containing the game's piu executable.
73 lines
4.0 KiB
Markdown
73 lines
4.0 KiB
Markdown
# PIUBTN API
|
|
This contains various PIUBTN related tools and libraries. PIUBTN is the button board that was first introduced with
|
|
Pump PRO and officially works as an optional peripheral on all classic pump games starting Fiesta.
|
|
|
|
## Pumptools PIUBTN API implementations
|
|
The following libraries implement pumptool's PIUBTN API interface. Set the configuration value `patch.piubtn.emu_lib`
|
|
in your hook configuration to point to the library you want to use, e.g.
|
|
`patch.piubtn.emu_lib=./ptapi-io-piubtn-null.so`.
|
|
|
|
The path can select a library installed beside one game or a library in a shared folder used by multiple games. For
|
|
keyboard input, the applicable X11 input-handler option must point to the same library.
|
|
|
|
The keyboard and joystick implementations first load their mapping file from the folder containing the selected
|
|
library. If that fails, they fall back to the folder containing the game's `piu` executable. This supports both of the
|
|
following layouts:
|
|
|
|
* Per-game: place the library and mapping file beside `piu` and use a relative path such as
|
|
`patch.piubtn.emu_lib=./ptapi-io-piubtn-keyboard.so`.
|
|
* Shared: place the library and mapping file in one common folder and configure every game with the same absolute path,
|
|
such as `patch.piubtn.emu_lib=/opt/pumptools/io/ptapi-io-piubtn-keyboard.so`.
|
|
|
|
When mapping files exist in both locations, the file beside the selected library takes precedence.
|
|
|
|
### Null: ptapi-io-piubtn-null.so
|
|
A null implementation for API dummy testing against libraries/applications calling API implementations.
|
|
|
|
### Real PIUIO: ptapi-io-piubtn-real.so
|
|
Support for a real USB PIUBTN. This library is not useful for games that already support the hardware natively.
|
|
However, games that require an emulation layer need this.
|
|
|
|
### Joystick/Gamepad: ptapi-io-piubtn-joystick.so
|
|
Support all (USB) Joysticks and Gamepads that are detected by the Linux kernel. This uses the Kernel's joystick API.
|
|
|
|
Button mappings are configured by using the `ptapi-io-piubtn-joystick-conf` (this is an executable!) tool. You might
|
|
have to `chmod +x ptapi-io-piubtn-joystick-conf` it prior being able to run it: `./ptapi-io-piubtn-joystick-conf`. Run
|
|
the tool and follow the instructions. Once successfully completed, a `piubtn-joystick-conf.bin` configuration file is
|
|
located in the same folder. Keep it beside `ptapi-io-piubtn-joystick.so`, either in the game's folder or in a shared
|
|
folder.
|
|
|
|
Configure your `hook.conf` file accordingly:
|
|
```
|
|
patch.piubtn.emu_lib=./ptapi-io-piubtn-joystick.so
|
|
```
|
|
|
|
### Keyboard: ptapi-io-piubtn-keyboard.so
|
|
Support for inputs via your standard keyboard using the X11 API.
|
|
|
|
Button mappings are configured by using the `ptapi-io-piubtn-keyboard-conf` (this is an executable!) tool. You might
|
|
have to `chmod +x ptapi-io-piubtn-keyboard-conf` it prior being able to run it: `./ptapi-io-piubtn-keyboard-conf`. Run
|
|
the tool and follow the instructions. Once successfully completed, a `piubtn-keyboard-conf.bin` configuration file is
|
|
located in the same folder. Keep it beside `ptapi-io-piubtn-keyboard.so`, either in the game's folder or in a shared
|
|
folder.
|
|
|
|
Configure your `hook.conf` file accordingly:
|
|
```
|
|
patch.piubtn.emu_lib=./ptapi-io-piubtn-keyboard.so
|
|
patch_hook_main_loop.x11_input_handler=./ptapi-io-piubtn-keyboard.so
|
|
```
|
|
|
|
Setting the key `patch_hook_main_loop.x11_input_handler` is important. Otherwise, the library does not receive any
|
|
input events from X11 and your configured keyboard input does not work in the game.
|
|
|
|
## Pumptools PIUBTN API tester: ptapi-io-piubtn-test
|
|
The tool *ptapi-io-piubtn-test* lets you easily test and debug your library implementing pumptool's piubtn API without
|
|
having to setup and/or run any games.
|
|
|
|
## Development
|
|
The [piubtn header](../../src/api/ptapi/io/piubtn.h) contains all the prototypes to be implemented by your library to
|
|
provide your own implementation for a PIUBTN. Checkout the header file for documentation.
|
|
|
|
Checkout the [stub implementation](../../dist/api/ptapi-io-piubtn-stub.c) to get started with a simple example.
|
|
Instructions are located in the header comment of the file.
|