Connected Textures

_images/icon5.webp

The textures appear to "connect".

File location

/assets/minecraft/optifine/ctm/**/*.properties

Connected Textures (CTM) connects matching blocks together, making them appear unified.

For each block or terrain tile to override with connected or random textures, create a .properties file in the /assets/minecraft/optifine/ctm folder of the resource pack. Properties files can be organized into subfolders of any depth.

_images/settings4.webp

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

Different types of connected texture methods are available with different requirements and restrictions.

General properties

These properties apply for all CTM methods.

Note

matchTiles and matchBlocks can be omitted if they can be inferred from the filename instead:

  • ~/ctm/xxx/<name>.properties assumes matchTiles=<name>

  • ~/ctm/xxx/block_<name>.properties assumes matchBlocks=<name> (unless either property is specified explicitly; defined keys override inferred filenames)

method

Values: ctm, ctm_compact, horizontal, vertical, horizontal+vertical, vertical+horizontal, top, random, repeat, fixed, overlay_ctm, overlay_random, overlay_repeat, or overlay_fixed
Optional

Method to use when choosing a block's replacement texture:

  • ctm: Standard 8-way method, 47 tiles.

  • ctm_compact: Compact 8-way method, uses 5 tiles. Cannot be combined with any overlay method.

  • horizontal: Connect to blocks on left and right only.

  • vertical: Connect to blocks above and below only.

  • horizontal+vertical: Connect horizontally, then connect vertically.

  • vertical+horizontal: Connect vertically, then connect horizontally.

  • top: Connect to block above only.

  • random: Pick a tile at random.

  • repeat: Repeat a fixed pattern over large areas.

  • fixed: Use a single fixed tile, equivalent to random with only one tile.

  • overlay: Overlay for block transitions, uses 17 tiles.

  • overlay_ctm: Overlay variant of ctm method.

  • overlay_random: Overlay variant of random method.

  • overlay_repeat: Overlay variant of the repeat method.

  • overlay_fixed: Overlay variant of fixed method.

Note

The overlay method can be combined with other methods if it comes before the other methods in the order alphabetically.

Warning

The ctm_compact method cannot be combined with any overlay method.

tiles

Values: List of tiles
Required

List of replacement tiles to use. Each tile must be a separate image, just like terrain and item textures Tiles can be specified in several ways:

  • 0 -> 0.png

  • 8-11 -> 8.png, 9.png, 10.png, 11.png

  • name -> name.png

  • name.png -> name.png

  • full/path/name.png -> full/path/name.png

  • <skip>: Skip this tile, continue with next CTM properties.

  • <default>: Use the default texture for that block/tile.

In all cases except the last (<default>), the PNG file must be in the same directory as the properties file itself.

The formats can be mixed and matched: tiles=0-4 5 some/other/name.png.

Note

The overlay methods may use the special name <skip> for empty tiles to be skipped; overlay methods cannot use the <default> special name.

matchTiles

Values: List of strings
Optional

List of tiles this method should apply to.

Multiple .properties file can refer to the same block/tile and they will be processed in alphabetical order by filename. All tile-based entries are checked before block ID-based ones; the first match wins.

matchBlocks

Values: List of blocks + optional properties
Optional

List of blocks this method should apply to.

To refer to a tile from vanilla Minecraft, simply use its name in textures/block: matchBlocks=dirt To refer to a tile from a mod, its name must be known: matchBlocks=botania:blazeblock

Tiles output by CTM rules can also be matched by another rule; the tile name is simply the full path to the tile: matchBlocks=optifine/ctm/mygrass/1.png

Block format: (optional parts are in []) [namespace:]name[:property1=value1,value2...:property2=value1,value2...] For example:

  • Short name: oak_stairs

  • Full name: minecraft:oak_stairs

  • Full name + properties: minecraft:oak_stairs:facing=east,west:half=bottom

weight

Values: Integer
Optional
Default: 0

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

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

connect

Values: block, tile, or state
Optional
Default: block for blocks, tile for tiles

The conditions under which two blocks should connect. For methods that connect to adjacent blocks, this rule specifies how the game should decide if two blocks should be connected:

  • block: Connect if this block's name == neighbor block's name.

  • tile: Connect if this block's tile texture == neighbor tile's texture.

  • state: Connect if this block's full state (block + properties) == neighbor block's state.

faces

Values: List of strings
Optional

Limit CTM to certain faces of the block:

  • bottom: Bottom face (negative Y).

  • top: Top face (positive Y).

  • north: North face (negative Z).

  • south: South face (positive Z).

  • east: East face (positive X).

  • west: West face (negative X).

  • sides: Shorthand for north south east west.

  • all: All sides.

Important

This property is ignored on non-cube blocks like signs and fences.

biomes

Values: List of biomes
Optional

Biome restrictions. Modded biomes also can be used.

heights

Values: List of integers or integer Range.
Optional

Height restriction, no limit. Since 1.18, negative values may be specified for height. When used in a range they have to be put in parenthesis ( ).

See Numbers, ranges.

minHeight

Legacy

Legacy property for heights.

maxHeight

Legacy

Legacy property for heights.

ctm.<ctm_index>

Values: Tile index
Optional

Compact CTM tile replacement. Allows definition of replacement tile for a specific CTM case.

<ctm_index> is the index of the CTM case from the template (0..46), Tile index is the index of the tile as defined in tiles, not the tile name.

With ctm_compact, more than 5 tiles can be defined and they can use the additional tiles as replacements.

Important

This rule is only for the ctm_compact method.

name

Values: List of block IDs
Optional

Only for blocks with have corresponding nameable tile entities. Generally, this means containers that can be renamed.

For example: Beacon, Brewing Stand, Enchanting Table, Furnace, Dispenser, Dropper, Hopper, and Command Blocks.

See Custom GUIs for the syntax.

Method properties

ctm: standard 8-way

Note

Implies method=ctm.

_images/ctm.webp

Important

48th tile is unused.

tiles

Values: List of 47 tiles
Required

List of the 47 tiles to use when connecting.

innerSeams

Values: Boolean
Optional
Default: false

Whether to show seams on inner edges when connecting to adjacent blocks.

ctm_compact: compact 8-way

Note

Implies method=ctm_compact,

_images/compact.webp

tiles

Values: List of 5 tiles
Required

List of the 5 tiles to use when connecting.

innerSeams

Values: Boolean
Optional
Default: false

Whether to show seams on inner edges when connecting to adjacent blocks.

ctm.N

Values: Integer
Optional

Indexes of replacement tiles for specific CTM cases. N is a tile index.

Important

This is generally only used for special cases where you want to override the default behavior.

horizontal: horizontal only

Note

Implies method=horizontal.

_images/horizontal.webp

tiles

Values: List of 4 tiles
Required

List of the 4 tiles to use when connecting.

vertical: vertical only

Note

Implies method=vertical.

_images/vertical.webp

tiles

Values: List of 4 tiles
Required

List of the 4 tiles to use when connecting.

top: top face only

Note

Implies method=top.

tiles

Values: String
Required

The single tile to use when connecting.

random: random connect

Note

Implies method=random.

tiles

Values: List of tiles
Required

List of the tiles to use when connecting. Can be infinitely long or short.

weights

Values: List of integers
Optional

List of weights to apply to the random choice.

For example, for tiles=1 2 3 4; weights=10 1 10 5, tile 1 has weight 10, 2 has 1, 3 has 10, and 4 has 5. Weights do not have to total any value; in the above example, tiles 1 and 3 will each be used ~38% of the time.

Important

This rule must have the same number of elements as the tiles rule.

randomLoops

Values: Integer Range from 0 to 9
Optional
Default: 0

Repeats the random function by this amount to increase randomness. Can be used to make different textures use different random patterns.

Warning

A high randomLoops value may decrease the chunk loading speed.

symmetry

Values: none, opposite, or all
Optional
Default: none

Desired level of symmetry for the faces of each block.

Applies to standard 6-sided blocks only (dirt, glass, not fences).

  • none: All 6 faces are textured independently.

  • opposite: 2-way symmetry; opposing faces have the same texture, but each pair can potentially have a different texture.

  • all: All 6 faces have the same texture.

linked

Values: Boolean
Optional
Default: false

Whether to link textures between related blocks.

If true, OptiFine uses the same random number seed for all parts of a multi-block object. For example, the top and bottom halves of tall grass. This allows randomized textures that will remain consistent within each set of blocks.

If false, the two halves will be scrambled, chosen independently. This property currently only applies to plants, double plants (rose bushes, peonys, etc.), and doors.

Important

For linked to work, multiple properties files with linked=true and the same number of replacement textures and same set of weights must be present. For example, double_plant_top.properties:

method=random
tiles=grass_top1 grass_top2 grass_top3
weights=1 2 3

repeat: repeated

Note

Implies method=repeat.

width

Values: Integer
Required

The width of the repeating pattern.

height

Values: Integer
Required

The height of the repeating pattern.

tiles

Values: List of tiles
Required

A list of tiles. The number of elements must equal width * height.

symmetry

Values: none, or opposite
Optional
Default: none

Desired level of symmetry for the faces of each block.

Applies to standard 6-sided blocks only (dirt, glass, not fences).

  • none: All 6 faces are textured so that the pattern tiling looks the same from all sides

  • opposite: 2-way symmetry; opposing faces have the same texture, which means that tiling on the south and east faces will be mirrored left-to-right when comapared to the north and west faces

fixed: one texture

Note

Implies method=fixed.

tiles

Values: String
Required

Single tile to use.

overlay: texture atop

Note

Implies method=overlay

_images/overlay.webp

Important

17th, 18th, 19th, and 20th tiles are unused.

tiles

Values: List of tiles
Required

List of replacement tiles to use.

May use the special name <skip> for empty tiles to be skipped; cannot use the <default> special name.

connectTiles

Values: List of tiles
Optional

Connect only to blocks which are using the specified tiles.

Note

This rule only applies to overlay methods.

tintIndex

Values: Integer
Optional
Default: -1; disabled

Tint index, only for overlay method. Tint index is for the tile's texture.

Use -1 to disable it.

tintBlock

Values: Block
Optional

The block used for the tile texture tinting.

Different blocks use different colors for the same tint index.

layer

Values: String of cutout_mipped, cutout, or translucent
Optional
Default: cutout_mipped

The layer on which the overlay texture should be rendered.

Values:

  • cutout_mipped: Transparent textures with mipmaps.

  • cutout: Transparent textures without mipmaps.

  • translucent: Translucent textures with mipmaps.

JSON schema

Note

Although this page is .properties based, it can be mapped to JSON.

{
	"$schema": "http://json-schema.org/draft/2020-12/schema",
	"$id": "https://gitlab.com/whoatemybutter/optifinedocs/-/blob/master/schemas/cit.schema.json",
	"title": "Connected Textures",
	"description": "Connected Textures (CTM) connects matching blocks together, making them appear unified.",
	"type": "object",
	"properties": {
		"method": {
			"enum": [
				"ctm",
				"ctm_compact",
				"horizontal",
				"vertical",
				"horizontal+vertical",
				"vertical+horizontal",
				"top",
				"random",
				"repeat",
				"fixed",
				"overlay_ctm",
				"overlay_random",
				"overlay_repeat",
				"overlay_fixed"
			],
			"description": "Method to use when choosing a block's replacement texture."
		},
		"tiles": {
			"type": "string",
			"description": "Space-separated string of replacment tiles to use."
		},
		"matchTiles": {
			"$ref": "common.schema.json#/$defs/item_id_list",
			"description": "Space-separated string of tiles this method should apply to."
		},
		"matchBlocks": {
			"$ref": "common.schema.json#/$defs/item_id_list",
			"description": "Space-separated string of blocks this method should apply to."
		},
		"weight": {
			"type": "integer",
			"default": 0,
			"description": "If multiple properties files match the same block, the highest weighted one is used."
		},
		"connect": {
			"enum": [
				"block",
				"tile",
				"state"
			],
			"description": "The conditions under which two blocks should connect."
		},
		"connectTiles": {
			"$ref": "common.schema.json#/$defs/item_id_list",
			"description": "Connect only to blocks which are using the specified tiles."
		},
		"faces": {
			"type": "string",
			"pattern": "(bottom|top|north|south|east|west|sides|all) ?",
			"description": "Limit CTM to certain faces of the block."
		},
		"biomes": {
			"type": "string",
			"description": "Space-separated string of biome restrictions."
		},
		"heights": {
			"type": "string",
			"description": "Height restriction ranges."
		},
		"minHeight": {
			"type": "integer",
			"minimum": -65535,
			"deprecated": true,
			"description": "Legacy key for heights."
		},
		"maxHeight": {
			"type": "integer",
			"maximum": 65535,
			"deprecated": true,
			"description": "Legacy key for heights."
		},
		"tintIndex": {
			"type": "integer",
			"minimum": -1,
			"default": -1,
			"description": "Tint index, only for overlay method."
		},
		"tintBlock": {
			"$ref": "common.schema.json#/$defs/item_id",
			"description": "The block used for the tile texture tinting."
		},
		"layer": {
			"enum": [
				"cutout_mipped",
				"cutout",
				"translucent"
			],
			"default": "cutout_mipped",
			"description": "The layer on which the overlay texture should be rendered."
		},
		"name": {
			"$ref": "common.schema.json#/$defs/item_id_list",
			"description": "Only for blocks with have corresponding nameable tile entities."
		}
	},
	"patternProperties": {
		"^ctm\\.\\d+$": {
			"type": [
				"string",
				"integer"
			],
			"minimum": 0,
			"description": "Compact CTM tile replacement. Allows definition of replacement tile for a specific CTM case."
		}
	},
	"required": [
		"tiles"
	],
	"additionalProperties": false,
	"allOf": [
		{
			"if": {
				"properties": {
					"connectTiles": {}
				}
			},
			"then": {
				"properties": {
					"method": {
						"const": "overlay"
					}
				}
			}
		},
		{
			"if": {
				"patternProperties": {
					"^ctm\\.\\d+$": {}
				}
			},
			"then": {
				"properties": {
					"method": {
						"const": "ctm_compact"
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"tintIndex": {}
				}
			},
			"then": {
				"properties": {
					"method": {
						"const": "overlay"
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"layer": {}
				}
			},
			"then": {
				"properties": {
					"method": {
						"const": "overlay"
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"method": {
						"const": "ctm"
					}
				}
			},
			"then": {
				"properties": {
					"innerSeams": {
						"type": "boolean",
						"default": false,
						"description": "Whether to show seams on inner edges when connecting to adjacent blocks."
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"method": {
						"const": "ctm_compact"
					}
				}
			},
			"then": {
				"properties": {
					"innerSeams": {
						"type": "boolean",
						"default": false,
						"description": "Whether to show seams on inner edges when connecting to adjacent blocks."
					}
				},
				"patternProperties": {
					"^ctm\\.\\d+$": {
						"type": [
							"string",
							"integer"
						],
						"minimum": 0,
						"description": "Indexes of replacement tiles for specific CTM cases."
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"method": {
						"const": "random"
					}
				}
			},
			"then": {
				"properties": {
					"weights": {
						"type": "string",
						"description": "Space-separated string of weights to apply to the random choice."
					},
					"randomLoops": {
						"type": "integer",
						"minimum": 0,
						"maximum": 9,
						"description": "Repeats the random function by this amount to increase randomness."
					},
					"symmetry": {
						"enum": [
							"none",
							"opposite",
							"all"
						],
						"default": "none",
						"description": "Desired level of symmetry for the faces of each block."
					},
					"linked": {
						"type": "boolean",
						"default": false,
						"description": "Whether to link textures between related blocks."
					}
				}
			}
		},
		{
			"if": {
				"properties": {
					"method": {
						"const": "repeat"
					}
				}
			},
			"then": {
				"properties": {
					"width": {
						"type": "integer",
						"minimum": 1,
						"maximum": 16384,
						"description": "The width of the repeating pattern."
					},
					"height": {
						"type": "integer",
						"minimum": 1,
						"maximum": 16384,
						"description": "The height of the repeating pattern."
					},
					"symmetry": {
						"enum": [
							"none",
							"opposite"
						],
						"default": "none",
						"description": "Desired level of symmetry for the faces of each block."
					}
				},
				"required": [
					"width",
					"height"
				]
			}
		}
	]
}

Assumes the latest OptiFine version.
Updated to commit feb2a450.

Last update: 2024 January 31