Add some documentation.
This commit is contained in:
parent
f5283f33ca
commit
5a2e9f354b
2 changed files with 129 additions and 0 deletions
45
examples/ruletypes.yml
Normal file
45
examples/ruletypes.yml
Normal file
|
@ -0,0 +1,45 @@
|
||||||
|
#
|
||||||
|
devices:
|
||||||
|
- name: flightstick
|
||||||
|
type: physical
|
||||||
|
device_name: Flightstick Name From evlist
|
||||||
|
- name: main
|
||||||
|
type: virtual
|
||||||
|
axes: 8
|
||||||
|
buttons: 80
|
||||||
|
rules:
|
||||||
|
# Currently axes can only be simple mappings
|
||||||
|
- type: simple
|
||||||
|
input:
|
||||||
|
device: flightstick
|
||||||
|
axis: ABS_X
|
||||||
|
output:
|
||||||
|
device: main
|
||||||
|
axis: ABS_X
|
||||||
|
# Simple mappings also work for buttons
|
||||||
|
- type: simple
|
||||||
|
input:
|
||||||
|
device: flightstick
|
||||||
|
button: BTN_BASE2
|
||||||
|
inverted: false
|
||||||
|
output:
|
||||||
|
device: main
|
||||||
|
button: BTN_BASE2
|
||||||
|
# A combo rule - BTN_TRIGGER will be active while BTN_THUMB and BTN_THUMB2 are pressed.
|
||||||
|
- type: combo
|
||||||
|
inputs:
|
||||||
|
- device: flightstick
|
||||||
|
button: BTN_THUMB
|
||||||
|
- device: flightstick
|
||||||
|
button: BTN_THUMB2
|
||||||
|
output:
|
||||||
|
device: main
|
||||||
|
button: BTN_TRIGGER
|
||||||
|
# A latched rule - the virtual BTN_BASE3 will toggle each time the physical BTN_BASE3 is pressed.
|
||||||
|
- type: latched
|
||||||
|
input:
|
||||||
|
device: flightstick
|
||||||
|
button: BTN_BASE3
|
||||||
|
output:
|
||||||
|
device: main
|
||||||
|
button: BTN_BASE3
|
84
readme.md
Normal file
84
readme.md
Normal file
|
@ -0,0 +1,84 @@
|
||||||
|
# Joyful - virtual joystick remapper for Linux
|
||||||
|
|
||||||
|
Joyful is a Linux tool for creating virtual joysticks and mapping inputs from various
|
||||||
|
real devices to them. This is useful when playing games that don't support multiple joysticks,
|
||||||
|
or for games that don't handle devices changing order (like Star Citizen).
|
||||||
|
|
||||||
|
Perhaps more significantly, Joyful allows you to map combinations of physical inputs to a single output,
|
||||||
|
as well as creating other complex scenarios. Want a single button press to simultaneously produce multiple outputs?
|
||||||
|
Joyful can do that!
|
||||||
|
|
||||||
|
Are you a Linux gamer who misses the features of Joystick Gremlin? Wish you could map combo inputs,
|
||||||
|
or combine your input devices into one virtual device? Are you ok with writing a bunch of YAML?
|
||||||
|
|
||||||
|
Joyful might be the tool for you.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
### Current Features - try them today!
|
||||||
|
|
||||||
|
* Create virtual devices with up to 8 axes and 80 buttons.
|
||||||
|
* Make simple 1:1 mappings of buttons and axes: Button1 -> VirtualButtonA
|
||||||
|
* Make combination mappings: Button1 + Button2 -> VirtualButtonA
|
||||||
|
|
||||||
|
### Future Features - try them at an unspecified point in the future!
|
||||||
|
|
||||||
|
* Multiple modes with per-mode behavior.
|
||||||
|
* Partial axis mapping: map sections of an axis to different outputs.
|
||||||
|
* Macros - have a single input produce a sequence of button presses with configurable pauses.
|
||||||
|
* Sequence combos - Button1, Button2, Button3 -> VirtualButtonA
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
Configuration is currently done via hand-written YAML files in `~/.config/joyful/`. Joyful will read every
|
||||||
|
yaml file in this directory and combine them, so you can split your configuration up however you like.
|
||||||
|
|
||||||
|
Configuration is divided into two sections: `devices` and `rules`. Each of these is a YAML list.
|
||||||
|
The options for each are described in some detail below. See the `examples/` directory for concrete examples.
|
||||||
|
|
||||||
|
### Device configuration
|
||||||
|
|
||||||
|
Each entry in `devices` must have a couple of fields:
|
||||||
|
|
||||||
|
* `name` - This is an identifier that your rules will use to refer to the device. It is recommended to avoid spaces or special characters.
|
||||||
|
* `type` - Should be `physical` for an input device, and `virtual` for an output device.
|
||||||
|
|
||||||
|
`physical` devices must additionally define these fields:
|
||||||
|
|
||||||
|
* `device_name` - The name of the device as reported by the included `evlist` command. If your device name ends with a space, use quotation marks (`""`) around the name.
|
||||||
|
|
||||||
|
`virtual` devices must additionally define these fields:
|
||||||
|
|
||||||
|
* `buttons` - a number between 0 and 80. Linux may not recognize buttons greater than 56.
|
||||||
|
* `axes` - a number between 0 and 8.
|
||||||
|
|
||||||
|
### Rules configuration
|
||||||
|
|
||||||
|
All `rules` must have a `type` field. Valid values for this field are:
|
||||||
|
|
||||||
|
* `simple` - a single input mapped to a single output
|
||||||
|
* `combo` - multiple inputs mapped to a single output. The output event will trigger when all the input conditions are met.
|
||||||
|
* `latched` - a single input mapped to a single output, but each time the input is pressed, the output will toggle.
|
||||||
|
|
||||||
|
Configuration options for each type vary. See <examples/ruletypes.yml> for an example of each type with all options specified.
|
||||||
|
|
||||||
|
|
||||||
|
## Technical details
|
||||||
|
|
||||||
|
Joyful is written in golang, and uses evdev/uinput to manage devices.
|
||||||
|
|
||||||
|
### Building
|
||||||
|
|
||||||
|
To build joyful, install `go` via your package manager, then run:
|
||||||
|
|
||||||
|
```
|
||||||
|
go build -o build/ ./...
|
||||||
|
```
|
||||||
|
|
||||||
|
Look for binaries in the `build/` directory.
|
||||||
|
|
||||||
|
### Contributing
|
||||||
|
|
||||||
|
Send patches and questions to [annabunches@gmail.com](mailto:annabunches@gmail.com). Make sure the subject of your email starts with `[Joyful]`.
|
||||||
|
|
||||||
|
If enough people show an interest in contributing, I'll consider mirroring the repository on Github.
|
Loading…
Add table
Add a link
Reference in a new issue