Dark Skies Atmosphere Documentation

Material based solutions are not available for shader models lower than SM5.

Modifying variables that have a slider such as a float range or the color wheel will cause the material based Heavenly Bodies to constantly update resulting in the GPU memory being filled up. This is purely an Editor issue. Setting PreviewHeavenlyBodiesMaterials value to false will prevent this from happening by only rendering a single low resolution material based Heavenly Body. Set it to true when you want to preview material based Heavenly Bodies in the editor. Set this to false before modifying any variables using sliders. Alternatively you can keep this variable set to true indefinitely and simply type your desired variable value into the value fields instead of sliding the sliders or dragging the color wheels.

The built in system of one to six Heavenly Bodies automatically culls any excess Heavenly Bodies from the array entry. If you are using a custom amount then be mindful of making the array length match the amount the custom material was setup for.

The demo character requires the Enhanced Input system to be enabled which is disabled by default in Engine versions 5.0.3 and below. If the required Enhanced Input Plugin is not enabled and both the DefaultPlayerInputClass and DefaultInputComponentClass are set not to use the Enhanced Input classes then the demo character will not function properly

The map Map_DSA_Overview found within Content/Jawadato/DarkSkiesAtmosphere/Examples/Overview/Maps/ showcases some of the functionalities of the system. It’s recommended that you check out that map.

The system is controlled by a single actor – BP_DarkSkiesAtmosphere which is located in the Content/Jawadato/DarkSkiesAtmosphere/Blueprints/ directory. Drag and drop that actor into your scene. You should ensure you do not have any other skysphere or similar system in your scene. You can pair heightfog, skylight and directional lights with the system to achieve more interesting scenes. The most common modifiable variables that will give you immediate customization reside within these categories – Atmosphere, Space and of course Heavenly Bodies.

The system contains a lot of customization options. The variables all have tooltip on them, hover your cursor over a variable and a short description should appear.

The quickest way to change the overall appearance of the atmosphere is to change the color variables found near the bottom of the Atmosphere category. Go through the Atmosphere and Space category and modify the variables to change the overall appearance of the system.

Before modifying anything in the Heavenly Body category, it is recommended that you read the section dedicated to that category. To add a new Heavenly Body to the sky such as a sun or a moon, simply add a new entry to the array HeavenlyBodiesSetup.

Ensure to read the section regarding the Editor category first before moving onto the Heavenly Bodies.

Expand each category to check it’s detailed explanation.

The overview map is called Map_DSA_Overview and is located in the Content/Jawadato/DarkSkiesAtmosphere/Examples/Overview/Maps/ directory. The Examples directory also contains other example maps. The entire Examples folder can be deleted without affecting the core system.

The settings under the Editor category only applies to the Editor and does not affect the system during runtime.

The most important part is the PreviewHeavenlyBodiesMaterials variable which determines whether to preview any material based Heavenly Bodies. The reason this is set to false by default is because the Editor as it currently stands, suffers from a drawback. Modifying variables that have a slider such as a float range or the color wheel will cause the material based Heavenly Bodies to constantly update resulting in the GPU memory being filled up. This is purely an Editor issue. Setting this value to false will prevent this from happening by only rendering a single low resolution material based Heavenly Body.

Set this to true when you want to preview material based Heavenly Bodies in the editor. Set this to false before modifying any variables using sliders. Alternatively you can keep this variable set to true indefinitely and simply type your desired variable value into the value fields instead of sliding the sliders or dragging the color wheels.

The PreviewEditorTime controls whether to preview the custom DSA time which replaces the default time in materials. In Editor, the DSA time will not flow, it only flows during runtime however this could be useful to see how the initial panner textures look.

The system uses it's internal passage of time to update any materials that has panning textures to keep it deterministic and compatible with the save system. However that time only starts flowing at the start of the play session. Which is why the editor provided default time is used for previewing the passage of time related texture updates while in the editor. Turning this off will stop the preview of the passage of time based on editor's time. This option only exists for preview purposes, setting it to either true or false has no effect on gameplay.

The variables that exist within the initial section of the Heavenly Bodies category initializes global settings for the Heavenly Bodies. These variables are – Render target texture format DynamicRenderTargetFormat, determining the number of Heavenly Bodies HeavenlyBodiesCount to display, choosing whether to use a predefined or custom skysphere material CustomDomeMaterial, setting intervals for updating the positions of runtime Heavenly Bodies RuntimeOrbitalUpdateIntervals, enabling automatic inversion of Heavenly Body's scale based on it's position in the sky AutoFlipHeavenlyBodies.

Each array entry within the HeavenlyBodiesSetup array counts as an individual Heavenly Body, and each of them contains it’s own unique set of variables. Once a new Heavenly Body has been added to that array, you can then expand it to expose additional settings specific to that particular Heavenly Body.

Identifier is an automatically generated string used to identify the Heavenly Body, this cannot be changed by the user however it’s very useful because it is this identifier that you will use when calling various runtime functions to modify a particular Heavenly Body’s behavior. Type lets you choose between texture based and material based Heavenly Body. Texture based uses a single texture for the Heavenly Body, while material based utilizes a material and updates in real time based on the provided interval time, allowing for animated materials. However, material based solutions are not available for shader models lower than SM5. StaticTexture is the texture asset to use for texture based Heavenly Bodies, while DynamicMaterial is the material to use for material based ones. Scale sets the arbitrary scale of the Heavenly Body on the sky and Rotation defines its rotational percentage value. CloudClearence determines how much of the clouds should be cleared when a Heavenly Body is behind the clouds. Color is the visual color of the Heavenly Body but does not modify its lighting if it has an associated directional light. MaterialResolution is the resolution at which to render the Heavenly Body if it is material based; adjust it accordingly based on the size of the body. For texture based Heavenly Bodies, set the resolution directly on the texture. CloudsBacklightIntensity controls how much the Heavenly Body lights up the clouds around it; the mask is radially distributed from the center of origin of the Heavenly Body in the sky and cannot be further customized. The radius of this mask scales linearly with the Heavenly Body scale. Phase indicates the current phase of the Heavenly Body. PhaseAngle is the rotational percentage value of the mask used for the phase of this Heavenly Body. Planetshine determines the indirectly lit portion of the Heavenly Body when it has a partial phase. DynamicUpdateIntervals specifies the update intervals used to refresh a material on material based Heavenly Bodies, setting this variable to zero disables the automatic update of the material entirely. DirectionalLight associates a directional light with the Heavenly Body. UseCoverageDependentIntensity allows the intensity of directional lights if present to change based on cloud coverage changes. The CoverageDependentIntensityCurve float curve asset controls how intensity changes in response to cloud coverage changes provided previous variable is checked. CoverageDependentIntensityMultiplier provides an extra multiplier to fine-tune the relationship between cloud coverage and light intensity.

CustomOrbitalRotation comes into play when OrbitalSetup is set to UseCustomRotation, allowing you to manually specify the rotation of the Heavenly Body. OrbitalSetup determines how the Heavenly Body's position on the sky is calculated. CopyDirectionalLight follows the rotation of any associated directional lights while UseCustomRotation uses the specified value set forth in CustomOrbitalRotation directly.

RuntimeOrbit is the advanced option which updates the position dynamically using a vector curve. This is the option you will use when creating a day night cycle using vector curves. Alternatively you can create a simple day night cycle by using CopyDirectionalLight and directly updating the rotation of the associated directional light externally.

Expanding RuntimeOrbit allows you to configure additional orbit related settings for the Heavenly Body. This only applies when the OrbitalSetup is set to RuntimeOrbit.

Now expanding the RuntimeOrbit – First let’s discuss the OrbitalCurve variable which stores a vector curve asset that determines the orbital position of the Heavenly Body as a function of orbital percentage on the time axis and the orbital literal rotation values on the vector values. Add a new key and modify the vector key’s X,Y,Z values to your liking. These values are directly converted to a rotational value Roll, Pitch, Yaw. You can survey ideal rotational values and copy them over to the curve asset by temporally setting RuntimeOrbit to UseCustomRotation mode and testing desirable location for the Heavenly Body on the sky by modifying the CustomOrbitalRotation. The curve goes from 0 to 1 in time dimension which completes a full orbit based on the orbital cycle duration.

For an example of a two body system with a sun and a moon, you would set the sun to rise and set from 0 to 0.5 and the moon to rise and set from 0.5 to 1. Meanwhile the sun will orbit below the horizon from 0.5 to 1 and come back at the position to get ready for the next cycle of sunrise and same for the moon which will orbit below the horizon from 0 to 0.5. This assumes you have a perfect two body system where the moon only rises once the sun sets. You can create much more complex orbital situations. Refer to the Sanctuary example level, it has a two body day-night cycle.

CycleDurationSeconds specifies the time taken to complete a full geocentric orbit in seconds. The current orbital percentage is determined by CyclePercentage, which goes from 0 to 1. This simply means the position on the vector curve, assuming the curve’s time goes from 0 to 1. The AutoUpdate flag enables automatic update of the position on the curve based on the cycle duration. Additionally, DisableDirectionalLightBelowHorizon allows you to disable directional lights associated with Heavenly Bodies when they dip below the horizon. ZenithColorCurve(Multiplier) specifies the linear color curve used to determine the zenith color of Heavenly Bodies as a function of orbital percentage, which is multiplied by the preexisting zenith color when using runtime orbit. All the vector color curves are multipliers to correctly blend when using multiple Heavenly Bodies, each with their own color curves. If you do not wish for a particular Heavenly Body to contribute to the multiplication then simply use a white color+alpha curve 1,1,1,1 which will multiply itself as 1 with the rest of the color curves without contributing to changing previous colors. HorizonColorCurve(Multiplier) controls the color of the horizon as a function of orbital percentage, while CloudsColorCurve(Multiplier) does the same for clouds. Similarly, SkylightColorCurve(Multiplier) determines the color of the associated skylight (if any), and HeightFogColorCurve(Multiplier) sets the color of the exponential height fog. CloudsBacklightCurve(Multiplier) is a float curve which adjusts the backlight color intensity of clouds as a function of orbital percentage.

These color and float curves only apply when using the runtime orbit mode. All these curves are multiplied by the preexisting curves to achieve the desired blend between multiple Heavenly Bodies.

You can control the zenith color ZenithColor, horizon color HorizonColor, cloud color CloudsColor, skylight color ReferencedSkylightColor, and fog insceattering color ReferencedFogInscatteringColor by modifying these color variables. However if the mode is set to RuntimeOrbit then these values will be automatically set to white 1,1,1,1 so they do not affect the curves used in Heavenly Bodies when multiplied against.

There are various other settings to customize the atmosphere further. These options include disabling the horizon DisableHorizon, mirroring clouds below the horizon MirrorClouds, allowing cloud coverage to reduce illumination CoverageAffectsIllumination, controlling the amount of sky covered by clouds CloudsCoverage, adjusting the intensity and tiling of clouds micro-details textures CloudsDetailsIntensity and CloudsDetailsTiling, controlling the tiling of clouds coverage textures CloudsCoverageTiling, defining panning speeds and fluid motion speeds for clouds CloudsSpeed and CloudsFluidSpeed, scaling arbitrary fluid motions for clouds CloudsFluidScale, enabling clouds vortex CloudsVortex, and setting the vortex rotational rate for clouds CloudsVortexRate.

You can control the visibility and coverage effects of background clouds BackgroundCloudsVisibility and BackgroundCloudsUseCoverage, the panning speed BackgroundCloudsSpeed, the falloff effect for the horizon HorizonFallof, the rotation rate and visibility of horizon clouds HorizonCloudsSpeed and HorizonCloudsVisibility, the horizontal position of horizon clouds HorizonCloudsVerticalPosition, the modifier value manipulating the visibility of horizon clouds HorizonCloudsExponent.

These two variables apply to the whole sky – The additional saturation added to the entire sky AdditionalSaturation, and the overall brightness of the sky OverallBrightness.

Configuring the Galactic Center, star field, and dust clouds allows you to fine-tune the appearance of the space to your liking. You can specify the color of the Galactic Center GalacticCenterColor, color of the dust clouds GalacticCenterDustColor, and overall tint GalacticCenterOverallColor.

Additionally, you can choose whether to mirror stars below the horizon MirrorStars, control the visibility of star fields StarsVisbility, vary the colors of stars by a specified percentage StarsColorVariation, and use different texture channels for stars StarsTextureVariation. You can also adjust the panning of the star field StarsPan for more variation.

You can control the frequency of nebulae NebulaeFrequency, vary their colors NebulaeColorVariation, adjust their intensity NebulaeIntensity, and pan them NebulaePan.

You can mirror the galactic center below the horizon MirrorGalacticCenter, invert its horizon mask InvertGalacticCenterHorizon, control its visibility GalacticCenterVisibility and GalacticCenterStarsVisibility, and brighten it GalacticCenterBrightness. You also have options to make the galactic center's dust clouds more or less visible GalacticCenterDustIntensity, rotate the galactic center arbitrarily GalacticCenterRotation, scale it arbitrarily GalacticCenterScale, stretch it along its elongated axis GalacticCenterLength, pan it GalacticCenterPan and increase the brightness of the whole space SpaceBrightness.

You can use custom textures in place of textures used for various objects like clouds, background clouds, horizon clouds, star fields, nebulae, and the galactic center. Each object type has specific texture slots where you can assign RGBA Red Green Blue Alpha channel packed textures.

For the CloudDetails, BackgroundClouds and HorizonClouds, you can use a 4 channel texture, each channel providing variation. You can specify to use a single channel or use AutoLerp to automatically interpolate between the channels by the rate set forth in LerpPeriod.

The CoverageTexture is unique in the sense that it’s RGBA channel goes from least coverage to most coverage.

The StarFieldTexture and NebulaeTexture only uses RGB channels for variation while the A channel is reserved for color variations.

The GalacticCenter texture is much more specific and it is recommended that if you want to create a custom texture for that slot then you export the existing texture and study it’s individual channels.

You can associate skylights and exponential height fogs to the system. These can help create more interesting atmosphere. Simply drag and drop either or both of these actors into the level and assign them to the system.

The Runtime Orbital mode will then update the colors on these according to the linear color curves assigned to them.

Additionally, you can enable periodic recapture of the skylight by checking the PeriodicallyRecaptureSkylight variable. The intervals at which the recapture function is called is determined by RecaptureIntervals You also have the option to trigger the recapture functions at startup using RecaptureSkylightOnStart. Note that periodic recapture of the skylight will cause hitches and it’s not avoidable, use with caution.

State Transitions are a powerful tool that allows you to update the sky at runtime using only a single function RuntimeTransitionToOrbitalsState. You can add a new array entry to the TransitionStates variable and give it a unique name. Each entry will count as an individual state.

You can then specify which of the Heavenly Bodies you will like to update. Note that State Transitions only work with Heavenly Bodies which are set to use RuntimeOrbit and already has a valid orbital curve setup. Once you have added the identifier of the Heavenly Bodies that you wish to update in the AffectedHeavenlyBodies, the float next to the identifier will determine the desired orbital percentage of this Heavenly Body when fully transitioned into this state.

You may also wish to update the cloud coverage as part of the State. Once done, call the function RuntimeTransitionToOrbitalsState during gamepaly with a reference to the Dark Skies Atmosphere Actor. You can define the transition duration or you can also use a custom transition float curve. Check out the Demonstration example map, the eclipse uses Runtime State Transitions.

Saving and loading the system is straightforward and done with just two simple functions, AttemptToLoadDarkSkiesAtmosphereFromSlot and AttemptToSaveDarkSkiesAtmosphereToSlot. Simply call these functions when necessary and supply the intended slot.

You can expand the system to support more than the built in 6. First find the material function called MF_HeavenlyBodies_6Total which is located in Content/Jawadato/DarkSkiesAtmosphere/Materials/Functions/HeavenlyBodyInputs/ directory. Duplicate that material function and rename it to MF_HeavenlyBodies_7Total or to as many heavenly body as you need. Open this new material function. Scroll down till you see the commented section Copy paste these. Copy and paste those nodes, each blocks of nodes are responsible for a unique Heavenly Body, so copy paste as many as you need.

Rename the parameters accordingly. Notice the once you copied from, they had the prefix HeavenlyBody_5. Which refers to the sixth Heavenly Body since the index starts at 0. So in your new blocks of nodes, replace the HeavenlyBody_5 in each parameters to HeavenlyBody_6. Then in your next block change those to HeavenlyBody_7 and so on.

For clarity, as an example, HeavenlyBody_5_A should be renamed to HeavenlyBody_6_A and so on. Ensure to rename all 5 vector parameter and the single texture parameter so a total of 6 nodes for each additional Heavenly Body that you wish to add.

Once you have the renamed nodes, you need to connect them up to the rest of the material, it may seem daunting but it’s pretty straight forward. Study the pattern in which each of the node blocks are connected. CameraVector comes from the function input CameraVector(Vector3). So connect that to the CameraVector input of the MF_HeavenlyBody material function.

Study the BlendMaterialAttributes node of the previous Heavenly Body HeavenlyBody_5. Note that an empty GetMaterialAttributes is connected to the A input of this node. Replace the empty GetMaterialAttributes with the BlendMaterialAttributes node’s output of the newly created Heavenly Body HeavenlyBody_6. Now you have effectively expanded the system to support 7 Heavenly Bodies instead of previous six. You can continue expanding, each time replacing the empty GetMaterialAttributes node with the output of the new Heavenly Body.

We are done with the complicated bit however you still need to tell the system to use this new material function so for that you will need to create a new custom material but it’s straightforward to do so. Head over to the Content/Jawadato/DarkSkiesAtmosphere/Materials/Skysphere/ directory and duplicate the M_DSA_6HeavenlyBodies material. Rename it to something akin to M_DSA_7HeavenlyBodies. Open it and simply replace the MF_HeavenlyBodies_6Total material function with the newly created MF_HeavenlyBodies_7Total material function.

Now select the Dark Skies Atmosphere actor in the level and scroll up to the Heavenly Bodies section. Set the value of HeavenlyBodiesCount to Custom and set the value of CustomDomeMaterial to the newly created M_DSA_7HeavenlyBodies material. And that it, that’s all you need to do to expand the system to support more Heavenly Bodies.

Note that when using the built in system of one to six Heavenly Bodies, the system automatically culls any excess Heavenly Bodies from the array entry. If you are using a custom amount then be mindful of making the array length match the amount the custom material was setup for.

The following runtime functions are available. Target is a reference to the Dark Skies Atmosphere Actor.