prongs/README.md

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.

WARNING prongs is alpha level at this point. APIs will most probably change.

NOTE prongs requires rust 1.32 or later.

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 = "0.0.3", features = ["backend_piston"] }

Documentation

Documentation link

Examples

See examples repo

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 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.

Adding a new backend

To add a new backend one must implement the ToEventType trait on the backend's event. Additionally a specialized SchemaBackendName newtype has to be created that will hold the actual Schema object specialized to backend's types for TEventType and TControllerID. Lastly the new schema has to be made visible in the main module under a configuration with the backend feature. Cargo.toml has to be expanded with the backend's dependencies marked optional and the new feature named.