Creating Cursor Textures

Cursor textures must meet the following requirements:

Size: 32x32 pixels (strict)
Format: .png

The file name of the texture must match the cursor key you want to retexture.

Example

To retexture the Default cursor (key: default), name the texture file default.png.

Animated Textures

To create animated textures, start with the standard 32x32 cursor texture. This will be the start of the sprite sheet.
- This also serves as the fallback cursor when the user disables the animation of the cursor or if the animation data fails to load.
Add frames by expanding the image downwards. Each frame is just another 32x32 cursor texture.
- The entire image height must be divisible by 32 pixels, while the width must remain 32 pixels.
- Frames are identified by their index starting at 0, meaning the first frame is identified as frame 0, the next frame as frame 1, and so on.
- There is no set limit to how many frames you can add.
Register the texture as an animated texture by adding a <key>.png.mcmeta file. Here is where you can also add animation data.

default.png.mcmeta:

Animation Data

The existence of the <key>.png.mcmeta file tells Minecraft Cursor that <key>.png is an animated texture. It also specifies the animation data.

It is in JSON format and can be opened with any text editor, preferably code editors like Notepad++ to aid with formatting.

Key Type Default Description

mode ^optional

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 ^optional int 1 The amount of ticks per frame. Minimum value: 1.

frames ^optional

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 frametime.
Array elements can either be an int or a Frame object.

`int`
Specifies the index of the frame on the sprite sheet starting at `0`

Frame
Key	Type	Description
`index` ^required	`int`	The index of the frame on the sprite sheet starting at `0`.
`time` ^required	`int`	The `frametime` of the frame. Minimum value: `1`.

Example usage:

<key>.png.mcmeta

json

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

Limitations

To maximize mod compatibility, interpolation is not feasible as the cursors are not being custom rendered. Minecraft Cursor simply changes the look of the native cursor, with each frame essentially being its own cursor.
Minecraft Cursor relies on Minecraft's render loop which is based on the user's frame rate. If this is paused or slowed down, the animation will also pause or slow down.

Practical Examples

For more examples, you can take a look at the built-in textures of Minecraft Cursor in the source files.

Getting Started