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
Name | Description |
---|---|
| Shows a single plain color for the full skybox. |
2.2 Textured skyboxes
Name | Description |
---|---|
| uses 6 separate 1:1 aspect ratio texture files for the 6 sides of the skybox |
| uses multiple sets of 6 separate 1:1 aspect ratio texture files for an animated skybox |
| uses a single 3:2 aspect ratio texture file for the skybox |
| uses multiple 3:2 aspect ratio texture files for an animated skybox |
| 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
Name | Description |
---|---|
| This will show the overworld's skybox. |
| This will show the end's skybox. |
3. Color
This is exclusive to- and is a requirement when using the monocolor
type of skybox.
Name | Description | Required | Default |
---|---|---|---|
| Specifies the amount of red color to be used. Must be a value between 0 and 1. | ✔️ | - |
| Specifies the amount of green color to be used. Must be a value between 0 and 1. | ✔️ | - |
| Specifies the amount of blue color to be used. Must be a value between 0 and 1. | ✔️ | - |
| Specifies the amount of alpha transparency to be used. Must be a value between 0 and 1. | ❌ |
|
4. Texture
This is exclusive to- and is a requirement for the two non-animated skybox types.
Name | Description |
---|---|
| Used for the |
| Used for the |
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.
Name | Description | Required |
---|---|---|
| Specifies the location of the texture to be used when rendering the animation | ✔️ |
| Specifies the location in UV ranges to render the animation | ✔️ |
| Specifies the amount of columns the animation texture has | ✔️ |
| Specifies the amount of rows the animation texture has | ✔️ |
| Specifies the default duration of each animation frame in milliseconds | ✔️ |
| Specifies the specific duration per animation frame, which overrides | ❌ |
Example for a skybox with 2 animations
5.1 UV ranges
Specifies a UV range object for defining texture coordinates. All fields are required.
Name | Description |
---|---|
| Specifies the minimum U coordinate |
| Specifies the minimum V coordinate |
| Specifies the maximum U coordinate |
| 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.
Name | Description |
---|---|
| Specifies the duration of the 1st animation frame in milliseconds |
| Specifies the duration of the 2nd animation frame in milliseconds |
| Specifies the duration of the 3rd animation frame in milliseconds |
| 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.
Name | Description |
---|---|
| 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.
Name | Description | Default |
---|---|---|
| Specifies the type of the blend for the skybox only. Valid types are: |
|
| only use this when using the |
OR
Name | Description | Default |
---|---|---|
| Specifies the OpenGL source factor to use. | |
| Specifies the OpenGL destination factor to use. | |
| Specifies the OpenGL blend equation to use. | |
| Specifies whether alpha state will be used in red shader color or predetermined value of 1.0. |
|
| Specifies whether alpha state will be used in green shader color or predetermined value of 1.0. |
|
| Specifies whether alpha state will be used in blue shader color or predetermined value of 1.0. |
|
| Specifies whether alpha state will be used in shader color or predetermined value of 1.0. |
|
More information on custom blend can be found in the blend documentation.
9. Properties
Specifies common properties used by all types of skyboxes.
Name | Description | Required | Default |
---|---|---|---|
| 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. | ❌ |
|
| Specifies the time of day in ticks that the skybox should start and end fading in and out. | ✔️ | - |
| Specifies the rotation speed and angles of the skybox. | ❌ |
|
| 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). | ❌ |
|
| 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). | ❌ |
|
| Specifies whether the skybox should change the fog color. | ❌ |
|
| Specifies the colors to be used for rendering fog. Only has an effect if changeFog is true. | ❌ |
|
| Specifies whether the skybox should disable sunrise/set sky color tinting. | ❌ |
|
| Specifies whether the skybox should be rendered in thick fog. | ❌ |
|
| Specifies the minimum value that the alpha can be. The value must be within 0 and 1. | ❌ |
|
| Specifies the maximum value that the alpha can be. The value must be within 0 and 1. | ❌ |
|
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.
Name | Description | Required | Default |
---|---|---|---|
| The time in ticks when a skybox will start to fade in. | ✔️ | ❌ | - |
| The time in ticks when a skybox will end fading in. | ✔️ | ❌ | - |
| The time in ticks when a skybox will start to fade out. | ✔️ | ❌ | - |
| The time in ticks when a skybox will end fading out. | ✔️ | ❌ | - |
| Whether the skybox should always be at full visibility. | ❌ | ✔️ |
|
Fade
and alwaysOn
can be use exclusively.
Conversion table:
Time in Ticks | Clock Time |
---|---|
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.
Name | Description | Default |
---|---|---|
| Specifies the static rotation in degrees |
|
| Specifies the axis rotation in degrees |
|
| Specifies the time shifted for rotation |
(integers only) |
| Specifies the speed of the skybox rotation around the X, Y or Z axis, in rotations per 24000 ticks |
|
| During sunset/rise, the rotation speed for the sun/moon will slow down/speed up. This object can toggle this behavior. |
|
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.
Name | Description |
---|---|
| Specifies a list of worlds sky effects that the skybox should be rendered in. |
| Specifies a list of dimension that the skybox should be rendered in. |
| Specifies a list of weather conditions that the skybox should be rendered in. Valid entries are |
| Specifies a list of biomes that the skybox should be rendered in. |
| Specifies a list of coordinates that the skybox should be rendered between. |
| Specifies a list of coordinates that the skybox should be rendered between. |
| Specifies a list of coordinates that the skybox should be rendered between. |
| Specifies the loop object that the skybox should be rendered between. |
| 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.
Name | Description |
---|---|
| Specifies the minimum value, inclusive |
| 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
Name | Description |
---|---|
| Specifies the length of the loop in days. |
| 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.
Name | Description | Default |
---|---|---|
| Specifies the type of the blend or the decorations only. Valid types are: |
|
| Specifies the location of the texture to be used for rendering the sun. | Default sun texture ( |
| Specifies the location of the texture to be used for rendering the moon. | Default moon texture ( |
| Specifies whether the sun should be rendered. |
|
| Specifies whether the moon should be rendered. |
|
| Specifies whether stars should be rendered. |
|
| Specifies the rotation of the decorations. |
|
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