Adding lights

So far in our "getting started" tutorial series we have been using only ambient lights. In this tutorial we will have a look at how to add more types of lights into your game.

Contents

• Ambient light
• Directional light
• Punctual lights
• Image-based light

Ambient light

We have already worked with this one before, but for completeness, let's walk through ambient lighting again. Ambient light is a light that comes from all directions and contributes only to diffuse lighting (it does not add to specular reflections). In BBMOD, ambient light is split into two parts - light coming from the upper hemisphere (+Z) and light coming from the lower hemisphere (-Z). You can use functions bbmod_light_ambient_set_up, bbmod_light_ambient_get_up, bbmod_light_ambient_set_down and bbmod_light_ambient_get_down to set/get those separately, or use function bbmod_light_ambient_set to set both to the same color at once. All of these functions take/return a BBMOD_Color, which allows each channel to have a value higher than 255. For each GameMaker's color constant there is an equivalent BBMOD_Color, e.g. BBMOD_C_RED for c_red, BBMOD_C_LIME for c_lime, BBMOD_C_BLUE for c_blue etc. This is the only light that is enabled by default. If you would like to disable it, simply set it to black color. You can also use function bbmod_light_ambient_set_dir in case your up direction is not the default +Z. This function takes a BBMOD_Vec3 as the direction vector.

bbmod_light_ambient_set_dir(new BBMOD_Vec3(0, -1, 0)); // Sets -Y as direction up
bbmod_light_ambient_set_up(BBMOD_C_AQUA);
bbmod_light_ambient_set_down(BBMOD_C_ORANGE);

Directional light

A directional light is a light that comes from a single direction and it usually used for the sun. To add this type of light, you first need to create a new BBMOD_DirectionalLight and then pass it into function bbmod_light_directional_set. A directional light's direction is specified using BBMOD_Vec3. The light also needs to be Enabled (which it is by default), otherwise it will not be passed to shaders. To retrieve the current directional light you can use function bbmod_light_directional_get (returns undefined if there is none).

var _directionalLight = new BBMOD_DirectionalLight();
_directionalLight.Color = BBMOD_C_WHITE;
_directionalLight.Direction = new BBMOD_Vec3(1, 1, -1);
bbmod_light_directional_set(_directionalLight);

Punctual lights

BBMOD has two types of punctual lights - point and spot lights. To add a new punctual light, you will first need to create either BBMOD_PointLight or BBMOD_SpotLight and pass it into function bbmod_light_punctual_add. There can be at most BBMOD_MAX_PUNCTUAL_LIGHTS enabled punctual lights simultaneously. To get the number of all added lights, you can use function bbmod_light_punctual_count. To retrieve a punctual light with specific index (goes 0..light count - 1), you can use function bbmod_light_punctual_get. You can also remove lights using bbmod_light_punctual_remove_index (removes a light at a specific index), bbmod_light_punctual_remove (removes a specific BBMOD_PunctualLight) and bbmod_light_punctual_clear (removes all added punctual lights).

var _pointLight = new BBMOD_PointLight();
_pointLight.Color = BBMOD_C_WHITE;
_pointLight.Position = new BBMOD_Vec3(x, y, z);
_pointLight.Range = 20;
bbmod_light_punctual_add(_pointLight);

var _spotLight = new BBMOD_SpotLight();
_spotLight.Color = BBMOD_C_WHITE;
_spotLight.Position = new BBMOD_Vec3(x, y, z);
_spotLight.Direction = new BBMOD_Vec3(1, 0, 0);
_spotLight.Range = 100;
_spotLight.AngleInner = 30;
_spotLight.AngleOuter = 40;
bbmod_light_punctual_add(_spotLight);

Tip: You can disable a punctual light without removing it with the bbmod_light_punctual_remove function by simply setting its Enabled property to false.

Image-based light

As the name suggest, image-based lights (IBLs) are lights that use an image to cast lighting onto the scene. In BBMOD this image needs to have a specific format - a single sprite of eight RGBM-encoded octahedrons pre-filtered for increasing material roughness. This sounds very complicated, but with BBMOD GUI you can create these easily from any .hdr file. If you do not have BBMOD GUI, then BBMOD also comes with a few ready to use pre-filtered HDRIs and you can find them in datafiles/Data/BBMOD/Skies/IBL*.png. To add a new IBL, you first need to create a new BBMOD_ImageBasedLight and pass it to function bbmod_ibl_set. You can also get the current IBL using bbmod_ibl_get.

/// @desc Create event
iblSprite = sprite_add("Data/BBMOD/Skies/IBL+60.png", 1, false, false, 0, 0);
var _ibl = new BBMOD_ImageBasedLight(sprite_get_texture(iblSprite, 0));
bbmod_ibl_set(_ibl);

/// @desc Clean up event
sprite_delete(iblSprite);