# Bindings API

## Bind Registry

{% hint style="info" %}
You should register bindings inside of the Controlify pre-init entrypoint. Read more in [Controlify Entrypoint](/controlify/developers/controlify-entrypoint.md#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);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.isxander.dev/controlify/developers/bindings-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.