Custom Sky

_images/icon11.webp

A space skybox with a moon.

File location

/assets/minecraft/optifine/sky/world*/*.properties /assets/minecraft/optifine/sky/**/*.png

Custom Sky changes the skybox texture and can apply different sets of skies depending on the time, biome, heights, weather, and more.

Place the file in:

  • ~/sky/world0/ for Overworld.

  • ~/sky/world1/ for End. (since version G9)

  • ~/sky/world-1/ for Nether.

in the resource pack.

Each file represents one layer of the sky. OptiFine will load them in order by their number, applying one on top of the previous.

Additionally, two special properties files are applied to the sun and moon if present. This is mainly intended to allow overriding the blend method used by the sun and moon:

  • ~/sky/world0/sun.properties: replaces sun.png.

  • ~/sky/world0/moon_phases.properties: replaces moon_phases.png.

_images/sun.webp

The Vanilla sun.png.

_images/moon_phases.webp

The Vanilla moon_phases.png.

Instead of a full skybox, the source texture should match the layout of sun.png or moon_phases.png.

Important

The "world0" in the path refers to the overworld. If there were other worlds with skies (the Nether and End do not use the standard sky rendering# methods), their files would be in ~/sky/world<world number>.

_images/skybox.webp

A simple template for a skybox, with directions labelled. Image is from this merge request

_images/star_sky.webp

An example of how a skybox might look.

Properties

Note

speed does not affect the fading in and out; this always occurs on a 24-hour cycle.

startFadeIn

Values: String: hh:mm 24-hour format
Optional

Fade in/out times. All times are in hh:mm 24-hour format. See Time format.

If no times are specified, the layer is always rendered.

endFadeIn

Values: See above
Optional
Default: None

endFadeOut

Values: See above
Optional
Default: None

source

Values: String: File path
Optional
Default: skyN.png in same directory, N is properties' file name N.

Path to source texture.

Multiple properties files can reuse the same source.

blend

Values: add, subtract, multiply, dodge, burn, screen, replace, overlay, or alpha
Optional
Default: add

The blending method between fading of layers.

Here, 'previous layer' can refer to the default sky or to the previous custom sky defined by sky<N-1>.properties. Supported blending methods are:

  • add: Add this sky bitmap to the previous layer. In case of overflow, white is displayed.

  • subtract: Subtracts this sky bitmap to the previous layer. In case of negative values, black is displayed.

  • multiply: Multiply the previous RGBA values by the RGBA values in the current bitmap.

  • dodge: Lightens the sky bitmap.

  • burn: Darkens the sky bitmap.

  • screen: Inverts both layers, multiplies them, and then inverts that result.

  • replace: Replace the previous layer entirely with the current bitmap. There is no gradual fading with this method; if brightness computed from the fade times is >0, the full pixel value is used.

  • overlay: RGB value > 0.5 brightens the image, < 0.5 darkens.

  • alpha: Weighted average by alpha value.

rotate

Values: Boolean
Optional
Default: true

Whether or not the source texture should rotate with the time of day.

speed

Values: Positive float
Optional
Default: 1.0

Rotation speed as a multiple of the default of one 360-degree cycle per game day.

A value of 0.5 rotates every two days.

Info

Irrational values can be useful to make clouds appear in different positions each day.

axis

Values: List of three floats
Optional
Default: 0.0 0.0 1.0

The axis of rotation of the skybox. If a player is looking in the given direction, the skybox will appear to be rotating clockwise around the line of sight.

Default rotation is along the southern axis (rising in the east and setting in the west).

For reference, the vectors corresponding to the six cardinal directions are below. However, the rotation axis can be any vector except 0.0 0.0 0.0:

down  =  0 -1  0
up    =  0  1  0
north =  0  0 -1
south =  0  0  1
west  = -1  0  0
east  =  1  0  0

days

Values: List of integers or integer Range
Optional

The days for which the layer is to be rendered.

Days are numbered from 0 to daysLoop-1, for example: days=0 2-4 6.

daysLoop

Values: Positive integer
Optional
Default: 8

Number of days in a loop, see above.

weather

Values: clear, rain, or thunder
Optional
Default: clear

Under what weather for which the layer is to be rendered. Several values can be specified separated by spaces, for example weather=clear rain thunder.

biomes

Values: List of biome IDs
Optional
Default: None

Limit the sky to only certain biomes.

heights

Values: List of integers or integer Range
Optional

Limit the sky to only certain heights.

Since 1.18, negative values may be specified for height. When used in a range they have to be put in parenthesis ( ): (-3)-64.

transition

Values: Integer
Optional
Default: 1

Transition time (in seconds) for the layer brightness. It is used to smooth sharp transitions, for example between different biomes.

Time format

All times are in hh:mm 24-hour format.

For reference,

Sunrise

6:00

/time set 0

Noon

12:00

/time set 6000

Sunset

18:00

/time set 12000

Midnight

0:00

/time set 18000

The fade times control the brightness when blending.

  • between startFadeIn and endFadeIn: 0 up to 1

  • between endFadeIn and startFadeOut: always 1

  • between startFadeOut and endFadeOut: 1 down to 0

  • between endFadeOut and startFadeIn: always 0

Important

startFadeOut does not need to be specified; its value is uniquely determined by the other three.

Blender model

Note

This Blender model was contributed by usernamegeri.

You can generate the vector coordinates that are required for the axis of rotation of the skybox by using a pre-made tool for Blender. It can be found here.

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/custom_sky.schema.json",
	"title": "Custom Sky",
	"description": "Custom Sky changes the skybox texture and can apply different sets of skies depending on the time, biome, heights, weather, and more.",
	"type": "object",
	"properties": {
		"startFadeIn": {
			"type": "string",
			"pattern": "^\\d{1,2}:\\d{1,2}$",
			"description": "Start time to fade in."
		},
		"endFadeIn": {
			"type": "string",
			"pattern": "^\\d{1,2}:\\d{1,2}$",
			"description": "End time to fade in."
		},
		"endFadeOut": {
			"type": "string",
			"pattern": "^\\d{1,2}:\\d{1,2}$",
			"description": "End time to fade out."
		},
		"source": {
			"$ref": "common.schema.json#/$defs/resource",
			"description": "Path to source texture."
		},
		"blend": {
			"$ref": "common.schema.json#/$defs/blending_method_enum",
			"default": "add",
			"description": "The blending method between fading of layers."
		},
		"rotate": {
			"type": "boolean",
			"default": true,
			"description": "Whether or not the source texture should rotate with the time of day."
		},
		"speed": {
			"type": "number",
			"minimum": 0.0,
			"default": 1.0,
			"description": "Rotation speed as a multiple of the default of one 360-degree cycle per game day."
		},
		"axis": {
			"type": "string",
			"pattern": "^-?\\d+(\\.\\d+)? -?\\d+(\\.\\d+)? -?\\d+(\\.\\d+)?$",
			"default": "0.0 0.0 1.0",
			"description": "The axis of rotation of the skybox."
		},
		"days": {
			"type": "string",
			"description": "The days for which the layer is to be rendered."
		},
		"daysLoop": {
			"type": "integer",
			"minimum": 0,
			"default": 8,
			"description": "Number of days in a loop."
		},
		"weather": {
			"enum": ["clear", "rain", "thunder"],
			"default": "clear",
			"description": "Under what weather for which the layer is to be rendered."
		},
		"biomes": {
			"type": "string",
			"description": "Limit the sky to only certain biomes."
		},
		"heights": {
			"type": "string",
			"description": "Limit the sky to only certain heights."
		},
		"transition": {
			"type": "integer",
			"default": 1,
			"minimum": 0,
			"description": "Transition time in seconds for the layer brightness."
		}
	},
	"additionalProperties": false
}

Assumes the latest OptiFine version.
Updated to commit feb2a450.

Last update: 2024 January 31