Custom Item Textures¶

Custom Item Textures can change items to different textures based on their properties, such as enchantments, name, or NBT rules.

_images/icon4.png

Amount changes the texture

Based on the configuration for MCPatcher's Custom Item Textures mod.

_images/settings3.png

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

Global properties¶

Location

/assets/minecraft/optifine/cit.properties

This file contains global properties for CIT and should be in the optifine/cit folder of the resource pack.

For individual item textures, see the "Properties" section.

Note

All property names are case-sensitive

All paths are relative to assets/minecraft/ unless otherwise specified

average and layered methods with cap=1 are equivalent and will both show only the "dominant" enchantment on an item

Warning

Not implemented: method , cap , fade

Key

Values

Meaning

method

average , layered , or cycle , optional

Specifies how to apply multiple effects on the same item.

Depending on the method chosen, multiple effects can be rendered with different intensities from 0 (not visible) to 1 (fully visible)

• average : Weighted average by enchantment level: intensity = enchantment_level / sum(enchantment_levels)

• layered : Similar to average , but max() is used instead of sum() : intensity = enchantment_level / max(enchantment_levels)

• cycle : Cycle through each effect in turn. The duration of each effect can be set via the duration property. The [group] value (if present) allows multiple sets of effects to be cycled through independently

cap

Positive integer, optional

Specifies how many layers can render for average and layered methods.

The top-most layers have priority over bottom-most layers as determined by the layer value of each effect.

fade

Positive float, optional

The speed at which one effect will transition into another in a cycle.

This does not affect the duration of the actual effect when displayed – for that use the effect's duration property.

Default is 0.5

useGlint

Boolean

Use default glint.png enchantment texture or not.

If true: glint.png is used if no other custom enchantment effect is available.

If false: the default glint.png enchantment stops rendering completely.

This is important for items that have no specific enchantment, but have an enchantment effect - such as potions and golden apples.

Default is true

Properties¶

Location

/assets/minecraft/optifine/cit/ANYNAME.properties

For each item to override with a custom texture, create a .properties file in the assets/minecraft/optifine/cit/ folder of the resource pack and write it's CIT. Properties files can be organized into subfolders of any depth, as long as everything is within the top-level optifine/cit folder.

Each properties file specifies:

  • a list of matching item IDs or names

  • a replacement texture

  • an optional set of rules specifying damage, stack size, NBT tags, etc.

Note

All property names are case-sensitive

All paths are relative to assets/minecraft/ unless otherwise specified

For best compability with tag matching, use escape sequences for characters outside the A to z range; \u0107 instead of ć

Key

Values

Meaning

Default

type

item , enchantment , armor , or elytra , optional

Type of texture replacement.

• item : Simple item texture replacement. Applies to items in GUI, held in hand, and in the world. If multiple properties files match the same item, only the first is used (sorted by weight, then by filename).

• enchantment : Overlay texture for enchantments (replaces misc/glint.png). If multiple properties files match the same item, they are blended together using rules specified in Global properties.

• armor : Armor texture replacement. Applies to armor models worn byplayers and mobs. If multiple properties files match the same item, only the first (sorted by weight, then by filename) is used.

• elytra : Elytra texture replacement. Applies to elytra model worn by players and mobs.If multiple properties files match the same item, only the first (sorted by weight, then by filename) is used

item

items

List of items, optional

List of item IDs to apply the replacement texture to

None

texture

String, path to texture, optional

Path to replacement texture. Can be a full path or just a name:

• mytextures/excalibur.png → mytextures/excalibur.png

• excalibur → optifine/cit/excalibur.png

Name of properties file, optifine/cit/excalibur.properties → optifine/cit/excalibur.png

model

String, path to texture, optional

Path to replacement model. Model must be in vanilla format.

• item/mymodel → /assets/minecraft/models/item/mymodel.json

• ./mymodel → mymodel.json from the same folder as the properties file

Model may reference textures from the same folder; for example ./mytexture

None

damage

Integer from 0 to 65535 , or integer range from 0 to 65535 , or percentage range, optional

Damage values, replacement texture is used only when the item damage is a certain value or range.

For items with durability, damage starts at 0 for a new item and increases as it gets damaged.

The maximum damage an item can take varies

For other items, damage represents different properties like potion type or wool color. See this page for specifics

None

damageMask

Integer bitmask, optional

Bitmask applied to the item's damage before checking it against the list of eligible damage values

Examples:

• Match any Fire Resistance potion: damage=3 damageMask=15

• Match any non-splash Fire Resistance potion: damage=3 damageMask=16399

• Match non-splash Fire Resistance I potion only: damage=3 damageMask=16447

• Match splash Fire Resistance II potion only: damage=16403 damageMask=16447

For a simpler way, see Potions

0

stackSize

Integer from 0 to 65535 , or integer range from 0 to 65535 , optional

Replacement texture is used only when the item's amount in an inventory slot is a certain value or range

0-65535

enchantments

List of strings, optional

List of enchantment names to match. The enchantment names may be short ( flame ) or full ( minecraft:flame )

For example: enchantments=minecraft:silk_touch sharpness smite .

If enchantmentLevels is not specified, matches any level

Any

enchantmentIDs

↑

Legacy property for enchantments

↑

enchantmentLevels

List of integers from 0 to 255 , optional

List of enchantment levels. - can be used as an equality, 3- matches 3 or higher, -5 matches 0 up to 5 .

For example: enchantmentLevels=1 3 5 10 , or enchantmentLevels=5- .

If enchantments is not specified, matches any enchantment type

Any

hand

any , main , or off , optional

Hand in which the item is placed onto (main hand, offhand). When rendered in the inventory GUI, the item is considered to be in the main hand

any

nbt.<tag>

Any value, optional

NBT-based rule. Replacement texture is used only when an NBT tag on the item has a specific value. See NBT rules.

None

Type-specific properties¶

Items¶

Key

Values

Meaning

Default

texture

String, path to texture

Item replacement textures are stitched into items.png , and thus follow the same rules as normal item textures. In particular, this means that animations must use Mojang's system of .mcmeta files for frame order and timing

None

texture.<name>

String, path to texture, optional

Replacement for alternate textures. For items with more than one texture, this allows specifying replacements for each texture separately.

For example: the vanilla bow has four possible textures depending on its' state: bow_standby , bow_pulling_0 , bow_pulling_1 , bow_pulling_2 .

To replace all four, this can be used:

texture.bow_standby=my_special_bow_standby

texture.bow_pulling_0=my_special_bow_pulling_0

texture.bow_pulling_1=my_special_bow_pulling_1

texture.bow_pulling_2=my_special_bow_pulling_2

Potions also have two textures. To replace them, use:

texture.potion_bottle_drinkable=... , or

texture.potion_bottle_splash=...

texture.potion_overlay=...

If no texture.<name> property matches, the generic texture property is used instead

None

model

String, path to texture, optional

Path to a JSON item model in vanilla format.

Can be a full path or just a name:

• item/mymodel → assets/minecraft/models/item/mymodel.json

• ./mymodel → mymodel.json from the same folder as the properties file

The model may reference textures from the same folder, for example: ./mytexture

None

model.<name>

String, path to texture, optional

Replacement for alternate models.

For items with more than one model, this allows specifying replacements for each model separately

For example: the vanilla bow has four possible textures depending on its' state: bow_standby , bow_pulling_0 , bow_pulling_1 , bow_pulling_2

To replace all four, this can be used:

model.bow_standby=my_special_bow_standby

model.bow_pulling_0=my_special_bow_pulling_0

model.bow_pulling_1=my_special_bow_pulling_1

model.bow_pulling_2=my_special_bow_pulling_2

None

weight

Positive integer, optional

If multiple properties files match the same item, the highest weighted one is used.

In the event of a tie, the properties filenames are compared next

0

Enchantments¶

Note

Implies type=enchantment

Note

duration only works for cycle enchantments

Key

Values

Meaning

Default

texture

String, path to texture

The enchantment texture can be any resolution.

To animate an enchantment, use the anim/*.properties method with to=full path to enchantment texture

None

blend

String, blend method, optional

Blend method when applying texture to the texture below it

See Custom Sky for a list of valid methods

add

speed

Positive integer, optional

Scrolling speed of texture

0 , no scrolling

rotation

Positive integer from 0 to 360 , optional

Angle of texture (in degrees) relative to the item

If speed is non-zero, the texture will also scroll in this direction

0

layer

Positive integer, optional

Specifies a unique layer and the ordering of the layers as they overlap each other.

If two or more effects use the same layer, weight determines which effect is rendered (the other is not rendered)

0 , bottom-most

weight

Positive integer, optional

Relative priority of the enchantment within a layer

Of the matching effects, only the highest weighted one within a layer is rendered.

In other words:

The layer property determines the ORDER in which effects are rendered

The weight property determines WHICH effect is rendered for each layer

If two effects have the same weight and layer, the filename is used as a tiebreaker

0

duration

Positive integer, optional

Duration in seconds of enchantment in a cycle

1

Armor¶

Key

Values

Meaning

Default

texture.<name>

String, path to texture, required

Replacement textures.

A replacement for each texture is needed in textures/models/armor for that armor type

For diamond armor (2 layers total):

texture.diamond_layer_1=my_diamond_armor_1

texture.diamond_layer_2=my_diamond_armor_2

For leather armor (4 layers total):

texture.leather_layer_1=my_leather_armor_1

texture.leather_layer_1_overlay=my_leather_armor_1_overlay

texture.leather_layer_2=my_leather_armor_2

texture.leather_layer_2_overlay=my_leather_armor_2_overlay

The texture should match the format of the corresponding armor texture.

For animated textures, use the anim/*.properties method with to

Generic texture

weight

Positive integer, optional

If multiple properties files match the same armor, the highest weighted one is used

In the event of a tie, the filenames are compared next

0

Potions¶

Note

While there is no specific potion-related tag, nbt can be used

Potions with custom effects can be matched using their NBT Potion string, or with nbt.CustomPotionEffects.*.Id .

                                    type                  =                  item                  items                  =                  potion                  nbt.Potion                  =                  minecraft:strength                

                                    type                  =                  item                  items                  =                  potion                  nbt.CustomPotionEffects.*.Id                  =                  20

Stronger versions of potions can be matched by prefixing strong_ to the Potion NBT tag match.

Longer versions of potions can be matched by prefixing long_ to the Potion NBT tag match.

Lingering and Splash potions can be matched with the same method by simply changing the items tag appropriately.

Shortcut¶

Note

Everything described here can be done via CIT properties files; this is a shortcut

Note

No properties files are necessary for this method

As an alternative to listing potion damage values, replacement textures for potions can be specified using a filename based system. See this page for the data-values.

There are three directories for potions:

  1. optifine/cit/potion/normal : drinkable potions

  2. optifine/cit/potion/splash : splash potions

  3. optifine/cit/potion/linger : lingering potions

Within any of these directories, create a PNG file with the name of the potion effect:

Note

Effect names in italic means they are obtainable in-game

Effects not in italic can only be created via commands

Important

This replaces both potion.png/potion_splash.png and potion_contents.png from the standard potion rendering

Warning

Be sure to include the colored liquid in the replacement textures

Effect name

File name

Absorption

absorption.png

Blindness

blindness.png

Confusion

confusion.png

Damage Boost

damageboost.png

Mining Fatigue

digslowdown.png

Haste

digspeed.png

Fire Resistance

fireresistance.png

Harming

harm.png

Healing

heal.png

Health Boost

healthboost.png

Hunger

hunger.png

Invisibility

invisibility.png

Leaping

jump.png

Slowness

moveslowdown.png

Speed

movespeed.png

Night Vision

nightvision.png

Poison

poison.png

Regeneration

regeneration.png

Resistance

resistance.png

Saturation

saturation.png

Water Breathing

waterbreathing.png

Weakness

weakness.png

Wither

wither.png

The names are the same as the potion. The replacement texture will automatically be used for that potion type; no properties file required. Note that this replaces both.

Similarly, textures can be replaced for the various "no effect" potions. These have drinkable versions only, the rest are in the code and are listed here only for completeness.

Note

Effect names in italic means they are obtainable in-game

Effects not in italic can only be created via commands

Effect name

File name

Artless

artless.png

Awkward

awkward.png

Bland

bland.png

Bulky

bulky.png

Bungling

bungling.png

Buttered

buttered.png

Charming

charming.png

Clear

clear.png

Cordial

cordial.png

Dashing

dashing.png

Debonair

debonair.png

Elegant

elegant.png

Fancy

fancy.png

Flat

flat.png

Foul

foul.png

Gross

gross.png

Harsh

harsh.png

Milky

milky.png

Mundane

mundane.png

Odorless

odorless.png

Potent

potent.png

Rank

rank.png

Sparkling

sparkling.png

Stinky

stinky.png

Suave

suave.png

Thick

thick.png

Thin

thin.png

Uninteresting

uninteresting.png

If a single texture for all "no effect" potions is preferred, optifine/cit/potion/normal/other.png is used as a fallback for any that do not have a specific replacement as listed above.

Two additional textures (drinkable only) can also be provided:

  • optifine/cit/potion/normal/water.png : water bottle

  • optifine/cit/potion/normal/empty.png : empty glass bottle

Examples¶

Stacked coins¶

                                    type                  =                  item                  items                  =                  iron_nugget                  stackSize                  =                  61-64                  texture                  =                  iron_coins_16

Splash potion¶

                                        type                    =                    item                    items                    =                    splash_potion                    model                    =                    item/fire_resistance_splash                    nbt.Potion                    =                    minecraft:fire_resistance                  

                                        {                    "parent"                    :                    "item/generated"                    ,                    "textures"                    :                    {                    "layer0"                    :                    "item/fire_resistance_overlay"                    ,                    "layer1"                    :                    "item/fire_resistance_splash"                    }                    }

🆚️ This documentation assumes the latest OptiFine version. Notes may be made for legacy versions (1.8), but there is no guarantee.

©️ This file is offered without any copyright restrictions. Please copy and modify it to suit your needs.