Crate bevy_ineffable

Expand description

§Bevy Ineffable

A simple-to-use input manager for the Bevy game engine that empowers players and makes accessibility easy.

§Core tenets

Make accessibility easy.
- Players can create and share custom input configs. Configs can be merged at runtime.
- Post acceptance delay helps players with conditions like Parkinson’s avoid unintended key presses.
- Toggling continuous input helps players who physically cannot hold down a button for long periods of time.
- Macro support coming soon.
Offer a unified, abstracted view of input.
- Games should be agnostic of specific input devices.
- No more manually gathering keyboard, mouse and gamepad input from multiple sources.
Never allow the game to crash, but provide clear and direct feedback when something goes wrong.
- Scans player-made keybinding configurations and composes a report containing detailed feedback.
Recognise the existence of different kinds of input (axis, dual-axis, continuous and pulse), and leverage the type system to differentiate between them at compile time.
- DualAxis: Inputs a direction along two axes. E.g. an analog stick.
- SingleAxis: Inputs a direction along one axis. E.g. the mouse wheel.
- Continuous: Is active continuously. E.g. while a button is held down.
- Pulse: Pulses occasionally. E.g. clicking left mouse button.

§Quickstart

[dependencies]
# Add bevy_ineffable as a dependency to your `Cargo.toml`
bevy_ineffable = "0.5.0"

use bevy::prelude::*;
use bevy_ineffable::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        // Always add the IneffablePlugin:
        .add_plugins(IneffablePlugin)
        // Also register GooseInput as an InputAction:
        .register_input_action::<GooseInput>()
        .add_systems(Startup, init)
        .add_systems(Update, update)
        .run();
}

/// Define an enum and derive `InputAction`.
/// These are the abstract actions that keys can be bound to.
#[derive(InputAction)]
pub enum GooseInput {
    /// In this example, the only thing the player can do is honk.
    /// We must define what kind of input Honk is. Honking is 
    /// enacted instantaneously, so we'll define it as a pulse.
    #[ineffable(pulse)]
    Honk,

    // You can add more actions here...

}

/// Create a config that binds the space bar to the `Honk` action.
fn init(mut ineffable: IneffableCommands) {
    // The builder pattern is used here, but configs can also 
    // be loaded as an asset.
    let config = InputConfig::builder()
        .bind(
            ineff!(GooseInput::Honk),
            PulseBinding::just_pressed(KeyCode::Space),
        )
        .build();
    ineffable.set_config(&config);
}

/// Whenever the Honk action pulses, write to the console.
fn update(ineffable: Res<Ineffable>) {
    if ineffable.just_pulsed(ineff!(GooseInput::Honk)) {
        println!("Honk!");
    }
}

§More examples

Mor examples can be found in the examples/ directory. Each example is in its own file. Try out the first one by running:

cargo run --example basics

§Compatible Bevy versions

bevy	bevy_ineffable
0.12	0.1.0 - 0.3.0
0.13	0.4.0 - 0.5.0

§Roadmap

Macro support
Recording and playing back input sequences
Helper functions for implementing a key re-mapping settings screen in-game.
Full local multiplayer support
Support for on-screen button prompts
Different input contexts
Maybe a tie-in to GUI?

§License

Ineffable is dual-licensed under either:

at your option. This means that when using this crate in your game, you may choose which license to use.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Modules§

bindings
commands
Contains the SystemParam that systems can use to set InputConfigs.
config
input_action
Holds the InputAction trait. Game devs don’t really need this, the trait should always be derived.
phantom
Types in this module are used to enforce compile time guarantees when interacting with different InputKinds.
plugin
Contains a bevy plugin to help set up all the resources etc. needed by Ineffable.
prelude
The prelude should be all you need to use this crate! Of course, if you want, you can also selectively use only the parts you need.
processed
register
Handles registering InputActions. This should be done once per InputAction enum at the start of the game.
reporting
Handles reports containing lint warnings about InputConfigs. Aims to provide detailed, helpful error messages about misconfigured keybinding profiles, and offer concrete suggestions on how to fix the problems.
resources