start work on separate API JAR

Author: isXander

api/build.gradle.kts

@@ -0,0 +1,18 @@
+plugins {
+    `java-library`
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation("org.slf4j:slf4j-api:2.0.17")
+    implementation("org.jspecify:jspecify:1.0.0")
+}
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(21))
+    }
+}

api/src/main/java/dev/isxander/controlify/api/CIdentifier.java

@@ -0,0 +1,4 @@
+package dev.isxander.controlify.api;
+
+public record CIdentifier(String namespace, String path) {
+}

api/src/main/java/dev/isxander/controlify/api/MinecraftComponent.java

@@ -0,0 +1,22 @@
+package dev.isxander.controlify.api;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotated on {@link Object} to indicate that the object is a
+ * <code>Component</code>/<code>Text</code> and can be safely cast.
+ * If annotated on a parameter, it indicates that the method expects the parameter
+ * to be a Minecraft Component/Text, and will result in a ClassCastException if it is not.
+ * <p>
+ * This is required because this API is designed without a direct dependency to Minecraft.
+ */
+@Retention(RetentionPolicy.SOURCE)
+@Target({
+        ElementType.TYPE_USE,
+        ElementType.PARAMETER
+})
+public @interface MinecraftComponent {
+}

api/src/main/java/dev/isxander/controlify/api/v1/ControlifyApi.java

@@ -0,0 +1,28 @@
+package dev.isxander.controlify.api.v1;
+
+import dev.isxander.controlify.api.v1.bindings.BuiltinBindings;
+import dev.isxander.controlify.api.v1.widgetguide.WidgetGuideApi;
+
+import java.util.Optional;
+
+public interface ControlifyApi {
+    WidgetGuideApi widgetGuide();
+
+    BuiltinBindings builtinBindings();
+
+    /**
+     * Checks if the current input mode is controller mode.
+     * This is always true when the user uses "Mixed Input" mode, or true
+     * when the controller was the last used input device.
+     * @return true if the current input mode is controller mode.
+     */
+    boolean isControllerMode();
+
+    static Optional<ControlifyApi> get() {
+        return Optional.ofNullable(ControlifyApiLoader.get());
+    }
+
+    static boolean isControlifyInstalled() {
+        return get().isPresent();
+    }
+}

api/src/main/java/dev/isxander/controlify/api/v1/ControlifyApiLoader.java

@@ -0,0 +1,23 @@
+package dev.isxander.controlify.api.v1;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.ServiceLoader;
+
+final class ControlifyApiLoader {
+    private static final Logger LOGGER = LoggerFactory.getLogger("Controlify API Loader");
+    private static ControlifyApi INSTANCE = null;
+
+    static ControlifyApi get() {
+        if (INSTANCE == null) {
+            INSTANCE = ServiceLoader.load(ControlifyApi.class)
+                    .findFirst()
+                    .orElseGet(() -> {
+                        LOGGER.warn("Controlify API implementation not found. Controlify not installed?");
+                        return null;
+                    });
+        }
+        return INSTANCE;
+    }
+}

api/src/main/java/dev/isxander/controlify/api/v1/ControlifyController.java

@@ -0,0 +1,20 @@
+package dev.isxander.controlify.api.v1;
+
+/**
+ * Represents a specific game controller.
+ * This could be a gamepad, or a generic joystick device.
+ * <p>
+ * Each controller has different capabilities and button layouts.
+ */
+public interface ControlifyController {
+
+    /**
+     * Gets the unique identifier for this controller.
+     * This identifier is stable and will be the same across sessions for the same
+     * physical controller. If there are multiple controllers of the same type connected,
+     * they will have different UIDs, the first to connect will have the same UID across sessions.
+     * @return the unique identifier for this controller.
+     */
+    String uid();
+
+}

api/src/main/java/dev/isxander/controlify/api/v1/bindings/BuiltinBindings.java

@@ -0,0 +1,63 @@
+package dev.isxander.controlify.api.v1.bindings;
+
+public interface BuiltinBindings {
+    InputBindingSupplier walkForward();
+    InputBindingSupplier walkBackward();
+    InputBindingSupplier walkLeft();
+    InputBindingSupplier walkRight();
+
+    InputBindingSupplier lookUp();
+    InputBindingSupplier lookDown();
+    InputBindingSupplier lookLeft();
+    InputBindingSupplier lookRight();
+
+    InputBindingSupplier jump();
+    InputBindingSupplier sprint();
+    InputBindingSupplier sneak();
+
+    InputBindingSupplier attack();
+    InputBindingSupplier use();
+
+    InputBindingSupplier dropIngame();
+    InputBindingSupplier dropStackIngame();
+
+    InputBindingSupplier pause();
+
+    InputBindingSupplier changePerspective();
+    InputBindingSupplier swapHands();
+
+    InputBindingSupplier nextHotbarSlot();
+    InputBindingSupplier previousHotbarSlot();
+
+    InputBindingSupplier openInventory();
+
+    InputBindingSupplier containerSelect();
+    InputBindingSupplier containerQuickMove();
+    InputBindingSupplier containerTakeHalf();
+    InputBindingSupplier containerDrop();
+
+    InputBindingSupplier pickBlock();
+    InputBindingSupplier pickBlockNbt();
+
+    InputBindingSupplier openChat();
+    InputBindingSupplier toggleHudVisibility();
+    InputBindingSupplier playerList();
+    InputBindingSupplier takeScreenshot();
+
+    InputBindingSupplier guiPress();
+    InputBindingSupplier guiBack();
+    InputBindingSupplier guiNextTab();
+    InputBindingSupplier guiPreviousTab();
+    InputBindingSupplier guiAbstract1();
+    InputBindingSupplier guiAbstract2();
+    InputBindingSupplier guiAbstract3();
+    InputBindingSupplier guiNavigateUp();
+    InputBindingSupplier guiNavigateDown();
+    InputBindingSupplier guiNavigateLeft();
+    InputBindingSupplier guiNavigateRight();
+    InputBindingSupplier guiSecondaryNavigateUp();
+    InputBindingSupplier guiSecondaryNavigateDown();
+    InputBindingSupplier guiSecondaryNavigateLeft();
+    InputBindingSupplier guiSecondaryNavigateRight();
+
+}

api/src/main/java/dev/isxander/controlify/api/v1/bindings/InputBinding.java

@@ -0,0 +1,78 @@
+package dev.isxander.controlify.api.v1.bindings;
+
+import dev.isxander.controlify.api.CIdentifier;
+import dev.isxander.controlify.api.MinecraftComponent;
+
+public interface InputBinding {
+    CIdentifier id();
+
+    @MinecraftComponent Object glyphIcon();
+
+    /**
+     * Gets the current analogue value of this binding.
+     * In the range [0.0, 1.0].
+     * <p>
+     * When the underlying binding is digital,
+     * this returns 1.0 if the digital value is true, otherwise 0.
+     */
+    float analogueNow();
+
+    /**
+     * Gets the previous tick analogue value of this binding.
+     * In the range [0.0, 1.0].
+     * <p>
+     * When the underlying binding is digital,
+     * this returns 1.0 if the digital value is true, otherwise 0.
+     */
+    float analoguePrev();
+
+    /**
+     * Gets the current digital value of this binding.
+     * <p>
+     * When the underlying binding is analogue,
+     * this returns true if the analogue value is greater than the configured threshold.
+     */
+    boolean digitalNow();
+
+    /**
+     * Gets the previous tick digital value of this binding.
+     * <p>
+     * When the underlying binding is analogue,
+     * this returns true if the analogue value is greater than the configured threshold.
+     */
+    boolean digitalPrev();
+
+    /**
+     * Whether the binding was just pressed this tick.
+     * <p>
+     * Equivalent to calling
+     * <pre><code>
+     *     binding.digitalNow() && !binding.digitalPrev()
+     * </code></pre>
+     */
+    boolean justPressed();
+
+    /**
+     * Whether the binding was just released this tick.
+     * <p>
+     * Equivalent to calling
+     * <pre><code>
+     *     !binding.digitalNow() && binding.digitalPrev()
+     * </code></pre>
+     */
+    boolean justReleased();
+
+    /**
+     * Whether the binding was just tapped (pressed and released).
+     */
+    boolean justTapped();
+
+    /**
+     * Similar to {@link #justTapped()}, but with infinite max hold time,
+     * and is canceled by GUI navigation.
+     * <p>
+     * In practice, this means if a user held down the binding when hovering a button,
+     * then whilst still holding it, navigated to another button, and then released, this would not activate.
+     */
+    boolean guiPressed();
+}

api/src/main/java/dev/isxander/controlify/api/v1/bindings/InputBindingBuilder.java

@@ -0,0 +1,59 @@
+package dev.isxander.controlify.api.v1.bindings;
+
+import dev.isxander.controlify.api.CIdentifier;
+import org.jspecify.annotations.NonNull;
+
+public interface InputBindingBuilder {
+    /**
+     * Sets the unique identifier for the binding.
+     * This is a required field. The namespace should be your mod's ID.
+     * <p>
+     * The id is used to automatically generate the translation keys for the name and description.
+     * <ul>
+     *     <li>Name: <code>controlify.binding.(namespace).(path)</code></li>
+     *     <li>Desc: <code>controlify.binding.(namespace).(path).desc</code>, optional</li>
+     * </ul>
+     * This is the ID referred to in {@link InputBindingSupplier#bindId()}.
+     *
+     * @param rl the binding's id
+     * @return this builder
+     */
+    InputBindingBuilder id(@NonNull CIdentifier rl);
+
+    /**
+     * Sets the unique identifier for the binding.
+     * This is a required field. The namespace should be your mod's ID.
+     * <p>
+     * The id is used to automatically generate the translation keys for the name and description.
+     * <ul>
+     *     <li>Name: <code>controlify.binding.(namespace).(path)</code></li>
+     *     <li>Desc: <code>controlify.binding.(namespace).(path).desc</code>, optional</li>
+     * </ul>
+     * This is the ID referred to in {@link InputBindingSupplier#bindId()}.
+     *
+     * @param namespace namespace of {@link CIdentifier}
+     * @param path path of {@link CIdentifier}
+     * @return this builder
+     */
+    default InputBindingBuilder id(@NonNull String namespace, @NonNull String path) {
+        return this.id(new CIdentifier(namespace, path));
+    }
+
+    /**
+     * Sets the category for the binding. <strong>Required field.</strong>
+     * This is used to group the binding in the option menu.
+     * It's recommended that you use a single category for all of your mod's bindings.
+     *
+     * @param category the category
+     * @return this builder
+     */
+    InputBindingBuilder category(@NonNull InputBindingCategory category);
+
+    /**
+     * Registers this binding as a radial menu candidate with the given icon.
+     * @param icon the radial icon
+     * @return this builder
+     */
+    InputBindingBuilder radialCandidate(@NonNull RadialIcon icon);
+
+}

api/src/main/java/dev/isxander/controlify/api/v1/bindings/InputBindingCategory.java

@@ -0,0 +1,6 @@
+package dev.isxander.controlify.api.v1.bindings;
+
+import dev.isxander.controlify.api.CIdentifier;
+
+public record InputBindingCategory(CIdentifier id) {
+}