Specification
This specification defines a format outlining a set of rules for custom sky rendering. These rules can be organized into 11 groups. Please refer to the side panel for the table of contents.
To start writing your configuration for your skybox, create a text file, and save it as a .json
. The format starts with a {
and ends with a }
. In between you can start adding your parameters from these 11 groups, called objects
. Each object is separated by a ,
and can be be arranged in any order.
Throughout the document, you will find examples. Additionally, at the bottom of the page, you'll find examples of various skybox types, demonstrating the structure of a complete file. Template files are also provided to assist you in starting your own pack quickly.
1. Schema version
The current version is 2, but this may change in the future. The mod isn't yet stable since we are in the 0.x
phase. This object is required.
2. Type
There are three main types of skyboxes: monocolor skyboxes, textured skyboxes, and vanilla skyboxes. One of the 3 types is required.
2.1 Monocolor skyboxes
monocolor
Shows a single plain color for the full skybox.
2.2 Textured skyboxes
square-textured
uses 6 separate 1:1 aspect ratio texture files for the 6 sides of the skybox
animated-square-textured
uses multiple sets of 6 separate 1:1 aspect ratio texture files for an animated skybox
single-sprite-square-textured
uses a single 3:2 aspect ratio texture file for the skybox
single-sprite-animated-square-textured
uses multiple 3:2 aspect ratio texture files for an animated skybox
multi-texture
uses a grid of textures- arranged in a single texture atlas- for an animation
Example for (animated-)square-textured
skybox
Example for single-sprite-(animated-)square-textured
skybox
Here's an example of an animation texture used for the multi-texture
skybox type. Frames should be ordered from top to bottom, then left to right as seen below. Each frame can be of any size and aspect ratio. However, the combined size of the texture should not exceed 8192x8192 pixels. Only very recent GPUs can handle textures up to 16384x16384 pixels.
2.3 Vanilla skyboxes
overworld
This will show the overworld's skybox.
end
This will show the end's skybox.
3. Color
This is exclusive to- and is a requirement when using the monocolor
type of skybox.
red
Specifies the amount of red color to be used. Must be a value between 0 and 1.
✔️
-
green
Specifies the amount of green color to be used. Must be a value between 0 and 1.
✔️
-
blue
Specifies the amount of blue color to be used. Must be a value between 0 and 1.
✔️
-
alpha
Specifies the amount of alpha transparency to be used. Must be a value between 0 and 1.
❌
1.0
4. Texture
This is exclusive to- and is a requirement for the two non-animated skybox types.
texture
Used for the single-sprite-square-textured
skybox type. Specifies the directory for the texture file.
textures
Used for the square-textured
skybox type. Specifies the directory for the texture files to be used for the top
, bottom
, east
, west
, north
and south
sides of the skybox.
OR
5. Animations
This is exclusive to- and is a requirement for the multi-texture
skybox type. You can incorporate as many animations as needed.
The animation texture will cycle through within the designated animation area, determined by the UV ranges. The number of steps in the cycle is defined by the number of rows and columns on the animation texture.
texture
Specifies the location of the texture to be used when rendering the animation
✔️
uvRanges
Specifies the location in UV ranges to render the animation
✔️
gridColumns
Specifies the amount of columns the animation texture has
✔️
gridRows
Specifies the amount of rows the animation texture has
✔️
duration
Specifies the default duration of each animation frame in milliseconds
✔️
frameDuration
Specifies the specific duration per animation frame, which overrides duration
❌
Example for a skybox with 2 animations
5.1 UV ranges
Specifies a UV range object for defining texture coordinates. All fields are required.
minU
Specifies the minimum U coordinate
minV
Specifies the minimum V coordinate
maxU
Specifies the maximum U coordinate
maxV
Specifies the maximum V coordinate
The UV map uses the 3:2 aspect ratio skybox template, as shown in the example below. It is worth noting, that the aspect ratio of your animated area does not necessarily need to match the aspect ratio of the frames in your animation texture. This means, that your frames will be stretched to fit the animation area, even if the aspect ratios do not match. As an example, if your frame is a perfect square, but your animated area is a rectangle, your frame will appear stretched.
5.2 Frame duration
Overrides the default duration of each frame that is set by duration
, allowing unique duration for each frame in the animation. All fields are optional. The total number of frames specified should not exceed the number of frames included on the animation texture.
1
Specifies the duration of the 1st animation frame in milliseconds
2
Specifies the duration of the 2nd animation frame in milliseconds
3
Specifies the duration of the 3rd animation frame in milliseconds
4
Specifies the duration of the 4th animation frame in milliseconds
6. Animation textures
This is exclusive to and a requirement for the two animated skybox types. Depending on the chosen skybox type, you will need to specify the textures differently.
Below is an example for animated-square-textured
skyboxes, using a 3-frame animation as an example.
And for the single-sprite-animated-square-textured
skybox type.
7. FPS
This is exclusive to- and a requirement for the two animated skybox types.
fps
Specifies the number of frames to be rendered per second.
8. Blend
Specifies how the skybox should blend with the previously rendered sky layer, the vanilla skybox being the first layer. All fields are optional.
In FabricSkyboxes, the blending of textured skyboxes is achieved using glBlendFunc
. The provided blending types serve as presets, utilizing the same equations outlined below for the custom type. For decorations
, the blending used aligns with the vanilla game's approach, particularly for the sun and moon blending.
type
Specifies the type of the blend for the skybox only. Valid types are: add
, subtract
, multiply
, screen
, replace
, alpha
, dodge
, burn
, darken
, lighten
, decorations
, disable
and custom
.
add
blender
only use this when using the custom
blend type
OR
sFactor
Specifies the OpenGL source factor to use.
dFactor
Specifies the OpenGL destination factor to use.
equation
Specifies the OpenGL blend equation to use.
redAlphaEnabled
Specifies whether alpha state will be used in red shader color or predetermined value of 1.0.
false
greenAlphaEnabled
Specifies whether alpha state will be used in green shader color or predetermined value of 1.0.
false
blueAlphaEnabled
Specifies whether alpha state will be used in blue shader color or predetermined value of 1.0.
false
alphaEnabled
Specifies whether alpha state will be used in shader color or predetermined value of 1.0.
false
More information on custom blend can be found in the blend documentation.
9. Properties
Specifies common properties used by all types of skyboxes.
priority
Specifies the order which skybox will be rendered. If there are multiple skyboxes with identical priority, those skyboxes are not re-ordered therefore being dependant of Vanilla's alphabetical namespaced identifier's loading.
❌
0
fade
Specifies the time of day in ticks that the skybox should start and end fading in and out.
✔️
-
rotation
Specifies the rotation speed and angles of the skybox.
❌
[0,0,0]
for static
/axis
/timeShift
, 0
for rotationSpeedX/Y/Z
, true
for skyboxRotation
transitionInDuration
Specifies the duration in ticks that skybox will fade in when valid conditions are changed. The value must be within 1 and 8760000 (365 days * 24000 ticks).
❌
20
transitionOutDuration
Specifies the duration in ticks that skybox will fade out when valid conditions are changed. The value must be within 1 and 8760000 (365 days * 24000 ticks).
❌
20
changeFog
Specifies whether the skybox should change the fog color.
❌
false
fogColors
Specifies the colors to be used for rendering fog. Only has an effect if changeFog is true.
❌
0
for each RGB value
sunSkyTint
Specifies whether the skybox should disable sunrise/set sky color tinting.
❌
true
inThickFog
Specifies whether the skybox should be rendered in thick fog.
❌
true
minAlpha
Specifies the minimum value that the alpha can be. The value must be within 0 and 1.
❌
0.0
maxAlpha
Specifies the maximum value that the alpha can be. The value must be within 0 and 1.
❌
1.0
As you can see, fade
, rotation
(and its static
, axis
and timeShift
components) have multiple object within, so let's take a look at those in more detail. For fogColors
, refer to Color for the specification.
9.1 Fade object
Stores a list of four integers which specify the time in ticks to start and end fading the skybox in and out.
startFadeIn
The time in ticks when a skybox will start to fade in.
✔️ | ❌
-
endFadeIn
The time in ticks when a skybox will end fading in.
✔️ | ❌
-
startFadeOut
The time in ticks when a skybox will start to fade out.
✔️ | ❌
-
endFadeOut
The time in ticks when a skybox will end fading out.
✔️ | ❌
-
alwaysOn
Whether the skybox should always be at full visibility.
❌ | ✔️
false
Fade
and alwaysOn
can be use exclusively.
Conversion table:
0
6 AM
6000
12 AM
12000
6 PM
24000
12 PM
9.2 Rotation Object
Specifies the speed, static- and axis of rotation for a skybox as well as its timeshift. This object is used by both Properties and Decorations. Properties only affects the skybox rotation, and Decorations only affect the sun, moon and stars rotation. All fields are optional.
static
Specifies the static rotation in degrees
[0,0,0]
axis
Specifies the axis rotation in degrees
[0,0,0]
timeShift
Specifies the time shifted for rotation
[0,0,0]
(integers only)
rotationSpeedX/Y/Z
Specifies the speed of the skybox rotation around the X, Y or Z axis, in rotations per 24000 ticks
0
skyboxRotation
During sunset/rise, the rotation speed for the sun/moon will slow down/speed up. This object can toggle this behavior.
true
for properties
, false
for decorations
Static
is a mapping option, which allows you to reorient your skybox's default position. For example, you can flip your skybox upside down using static
. The axis
refers to the actual axis, which the skybox will visibly revolve around. The speed parameter determines how many full rotations the sky makes in a single in-game day.
timeShift
facilitates synchronization between the skyboxes utilized by both FabricSkyBoxes and OptiFine. By default, FabricSkyBoxes initiates rotation at 0 tick time, whereas OptiFine begins at 18000 tick time.
skyboxRotation
becomes noticeable when the time is set to 12000 or 0. During sunrise and sunset, the sun/moon will be slightly above the horizon. This represents the default behavior for decorations when skyboxRotation is set to false
. If set to true
, the sun/moon will align exactly with the horizon line at times 12000 and 0. This adjustment ensures that the rotation parameters function similarly for both the skyboxes and the sun/moon, enhancing the reliability of rotation configuration.
9.3 Float vector
Specifies a list of three floating-point literals to represent degrees of rotation.
To get a better understanding on how to define these degrees for static and axis, take a look at the image below.
Additionally, a Blender tool has been developed courtesy of @UsernameGeri, allowing real-time visualization and adjustment of both static rotation and axis, providing insights into their impact on the skybox's rotation. This tool is compatible with both FabricSkyBoxes and OptiFine.
Instructions for the tool are documented within the blend file. Only the most basic Blender skills are required to utilize this tool, such as navigating the interface and selecting and rotating objects.
Blender is a free, open source software. Download at https://www.blender.org/
10. Conditions
Specifies when and where a skybox should render. All fields are optional.
worlds
Specifies a list of worlds sky effects that the skybox should be rendered in.
dimensions
Specifies a list of dimension that the skybox should be rendered in.
weather
Specifies a list of weather conditions that the skybox should be rendered in. Valid entries are clear
, rain
, rain_biome
, thunder
and snow
.
biomes
Specifies a list of biomes that the skybox should be rendered in.
xRanges
Specifies a list of coordinates that the skybox should be rendered between.
yRanges
Specifies a list of coordinates that the skybox should be rendered between.
zRanges
Specifies a list of coordinates that the skybox should be rendered between.
loop
Specifies the loop object that the skybox should be rendered between.
effects
Specifies a list of player status effects during which the skybox should be rendered.
The difference between rain
and rain_biome
will be apparent in a desert for example. Here, when it rains in the world, a sky using rain_biome
will not be visible, whereas one using rain
will be. This is to allow to differentiate between biomes where it actually rains, and where it doesn't during weather.
Similarly to Properties, some conditions have multiple objects within. Let's take a look at them.
10.1 MinMax Entry Object
These objects are used by the x-y-z range
objects, and the loop
object. Multiple MinMax
entries can be specified within one range.
min
Specifies the minimum value, inclusive
max
Specifies the maximum value, exclusive
These MinMax
ranges should be thought of as sections on a number line, rather than incremental steps, like blocks in Minecraft. This means, that you can specify them to a decimal point precision.
To show a concrete example, let's take a look at the day ranges of a loop object.
For the purposes of x-y-z ranges, this means that if you want 2 skyboxes to transition when crossing a certain coordinate threshold, you will need to look out for a "gap", as seen in the image above. To avoid this gap, where no sky is shown, you will need to specify the ranges something like this:
sky1.json
sky2.json
The reason why we don't write "min": 150.0
in sky2.json, is because then both sky 1 and 2 would overlap and show when standing on Y=150. This peculiarity is really only noticeable on the Y coordinate, as it is easy to align the player on exact whole coordinates, but it can also happen on the X and Z coordinates as well, it's just less likely. Even with the method show above, there is still a gap in-between the 2 skyboxes, but it's very unlikely you will manage to align the player that precisely.
10.2 Loop object
days
Specifies the length of the loop in days.
ranges
Specifies the days where the skybox is rendered.
The loop object's start and end points are determined by the fade times in the given skybox. The loop starts at startFadeIn
, and ends at endFadeOut
after the specified number of days. To give a concrete example, let's use these parameters:
In this scenario, the loop starts at /time set 1000
. Then if we /time add 195000
(8×24000+(4000-1000)), that is when the loop will end, and it will start again the next day at time 1000.
See also MinMax Entry Object for examples on the implementation.
11. Decorations
Stores all specifications for the stars, sun and moon configuration. For optimal results, the moon texture should use the same layout as the vanilla moon texture. The Default value stores the overworld sun and moon textures and sets all enabled to true. All fields are optional.
blend
Specifies the type of the blend or the decorations only. Valid types are: add
, subtract
, multiply
, screen
, replace
, alpha
, dodge
, burn
, darken
, lighten
, decorations
and disable
.
decorations
sun
Specifies the location of the texture to be used for rendering the sun.
Default sun texture (minecraft:textures/environment/sun.png
)
moon
Specifies the location of the texture to be used for rendering the moon.
Default moon texture (minecraft:textures/environment/moon_phases.png
)
showSun
Specifies whether the sun should be rendered.
true
showMoon
Specifies whether the moon should be rendered.
true
showStars
Specifies whether stars should be rendered.
true
rotation
Specifies the rotation of the decorations.
[0,0,0]
for static
/axis
/timeShift
, 0
for rotationSpeedX/Y/Z
, false
for skyboxRotation
Rotation in Decorations only affects the sun, moon and stars, and not the skybox. To see how to implement the rotation, check Rotation Object and Float Vector.
It is worth knowing, that it is possible to specify unique rotation and blending mode for the sun, moon and stars all individually, if they are set to show true
in 3 separate json files, and the other 2 decorations are set to show false
. You can also add multiple suns and moon with different blending and/or rotation, if you assign them to multiple different sky layers.
Examples and templates
Last updated