Custom Item Textures

Global Properties

File 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: Average and layered methods with cap=1 are equivalent and will both show only the first enchantment on an item.

Danger: Not implemented: method, cap, fade.

method

• Values: average, layered, or cycle
• Optional
• Default: average
• Specifies how to apply multiple effects to the same item. Depending on the method chosen, multiple effects can be rendered with different intensities from 0 (invisible) 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

• Values: Positive integer
• Optional
• Specifies how many layers can be rendered for average and layered methods. The top-most layers have priority over the bottom-most layers, as determined by the layer value of each effect.

fade

• Values: Positive float
• Optional
• Default: 0.5
• 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.

useGlint

• Values: Boolean
• Optional
• Default: true
• Whether to use the 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.

Danger: This has been broken since 1.12. See GH-6480.

Properties

File Location

/assets/minecraft/optifine/cit/**/*.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. 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 items.
• A replacement texture or model.
• An optional set of rules specifying when this CIT will apply to the item.

Note: For best compatibility with tag matching, use escape sequences for characters outside the ASCII range: \u0107 instead of ć. These properties apply to all CIT types.

type

• Values: item, enchantment, armor, or elytra
• Optional
• Default: item
• Type of texture replacement.
• item: Simple item texture replacement. It applies to items in the GUI, held in hand, and in the world. If multiple CIT rules match the same item, only the first is used (sorted by weight, then by file name).
• enchantment
• armor
• elytra

items

• Values: List of items
• Optional
• What items to apply the CIT to. If more than 1 item is specified, the CIT will apply to any item in the list.

texture

• Values: String: File path
• Optional
• Default: Name of properties file: x.properties -> x.png
• Path to the replacement texture.
• It can be a full path or a lone name:
• mytextures/excalibur.png -> mytextures/excalibur.png
• excalibur -> optifine/cit/excalibur.png

model

• Values: String: File path
• Optional
• Path to the replacement model. The 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

Note: The model may reference textures from the same folder as where the originating CIT file is.

damage

• Values: Integer from 0 to 65535, integer Range from 0 to 65535, or percentage range
• Optional
• Damage values. CIT will apply 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. A brand-new item's damage will always be 0. The maximum damage an item can take varies.
• For 1.12 and below, damage represents different properties like potion type. See this page for specifics.

damageMask

• Values: Integer bitmask
• Optional
• Default: 0
• A 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

Note: For a simpler way, see Potions.

Danger: This is an extremely unreliable and largely-unused method of checking properties. Do not use it.

stackSize

• Values: Integer from 0 to 65535, or integer Range from 0 to 65535
• Optional
• Default: 0-65535
• The required amount(s) of item that must be in an inventory slot.
• Although the maximum legitimate amount is 64, values up to 65535 are allowed.

Note: Values above 64 are useless.

enchantments

• Values: List of strings
• Optional
• Default: Any
• List of enchantment names to match.
• The enchantment names may be short (flame) or in full (minecraft:flame). For example: enchantments=minecraft:silk_touch sharpness smite.

Note: If the enchantmentLevels rule is not specified, this rule matches any enchantment level.

enchantmentIDs

• Legacy
• Alias to enchantments.

enchantmentLevels

• Values: List of integers from 0 to 255
• Optional
• Default: Any
• List of enchantment levels.
• Also allows ranges. For example: enchantmentLevels=1 3 5 10, or enchantmentLevels=5-.

Note: If enchantments is not specified, this rule matches any enchantment type.

hand

• Values: any, main, or off
• Optional
• Default: any
• Hand on which the item is placed onto: main hand or off-hand.
• When rendered in the inventory GUI, the item is considered to be in the main hand.

Note: CIT can apply conditionally if you're holding the item in the left or right hand.

nbt

• Values: Any valid NBT matching rule
• Optional
• NBT-based rule.
• Replacement texture is used only when an NBT tag on the item has a specific value. See NBT. You can have infinitely many NBT rules in a CIT.

Type-Specific Properties

Items

Note: Implies type=item.

texture

• Values: String: File path
• Required
• Replacement texture.
• Animations must use Mojang's system of .mcmeta files for frame order and timing.

texture.<name>

• Values: String: File path
• Optional
• Replacement for alternate textures.
• For items with more than one texture, this allows specifying replacements for each texture separately. These textures depend on the item's model. For example, the bow has four possible textures depending on its state: bow_standby, bow_pulling_0, bow_pulling_1, or bow_pulling_2.

To replace all four: properties 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:

properties

Copy code

texture.potion_overlay=... texture.potion_bottle=...

Note: The special textures must be exactly named to match the item textures in Minecraft.

Enchantments

Note: Implies type=enchantment.

texture

• Values: String: File path
• Required
• Texture for the enchantment.

Armor

Note: Implies type=armor.

model

• Values: String: File path
• Required
• Model path for the armor piece.

texture

• Values: String: File path
• Optional
• Texture path for the armor piece. Typically not used with models.

Elytra

Note: Implies type=elytra.

model

• Values: String: File path
• Required
• Model path for the Elytra wings.

Note: For Elytra, textures cannot be directly replaced like with other items. Use models for complete replacements.