The sky provides a background for a world. A world has at most one Sky objects assigned. Sky objects are build on a layer system to provide a lot of flexibility while working with various kinds of skies. The sky itself contains only a background color. This is the color of all pixels not covered by scene geometry or sky layers. The sky is always located around the camera and moves with it. Therefore the sky layers should only host very far away objects.
Sky Layers provide a container for individual sky elements. Layers can contain a layer skin, sky bodies and a sky light. Layers have an orientation relative to the world coordinate system given by a quaternion. Using this orientation layers can be slowly rotated to simulate day/night cycles or even complex planetary movement if required by the game. Furthermore each layer has a color and intensity parameter. They are used by the layer skin and layer bodies to alter the color and intensity. The intensity is used the same way as in lighting and measures the luminance of the layer components in lumen. A typical daylight sky has roughly 2500 lumen whereas a starlight sky has around 0.1 lumen. Each of the layer components can be specified alongside each other if required. Important to know is that the content of the sky is not influenced by any light cast in the world. Use the intensity parameters to set the proper light level for the sky.
The layer skin maps a sky texture onto the layer covering the entire space around the camera. A typical example for a sky texture could be a sky box as used with many games. Since there exist various ways to handle such sky textures the Drag[en]gine adopts a simple yet flexible way to define sky textures. The names of the textures in the assigned Skin object determine what kind of sky texture has to be used. The advantage of this system is the same as the one for texture properties in Skin objects. The game engine is not required to know anything about the used system at all. What a given texture name means is simply a contract between the game artist and the Graphic Module. This way new sky texture ways can be implemented without having to change anything except the Graphic Module. The possible names and how they work are explained in the Sky Skin Listing. The color and intensity of the Sky Layer is multiplied with the used textures. Typically for the first layer ( which is sort of the furthest away layer ) skins are used which are not transparent covering the entire sky. For all other layers typically transparent skins are used to overlay elements like clouds, distant geological formations or distant structures. Sky Layers are fully rendered so there is no need to worry about clipping issues. Important to know is that only the color and transparency texture property are used for rendering.
A Sky Body is simply a celestrical body which is pinned to the Sky Layer. A typical example is the sun or moon. Each body has a skin, a size, an orientation, a color and an intensity assigned. The skin defines the texture to be used for the body and is typically transparent. The first texture in the skin is used ( this might change in the future ). The size indicates how large the body is drawn and is measured in radians. This is comparable to the view angle used in astronomic under which a celestrical body can be seen. Therefore using values from astronomic tables yields good results to start with. By default the body is located along the positive Z axis. Usually this is enough since the rotating of the Sky Layer rotates the body too. If though for some reason the body has to be offseted from this position the orientation quaternion can be used. This is useful if you have for example multiple bodies which belong though all to the same celestrical body to avoid wasting texture space. The color and intensity are multiplied with the texture. This allows to tint bodies if required. The color and intensity of the Sky Layer are multiplied first with the Sky Body color and intensity before being used during rendering. As a rule of thumb the intensity of a Sky Body should be roughly 40 times the intensity of the light it emits. Therefore if a Sky Layer uses a sky texture of 2'500 lumen intensity ( which is caused by the diffuse reflection of the sky body light ) the respective sky body itself should have 100'000 lumen. Now you know why the sun burns your eyes if you look straight at it.
In addition to the graphic representation a Sky Layer can also emit light. The emitted light is always directional along the negative Z axis of the Sky Layer. The direction of the light is fixed to the Sky Layer itself since there can be only one light per layer and having an additional light orientation does not add anything worthwhile. If you need a separate orientation for your sky light simply use a second Sky Layer with no skin and bodies but just the light and sync the orientation with the main Sky layer. The sky light has only a color, diffuse intensity and ambient intensity parameter. To stick with our example a sky light for a sun at 100'000 lumen should have 40 times less diffuse intensity, therefore 2'500 lumen similar to the layer skin. The diffuse intensity indicates the intensity of light applied to objects directly hit by the sky light. The ambient intensity indicates the intensity of light applied to objects in partial or full shadow. Typically the ambient intensity is roughly 10-20 percent of the diffuse intensity. Sky lights have the tendency to be rather time consuming ( especially the shadow casting ) since they illuminate the entire world in contrary to local light sources having a limited area of effect. Therefore you should use only 1 sky light if possible but the number itself is not limited.