# Minecraft Cursor A Fabric mod that replaces the boring old default system cursor with an adaptive Minecraft-themed cursor. ## Requirements - Fabric for Minecraft 1.20.1 or 1.21+ - (Optional) [Mod Menu](https://modrinth.com/mod/modmenu) ## Adaptive Cursor ![default](https://github.com/user-attachments/assets/6c632b54-e284-47a0-8634-f4ba1ef03f29) ![pointer](https://github.com/user-attachments/assets/83a41d81-5a0b-4399-8d70-61ca421117c0) ![grabbing](https://github.com/user-attachments/assets/bdcd6392-a8bb-40af-b2fa-10a465363545) ![text](https://github.com/user-attachments/assets/049fc447-6f3f-4c7a-a0a2-b87d0348c593) ![shift](https://github.com/user-attachments/assets/27f97a5c-be91-45c9-ad5d-91a5e162fb50) ![busy](https://github.com/user-attachments/assets/2b4e338a-7068-4998-8f79-e7ccfc3a97fa) - The cursor changes on certain actions and when hovering over buttons, text fields, and grabbing sliders (limited to Minecraft's out of the box GUI elements). - Disable all cursors except default in the cursor settings to disable this feature, - You can also toggle all non-default cursors in one click from More Cursor Options - You can disable adaptive cursors for certain actions in More Cursor Options - Mods that shift the sizes and positions of certain **in-game** GUIs may lead to unexpected cursor switching. - Check the **Mod Compatibility** section to see affected GUIs. - You can disable adaptive cursors for affected GUIs in More Cursor Options ## Configure Cursors - Configure from Mod Menu (if installed) - Configure from Options > Controls > Mouse Settings... > Cursor Settings... - Configure More Cursor Options from Cursor Settings > More Cursor Options... - Disabled cursors will fallback to the default cursor unless it is also disabled. options-menu

All Cursors

Cursor Name	Key	When it is used
Default	`default`	The default cursor. If another cursor is disabled.
Pointer	`pointer`	Hovered over: Discoverable `PressableWidget` elements. Inventory slots with item/s. Creative inventory tabs. Recipe book tabs and recipes. Available enchantments in the enchanting table. Available stonecutter recipes. Available loom patterns. Crafter slots.
Text	`text`	Hovered over discoverable `TextFieldWidget` elements. Hovered inside Book and Quill book.
Grabbing	`grabbing`	Grabbing items. Dragging the slider in discoverable `SliderWidget` elements.
Shift	`shift`	Shift is pressed and mouse is hovered over: Inventory slots with item/s. Creative inventory destroy item slot. Recipe book recipes. Villager trade offers.
Busy	`busy`	In loading screens: `MessageScreen` `DownloadingTerrainScreen` `ProgressScreen` `LevelLoadingScreen`

Resource Pack Support

Image Format

32x32 pixels
png format

File Structure

└── minecraft-cursor/
    ├── atlases/
    │   └── cursors.json
    └── textures/
        └── cursors/
            ├── busy.png
            ├── default.png
            ├── grabbing.png
            ├── pointer.png
            ├── shift.png
            └── text.png

Custom Configuration

Define a custom configuration for your resource pack in atlases/cursors.json.
Can be overridden by users through the Cursor Settings menu.
The user's config will reset to the provided config when changing resource packs.

Example cursors.json:

{
  "settings": {
    "default": {
      "xhot": 7,
      "yhot": 3,
      "scale": 0.8
    },
    "pointer": {
      "xhot": 7,
      "yhot": 3,
      "scale": 0.8
    },
    "text": {
      "xhot": 12,
      "yhot": 15,
      "scale": 0.8
    },
    "grabbing": {
      "enabled": false 
    },
    "shift": {
      "xhot": 11,
      "yhot": 3
    }
  }
}

All Settings:

Key	Type	Range	Default	Description
`enabled`	`boolean`	`true` or `false`	`true`	Determines whether the cursor type is enabled or not.
`scale`	`float`	`0.50` - `3.00` (incrementing by `0.05`)	`1.00`	Specifies the scale factor for the cursor type.
`xhot`	`int`	`0` - `31`	`0`	Specifies the x hotspot position.
`yhot`	`int`	`0` - `31`	`0`	Specifies the y hotspot position.

Animated Cursors

Create a sprite sheet in PNG format for the cursor type. The sprites will be evaluated from top to bottom.
Each sprite must be 32x32 pixels as per usual with no gaps in between.
The first sprite serves as the fallback cursor type when the animation is disabled by the user, or if the animation data does not load.
Add a .mcmeta file for the cursor type to register the animation and to specify the animation data.

Example structure:

└── minecraft-cursor/
    └── textures/
        └── cursors/
            ├── busy.png
            └── busy.png.mcmeta

The .mcmeta file is in JSON format:

Key Type Default Description

mode

String

loop

Determines the animation mode.

Animation Modes
Name	Description
`loop`	Repeats in a continuous loop. The default mode.
`loop_reverse`	Repeats in a continuous loop but in reverse.
`forwards`	Plays the animation and stops at the last frame.
`reverse`	Plays the animation in reverse and stops at the first frame.
`oscillate`	Loops back and forth continuously.
`random`	Randomly selects frames in a loop. Does not repeat the same frame twice.
`random_cycle`	Randomly selects frames in a loop, cycling through all frames before repeating.

frametime int 1 The amount of ticks per frame. Minimum value: 1.

frames

Array

null

Determines the order and/or time of the frames to be played.

If this is null, then the frames will be auto-generated based on the sprite sheet and the given timeframe.
The array element can either be an int or a Frame object.
An array element of type int specifies the index of the sprite starting from 0.

Frame
Key	Type	Description
`index`	`int`	The index of the sprite starting from `0`.
`time`	`int`	The amount of ticks before going to the next frame. Minimum value: `1`.

Example .mcmeta file:

{
  "mode": "loop",
  "frametime": 1,
  "frames": [{ "index": 0, "time": 2 }, 1, 2, 3, 2]
}

Mod Compatibility

Widgets are automatically registered by this mod with the following conditions:

Pointer elements must be an instance of PressableWidget or SliderWidget

ClickableWidget is not registered as they are not always a button. For example: ScrollableWidget is a subclass of ClickableWidget

Text elements must be an instance of TextFieldWidget
They must be a child of ParentElement (e.g. Screen), accessible through children() method
Container elements must be an instance of ParentElement and nested containers must be an instance and child of ParentElement

GUI "elements" that may be affected from shifting their positions and sizes:

CreativeInventoryScreen tabs
EnchantmentScreen choices
StonecutterScreen recipes
BookEditScreen book
LoomScreen patterns
AdvancementsScreen tabs
WorldListWidget world icon play button
MultiplayerServerListWidget server icon play button

# Developer API The Minecraft Cursor mod provides an API for mod developers to: - Create custom cursor types. - Register elements with custom cursor type functions. - Use an interface for elements that implements a `getCursorType()` method to declare its cursor type. - Directly change the cursor, bypassing the element-based system. Visit the Minecraft Cursor Wiki for more details: https://github.com/fishstiz/minecraft-cursor/wiki Minecraft Cursor API JavaDocs: https://minecraft-cursor.bitbucket.io