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.
"schemaVersion": 2
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
"type": "monocolor"
2.2 Textured skyboxes
"type": "single-sprite-square-textured"
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
"type": "overworld"
3. Color
This is exclusive to- and is a requirement when using the monocolor type of skybox.
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.
Specifies a UV range object for defining texture coordinates. All fields are required.
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.
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.
This is exclusive to- and a requirement for the two animated skybox types.
"fps": 1
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.
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.
Fade and alwaysOn can be use exclusively.
Conversion table:
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 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.
Specifies when and where a skybox should render. All fields are optional.
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.
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
"yRanges": [ {"min":-128.0,"max":150.0}]
sky2.json
"yRanges": [ {"min":150.0001,"max":200.0}]
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
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.
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.
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.