CursorController

Important

The Minecraft Cursor Wiki has moved to:
https://fishstiz.github.io/minecraft-cursor-wiki/.

This page will no longer be updated.

---

The CursorController instance allows you to bypass the element-based system and directly control the cursor.

Note: Make sure Minecraft Cursor is loaded or simply make it a required dependency before using CursorController.

It will also only be instantiated after the Minecraft Cursor entrypoints have been initialized, and will throw an error if accessed too early.

Getting the CursorController instance

CursorController cursorController = CursorController.getInstance();

Methods

The CursorController instance provides methods for changing the cursor's cursor type.

void setSingleCycleCursor(CursorType cursorType)

Changes the cursor to a specified CursorType for only one render/tick cycle.

Example Usage:

public class DeeplyNestedButton extends ClickableWidget {
    // ...

    @Override
    protected void renderWidget(DrawContext context, int mouseX, int mouseY, float delta) {
        // ...

        if (this.isMouseOver(mouseX, mouseY)) {
            CursorController.getInstance().setSingleCycleCursor(CursorType.POINTER);
        }
    }
}

void overrideCursor(CursorType cursorType, int index)

Overrides the current cursor with a specified CursorType and priority index. Higher index values take precedence when multiple overrides exist.

Note: Use positive values for the index as Minecraft Cursor uses negative index values internally to ensure they do not override with your custom cursor overrides.

void removeOverride(int index)

Removes the cursor override at the given index.

Note: Overrides will automatically be removed if they are not loaded or if the cursor type is disabled by the user.

Example usage of overrideCursor and removeOverride:

public class MyScreen extends Screen {
    // ...

    private static final CursorController CURSOR_CONTROLLER = CursorController.getInstance();
    private boolean doingSomething;

    public void setDoingSomething(boolean isDoingSomething) {
        if (isDoingSomething) {
            CURSOR_CONTROLLER.overrideCursor(CustomCursor.DOING_SOMETHING, 100); // 100 is just an arbitrary number
        } else {
            CURSOR_CONTROLLER.removeOverride(100);
        }
    }

    @Override
    public void close() {
        // Remove the override on close to ensure the cursor doesn't get stuck.
        CURSOR_CONTROLLER.removeOverride(100);
        super.close();
    }
}

Take Complete Control of the Adaptive Behavior

By using only overrideCursor with the same index throughout your whole mod and never removing the override, you can almost completely override the default adaptive behavior of the cursor.

USE WITH CAUTION: This makes the element-based system obsolete.

Completely overriding Minecraft Cursor's sytem may also not be the best for mods that also depend on Minecraft Cursor if mod compatibility is a concern.

Create a CursorController Utility or Wrapper Class for Cursor Management

public CursorControllerUtil {
    public static setCursor(CursorType cursorType) {
        // 1 is just an arbitrary number
        CursorController.getInstance().overrideCursor(cursorType, 1);
    }
}

With this, you've effectively overriden most of Minecraft Cursor's cursor type specifications. Manage the cursor type yourself—build an event-based system, reinvent the wheel and use another registry-based approach, make it adaptive in whatever way your mod requires. Minecraft Cursor now only abstracts the internal logic of creating and setting cursors.

This approach does not override Minecraft Cursor's:

• Default fallback system.
• Cursor overrides with a higher index.

Practical Examples

Take a look at the Minecraft Cursor source code for an example of using cursor overrides: https://github.com/fishstiz/minecraft-cursor/blob/release/1.21.4/common/src/main/java/io/github/fishstiz/minecraftcursor/gui/widget/CursorOptionsHandler.java#L72

Explanation: When the user changes the scale setting of the cursor, the current cursor changes to the cursor being modified. Normally, the cursor changes to grabbing when dragging the slider, but the overrideCursor method is used to override this and any other cursor behavior.

---

Previous: CursorProvider Interface A more declarative alternative to Element Registration.