Author Topic: Guide to Blockland Environments  (Read 9219 times)

Guide to Blockland Environments

Blockland environments are comprised of four parts: the ground, the water, the sky, and the day cycle. These four parts are all separate add-ons so you can easily pick and choose the ones you want. In this guide I will explain the creation process of these add-ons and the usage of the Environment Editor. I will not go into the creative process behind textures or how to use an image editor, but I will explain a few technical details regarding these. It is up to you learn the skills required to create something on your own. Or have the Googling skills to find something useful on the public domain.

Table of Contents

Environment Editor

The Environment Editor is the graphical user interface (GUI) that is used to modify the environment. To access the editor you must be a Super Admin or the Host on a server. Press Escape then Admin Menu or alternatively press Ctrl + A to open the Administrator Menu. When in the Administrator Menu press the Environment >> button to access the Environment Editor.


  By default this tab is open. It is as the name suggest a quick and easy way to change the sky, water, and ground. Simply click the images to open a list of available skies, waters, or ground and select a one that you like.

Skies come with preset settings that change the lighting, fog, visibility, and vignette.

Waters have their own settings that only change water properties

Grounds simply change the ground texture.


  The advanced tab allows for finer control over the environment.

Enabling a day cycle disables the manual editing of the following settings: sun elevation, direct light, ambient light, shadow color, sun flare color, sky color. These are controlled by the day cycle file.

Since the game is still a little buggy quite often you find yourself in a situation where you have loaded a sky but the lighting is all wrong. This happens because the advanced tab seems to save the settings of the previous sky and does not load the values from the newly selected sky when switching tabs. Simply press the Reset button to load the settings from the currently selected sky's file.

The settings in this tab are quite self-explanatory so I don't feel the need to explain them but I would like to clarify a few things.

In color selectors the fourth slider A is for alpha. It changes the transparency of the color. This slider is not always available. Changing the alpha of the ground texture to 0 makes it fully transparent and shadows are no longer cast on it. This allows space skyboxes to work as intended.

The day length is in seconds and the maximum value is 86,400 which is 24 hours.

Checking the multiply checkbox next to vignette color tints the entire screen with that color instead of just the edges.

Textures in General

The maximum resolution for a ground, sky, or water texture is 2048x2048 pixels. Supported file formats are JPG and PNG. JPEG and JPE are not supported. Transparency is allowed.

2048x2048 textures would indeed look the best but you have to keep in mind the file size. Making your server players download huge images for several minutes is a sure fire way to make them disconnect. Here I have compared the file size of one image at several resolutions and both formats. The texture was procedurally generated and not scaled using an image editor so there is no quality or color information loss.

Format  Resolution  Size
     Remember that it is best to adjust the JPG quality on a case-by-case basis. Some of the textures I have released are saved at JPG quality level 7 and they look just fine. Some textures I don't even dare to save as JPG as I wish to keep maximum quality.

As you can see JPG produces files with the smallest size but the file format is not lossless so some grain and artifacts are included. However depending entirely on your texture and the quality at which you saved these minor defects do not matter at all. I saved the image used in the comparison at quality level 9 which is what I most commonly use. It gives a nice balance between file size and quality but you should still try out other quality levels and see what works best for the texture you have.

For ground and water textures 256x256 and 512x512 are quite fine. Anything larger or smaller than that is unnecessary. As for skies I would suggest 512x512 and 1024x1024 resolutions preferably as PNG images to preserve the quality. Grain and artifacts look especially ugly in the sky where the image is greatly enlarged.

All textures, be it ground or sky, need a thumbnail image. This thumbnail must in JPG format, 64x64 pixels, and named TextureName-thumb. This thumbnail is displayed in the Environment Editor.

Creating Grounds

As I stated earlier I will not go into how to create the textures. This is not an image editing guide. The creative process is up to you. Once you have your texture and thumbnail ready, let's begin.

Create a folder named Ground_TextureName and change "TextureName" to whatever you wish. This name is only displayed in the add-on list. Move your texture and your thumbnail into this folder. Next we will need a .ground file. Yes. The file extension is ".ground" but worry not, it is a plain text file. The easiest and fastest way to get one is a copy it from another add-on. Just remember to give it the same name as your texture. This is what it could look like.

Code: [Select]

$Ground::topTexture Add-Ons/Ground_Example/example.jpg

$Ground::scrollSpeed 0 0

$Ground::loopsPerUnit 0.5

$Ground::Color 1.0 1.0 1.0 1.0

$Ground::ColorMultiply 1
$Ground::topTexture     The path to your texture.
$Ground::scrollSpeedMakes the ground texture move. It goes from -10 to +10 and the first value is X axis and the second one Y axis. The units are Torque Units per second. 1 Torque Unit is 2 studs.
$Ground::loopsPerUnitThe size of the texture. Value of 2 makes the texture one stud in size.
$Ground::ColorColor of the texture. White renders the texture as is without coloring it. The fourth value is alpha or transparency. It accepts decimal colors (0.0 : 1.0) and RGB colors (0 : 255).
$Ground::ColorMultiplyAllow (proper) coloring of the texture through the Environment Editor. If this is set to 1 you can only change the hue of the texture through the editor. If it is set to 0 the entire texture is colored.

Recoloring Grounds
All ground textures can be recolored through the Environment Editor. How the texture color changes depends on the value of the $Ground::ColorMultiply variable. The texture's color also affects the coloring. Grayscale textures change color very well. Colored textures not as well as grayscale ones. If your texture only has one color (Say grass or dirt.) it might be best to make the texture grayscale and color it through the ground script.

I explained above that you can change the hue or the color of the texture. What do they mean? Here is a random texture I chose because it had several colors.

On the left is the original texture.
In the middle we have a hue shifted texture. This is what the texture would look like in game if someone changed it's color and the color multiply variable was set to 0.
On the right is what the texture would look like after coloring if it was grayscale and the color multiply was set to 1.

When you're ready to release make sure you have three necessary files. You can have multiple textures in one add-on.
Quote from: Files you should have in your Ground_TextureName ZIP
TextureName.jpg / TextureName.png
That's all you need. ZIP it up and release away!

Creating Waters

The process of creating water textures is essentially the same as creating ground textures. The differences are that the file extension is ".water", the folder is called "Water_TextureName", and you have 4 new variables to play with.

Code: [Select]

$Water::topTexture Add-Ons/Water_Example/Example.jpg
$Water::bottomTexture Add-Ons/Water_Example/Example.jpg
$Water::ScrollSpeed 0 0
$Water::loopsPerUnit 0.05
$Water::color 1.0 1.0 1.0 0.7
$Water::overlayColor 223 64 2 255
$Water::height 5
$Water::kill 1
$Water::bottomTexture  The texture visible on the surface of the water when viewed from underwater.
$Water::overlayColor  Color of the screen overlay when underwater. Once again accepts decimal and RGB colors. For whatever reason settings the fourth value (alpha) to 255 or 1.0 does not make the underwater color solid. There is still some transparency.
$Water::height 5Height of the water in Torque Units. 1 brick is 0.6 Torque Units tall.
$Water::kill 1Toggle whether the water does damage to players when they touch it. 1 for yes and 0 for no.
The scroll speed variable in ground files is purely a visual effect. With waters the effect, however, is not merely visual but it actually moves the player with the water at the speed defined in the water file. That is really all there is to it. Just remember to name your files correctly!
Quote from: Files you should have in your Water_TextureName ZIP
TextureName.jpg / TextureName.png

Creating Skies

Skies are a whole new ball game. You are not only creating the sky textures but also defining some the most prominent features of an environment like the lighting and sun flare. The creation process for a skybox is completely different from other textures, you need more than one texture, and need to pay special attention that everything is seamless so as not to ruin the illusion. A skybox is exactly what it sounds like. A cube with 6 faces and 6 textures. It doesn't look like a cube because of the special methods used to create them and the way they are used in games. Google around for tutorials on how to create them.

A skybox could be composed anywhere from 2 to 6 images. Most commonly they have 6 images that cover all 6 faces of the cube. Once you have your images you need to define which cube faces get what images. This is done using a .DML file which is also a plain-text file that you can easily copypaste from other add-ons. This is what a DML file could look like.

Code: [Select]
  The names in the file must correspond to the names of the images but without the extension. Here I've named the images with descriptive names but the names themselves are irrelevant. The line at which each image name is on determines it's location on the skybox. On the left is a "technically correct" skybox where the "front" image is mapped to +Y axis, "top" to +Z axis and so forth. This is technically how you should map the images to the skybox but in reality it doesn't matter at all.

As long as your "front" image is on the left side of your "right" image it doesn't matter what cube faces they are mapped to. It usually takes a bit of trial-and-error to get a skybox to work as it should. If the images are not mapped correctly it is very obvious as you can clearly see the seams between the images. When a skybox is mapped correctly there are no seams and it looks like you are inside a never ending world.

Now that you have mapped the skybox correctly we need an .atmosphere file. These are the variables you can play with. I have only explained the variables that I believe need some describing. "Fog color" is pretty self-explanatory, right?

Code: [Select]
$Sky::visibleDistance 1000
$Sky::fogDistance 800
$Sky::fogColor 0.9 0.9 0.9

$Sky::sunAzimuth 0
$Sky::sunElevation 45
$Sky::sunFlareColor 1.0 1.0 1.0 1.0
$Sky::sunFlareSize 0.2
$Sky::sunFlareTopTexture base/lighting/lightFalloffMono.png
$Sky::sunFlareBottomTexture base/lighting/corona.png

$Sky::directLightColor 0.7 0.7 0.7 1.0
$Sky::ambientLightColor 0.5 0.5 0.5 1.0
$Sky::shadowColor 0.3 0.4 0.45 1.0
$Sky::skyColor 1.0 1.0 1.0 1.0

$Sky::cloudHeight0 0.0
$Sky::cloudHeight1 0.0
$Sky::cloudHeight2 0.0
$Sky::cloudSpeed0 0.0
$Sky::cloudSpeed1 0.0
$Sky::cloudSpeed2 0.0

$Sky::windVelocity 1
$Sky::windEffectPrecipitation 1

$Sky::vignetteMultiply 0
$Sky::vignetteColor 0.0 0.0 0.0 0.0

$Sky::dayCycleEnabled 1
$Sky::dayCycleFile Add-Ons/DayCycle_Default/default.daycycle
$Sky::dayLength 300
$Sky::visibleDistanceHow far you can see in Torque Units. 1000 is a pretty good amount but you can live with smaller distances too.
$Sky::fogDistanceThe distance at which the fog kicks in. This should always be under the visible distance. I've found that making the fog start 200 units before the visible distance ends is a good balance between distance and looks.
$Sky::sunAzimuthRotation of the sun around the Z axis/player/world center.
$Sky::sunFlareTopTextureTexture of the sun flare. Can be left empty for no sun flare.
$Sky::sunFlareBottomTextureSecond texture for the sun flare. Can also be left empty for no sun flare.
$Sky::directLightColorThe light color that comes from the sun. Bricks that are directly in the light of the sun, hence the name, are tinted this color.
$Sky::ambientLightColorLight color that comes from the world itself. There is no real source for this light as it is applied to everywhere and everything evenly. If you are having problems with your lighting colors, you might want to try and set this light to a neutral (128 128 128 or 0.5 0.5 0.5) gray.
$Sky::skyColorColor of the sky. Depending on the sky textures this could either color the sky, or change the hue. White color means no change the sky colors.
$Sky::vignetteMultiply1 to enable, 0 to disable vignette multiply. See the Advanced section of the Environment Editor category for a description of this effect.
$Sky::windEffectPrecipitation1 to enable, 0 to disable wind effecting rain/snow and such. Wind, if there is any, always effects emitters.
If you don't want clouds you can delete all the cloud variables.
If you don't want a day cycle you can disable it and delete the file and length variables.

I have not explained all variables here because I have either already described them or they are self-explanatory. That is really I can think of that relates to skies. As always, check your file names.
Quote from: Files you should have in your Sky_TextureName ZIP
Something.jpg / Descriptive.png
Might.jpg / Make.png
Your.jpg / Life.png
Much.jpg / Easier.png
But.jpg / Not.png
Necessarily.jpg / Word.png
« Last Edit: August 19, 2012, 06:30:43 AM by Demian »

Creating Day Cycles

Day cycles are surprisingly simple. If you know how the sky variables work then you can make day cycles. You are essentially defining multiple values for the sky variables then setting them in order at specified times. The order at which the variables are changed is defined the the FRACTION variable. It is the time of day, going from 0.0 to 1.0. At first it took me a bit to figure out how it works. Below is an image that shows how the fraction changes over the time of day.

0.0 is sunrise.
0.25 is midday.
0.5 is sunset.
0.75 is midnight.
Value of 1.0 does exist but you need to be careful when using it. It is only 4 degrees below 0.0 and if the sky variables at 1.0 are very different from 0.0 then you will get an odd effect where the lighting and changes very quickly.
I have no idea why the cycle speeds up between 0.6 and 0.9 but I don't think causes any problems.
Code: [Select]
DIRECTCOLOR 1.0 0.5 0.2 1.0
AMBIENTCOLOR 0.5 0.5 0.5 1.0
SKYCOLOR 0.8 0.7 0.0 1.0
FOGCOLOR 0.8 0.3 0.1 1.0
SHADOWCOLOR 0.45 0.45 0.45 1.0
SUNFLARECOLOR 1.0 1.0 0.0 0.5

DIRECTCOLOR 0.1 0.3 0.8 1.0
AMBIENTCOLOR 0.5 0.5 0.5 1.0
SKYCOLOR 0.1 0.4 1.0 1.0
FOGCOLOR 0.0 0.1 0.5 1.0
SHADOWCOLOR 0.4 0.4 0.4 1.0
SUNFLARECOLOR 0.0 0.3 0.8 0.5

DIRECTCOLOR 0.2 0.2 0.2 1.0
AMBIENTCOLOR 0.2 0.2 0.2 1.0
SKYCOLOR 0.2 0.2 0.2 1.0
FOGCOLOR 0.0 0.0 0.0 1.0
SHADOWCOLOR 0.2 0.2 0.2 1.0
SUNFLARECOLOR 0.0 0.3 0.8 0.5

DIRECTCOLOR 0.2 0.2 0.2 1.0
AMBIENTCOLOR 0.2 0.2 0.2 1.0
SKYCOLOR 0.2 0.2 0.2 1.0
FOGCOLOR 0.0 0.0 0.0 1.0
SHADOWCOLOR 0.2 0.2 0.2 1.0
SUNFLARECOLOR 0.0 0.3 0.8 0.5
  This is just a simple and ugly day cycle for demonstration purposes. You should already know what all the variables do even if they look different. Again, RGB (0 : 255) and decimal (0.0 : 1.0) colors are allowed.

And that's the only file you need!
Quote from: Files you should have in your DayCycle_DayCycleName ZIP

If you find any typos, errors, or have a suggestion to improve this guide please let me know!
Fun facts: ~2700 words, approximately 9 hours of writing.
« Last Edit: August 19, 2012, 07:05:07 AM by Demian »

cul hope it gets sticky-d

Is it possible to reload a daycycle while ingame?

Very helpful! I'm working on some day cycles now, in fact! Thankyou, Demian :)

Is there some way to reload the cycles while in game, like you could do with a script?

I'd really appreciate that!

Is it possible to reload a daycycle while ingame?
I hardly know any Torque Script but I would assume that it is possible in a similar fashion one would re-excute a script. I don't know how you would re-excute the day cycle though since it only has variables in it.

That's what I figured...

Thanks again for this guide, your diagram on the fractions was really, really helpful.

Updated the day cycle diagram with more accurate details based on recent observations. It should be correct on a practical level but might be some decimals off in reality.

Good Job for make this nice tutorial.

hope it gets sticky'd

cool really nice guide

size 512x512
$Ground::loopsPerUnit 0, 0.10, 0.125 to $Ground::loopsPerUnit 2
It look like stuffty tiles box, How I am going fix it?

size 512x512
$Ground::loopsPerUnit 0, 0.10, 0.125 to $Ground::loopsPerUnit 2
It look like stuffty tiles box, How I am going fix it?
You can't really help it. Humans are especially adept at picking out patterns and unless your texture is very monotonous there is very little you can do. You could try making the loopsPerUnits a smaller number which in turn makes the texture more pixelated.

If I can try resize to 2048 or 1024.