Custom GUIs

_images/icon7.webp

Custom Shulker box GUI

File location

/assets/minecraft/optifine/gui/container/*.properties

Custom GUIs can define a texture for each GUI, and apply them based on different criteria, such as the entity, biome, height, and more.

For each container GUI texture to override, create a .properties file in the /assets/minecraft/optifine/gui/container folder of the resource pack. Properties files can be organized into subfolders of any depth, as long as everything is within the top-level /assets/minecraft/optifine/gui/container folder.

_images/settings6.webp

Button and tooltip for the option, found in Video Settings ‣ Quality.

Important

Different container types have different requirements and restrictions.

General properties

container

Values: anvil, beacon, brewing_stand, chest, crafting, dispenser, enchantment, furnace, hopper, horse, villager, shulker_box, creative, or inventory
Required
Default: None

Type of container GUI to apply to.

  • creative refers to the creative inventory with the tabs.

  • inventory refers to the normal survival inventory, with the player in a window.

texture, texture.PATH

Values: String: File path
Required
Default: None

The replacing texture for the GUI.

The texture property replaces the default GUI texture. The texture.PATH property can be used to replace any GUI texture; PATH is relative to /assets/minecraft/textures/gui.

Important

The creative inventory GUI does not have a default texture, so it must use PATH textures.

Example for creative inventory:

/assets/minecraft/optifine/gui/container/creative/creative_desert.properties
container=creative
biomes=desert
texture.container/creative_inventory/tab_inventory=tab_inventory_desert
texture.container/creative_inventory/tabs=tabs_desert
texture.container/creative_inventory/tab_items=tab_items_desert
texture.container/creative_inventory/tab_item_search=tab_item_search_desert

Important

At least one texture or texture.PATH is required.

name

Values: String
Optional
Default: None

Custom entity or block entity name.

This will apply the replacement GUI only when the container matches this rule.

See Regular expressions for details.

biomes

Values: List of biomes
Optional
Default: None

Biomes where this replacement applies.

Biomes added by mods can also be used with the same syntax.

heights

Values: Integer, or range of integers
Optional
Default: None

Heights where this replacement applies.

Since 1.18, negative values may be specified for height. When used in a range they must be put in parenthesis: (-3)-64.

Specific properties

These additional properties do not need any separate files. They are just properties that apply only when container equals their required value.

Chests

Note

Implies container=chest.

large

Values: Boolean
Optional

Whether to use the replacement GUI on a large (double) chest.

trapped

Values: Boolean
Optional

Whether to use the replacement GUI on a trapped chest.

christmas

Values: Boolean
Optional

Whether to use the replacement GUI on any Christmas chest. Christmas chests appear from December 24 to 26 of any year.

ender

Values: Boolean
Optional

Whether to use the replacement GUI on an Ender Chest.

Beacons

Note

Implies container=beacon.

levels

Values: Integer, or range of integers.
Optional
Default: None

What levels of beacon power to apply the replacement to; how many bases of blocks.

_images/beacon_pyramid.webp

The levels from left to right: 4, 3, 2, 1.

Villagers

Note

Implies container=villager.

professions

Values: none, armorer, butcher, cartographer, cleric, farmer, fisherman, fletcher, leatherworker, librarian, mason, nitwit, shepherd, toolsmith, or weaponsmith, along with an optional level experience format
Optional

List of villager professions with an optional level specifier.

Entry format: <profession>[:level1,level2,...]

Examples:

  • Professions farmer (all levels) or librarian (levels 1,3,4): professions=farmer librarian:1,3-4

  • Professions fisher, shepard, nitwit: professions=fisherman shepherd nitwit

Horse

Note

Implies container=horse.

variants

Values: horse, donkey, mule, llama
Optional

What specific horse type to apply replacement to.

Dispenser, dropper

Note

Implies container=dispenser. Dropper applies as well.

variants

Values: dispenser or dropper
Optional
Default: dispenser

What specific block to apply the replacement GUI to.

Llama, shulker box

Note

Implies container=shulker_box or container=horse.

Important

Despite the container being horse, this property will apply to Llamas instead.

colors

Values: white, orange, magenta, light_blue, yellow, lime, pink, gray, light_gray, cyan, purple, blue, brown, green, red, black
Optional

Shulker box color or llama carpet color to apply the replacement texture to.

JSON schema

Note

Although this page is .properties based, it can be mapped to JSON.

{
	"$schema": "http://json-schema.org/draft/2020-12/schema",
	"$id": "https://gitlab.com/whoatemybutter/optifinedocs/-/blob/master/schemas/custom_guis.schema.json",
	"title": "Custom GUIs",
	"description": "Custom GUIs can define a texture for each GUI, and apply them based on different criteria, such as the entity, biome, height, and more.",
	"type": "object",
	"properties": {
		"container": {
			"enum": [
				"anvil",
				"beacon",
				"brewing_stand",
				"chest",
				"crafting",
				"dispenser",
				"enchantment",
				"furnace",
				"hopper",
				"horse",
				"villager",
				"shulker_box",
				"creative",
				"inventory"
			],
			"description": "Type of container GUI to apply to."
		},
		"texture": {
			"$ref": "common.schema.json#/$defs/resource",
			"description": "The replacing texture for the GUI."
		},
		"name": {
			"type": "string",
			"description": "Custom entity or block entity name."
		},
		"biomes": {
			"type": "string",
			"description": "Space-separated string of biomes where this replacement applies."
		},
		"heights": {
			"type": [
				"string",
				"integer"
			],
			"description": "Heights where this replacement applies."
		}
	},
	"patternProperties": {
		"^texture\\.[/0-9a-z._]+$": {
			"$ref": "common.schema.json#/$defs/resource",
			"description": "The replacing texture for the GUI."
		}
	},
	"allOf": [
		{
			"if": {
				"properties": {
					"container": {
						"const": "chest"
					}
				}
			},
			"then": {
				"properties": {
					"large": {
						"type": "boolean",
						"description": "Whether to use the replacement GUI on a large chest."
					},
					"trapped": {
						"type": "boolean",
						"description": "Whether to use the replacement GUI on a trapped chest."
					},
					"christmas": {
						"type": "boolean",
						"description": "Whether to use the replacement GUI on any Christmas chest."
					},
					"ender": {
						"type": "boolean",
						"description": "Whether to use the replacement GUI on an Ender Chest."
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"container": {
						"const": "beacon"
					}
				}
			},
			"then": {
				"properties": {
					"levels": {
						"type": [
							"string",
							"integer"
						],
						"minimum": 1,
						"maximum": 4,
						"description": "What levels of beacon power to apply the replacement to; how many bases of blocks."
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"container": {
						"const": "villager"
					}
				}
			},
			"then": {
				"properties": {
					"professions": {
						"type": "string",
						"pattern": "(none|armorer|butcher|cartographer|cleric|farmer|fisherman|fletcher|leatherworker|librarian|mason|nitwit|shepherd|toolsmith|weaponsmith)(:\\d+(-\\d+)?(,\\d+(-\\d+)?)*)",
						"description": "Space-separated string of villager professions with an optional level specifier."
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"container": {
						"const": "horse"
					}
				}
			},
			"then": {
				"properties": {
					"variants": {
						"enum": [
							"horse",
							"donkey",
							"mule",
							"llama"
						],
						"description": "What specific horse type to apply replacement to."
					},
					"colors": {
						"enum": [
							"white",
							"orange",
							"magenta",
							"light_blue",
							"yellow",
							"lime",
							"pink",
							"gray",
							"light_gray",
							"cyan",
							"purple",
							"blue",
							"brown",
							"green",
							"red",
							"black"
						],
						"description": "Llama carpet color to apply the replacement texture to."
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"container": {
						"const": "dispenser"
					}
				}
			},
			"then": {
				"properties": {
					"variants": {
						"enum": [
							"dispenser",
							"dropper"
						],
						"default": "dispenser",
						"description": "What specific block to apply the replacement GUI to."
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"container": {
						"const": "shulker_box"
					}
				}
			},
			"then": {
				"properties": {
					"colors": {
						"enum": [
							"white",
							"orange",
							"magenta",
							"light_blue",
							"yellow",
							"lime",
							"pink",
							"gray",
							"light_gray",
							"cyan",
							"purple",
							"blue",
							"brown",
							"green",
							"red",
							"black"
						],
						"description": "Shulker box color to apply the replacement texture to."
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"colors": {}
				}
			},
			"then": {
				"properties": {
					"variants": {
						"enum": [
							"shulker_box",
							"llama"
						]
					}
				},
				"required": [
					"colors"
				]
			}
		}
	],
	"required": [
		"container"
	],
	"additionalProperties": false
}

Assumes the latest OptiFine version.
Updated to commit 15ef3106.

Last update: 2024 June 12