Wiki

Custom Item Textures

What CTM does for terrain, CIT offers for items. You can customize an item's appearance by damage value, stack size, and NBT data. Create different effects for different enchantments and customize armor models.

CIT behavior is defined in multiple properties files within the assets/minecraft/mcpatcher/cit folder. As with CTM, each file represents a single rule, and rules can be further organized into subfolders. Each properties file specifies a type (item, enchantment, or armor), one or more replacement textures, and criteria for when the replacement should happen based on item ID, damage, and other values.

An optional assets/minecraft/mcpatcher/cit.properties file specifies global behavior of CIT, particularly with how items with multiple custom enchantment effects are handled.

Properties file format (Template)

(Optional) Type of texture replacement

type=<item | enchantment | armor>

item: Replace the base assets/minecraft/textures/items texture. See CIT Item Replacements.
enchantment: Replace the generic enchanted_item_glint.png texture. See CIT Enchantments.
armor: Replace the default assets/minecraft/textures/models/armor texture. See CIT Armor.

The default type is item. Each type has properties specific to it detailed in the pages above. Properties common to all types are described below.

(Optional) Replacement texture(s)

texture=<replacement texture>

The path to the replacement texture. The .png suffix is optional.

In most cases a single replacement texture is all you need, but some items have multiple textures. For example, bows have four, a default texture and three stages of "pulling" animation. Potions and leather armor have two textures layered on top of one another. For these cases, there is an alternative syntax to specify multiple replacements in the same file.

texture.<original texture 1>=<replacement texture 1>
texture.<original texture 2>=<replacement texture 2>
...

An example using the bow textures,

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

The two methods can be mixed: If no texture.<name> property matches, the generic texture property is used instead.

If no texture properties are provided, MCPatcher will use the name of the properties file itself, e.g., excalibur.properties -> excalibur.png

(Required if `type=item` or `type=armor`) List of matching items

Apply the replacement only to the listed items.

items=<list of items>

See About Properties Files for the proper way to refer to items.

(Optional) Damage values

damage=<damage values 0-65535>

Use the replacement texture only when the item damage is a certain value or range. Open-ended ranges are acceptable:

# Match if damage >= 100
damage=100-
# Match if damage <= 99
damage=-99

For items with durability, damage starts at 0 for a new item and increases as it gets damaged. The max damage an item can take varies, see Item durability on Minecraft wiki.

Damage can also be given as a percentage:

# Match if item is < 50% damaged
damage=0-50%

The two formats (percentage and absolute) cannot be combined.

(Optional) Stack size.

stackSize=<stack sizes 0-65535>

Use the replacement texture only when the stack size is a certain value or range. Again, open-ended ranges are acceptable:

(Optional) Enchantment IDs and/or levels (See list)

enchantmentIDs=<enchantment IDs 0-255>
enchantmentLevels=<enchantment levels 0-255>

Match a list of enchantments and/or enchantment levels. While this is normally used with type=enchantment, it can be used with the other types too to give an item a different base texture when it has certain enchantments.

Examples,

# Match Silk Touch, any level:
enchantmentIDs=33
# Match Flame or Fire Aspect, level 3 or higher:
enchantmentIDs=20 50
enchantmentLevels=3-
# Match any enchantment, with 8-10 total levels across all enchantments:
enchantmentLevels=8-10

(Optional) NBT-based rules

nbt.<tag>=<value>

Use the replacement texture only when an NBT tag has a specific value. If multiple rules are provided, all of them must match. Use a utility like NBTExplorer to view the NBT tags for various items.

Currently, only the following NBT types are supported:

String, Integer, Short, Long, Double, Float - match exact value only
Compound - Can match a specific tag or any tag (*).
List - Can match a specific index (starting at 0) or any index (*).

Examples,

# Match item display name:
nbt.display.Name=My Sword
# Match item display name with special formatting:
# NOTE: For best compatibility, use the escape sequence '\u00a7' instead of §:
nbt.display.Name=\u00a74\u00a7oMy Sword
# Match item lore (first line only):
nbt.display.Lore.0=My Lore Text
# Match item lore (any line):
nbt.display.Lore.*=My Lore Text

Strings can also be matched by wildcard and regular expression.

# Wildcards using ? and *
nbt.display.Name=pattern:Letter to *

Matches Letter to Herobrine, Letter to a creeper, but not letter to herobrine.

# Wildcards, case-insensitive
nbt.display.Name=ipattern:Letter to *

Matches Letter to Herobrine, Letter to a creeper, letter to herobrine.

# Regular expressions
nbt.display.Name=regex:Letter (to|from) .*

Matches Letter to Herobrine, Letter from Herobrine, but not letter to Herobrine or A Letter to Herobrine.

# Regular expressions
nbt.display.Name=iregex:Letter (to|from) .*

Matches Letter to Herobrine, Letter from Herobrine, letter to Herobrine, but not A Letter to Herobrine.

Any backslashes to the right of the = must be doubled. Literal backslashes within a regular expression or wildcard must be quadrupled.

# Correct:
nbt.display.name=regex:\\d+
nbt.display.name=regex:\\\\
nbt.display.name=/\\/\\
# Wrong:
nbt.display.name=regex:\d+
nbt.display.name=regex:\\
nbt.display.name=/\/\