Skip to content

Replacing GUI textures

This page describes the usage of OptiGUI 2.1.0-beta.1+ INI files. The OptiFine custom GUI documentation is available here.

This page assumes you to be familiar with the OptiGUI syntax.

Warning

OptiGUI 2.1.0-beta.1 removed all OptiFine extensions from OptiFine files: _cartography_table, _chest_boat, _grindstone, _loom, _smithing_table, _stonecutter, _barrel, _minecart, _furnace, _blast, _blast_furnace, _smoker, _camel, _zombie_horse, _skeleton_horse, _wandering_trader.

See the migration guide to learn how to convert your resource pack.

You can define a texture replacement for each inventory GUI, and apply them based on different criteria.

For each container GUI texture to replace, create a .ini file in /assets/optigui/gui/ folder (or any of its subfolders in any depth) of the resource pack.

Note

When specifying texture paths, do not forget file extensions, otherwise OptiGUI will not find the resources!

Special selectors

These are not real selectors used for selecting entities and block entities, just have the same syntax. OptiGUI processes these specially when loading the resource.

replacement

Required OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Path to the replacement texture for the default GUI texture of the container. This is not really a selector, as it is not used to match against an interaction, but specifies the replacement if all other selectors match.

load.priority

Optional OptiGUI 2.2.0-alpha.1+ Minecraft 1.18+

A single integer (not range) specifying the load priority of the group. Default load priority is 0. Higher load priority means earlier processing while evaluating the loaded filters.

Interaction selectors

interaction.texture

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Path to the texture to replace (the default texture of the container). When left empty, OptiGUI looks up the default texture of the specified containers.

interaction.hand

Optional OptiGUI 2.2.0-alpha.1+ Minecraft 1.18+

The hand the player started the interaction with. Possible values:

  • main_hand
  • off_hand

interaction.screen_title

Upcoming

Common selectors

name

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A String specifying the exact value of the name of the entity or block entity.

name.wildcard

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A String specifying the case-sensitive wildcard to match against the name of the entity or block entity.

name.wildcard.ignore_case

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A String specifying the case-insensitive wildcard to match against the name of the entity or block entity.

name.regex

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A String specifying the case-sensitive regex to match against the name of the entity or block entity.

name.regex.ignore_case

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A String specifying the case-insensitive regex to match against the name of the entity or block entity.

biomes

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A list of biome identifiers specifying the biomes of the entity or block entity where this replacement applies.

heights

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A list of integers and ranges specifying the heights (Y coordiantes) of the entity or block entity, where this replacement applies.

Independent selectors

date

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A list of dates specifying when the texture should be replaced.

Player selectors

player.name

Optional OptiGUI 2.3.0-beta.3+ Minecraft 1.18+

A String specifying the exact value of the name of the entity or block entity.

player.name.wildcard

Optional OptiGUI 2.3.0-beta.3+ Minecraft 1.18+

A String specifying the case-sensitive wildcard to match against the name of the entity or block entity.

player.name.wildcard.ignore_case

Optional OptiGUI 2.3.0-beta.3+ Minecraft 1.18+

A String specifying the case-insensitive wildcard to match against the name of the entity or block entity.

player.name.regex

Optional OptiGUI 2.3.0-beta.3+ Minecraft 1.18+

A String specifying the case-sensitive regex to match against the name of the entity or block entity.

player.name.regex.ignore_case

Optional OptiGUI 2.3.0-beta.3+ Minecraft 1.18+

A String specifying the case-insensitive regex to match against the name of the entity or block entity.

player.biomes

Optional OptiGUI 2.3.0-beta.3+ Minecraft 1.18+

A list of biome identifiers specifying the biomes of the entity or block entity where this replacement applies.

player.heights

Optional OptiGUI 2.3.0-beta.3+ Minecraft 1.18+

A list of integers and ranges specifying the heights (Y coordiantes) of the entity or block entity, where this replacemen

Comparator selectors

comparator.output

Optional OptiGUI 2.1.3+ Minecraft 1.18+

A list of integers and ranges specifying the redstone comparator output of the entity or block entity, where this replacement applies.

Anvil

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/anvil.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[anvil chipped_anvil damaged_anvil]

Barrel

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/generic_54.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[barrel]

Beacon

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/beacon.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[beacon]
beacon.levels = 1 3-5

beacon.levels

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A list of integers and ranges specifying the levels of beacon power to apply to (how many bases of blocks).

Book

OptiGUI 2.1.3+ Minecraft 1.18+

Texture path: minecraft:textures/gui/book.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[written_book]
book.page.current = 1 3-4
book.page.count = 5 10-15

book.page.current

Optional OptiGUI 2.1.3+ Minecraft 1.18+

A list of integers and ranges specifying the the current page of the book, where this replacement applies.

book.page.count

Optional OptiGUI 2.1.3+ Minecraft 1.18+

A list of integers and ranges specifying the the page count of the book, where this replacement applies.

Book and Quill

OptiGUI 2.1.3+ Minecraft 1.18+

Texture path: minecraft:textures/gui/book.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, book selectors

Example

[writable_book]

Brewing stand

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/brewing_stand.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[brewing_stand]

Cartography table

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/cartography_table.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[cartography_tabe]

Chest

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/generic_54.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[chest]
chest.large = true

chest.large

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A single boolean specifying if the texture of a double chest should be replaced.

Trapped chest

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/generic_54.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors, chest selectors

Example

[trapped_chest]
chest.large = true

Ender chest

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/generic_54.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[ender_chest]

Chest boats

OptiGUI 2.1.0-beta.1+ Minecraft 1.19+

Texture path: minecraft:textures/gui/container/generic_54.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[chest_boat]
chest_boat.variants = oak spruce

chest_boat.variants

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.19-1.21.1 Removed in Minecraft 1.21.2

Warning

Entity minecraft:chest_boat was split in snapshot 24w39a. Use the new entity IDs instead of this selector. Use conditional loading to support multiple versions of the game.

A list of strings specifying the wood type of the chest boat. Possible values:

  • acacia
  • bamboo Minecraft 1.20+ Minecraft 1.19.3+ with 1.20 experiments
  • birch
  • cherry Minecraft 1.20+ Minecraft 1.19.4+ with 1.20 experiments
  • dark_oak
  • jungle
  • mangrove
  • oak
  • spruce

Chest minecart

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: mniecraft:textures/gui/container/generic_54.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[chest_minecart]

Crafting table

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/crafting_table.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[crafting_table]

Dispenser

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/dispenser.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[dispenser]

Dropper

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/dispenser.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[dropper]

Enchanting table

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/enchanting_table.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[enchanting_table]

Furnace

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/furnace.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[furnace]

Blast furnace

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/blast_furnace.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[blast_furnace]

Smoker

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/smoker.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[smoker]

Grindstone

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/grindstone.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[grindstone]

Hopper

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/hopper.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[hopper]

Hopper minecart

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/hopper.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[hopper_minecart]

Horse

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/horse.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, donkey selectors

Example

[horse]

horse.has_saddle

Optional OptiGUI 2.2.0-alpha.1 Minecraft 1.18+

A single boolean specifying if the entity needs to be or not be saddled.

horse.variants

Optional OptiGUI 2.2.0-alpha.1+ Minecraft 1.18+

A list of strings specifying the horse's variant. Possible values:

  • black
  • brown
  • chestnut
  • creamy
  • dark_brown
  • gray
  • white

horse.markings

Optional OptiGUI 2.2.0-alpha.1+ Minecraft 1.18+

A list of strings specifying the marking on a horse. Possible values:

  • black_dots
  • none
  • white
  • white_dots
  • white_field

Donkey

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/horse.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, horse.has_saddle

Example

[donkey]

donkey.has_chest

Optional OptiGUI 2.1.3+ Minecraft 1.18+

A single boolean specifying if the entity needs to have or not have a chest.

Mule

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/horse.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, donkey selectors

Example

[mule]

Llama

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/horse.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, donkey selectors

Example

[llama trader_llama]
llama.colors = red green blue

llama.colors

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A list of strings specifying the llama's carpet color. Possible values:

  • white
  • orange
  • magenta
  • light_blue
  • yellow
  • lime
  • pink
  • gray
  • light_gray
  • cyan
  • purple
  • blue
  • brown
  • green
  • red
  • black

llama.variants

Optional OptiGUI 2.2.0-alpha.1+ Minecraft 1.18+

A list of strings specifying the llama's variant. Possible values:

  • brown
  • creamy
  • gray
  • white

Trader llama

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/horse.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, donkey selectors, llama selectors

Example

[llama trader_llama]
llama.colors = red green blue

Skeleton horse

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/horse.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[skeleton_horse]

Zombie horse

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/horse.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[zombie_horse]

Camel

OptiGUI 2.1.0-beta.1+ Minecraft 1.20+ Minecraft 1.19.3+ with 1.20 experiments

Texture path: minecraft:textures/gui/container/horse.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, horse.has_saddle

Example

[camel]

Lectern

OptiGUI 2.1.0+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/horse.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors, book selectors

Example

[lectern]

Loom

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/loom.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[loom]

Shulker boxes

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/shulker_box.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors, comparator selectors

Example

[shulker_box]
[white_shulker_box]
[orange_shulker_box]
[magenta_shulker_box]
[light_blue_shulker_box]
[yellow_shulker_box]
[lime_shulker_box]
[pink_shulker_box]
[gray_shulker_box]
[light_gray_shulker_box]
[cyan_shulker_box]
[purple_shulker_box]
[blue_shulker_box]
[brown_shulker_box]
[green_shulker_box]
[red_shulker_box]
[black_shulker_box]

Sign

Not supported

Sign edit GUI renders a block model of the sign block, it doesn't have a texture.

Hanging sign

OptiGUI 2.1.3+ Minecraft 1.20+ Minecraft 1.19.3+ with 1.20 experiments

Texture path: minecraft:textures/gui/hanging_signs/*.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[acacia_hanging_sign acacia_wall_hanging_sign]
[bamboo_hanging_sign bamboo_wall_hanging_sign]
[birch_hanging_sign birch_wall_hanging_sign]
[cherry_hanging_sign cherry_wall_hanging_sign]
[crimson_hanging_sign crimson_wall_hanging_sign]
[dark_oak_hanging_sign dark_oak_wall_hanging_sign]
[jungle_hanging_sign jungle_wall_hanging_sign]
[mangrove_hanging_sign mangrove_wall_hanging_sign]
[oak_hanging_sign oak_wall_hanging_sign]
[spruce_hanging_sign spruce_wall_hanging_sign]
[warped_hanging_sign warped_wall_hanging_sign]

Smithing table

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/smithing.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[smithing_table]

Stonecutter

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/stonecutter.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[stonecutter]

Villagers

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/villager2.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[villager]

villager.professions

Optional OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

A list of professions specifying villager professions with optional levels.

Cleric (any levels) or fisherman (any levels)

[villager]
villager.professions = cleric minecraft:fisherman

Fletcher (levels 1, 3, 4)

[villager]
villager.professions = fletcher@1 minecraft:fletcher@3-4

Vanilla professions

  • armorer
  • butcher
  • cartographer
  • cleric
  • farmer
  • fisherman
  • fletcher
  • leatherworker
  • librarian
  • mason
  • nitwit
  • shepherd
  • toolsmith
  • weaponsmith

Tip

OptiGUI supports professions from other mods, if prefixed with a namespace.

villager.type

Optional OptiGUI 2.1.3+ Minecraft 1.18+

A list of strings specifying villager types (which biome was it born in). This is how its clothing looks like. Possible values:

  • desert
  • jungle
  • plains
  • savanna
  • snow
  • swamp
  • taiga

Wandering trader

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/villager2.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Example

[wandering_trader]

Survival inventory

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Texture path: minecraft:textures/gui/container/inventory.png

Supports the following additional selectors: common selectors, interaction selectors, independent selectors

Note

Common selectors apply to the player instead of the interacted container, because there is no interaction with another entity or block entity.

Example

[player]
interaction.texture = minecraft:textures/gui/container/inventory.png

Creative inventory & everything else

OptiGUI 2.1.0-beta.1+ Minecraft 1.18+

Note

GUIs not having a default texture must to be fitered with interaction.texture.

Example for creative inventory

This is the equivalent syntax of OptiFine's texture.PATH example in the table. In /assets/optigui/gui/creative_desert.ini:

[player #1]
biomes = desert
interaction.texture = minecraft:textures/gui/container/creative_inventory/tab_inventory.png
replacement = tab_inventory_desert.png

[player #2]
biomes = desert
interaction.texture = minecraft:textures/gui/container/creative_inventory/tabs.png
replacement = tabs_desert.png

[player #3]
biomes = desert
interaction.texture = minecraft:textures/gui/container/creative_inventory/tab_items.png
replacement = tab_items_desert.png

[player #4]
biomes = desert
interaction.texture = minecraft:textures/gui/container/creative_inventory/tab_item_search.png
replacement = tab_item_search_desert.png