Specification

This specification defines a format outlining a set of rules for custom sky rendering. These rules can be organized into 9 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 9 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.

A template resource pack is also provided containing a full day cycle for textures, as well as one of every other type of skybox element to assist you in starting your own pack quickly.

1. Schema version

This object is required.

"schemaVersion": 1

2. Type

There are four types of skyboxes: monocolor-, textured-, decoration-, and vanilla skyboxes. One of the 4 types is required.

"Nuit" can be specified as a namespaced identifier, but it is not a requirement (e.g. nuit:monocolor)

2.1 Monocolor skybox

"type": "nuit:monocolor"

2.2 Textured skyboxes

"type": "nuit:square-textured"

Example for nuit:square-textured skybox.

Example of an animation texture used for the nuit:multi-textured 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 Decoration skybox

"type": "nuit:decorations"

2.4 Vanilla skyboxes

"type": "nuit:overworld"

3. Color

This is exclusive to- and is a requirement for the monocolor skybox type.

"color": {"red": 0.84, "green": 0.91, "blue": 0.72, "alpha": 1.0}

4. Texture

This is exclusive to- and is a requirement for the square-textured skybox type.

"texture": "nuit:sky/skybox.png"

5. Animatable textures

This is exclusive to- and is a requirement for the nuit:multi-textured 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 range. The number of steps in the cycle is defined by the number of rows and columns on the animation texture.

Example for a skybox with 2 animations:

"animatableTextures": [
  {
    "texture": "nuit:sky/anim_texture_1.png",
    "uvRange": {
      "minU": 0.25,
      "minV": 0.25,
      "maxU": 0.5,
      "maxV": 0.5
    },
    "gridColumns": 2,
    "gridRows": 4,
    "duration": 50,
    "frameDuration": {"1": 20, "5": 10}
  },
  {
    "texture": "nuit:sky/anim_texture_2.png",
    "uvRange": {
      "minU": 0.3333,
      "minV": 0.6666,
      "maxU": 0.2,
      "maxV": 0.4
    },
    "gridColumns": 3,
    "gridRows": 5,
    "duration": 10,
    "frameDuration": {"1": 30, "5": 40}
  }
]

5.1 UV range

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. The texture will only appear inside the animated area, the rest of the skybox will be empty.

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. Decorations

These are exclusive to the decorations skybox type. All objects are optional. For optimal results, the Moon texture should use the same layout as the vanilla Moon texture. The Default values store the overworld Sun and Moon textures and sets all enabled to true.

"sun": "minecraft:textures/environment/sun.png"

"moon": "minecraft:textures/environment/moon_phases.png"

"showSun": true

"showMoon": true

"showStars": true

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 moons with different blending and/or rotation, if you assign them to multiple different sky layers.

7. Blend

Specifies how the skybox should blend with the previously rendered sky layer, the vanilla skybox being the first layer. All fields are optional.

Within Nuit, 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.

"blend": {
  "type" : "normal"
}

OR

"blend": {
  "type" : "custom",
  "blender": {
    "sFactor": 0,
    "dFactor": 769,
    "equation": 32774,
    "redAlphaEnabled": true,
    "greenAlphaEnabled": true,
    "blueAlphaEnabled": true,
    "alphaEnabled": false
  }
}

More information on custom blend can be found in the blend documentation.

8. Properties

Specifies common properties used by all types of skyboxes. All objects are optional.

"properties": {
  "layer": 1,
  "fade": { 
    "duration": 24000,
    "alwaysOn": false,
    "keyFrames": {
      "0": 0.0,
      "6000": 0.75,
      "18000": 1.0
      }
  },
  "rotation": {
    "speed": 0.866,
    "mapping": {
      "0": [0.0, 0.0, 0.0],
      "6000": [0.0, 90.0, 0.0]
      },
    "axis": {"0": [0.0, 0.0, 90.0]},
    "skyboxRotation": true
  },
  "transitionInDuration": 200,
  "transitionOutDuration": 300,
  "fog": {
    "modifyColors": true,
    "red": 0.84,
    "green": 0.91,
    "blue": 0.97,
    "modifyDensity": true,
    "density": 1.0,
    "showInDenseFog": true
    },
  "sunSkyTint": true,
  "visibleUnderwater": false
}

As you can see, fade, fog, rotation (and its mapping and axis components) have multiple object within, so let's take a look at those in more detail.

8.1 Fade object

All objects are optional.

When no fade objects are specified, the given sky will be rendered at all times.

8.1.1 Keyframes

When using keyframes, you will need to specify the time of day in ticks, and the opacity the sky at that time. You can add any number of time points in your keyframes. The given times should not exceed the duration however. The opacity values must be within 0 and 1. Since these keyframes are in a loop, your last keyframe will be followed by your first one.

Here's a concrete example of how this will work:

"keyFrames": {
      "0": 0.0,
      "6000": 1.0,
      "18000": 1.0
      }

Conversion table:

8.2 Fog

All fields are optional.

8.3 Rotation Object

All fields are optional.

Mapping allows you to reorient your skybox's default position. For example, you can flip your skybox upside down using this parameter. 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.

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.

In addition, both mapping and axis can be keyframed, to change over time. Please refer to 8.1.1 to see examples for keyframing.

8.3.1 Float vector

Specifies a list of three floating-point literals to represent degrees of rotation.

As seen on the image below, the default axis of rotation ([0,0,0]) is the Minecraft Y axis (up-down axis), and the sky will rotate clock-wise looking directly up from the player's point of view, when using a positive speed value.

To generate different axis or mapping values, a Blender tool has been developed courtesy of @UsernameGeri, allowing real-time visualization and adjustment of both values, providing insights into their impact on the skybox's rotation. This tool is compatible with both Nuit 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/

9. Conditions

Specifies when and where a skybox should render. All fields are optional.

"conditions": {
  "worlds": {"entries": ["minecraft:overworld"]},
  "dimensions": {"entries": ["my_datapack:custom_world"]},
  "weather": {"entries": ["rain", "thunder"]},
  "biomes": {
    "entries": ["minecraft:plains", "minecraft:forest", "minecraft:river"],
    "excludes": true
    },
  "xRanges": {"entries": [{"min": -100.0, "max": 100.0}]},
  "yRanges": {"entries": [{"min": -128.0, "max": 150.0}, {"min": 200.0, "max": 320.0}]},
  "zRanges": {"entries": [{"min": -150.0, "max": 150.0}]},
  "effects": {"entries": ["minecraft:jump_boost", "minecraft:speed"]}
}

Each condition type has an entries and excludes object. The entries contain all the valid information for that specific condition type. Excludes serves a condition inverter, meaning the the sky will be rendered everywhere but the specified condition if set to true.

9.1 Weather

9.2 MinMax Entry Object

These objects are used by the x-y-z range objects. 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.

Below you can see an example for a smooth transition between 2 skies.

sky1.json

"xRanges": [{"min": 0, "max": 4}]

sky2.json

"xRanges": [{"min": 4, "max": 8}]

Examples and template pack

{
  "schemaVersion": 1,
  "type": "nuit:square-textured",
  "texture": "nuit:sky/sky1.png",
  "blend": {"type" : "normal"},
  "properties": {
    "layer": 1,
    "fade": {
      "alwaysOn": false,
      "duration": 24000,
      "keyFrames": {
        "500": 0.0,
        "1500": 1.0,
        "10500": 1.0,
        "11500": 0.0
        }
      },
    "rotation": {
      "speed": 0.0,
      "mapping": {"0": [0.0, 0.0, 0.0]},
      "axis": {"0": [0.0, 0.0, 0.0]}
      },
    "transitionInDuration": 10,
    "transitionOutDuration": 15,
    "fog": {
      "modifyColors": true, "red": 0.0, "green": 0.4, "blue": 0.5,
      "modifyDensity": true, "density": 1.0,
      "showInDenseFog": true
      },
    "sunSkyTint": false
  },
  "conditions": {
    "worlds": {"entries": ["minecraft:overworld"]},
    "dimensions": {"entries": []},
    "weather": {"entries": ["clear", "rain"]},
    "biomes": {"entries": []},
    "xRanges": {"entries": []},
    "yRanges": {"entries": []},
    "zRanges": {"entries": []},
    "effects": {"entries": []}
  }
}

{
  "schemaVersion": 1,
  "type": "nuit:decorations",
  "showSun": true,
  "showMoon": true,
  "showStars": true,
  "properties": {
    "layer": 5,
    "fade": {
      "alwaysOn": true,
      "duration": 24000,
      "keyFrames": {}
      },
    "rotation": {
      "speed": 1.0,
      "mapping": {"0": [0.0, 0.0, 0.0]},
      "axis": {"0": [90.0, 0.0, 0.0]},
      "skyboxRotation": false
      },
    "transitionInDuration": 10,
    "transitionOutDuration": 15,
    "fog": {
      "modifyColors": false, "red": 1.0, "green": 1.0, "blue": 1.0,
      "modifyDensity": false, "density": 1.0,
      "showInDenseFog": true
      },
    "sunSkyTint": false
  },
  "conditions": {
    "worlds": {"entries": ["minecraft:overworld"]},
    "dimensions": {"entries": []},
    "weather": {"entries": ["clear"]},
    "biomes": {"entries": []},
    "xRanges": {"entries": []},
    "yRanges": {"entries": []},
    "zRanges": {"entries": []},
    "effects": {"entries": []}
  }
}