# 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. ```json "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

Name	Description
`nuit:monocolor`	Shows a single plain color for the full skybox.

```json "type": "nuit:monocolor" ``` ### 2.2 Textured skyboxes

Name	Description
`nuit:square-textured`	uses a 3:2 aspect ratio texture file for the skybox
`nuit:multi-textured`	uses a grid of textures- arranged in a single texture atlas- for an animation

```json "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

Name	Description
`nuit:decorations`	Shows the Sun, Moon and Stars.

```json "type": "nuit:decorations" ``` ### 2.4 Vanilla skyboxes

Name	Description
`nuit:overworld`	This will show the overworld's skybox.
`nuit:end`	This will show the end's skybox.

```json "type": "nuit:overworld" ``` ## 3. Color This is exclusive to- and is a requirement for the `monocolor` skybox type.

Name	Description	Required	Default
`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`

```json "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.

Name	Description
`texture`	Specifies the directory for the texture file.

```json "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.

Name	Description	Required
`texture`	Specifies the location of the texture to be used when rendering the animation	✔️
`uvRange`	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: ```json "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.

Name	Description
`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. 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.

Name	Description
`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. 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.

Name	Description	Default
`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`

```json "sun": "minecraft:textures/environment/sun.png" ``` ```json "moon": "minecraft:textures/environment/moon_phases.png" ``` ```json "showSun": true ``` ```json "showMoon": true ``` ```json "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.

Name	Description	Default
`type`	Specifies the type of the blend for the skybox only. Valid types are: `normal`, `lighten`, `screen`, `dodge`, `add`, `darken`, `multiply`, `burn`, `subtract`, `replace`, `decorations`, `disable` and `custom`.	`add`
`blender`	only use this when using the `custom` blend type	`-`

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

Name	Description	Default
`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](https://github.com/FlashyReese/nuit/blob/1.19.x-dev/docs/blend.md). ## 8. Properties Specifies common properties used by all types of skyboxes. All objects are optional.

Name	Description	Default
`layer`	Specifies the order which skybox will be rendered. If there are multiple skyboxes with identical layer number, those skyboxes will be loaded in alphabetical order.	`0`
`fade`	Controls the opacity of the skybox based on the in-game time.	-
`rotation`	Specifies the rotation speed and angles of the skybox.	-
`transitionIn` `Duration`	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`
`fog`	Includes all fog specification. See below for more details.	`-`
`sunSkyTint`	Specifies whether the skybox should disable sunrise/set sky color tinting.	`true`
`visibleUnderwater`	Whether the sky should render when the player is under water.	`true`

```json "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.

Name	Description	Default
`duration`	Duration of the loop in ticks that the keyframes will cycle through.	`24000`
`keyFrames`	Controls when and what opacity the skybox should have.	-

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. | Name | Description | | :---: | :---------------------------------------: | | 0 | Opacity of the skybox at 0 tick time. | | 6000 | Opacity of the skybox at 6000 tick time. | | 12000 | Opacity of the skybox at 12000 tick time. | Here's a concrete example of how this will work: ```json "keyFrames": { "0": 0.0, "6000": 1.0, "18000": 1.0 } ```

Conversion table:

Time in Ticks	Clock Time
0	6 AM
6000	12 AM
12000	6 PM
18000	12 PM

### 8.2 Fog All fields are optional.

Name	Description	Default
`modifyColors`	Whether the fog color should be changed.	`false`
`red`	Specifies the amount of red color to be used for rendering the fog. Must be a value between 0 and 1.	`0`
`green`	Specifies the amount of green color to be used for rendering the fog. Must be a value between 0 and 1.	`0`
`blue`	Specifies the amount of blue color to be used for rendering the fog. Must be a value between 0 and 1.	`0`
`modifyDensity`	Whether the fog density should be changed.	`false`
`density`	Specifies the density of the fog. Must be a value between 0 and 1.	`0`
`showInDenseFog`	Whether the skybox will display in dense fog (ex. Nether and boss overlay)	`true`

### 8.3 Rotation Object All fields are optional.

Name	Description	Default
`mapping`	Rotates the default template layout as seen in the `square-textured` skybox type	`[0,0,0]`
`axis`	Specifies the axis of rotation in degrees	`[0,0,0]`
`speed`	Specifies how many rotations the skybox will do per day. Negative values can be used for reverse rotation.	`0`
`skyboxRotation`	During sunset/rise, the rotation speed for the sun/moon will slow down/speed up. This object can toggle this behavior.	`true`

`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. {% file src="" %} Blender is a free, open source software. Download at ## 9. Conditions Specifies when and where a skybox should render. All fields are optional.

Name	Description
`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`, `thunder`, `rain_biome`, `rain_thunder`, `snow` and `snow_thunder`.
`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.
`effects`	Specifies a list of player status effects during which the skybox should be rendered.

```json "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`. | Name | Description | Required | Default value | | :--------: | :-----------------: | :------: | :-----------: | | `entries` | contains conditions | ✔️ | `-` | | `excludes` | inverts conditions | ❌ | `false` | In addition, `nuit:default` can be used for `worlds`, `dimensions` and `biomes` which will become activated whenever there are no skies active in a given place. ### 9.1 Weather

Name	Description
`clear`	No precipitation
`rain`	World is raining only. No precipitation, i.e. desert biome
`thunder`	World is raining and thundering. No precipitation, i.e. desert biome
`rain_biome`	World is raining only. Rain precipitation, i.e. plains biome
`rain_thunder`	World is raining and thundering. Rain precipitation, i.e. plains biome
`snow`	World is raining only. Snow precipitation, i.e. snowy plains biome
`snow_thunder`	World is raining and thundering. Snow precipitation, i.e. snowy plains biome

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

Name	Description
`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. Below you can see an example for a smooth transition between 2 skies. **sky1.json** ```json "xRanges": [{"min": 0, "max": 4}] ``` **sky2.json** ```json "xRanges": [{"min": 4, "max": 8}] ```

## Examples and template pack

Textured example

```json { "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": []} } } ```

Decorations example

```json { "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": []} } } ```

{% file src="" %}