Syntax¶

The syntax describes how OptiFine's resource pack features will behave and operate.

Different formats and types of values are used within files used by OptiFine-specific features. Rather than describe these common types separately in each feature's section, they are summarized here instead.

File structure¶

Many OptiFine features use properties files to control how OptiFine-specific elements will work within a resource pack.

Properties files are simple text files similar to the Windows INI format. Each line is a property, specified as name=value.

# Comments begin with a hashtag and are ignored.
property1=value
property2=some_other_value

# Blank lines are allowed.
property3=yet_another_value

All property names are case-sensitive; renderpass is not the same as renderPass. The order of properties within the file does not matter. Many properties have default values and can be omitted, and in some cases, the entire properties file is optional.

Paths, file locations¶

Often, OptiFine requires specifying a path to a texture or other file within the resource pack. A path is a "location" of where a file is.

All paths must match the regex ^[a-z0-9_.\/-]+$ (Test this pattern on Regex101).

The folder structure within a resource pack is deeply nested, so OptiFine has some shortcuts to make paths easier to write. Any of these options can be used to specify the same path.

Always use the forward slash "/" to separate folders.

The below table summarizes path shortcuts:

texture=texture.png
# Resolves to /assets/minecraft/optifine/texture.png

texture=./texture.png
texture=./subdirectory/texture.png

texture=~/texture.png
texture=~/subfolder/texture.png

texture=minecraft:textures/entity/creeper/creeper.png

texture=MODID:subfolder/texture.png

Biomes¶

For features that call for a list of biomes, use this page. Biomes added by mods can also be used.

biomes=ocean deep_ocean river beach modid:biome

Components, NBT¶

OptiFine supports conditions based on an item's data. These are most often used in Custom Item Textures.

Components are the newest format, added in Minecraft 1.20.5. Prior to this, the format was NBT.

For general behavior that applies to both components and NBT, this documentation uses the name "data rules" to refer to both format types.

Entities (such as Random Entities) still use the NBT format.

General behavior¶

If multiple data rules are provided, all of them must match.

A value starting with an exclamation mark "!" negates the match (match the opposite of this). Multiple exclamations do nothing; !!0 is not equivalent to 0.

Component format¶

Components are specified as keys with the components. syntax.

Components may include a namespace. To specify a namespace, the first : must be escaped - prefixed with a backslash \\. If no namespace is specified, it defaults to minecraft:.

Components and component keys that use the minecraft: namespace can be shortened with a tilde (~) instead. For example, components.enchantments.levels.~thorns becomes components.minecraft\:enchantments.levels.minecraft\:thorns.

NBT format¶

NBT are specified as keys with the nbt. syntax.

For older versions of Minecraft and for entities, the NBT format is used instead of the Component format.

Types¶

Strings¶

A string is text, optionally wrapped in double- or single-quotes " '.

If a strings contains only the characters 0-9 A-Z a-z _ - . +, it does not need to be wrapped in quotes. You can test this on Regex101.

All characters can be escaped with the Unicode codepoints, like \u2605 for ★, This is recommended for characters with a codepoint above U+007E TILDE ~.

When matching strings, any formatting (like color or bold) is stripped out. To test specifically for this formatting, use raw instead.

Lists¶

A list (or array) is a sequence of elements wrapped in brackets [ ] and delimited by commas: [E0,E1,E2,...].

They are an ordered collection of data of the same type.

Each element can be accessed with its index, its position in the list. Lists are zero-indexed; this means that 0 refers to the first element, and 1 is the second.

The length of a list (the number of elements in it) can be accessed with the count attribute: components.banner_patterns.count=range:0-9

Compounds¶

A compound (or object, map, dictionary) is a sequence of key-value pairs wrapped in braces { } with pairs delimited by commas and split by colons :: {key:value,a:b,...}.

Each key is unique and points to a value. Keys are always Strings.

Unlike Lists, values do not have to be of the same type in a compound. For example, {a:1,b:"string",c:64s} is valid, while the list [1,"string",64s] would not be.

Each value can be accessed with its key. With lists, elements are accessed with their index. Likewise, values are accessed with their key as the "index".

Numbers¶

A number is a byte, short, integer, long, float, or double. This term is used to refer to all of these types collectively, so "number" itself is not a real type.

Booleans¶

A boolean is either true or false.

NBT does not have a boolean type, however. The values true and false are simply aliases for 1b and 0b, respectively (byte 1 and byte 0).

Typed Arrays¶

A typed array is a byte array, int array, or long array. This term is used to refer to all of these types collectively, so "typed array" itself is not a real type.

They are wrapped in brackets [ ] and the first element is an identifier of their type. For example, [N;e,e,e,...] where N is the identifier and e are elements.

Prefixes¶

A prefix can be used to change how a key or value is tested. Some prefixes can be combined with other prefixes.

Exists¶

The prefix exists: checks if a key is defined at all. It takes 1 value, true or false.

• true will apply if the key exists.

• false will apply if the key does not exist - it is not defined.

components.lore=exists:true
components.item_name=exists:false
components.pot_decorations.0=exists:true
components.potion_contents.custom_effects.*.show_icon=exists:false

Pattern¶

The prefix pattern: and ipattern: match with wildcards.

Wildcards are shorter versions of regular expressions - they only support two special symbols:

• The symbol ? matches any one character.

• The symbol * matches any number of characters.

• pattern is case-sensitive; pattern:a will not match "A".

• ipattern is case-insensitive; pattern:a will match both "A" and "a".

Range¶

The prefix range: checks if an integer value is within a list of other integers or integer ranges.

Items are delimited by a space, as in range:1 2 3 9-15 4. Items do not need to be in order.

components.max_damage=range:(-50)-(-25) 200 0-100
components.instrument.*.range=range:3-18
components.potion_contents.*.custom_effects.*.duration=range:(-1)-3 5 10 26

Raw¶

The prefix raw: matches exact SNBT values.

Raw can be used to match types explicitly, such as bytes, shorts, floats, doubles, and typed arrays. It can also be used to match formatted text, since formatting is normally removed for checks against Strings.

raw: can also be combined with all other prefixes. For example: raw:pattern:, raw:iregex:, etc.

components.item_name=raw:'[{"text":"Dark red italics","italic":true,"color":"dark_red"}]'
components.bucket_entity_data.Health=raw:10.0f
nbt.1.UUID=raw:[I;-1668711424,-1434628111,-1613745989,1749596493]
nbt.5.someRandomShort=raw:64s

Regex¶

The prefix regex: and iregex: match with regular expressions.

Regular expressions (or regex) are patterns that can match complex text succinctly.

Regexes can be a simple Hi, .*! or a complex ^(?:(?:25[0-5]|2[0-4]\d|1?\\d{1,2})(?:\\.(?!$)|$)){4}$.

The syntax understood by OptiFine is the Java syntax. OptiFine regular expressions are not multiline and are not global ("/gm").

To match a string with regular expressions, use the regex: or iregex: prefix;

• regex is case-sensitive; regex:a{4} will not match "AAAA".

• iregex is case-insensitive; iregex:a{4} will match both "AaAA", "aaaa", "aaAA", etc.

Client-side data¶

Not all data can be detected.

Minecraft operates on a server/client model, even when in singleplayer mode. As OptiFine functions as a client-side mod, it only has access to data transmitted from the server to the client. If the data is exclusively server-side and not mirrored on the client side, it cannot be tested under NBT rules.

A general guideline is as follows: if the component/NBT visibly alters it, it can likely be used.

There is no definitive list yet of what data tags are client-side and which ones are not.

Blocks, items¶

Blocks and items can be specified in the same way that they are in Minecraft, by name.

The block name format is [namespace:]name[:property1=value1:property2=value2:...]. Optional parts are in brackets [ ]. The default namespace is minecraft.

blocks=minecraft:oak_stairs:facing=east,west:half=bottom
blocks=oak_stairs:facing=east,west:half=bottom

The minecraft: namespace is optional, so it can also be omitted.

Block states¶

Block states are extra data attached to a block. They are simple key-value pairs.

Block states can be specified in addition to the block name.

Block states are specified after a block name and are delimited by the : character. Each block state that follows is a simple key=value pair. To match more than one possible value for the key, split the value's options by a ,. For example, facing=west,east will match a block state where facing is equal to either west or east.

Block state keys and values themselves can only be simple strings. An infinite number of block states may be specified. Any invalid block states (states not applicable to a block) are ignored.

Blending methods¶

When two or more textures are combined, OptiFine offers several options for specifying the blending operation, if applicable.

"This" or "current" texture refers to the texture currently being applied. "Previous" refers to whatever has been rendered so far, which could be a single texture or the result of an earlier blending operation.