Environments

Environments define the sun light, atmosphere, water coloring and skybox. The configuration is done in .lua files, which lay in the res/config/environment/ folder. They basically look like this:

function data()
  return {
 
    light = {...},
 
    atmosphere = {...},
 
    water = {...},
 
    skyBox = {...},
    skyRotation = .0,
  }
end

The light block consists of several properties:

• direction is the vector in which direction the sunshine points. It is a unit vector with length 1 where the three values each stand for one axis.
• pmremShadow is a hdr DDS texture file that is used for the calculation of shadow.
• pmremSun is a hdr DDS texture file that is used for the calculation of sunlight.
• refBrightness is a value that adjusts the overall brightness. 10 is the maximum value that results in a darker mood. Values near 0 are very bright while 0 is absolute darkness.

In the real world, the atmosphere usually has a blue sky at daylight and some red colors in the morning and evening at dawn and sunset. This is caused by the rayleigh scattering phenomena. The atmosphere block contains several properties which are used to simulate a similar effect in the game:

• sunColor is a color definition used for the hue of the atmospheric haze.
• rayleightExtinctionCoeff is a coefficient for the calculation of rayleigh effect that has approximately the same intensity in every direction. The value range is from 0 to 1000.
• mieScatteringCoeff is another coefficient, this one is responsible for the mie scattering effect that is more intense in the direction of the sun. The value range is from 0 to 1000 too.
• phaseG is another coefficient in the range between -1 and 1. It is used for the phase function by Henyey and Greenstein, which results in a range between backscattering and forward scattering.
• rayleightScaleHeight is a scaling factor for the rayleigh effect. Possible values are between 0 and 10000.
• mieScaleHeight is a scaling factor for the mie scattering effect. Possible values are between 0 and 10000.

It is recommended to use the ingame debug tools to experiment with the values.

The water effects are adjusted with the properties in the water block:

• normalTex is a texture reference to a normalmap that is used for the wave effects on the water.
• normalScale is a factor to adjust the intensity of the wave effect. 0 results in still water.
• preferLowFreq is a boolean value. If set to true, the watermovement effect is more subtle to simulate still water.
• roughness is another factor to control the roughness of water surface. The higher this factor is, the less reflexion effects will occur on the water surface.
• depthColorTex is a texture reference to a file that contains a set of colors that is used for the deepness effect of water.
• extinctionCoeff is the factor that controls the clearness of the water. 0 is total transparency, 1 is opaque water. The lower the value is, the deeper can be seen through the water.
• waveFoamTex is a texture reference to a texture that shows some waves. If set, there is a shoreline effect with animated foam waves visible.

Most of the properties for water effects can be controlled with the ingame debug tools too.

There are two further properties to control the sky that is shown as a background of the game world. The skyBox.texture property is a reference to the skybox hdr dds texture. This may either be a single file or six seperate files for the six sides of the box with the suffixes _1 to _6. With skyRotation, it is possible to rotate the skybox from -180 to 180 degrees. This turns around shadow drop too.

To get a lighting setup that matches the skybox, the provided EnvironmentMapConverter tool can be used. Use an HDR image file with an equirectangular projection of a skybox with an aspect ratio of 2:1. Make sure the hdr file has a high dynamic range (Multi EV) that is unclipped. The upper half 1 should contain the sky. Normally the portion above the horizon 2 is visible ingame. The other half of the skybox is visible when the player looks from above onto the map and the map edges are visible in the viewport. Therefore terrain 3 in the HDR file should be replaced by sky as well. Follow the steps below to setup the skybox:

1. Drag the file onto the bat to execute the tool once. It will generate a skybox.dds, sun.dds and shadow.dds file next to the hdr file. Additionally the console output tells you the values for the sun direction, color and reference brightness.
2. Put the dds files into your mod and adjust the references and values in your environment config if needed.
3. Start the game with your mod loaded.
4. Position the camera approximately 50 meters above ground in an urban area.
5. Use the Camera Tool to generate a environment cube map with the skybox loaded. You can find the generated files in the screenshot folder in your userdata directory.
6. Drag these 6 files onto the bat file to execute the second run.
7. Put only the sun.dds and shadow.dds file into your mod and keep the skybox.dds from the first run.
8. Repeat the last 5 steps until you have a satisfying result.