Create Cursor Textures

Important

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

This page will no longer be updated.

---

The size of the texture is strictly 32x32 pixels and must be in .png format.

The file name of the texture must be the key of the cursor you want to customize.

Example Customizing the Default cursor:

Animated Textures

1. 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 does not load.
   
   

2. 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 hard limit to how many frames you can add besides your allocated memory.
   
   

3. 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 <key>.png.mcmeta file:

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

Limitations

• 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. This is to maximize mod compatibility.
• 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: https://github.com/fishstiz/minecraft-cursor/tree/release/1.21.4/common/src/main/resources/assets/minecraft-cursor/textures/cursors.

---

Previous: All Cursors View all Cursors, their keys, and their uses.

Next: Custom Settings Specify custom settings for each cursor.