From eded6cae40734700e310d4a52230feacb0f63d2f Mon Sep 17 00:00:00 2001 From: Ellet Date: Fri, 31 Oct 2025 23:50:59 +0300 Subject: [PATCH 1/5] docs(entrypoint): add the add Controlify mod dependency section to copy-paste --- docs/developers/controlify-entrypoint.mdx | 41 +++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/developers/controlify-entrypoint.mdx b/docs/developers/controlify-entrypoint.mdx index d51e1d5f..513f4fac 100644 --- a/docs/developers/controlify-entrypoint.mdx +++ b/docs/developers/controlify-entrypoint.mdx @@ -6,6 +6,47 @@ _Learn how to hook into Controlify._ Controlify provides a Fabric entrypoint to hook into important lifecycle stages of Controlify. You do this just like `ClientModInitializer`. +## Adding Controlify dependency + +In your `build.gradle` (or `build.gradle.kts`), you need to add the maven +repository and the Controlify mod dependency. + +
+Maven repository + +```kotlin +repositories { + exclusiveContent { + forRepository { maven { url "https://maven.isxander.dev/releases" } } + filter { includeGroup "dev.isxander" } + } +} +``` + +
+ +
+Dependency + +Add the version to your `gradle.properties`: + +```properties +# You can find the versions in here: https://maven.isxander.dev/#/releases/dev/isxander/controlify +controlify_version=2.4.3+1.21.1-neoforge +``` + +```kotlin +dependencies { + // You can change "compileOnly" to "implementation" for testing in-game. + compileOnly("dev.isxander:controlify:${project.controlify_version}") { + // Only need Controlify API, ignore the transitive dependencies (e.g, QuiltMC parsers) + transitive = false + } +} +``` + +
+ ## Registering the entrypoint - On Fabric, you register an entrypoint like any other, by adding an entry to your `fabric.mod.json` file under the `entrypoints` section. From 853dc00d3c2b3a9d1b846f3db9df00bd15c69e48 Mon Sep 17 00:00:00 2001 From: Ellet Date: Fri, 31 Oct 2025 23:51:55 +0300 Subject: [PATCH 2/5] docs(entrypoint): allow copy-paste the SPI file for NeoForge users --- docs/developers/controlify-entrypoint.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developers/controlify-entrypoint.mdx b/docs/developers/controlify-entrypoint.mdx index 513f4fac..d973152a 100644 --- a/docs/developers/controlify-entrypoint.mdx +++ b/docs/developers/controlify-entrypoint.mdx @@ -50,7 +50,7 @@ dependencies { ## Registering the entrypoint - On Fabric, you register an entrypoint like any other, by adding an entry to your `fabric.mod.json` file under the `entrypoints` section. -- On NeoForge, you register an entrypoint using a Java service provider interface (SPI) in your `META-INF/services` directory. +- On NeoForge, you register an entrypoint using a Java service provider interface (SPI) in **`META-INF/services/dev.isxander.controlify.api.entrypoint.ControlifyEntrypoint`**. ```json !!tabs (Fabric) fabric.mod.json From 89444c6360b52a382cbad1654f86c34ca3d412f4 Mon Sep 17 00:00:00 2001 From: Ellet Date: Fri, 31 Oct 2025 23:59:39 +0300 Subject: [PATCH 3/5] docs(api): make it clear which method to use when registering custom input binds --- .../controlify/api/entrypoint/ControlifyEntrypoint.java | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/main/java/dev/isxander/controlify/api/entrypoint/ControlifyEntrypoint.java b/src/main/java/dev/isxander/controlify/api/entrypoint/ControlifyEntrypoint.java index e83fd772..bbae7e0f 100644 --- a/src/main/java/dev/isxander/controlify/api/entrypoint/ControlifyEntrypoint.java +++ b/src/main/java/dev/isxander/controlify/api/entrypoint/ControlifyEntrypoint.java @@ -15,13 +15,17 @@ public interface ControlifyEntrypoint { * Called once Controlify has initialised some systems but controllers * have not yet been discovered and constructed. This is the ideal * time to register events in preparation for controller discovery. + * Input bindings cannot be registered here; use {@link #onControlifyPreInit} instead. */ void onControlifyInit(InitContext context); /** * Called at the end of Controlify's client-side entrypoint. - * You can register guides here. + * Use this to register guides, input bindings, radial icons, or screen processors, + * and to subscribe to events from {@link dev.isxander.controlify.api.event.ControlifyEvents}. + * Avoid referencing objects that are registered later (e.g. custom mod items), + * as they may not be initialized yet and could cause errors due to deferred registration. */ void onControlifyPreInit(PreInitContext context); From d51805e1b2a089de2c5026ef6ee2d9e8e5fa17fa Mon Sep 17 00:00:00 2001 From: Ellet Date: Sat, 1 Nov 2025 00:30:57 +0300 Subject: [PATCH 4/5] docs(bindings): update outdated API references --- docs/developers/bindings-api.mdx | 42 ++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/docs/developers/bindings-api.mdx b/docs/developers/bindings-api.mdx index 5eb4b215..c094a532 100644 --- a/docs/developers/bindings-api.mdx +++ b/docs/developers/bindings-api.mdx @@ -7,40 +7,46 @@ _Learn how to register new controller bindings._ ## Registering a custom input binding - You should register bindings inside of the Controlify init entrypoint. Read more in [Controlify Entrypoint](controlify-entrypoint#using-the-entrypoint). + The custom input bindings must be registered inside the Controlify pre-init entrypoint. Read more in [Controlify Entrypoint](controlify-entrypoint#using-the-entrypoint). 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. -To register a controller binding, you must use the `ControllerBindingsApi.` +To register a controller binding, use the `ControllerBindingsApi.get()` method: ```java -private BindingSupplier action1Binding; +private InputBindingSupplier actionBinding; @Override public void onControlifyInit(InitContext ctx) { - action1Binding = ctx.bindings().registerBinding( + final ControlifyBindApi registrar = ControlifyBindApi.get(); + registerInputBindings(registrar); +} + +private void registerInputBindings(ControlifyBindApi registrar) { + actionBinding = registrar.registerBinding( builder -> builder - .id("mymod", "action1") // the id of the binding, this should be unique to your mod - .category(Component.translatable("mymod.binding.category")) // the category of the binding, this is used to group bindings together in the settings - .allowedContexts(BindContext.IN_GAME) // a context is where the binding can be used, you can use multiple contexts - .radialCandiate(RadialIcons.getEffect/getIcon(...)) // if you want to allow your binding to be used in the radial menu + .id(ResourceLocation.fromNamespaceAndPath(MyMod.MODID, path)) + // The category of the binding, this is used to group bindings together in the settings. + .category(Component.translatable("mymod.binding.category")) + // A context is where the binding can be used. Multiple contexts can be used. + .allowedContexts(BindContext.IN_GAME) + // Allow using the binding in the radial menu. + // You can't use a custom modded item directly in here, since it's not registered yet + // and a runtime error will be thrown. Continue reading for a better alternative. + .radialCandidate(RadialIcons.getItem(Items.BARRIER))) + // Prevents Controlify from auto-registering controller bindings for Epic Fight's + // vanilla key mappings due explicit native support. + // You could also use ".keyEmulation(MyModKeyMappings.ACTION) to emulates + // the vanilla KeyMapping behavior, which may not always work well. + .addKeyCorrelation(MyModKeyMappings.ACTION) ); } ``` To add a name and description to the binding, you need to define the language keys `controlify.binding..` and `controlify.binding...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.on(controller);` - -Controlify automatically converts your existed modded `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 onControlifyInit(InitContext ctx) { - ctx.bindings().exclude(MyMod.myKeyMapping); -} -``` +Registering the binding provides you with a `InputBindingSupplier`, where you can then access the binding with `actionBinding.on(controller);` ## Defining a default binding From 8e0e9791abb24c4c5b94a2875c37bd51cc4dfcb3 Mon Sep 17 00:00:00 2001 From: Ellet Date: Sat, 1 Nov 2025 00:31:36 +0300 Subject: [PATCH 5/5] docs(bindings): document how to register a custom radial icons --- docs/developers/bindings-api.mdx | 62 +++++++++++++++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/docs/developers/bindings-api.mdx b/docs/developers/bindings-api.mdx index c094a532..e9d83809 100644 --- a/docs/developers/bindings-api.mdx +++ b/docs/developers/bindings-api.mdx @@ -12,7 +12,7 @@ _Learn how to register new controller bindings._ 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. -To register a controller binding, use the `ControllerBindingsApi.get()` method: +To register a controller binding, use the `ControlifyBindApi.get()` method: ```java private InputBindingSupplier actionBinding; @@ -89,3 +89,63 @@ There are more properties available inside of `InputBinding` which you can look There is nothing special about rendering glyphs for controller bindings, as Controlify utilises custom fonts. This means you can use the glyphs within localised text, or just render it with `graphics.drawString(myBinding.inputGlyph(), x, y, -1);` + +## Registering Custom Radial Icons + +When registering a radial menu candidate, you must provide an icon to render it in the GUI. +You can use `RadialIcons.getEffect(...)` or `RadialIcons.getItem(...)` (for example, `RadialIcons.getItem(Items.REDSTONE)`). + +However, **do not reference modded items directly** (e.g., `RadialIcons.getItem(ModItems.CUSTOM.get())`), +as item registration is deferred — meaning those items are not yet registered at this stage. + +What you can do instead, is to reference the texture image file in the bundled resource-pack of your mod, +using the following approach: + +```java +private enum MyRadialIcons { + CUSTOM(MyMod.rl("textures/item/custom.png")),; + + private final @NotNull ResourceLocation id; + + MyRadialIcons(@NotNull ResourceLocation id) { + this.id = id; + } + + public @NotNull ResourceLocation getId() { + return id; + } +} + +@Override +public void onControlifyPreInit(PreInitContext context) { + final ControlifyBindApi registrar = ControlifyBindApi.get(); + registerCustomRadialIcons(); + + // Must be called after registerCustomRadialIcons + registerInputBindings(registrar); +} + +private void registerCustomRadialIcons() { + for (MyRadialIcons icon : MyRadialIcons.values()) { + final ResourceLocation location = icon.getId(); + + // For consistency with the current Controlify radial icons, + // this code is equivalent to: + // https://github.com/isXander/Controlify/blob/f5c94c57d5e0d4954e413624a0d7ead937b6e8ab/src/main/java/dev/isxander/controlify/bindings/RadialIcons.java#L106-L112 + RadialIcons.registerIcon(location, (graphics, x, y, tickDelta) -> { + var pose = CGuiPose.ofPush(graphics); + pose.translate(x, y); + pose.scale(0.5f, 0.5f); + Blit.tex(graphics, location, 0, 0, 0, 0, 32, 32, 32, 32); + pose.pop(); + }); + } +} + +private void registerInputBindings(ControlifyBindApi registrar) { + actionBinding = registrar.registerBinding( + builder -> builder + .radialCandidate(MyRadialIcons.CUSTOM.getId()) + ); +} +```