# Bindings API

## Bind Registry

{% hint style="info" %}
You should register bindings inside of the Controlify pre-init entrypoint. Read more in [Controlify Entrypoint](https://docs.isxander.dev/controlify/controlify-entrypoint#pre-init-method).
{% endhint %}

Controlify allows users to configure different buttons on their controllers to actions in-game. You may want your own mod's actions to be able to be invoked from the controller too, or you may want your `KeyMapping` to be able to used on a controller.

To register a controller binding, you must use the `ControllerBindingsApi.`

```java
private BindingSupplier action1Binding;

@Override
public void onControlifyPreInit(ControlifyApi controlify) {
    action1Binding = ControllerBindingsApi.registerBinding(
            new ResourceLocation("mymod", "action_1"), 
            builder -> builder
                    .defaultBind(GamepadBinds.A_BUTTON)
                    .category(Component.translatable("mymod.binding.category"))
    )
}
```

To add a name and description to the binding, you need to define the language keys `controlify.binding.<namespace>.<path>` and `controlify.binding.<namespace>.<path>.desc` respectively, alternatively, you can set `.name(Component)` and `.description(Component)`

Registering the binding provides you with a `BindingSupplier`, where you can then access the binding with `action1Binding.onController(controller);`

Controlify automatically converts `KeyMapping`s to controller bindings, but relying on this behaviour if you are going to explicitly support Controlify is not recommended. You can stop this conversion with the following...

```java
@Override
public void onControlifyPreInit(ControlifyApi controlify) {
    ControllerBindingsApi.exclude(MyMod.myKeyMapping)
}
```

## Using the binding

Once you have access to a binding through `bindingSuppler.onController(controller)`, you can access many properties of the binding:

<table data-view="cards"><thead><tr><th>Property</th><th>Description</th></tr></thead><tbody><tr><td><code>state()</code></td><td>Gets a float value between 0 - 1 which describes its analogue state.</td></tr><tr><td><code>justPressed()</code></td><td>Returns if the binding was pressed this tick, if it returns true, the state is consumed and will return false for the remaining tick.</td></tr><tr><td><code>justReleased()</code></td><td>Returns if the binding was just released this tick, if it returns true, the state is consumed and will return false for the remaining tick.</td></tr><tr><td><code>held()</code></td><td>Returns true if the binding is down this tick.</td></tr><tr><td><code>generateYACLOption()</code></td><td>Creates a YetAnotherConfigLib option that you can add to your own YACL GUIs.</td></tr></tbody></table>

There are more properties available inside of `ControllerBinding` which you can look at in the sources, but the above are the most notable that you will use the most.

## Rendering bindings

If you want to render a specific bind's icon, you can get `ControllerBinding#renderer()`, `BindingRenderer` provides two methods, `size()` and `render(PoseStack, int, int)`.

```java
BindingRenderer renderer = binding.renderer();
DrawSize size = renderer.size();
int width = size.width()
int height = size.height();
renderer.render(matrices, x, y);
```