An easy to use tool for key-binding in Unity.
Supports input filtering (You can choose which keys are valid for binding).
The tool has detaild documentation, and simple examples of usage.
The main class of the KeyBinder tool, used for detecting when a user/player presses a key.
All these members are static, so you don't need to create an instance of a KeyDetector.
-
Properties
-
InputCheckIsActive
Set to false by default
Determines if the KeyDetector is currently checking for input
To activate see methods: InputCheckOnce and InputCheckSetActive bellow -
InputFilter
The input filter of the detector
Filtering is disabled by default
To activate read about Input Filtering
To disable filtering call - DisableInputFilter() -
LatestKey
Returns the latest valid key the KeyDetector received
-
-
Events
-
KeyReceived (KeyCode)
Raised when a valid key has been received by the key detector -
InvalidKeyReceived (KeyCode)
Raised when an invalid key has been detected
Will be raised only if there is an active input filtering
When the InputFilter detects an invalid key it will raise this event
-
-
Methods
-
InputCheckOnce (Action<KeyCode>)
Waits until a key is detected, calls the action, and turns off input checking
Call this if you want to stop the input checking after a single key press
After the input detection, the Action you passed is removed from the event listeners
If the detector receives an invalid key, it will continue checking for input -
InputCheckSetActive (bool)
Set manually whether you want to check for input, keeps checking until deactivation
Call this if you want to keep checking for the key the user/player is pressing
The KeyDetector will keep checking for input and will activate events until you deactivates the input checking manually -
RemoveAllListeners ()
Removes all the listeners from the KeyReceived event -
SetInputFilter (InputFilter)
Used to set custom filtering for the KeyDetector
Just call and input an InputFilter object
It is reccomended to use the method bellow instead -
SetInputFilter (IInputFilterPreset)
Used to set custom filtering for the KeyDetector
Will create an input filter based on the preset you passed -
DisableInputFilter ()
Disables input filtering
Sets the InputFilter of the detector to an empty filter
-
For input filtering there is a class named InputFilter, a class the KeyDetector uses to filter input.
That means that you can prevent the KeyDetector from detecting certain keys
The KeyDetector has an empty inactive InputFilter by default (not filtering).
If you want to use input filtering on the KeyDetector,
you need to set it up before you check for input.
The best practice it to do it inside the Start() or Awake() methods.
See Examples
-
Keys
An array of KeyCode, containing the keys the filter is using for filtering
If null/empty, the filter is inactive - see bellow -
FilteringActive
Returns a bool that determines whether the filter is filtering
When an input filter is created this value is initialized to true or false
Only if the list of keys given to the filter is not empty and contains at least one key, the filter is activated (value set to true) -
FilteringMethod
Returns an enum of type InputFilter.Method
Can be either Whitelist or Blacklist - see bellow
The key will be validated by the filter only if:
- Whitelist - it is inside the list of keys of the filter
- Blacklist - it is not inside the list of keys of the filter
Lets say you want the KeyDetector to only detect the keys:
A, X, Q, Right Mouse Click, Left Mouse Click
You can do it like this:
Start()
{
// Create an array of KeyCodes or use an existing one
// It should contain all the keys you want to filter
KeyCode[] keysToFilter =
{
KeyCode.A,
KeyCode.X,
KeyCode.Q,
KeyCode.Mouse0, // left mouse button
KeyCode.Mouse1 // right mouse button
};
// 1 - Create and allocate a new InputFilter
// 2 - Pass the array of keys and choose filtering method
InputFilter inputFilter = new InputFilter(keysToFilter, InputFilter.Method.Whitelist);
// Call the method "SetInputFilter" and pass the filter
KeyDetector.SetInputFilter(inputFilter);
}Also, if you want instead that the KeyDetector will only detect the keys that are not inside the list
Just set the method to Blacklist like that:
InputFilter inputFilter = new InputFilter(keysToFilter, InputFilter.Method.Blacklist);Also, if you want to use the Whitelist filtering method
You can call the constructor without specifing the method. Like so:
InputFilter inputFilter = new InputFilter(keysToFilter);Altough it is more advanced, and may look a bit complex -
It is recommended to use input filter presets instead of creating a new InputFilter with a constructor.
This way is a lot more professional and organized.
To do this you need to create an input filter preset class.
And for this the KeyBinder tool has the interface IInputFilterPreset
And interface used for creating a preset for an InputFilter
Recommended name for a preset class is to start it with InputFilterPreset
Just create a class and implemet these members:
-
KeyCode[] KeysList { get; }
An array of keys you want to be filtered -
InputFilter.Method FilteringMethod { get; }
The filtering method see here
Lets say you want the KeyDetector to only detect the keys:
A, X, Q, Right Mouse Click, Left Mouse Click
First open a new file and create a new class for the InputFilterPreset:
using UnityEngine;
using KeyBinder;
// use the interface IInputFilterPreset
public class InputFilterPresetExample : IInputFilterPreset
{
// implement the array of keys like this
public KeyCode[] KeysList => new KeyCode[]
{
KeyCode.A,
KeyCode.X,
KeyCode.Q,
KeyCode.Mouse0, // left mouse button
KeyCode.Mouse1, // right mouse button
};
// choose a filtering method
public InputFilter.Method FilteringMethod => InputFilter.Method.Whitelist;
}Now, you just need to call the method SetInputFilter in Start() or Awake() like so:
Start()
{
// Just create a new instance of the preset class we created before
KeyDetector.SetInputFilter(new InputFilterPresetExample());
}Done! Now your KeyDetector uses a filter based on the preset class you created.
Name the class of the preset by starting with "InputFilterPreset" and then add anything you want
In this case I added "Example" and named it "InputFilterPresetExample"
This tool can be used in many ways.
Here are some examples:
You can can check which key the player/user pressed recently.
To to that, turn on input checking in the KeyDetector class.
After checking, you can get the key that was pressed from the property "LatestKey"
You can write the key name to the console like so:
using KeyBinder; // important to use the KeyBinder namespace
using UnityEngine;
public class ExampleDebugScript : MonoBehaviour
{
void Start()
{
KeyDetector.InputCheckSetActive(true); // turns on input checking
}
void Update()
{
Debug.Log(KeyDetector.LatestKey); // logs to the console the latest pressed key
}
}You can make it that it logs the key every time the detector detects a new key
Instead of updating every frame the latest key.
Do this inside the class ( no need for Update() ):
void Start()
{
KeyDetector.InputCheckSetActive(true); // turns on input checking
// adds the method "DebugKey" to the event "KeyReceived"
// it will call the method "DebugKey" every time a new key is detected
KeyDetector.KeyReceived += DebugKey;
}
void DebugKey(KeyCode keyCode)
{
Debug.Log(KeyDetector.LatestKey); // logs to the console the latest pressed key
}Let's say you have a game that uses a KeyCode variable for the shoot key.
Whenever the player presses the shoot key, the game will shoot a bullet.
And by default the shoot key is the key X:
KeyCode shootKey = KeyCode.X;
void Update()
{
if (Input.GetKeyDown(shootKey))
{
Shoot()
}
}
void Shoot()
{
// shooting behavior
}Now you want to let the player choose the key he wants to use for shooting.
To do that add a method that sets the "shootKey" variable to a new KeyCode.
void SetShootKey(KeyCode key)
{
shootKey = key;
}Add the namespace "KeyBinder" at the top of the script.
using KeyBinder;You already have a method for setting the keybind of the shoot key.
Nowreate a new method named BindShootKey().
Inside, call the function "InputCheckOnce" and pass the method SetShootKey as a parameter.
void BindShootKey()
{
KeyDetector.InputCheckOnce(SetShootKey);
}Now call this method every time you want the player to change the key for shooting.
It will wait until a key is pressed, and will call the function "SetShootKey" with the new key.
It will also automatically stops checking for input after the key is pressed.
So you don't need to worry about stoping the input checking manually.
You can also make the "BindShootKey" method - public, to assign it to a button in the UI.
The KeyDetector also supports InputFiltering read about it here
Clone the repository
In the folder "samples" you can find a unity project named "keybinder-unity-examples"
Inside this unity project you have many examples that show you what you can do with the tool
In the unity file browser, you will see these folders:
Then enter the "Examples" folder and you will see all the available examples
In every example folder you will have a different scene that shows the example
Now just open the scene and press play to see what happens.
Inside the project you have 6 examples.
You can learn from every example how the tool works.
Click here to download, or go to the packages folder of the repository and download the package file.
Then import the package directly to your project like any other Unity package.
This is he fastest and easiest way.