Creating Cursor Textures

Requirements:

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

Recommendations:

• Use 1x scale for best resolution and accuracy, and dimensions in powers of two (16x16, 32x32, 64x64, etc.).
• Use 0x scale for GUI scale.
• Other scale values should be configured on a per-user basis.

Animated Textures

1. In a single image, stack multiple textures vertically from top to bottom to create frames.
   • All frames must have the same size. Refer to the requirements above.
   • The topmost frame will be used when the animation is disabled.
2. Create a cursor settings file in the same directory as the image.
   • For example, if creating an animated texture for the default cursor, you will need the default.png and default.png.json.
3. Add the animation property to the cursor settings file. Without it, the whole image will be read as a single cursor texture.

cursor-name.png.json

{
 "animation": {}
}

Cursor Settings

Specifies the default cursor settings and may also include animation properties. This file is optional; if omitted, the default or inherited 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.
height	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 frame duration in ticks. Min value: 1.
frames	Array	null	Determines which frames to play in the specified order and in the specified duration. If undefined, all frames will be played from top to bottom of the image. Array elements can either be an int or a Frame object. int The frame's index (or position) in the image. Starts from 0. Frame Key Type Description index * int Required. The frame's index (or position) in the image. Starts from 0. time * int Required. The frame duration in ticks. Min value: 1.

Example

Suppose we have an animated texture for the default cursor. It has four frames, each with a different color:

1. Frame 0 is Red.
2. Frame 1 is Orange.
3. Frame 2 is Yellow.
4. Frame 3 is Green.

default.png

Next we add the following cursor settings. Note the line numbers.

default.png.json

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

With these settings, our animated texture will play in this order:

1. Green for 2 ticks.
   • line #6 specifies frame 3 (or green) as the first frame to play.
   • line #4 specifies the frame duration as 2 ticks.
2. Orange for 4 ticks.
   • line #7 specifies frame 1 (or orange) as the next frame and should play for 4 ticks instead of 2 from line #4.
3. Red for 2 ticks.
   • line #8 specifies frame 0 (or red) as the last frame
   • line #4 specifies the frame duration as 2 ticks.
4. Repeat.
   • line #3 specifies the animation mode as "loop"

• Yellow is never played since it's not included in frames.

Most of the animation settings are optional, so lets remove everything but the frametime:

default.png.json

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

Now the animated texture will loop and play all frames in the natural order in 2 ticks per frame.

1. Red for 2 ticks.
2. Orange for 2 ticks.
3. Yellow for 2 ticks.
4. Green for 2 ticks.
5. Repeat
   • "loop" is the default animation mode.

Practical Examples

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

You may also view the community-made resource packs here.