You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
71 lines
2.8 KiB
Markdown
71 lines
2.8 KiB
Markdown
# prongs
|
|
|
|
Input handling schema written in rust. Backend agnostic, provides serializability, assignment and unified interface for working with inputs. Keyboard, mouse and controllers supported.
|
|
|
|
Current backends include Piston and Gilrs with more on the way.
|
|
|
|
## Using prongs library
|
|
|
|
To use the prongs library include it in your `Cargo.toml` file. You *MUST* specify a backend via features e.g.
|
|
```
|
|
[dependencies]
|
|
prongs = { version = "1.0.0", features = ["backend_piston"] }
|
|
```
|
|
|
|
### Documentation
|
|
|
|
[Documentation link](https://doc.bitsmart.ltd/prongs/index.html)
|
|
|
|
### Examples
|
|
|
|
See [examples repo](https://gitlab.bitsmart.ltd/open/prongs-examples)
|
|
|
|
### Design
|
|
|
|
Prongs provides a specific backend Schema struct that unifies and simplifies working with input events.
|
|
The goal is to provide serializability, input assigning and unify the interface for working with inputs.
|
|
Main target audience are game developer and engine developers.
|
|
|
|
The main workhorse of the prongs is the Schema. It is a combination of:
|
|
1. A keymap (input -> user action mapping)
|
|
2. Assigning functionality (create mapping by actuating controls)
|
|
3. Processing functionality (apply mapping in main loop)
|
|
4. Unified interface and simplification
|
|
|
|
Prongs abstracts input events into a three layered structure. The layers are:
|
|
|
|
1. Class of input, e.g. mouse or keyboard or controller
|
|
2. Instance of input, e.g. key "k", mouse button #2 or axis #2
|
|
3. State of input, e.g. button pressed/released or value of axis
|
|
|
|
This is expressed best in the [InputCause](https://doc.bitsmart.ltd/prongs/types/enum.InputCause.html) enum.
|
|
|
|
The library does not run any event loop due to various differences between how backends handle the event loop.
|
|
To use prongs you need to define an actions type that will identify the mappings on input events.
|
|
For example:
|
|
```
|
|
enum Actions
|
|
{
|
|
Up,
|
|
Down,
|
|
Left,
|
|
Right,
|
|
}
|
|
```
|
|
|
|
You then need to "hook" the `process_event` function into your main event loop for processing. This will
|
|
map the input event into the action you specified when you assigned or loaded the Schema configuration.
|
|
|
|
Assigning the mapping from input events to user actions is done by using the `assign_input` function. This
|
|
can be used to assign actions to input events individually as required (e.g. in a menu when something gets clicked).
|
|
Note that `assign_input` handles required de-duplication (e.g. it won't consider a button release as a separate mapping to a button press).
|
|
Because the Schema object is fully serializable you can also load existing setup from any previously stored one.
|
|
|
|
## Development
|
|
|
|
To build you need to specify the required backends e.g. `cargo build --features backend_piston,backend_gilrs`
|
|
|
|
Same goes for testing `cargo test --features backend_piston,backend_gilrs`
|
|
If you don't specify a backend the tests for it will not be compiled and won't run.
|
|
|