Creating Cursor Textures

Requirements:

• Minimum Size: 8x8
• File name must match a cursor name.
• Format: .png

Recommendations:

• For 1x scale: Use a power-of-two size (16x16, 32x32, 64x64, etc.).
• For 0x scale (auto): Match your resource packs' resolution (16x16 in vanilla).
• Other, non-standard scale values should be configured on a per-user basis.

Animated Textures

1. All frames must be equal in size. Follow the requirements above.
2. Stack frames vertically from top to bottom. The topmost sprite is used as fallback when the animation is disabled.
3. Add the animation properties to the cursor settings. Without the animation properties, the whole image will be read as a single cursor texture.

Cursor Settings

Specifies the default cursor settings and may also include animation properties. This file is optional; if omitted, the default values will be applied instead.

cursor-name.png.json

{
  "cursor": {
    "scale": 1,
    "xhot": 0,
    "yhot": 0,		
  },          
  "animation": {               
    "frametime": 1,            
  }
}

cursor

Key	Type	Default	Description
enabled	boolean	true	Can only be used to disable the cursor by specifying false.
scale	float	1.00	The scale of the texture. Caps at 8. To enable auto-scale, set the value to 0.
xhot	int	0	The x-hotspot position. Caps at image width minus one.
yhot	int	0	The y-hotspot position. Caps at image height minus one.
animated	boolean	null, or true if animation properties exist	Determines whether the animation should be played if animation properties exist.

animation

Key	Type	Default	Description
mode	String	loop	The animation mode. Animation Modes Name Description loop Repeats in a continuous loop. loop_reverse Repeats in a continuous loop 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.
width	int	min dimension	The width of each frame. Defaults to the smaller value between the image's width and height. Caps at image width.
width	int	min dimension	The height of each frame. Defaults to the smaller value between the image's width and height. Caps at image height.
frametime	int	1	The amount of ticks per frame. Min value: 1.
frames	Array	null	Determines the order and/or time of the frames to be played. Array elements can either be an int or a Frame object. int Specifies the index of the frame in the sprite sheet starting from 0. Frame Key Type Description index * int Specifies the index of the frame in the sprite sheet starting from 0. time * int The frametime of the frame. Min value: 1.

Examples

cursor-name.png.json

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

• Animation loops continuously.
• Default frame duration is 4 ticks.
• Frames played in this order: 3 → 1 → 0 → 5 → 2.
• Frame 1 plays for 6 ticks (overridden).
• Frame 2 plays for 3 ticks (overridden).
• All other frames play for 4 ticks (default).

---

cursor-name.png.json

{
	"animation": {
		"frametime": 2
	}
}

• Frames are played in order from top to bottom.
• Each frame lasts two ticks.
• Animation loops by default.

Practical Examples

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