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