Tutorial - Advanced Lighting


Just install like any other plugin and make sure it's placed after the required plugins. If you're unsure on how to do it, please check the plugin installation tutorial.

Additionaly, you will need to copy the lights folder to your project's img folder. Then, if you want to create your own lights, place the light images in that folder (more details later).

If you're using the Advanced Fog plugin, place this plugin after it.

Test the plugin
Open any map on your project, right click it and click on Edit:

Then, add the [ambient_light 50] command to its note:

Click OK to close and save. Now create a new event and add the [light torch] command as a comment:

Save and run the game. Start a new game and transfer the player to that map. It should look like this:

This plugin assumes two sources of lights: ambient light and point lights. Ambient light illuminates the whole screen and its intensity is set to 100 when you start the game. If you want to darken the map you will need to set the ambient light's intensity to something between 0 and a 100.

Please note that this plugin works like a state machine, that is, there's the ambient light state on the game and it can be set to any number between 0 and 100. Then, the system will remain at that state until you use a command to change the ambient light to a new state. The state persists when transferring between maps and after saving/loading the game.

Let's start by setting the ambient light to 50. You may use the AmbientLight plugin command, like below:

This command will change the ambient light instantly. If you want a gradual change (like in 2 seconds - 120 frames), you can add the time to the command:

The most convenient way to change ambient light is to use the [ambient_light intensity] map command, as you did when testing the plugin. Then, whenever the player is transfered to that map, the command will run and change the ambient light to a new state. However, this command will run only if AutoAmbientLight is enabled (it's enabled by default). If you want to set AutoAmbientLight ON/OFF, please use the following command:

If AutoAmbientLight is OFF, the map command will be ignored and the state will be preserved between map changes.

Now let's say you have a map that the player will visit during two parts of the game: one happens during the day and one happens during the night. Additionally, let's say that the switch 2 set to ON whenever it's night during the game. Of course you could use plugin commands to set the correct lighting, but let's use map commands instead. In order to have the desired effect, you may use the following commands:

The [ambient_light intensity switchId] command runs only if the switch is ON at that time, regardless of the AutoAmbientLight setting. Thus, when switch 2 is ON, the second command above will run and override the previous ambient light value.

Finally, you can enable/disable the entire system by using the Lighting ON/OFF plugin command:

That's enough about ambient light. Now you will learn how to create point lights!

The easiest way to create point lights is to use the [light X] command as a comment in any event. X is the light name - the following are available with the plugin:

Lights - Artificial:
     halogen, tungsten, fluorescent, broken, flashlight

Lights - Candle:

Lights - Torch:
     torch, white_torch, red_torch, green_torch, blue_torch, pink_torch,
     cyan_torch, yellow_torch, purple_torch

Lights - Colored:
     white, red, green, blue, pink, cyan, yellow, purple

Lights - Test (use this to test and adjust offset):

Please note that light names are case sensitive!
You can create your own lights - there's more detail later.

Try creating a torch with the command:

Lights added to events using the method above will remain lit while the page is active. Therefore, an event can have multiple lights (like a traffic light), and you can switch its pages to change between the lights.

Each light has an offset (usually 0 for both axes). You may use the command [light_offset OX OY] to override the default offset. OX and OY are the offset values for X and Y. They can be a positive number (without the + sign), or a negative number.

Now let's say you have a lava lake and you want it to emit light! Adding an event for each tile would be too much work, so an easier way would be to add the [tag_light T L] command in in the tilesets's note. Then, a light will be added to whichever tile has this tag. L is the light's name and T is the terrain tag number.

But perhaps you want a glowing lake at only one map - you can't use the method above! This plugin has other useful method for achieving this: the [region_light R L] map command. This command assigns a light to a region, then, a light will be added to any tile marked with this region. L is the light's name and R is the region number.

Before we talk about battle lighting (yay!), I need to tell you about one more way to add point lights: you can give lights to the player! Call the PlayerLantern OFF/X plugin command. X can be a light name or OFF:

Now that you understand the system better, it's safe to let you know that it actually has two lighting states: one for the map and one for battles. Like above, the battle lighting state will remain the same until changed.

Let's say you transfer to a map where battles should have ambient light set to 10. Then, you can use the BattleLighting AmbientLight X plugin command, where X is the ambient light intensity.

Now you may want to add point lights to the battle scene. Use the BattleLighting AddLight I X Y plugin command, where I is the light ID (case sensitive!), and X and Y are the screen coordinates, in pixels.

Finally, whenever you want to reset the battle lighting state (set the ambient light intensity to 100 and removes any added light), use the BattleLighting Reset command.

If you want to create custom lights, you will need to edit this plugin. You can do that in notepad, but my recommendation is to use Notepad++ or Microsoft Visual Studio Code.

Once you opened the plugin, search for Custom Lights. Then use the templates/examples there to create your custom content! Please note that some programming experience is recommended.

If you are creating custom lights, do not forget to add your custom light images to the img/lights folder.

Tutorial - New Features (version 3.0)
The version 3.0 makes battle lighting way easier! If you set the new Auto Battle Lighting plugin parameter to ON, ambient light will be picked from the current map ambient light, and lights will be added to battlers automatically!

But before any battler has any light, you need to tell the system who has what light. In order to do that, you need to use the new SetActorLight/SetEnemyLight plugin parameters! They work in the following way:

SetActorLight ActorID LightID
SetEnemyLight EnemyID LightID

ActorID and EnemyID are the IDs of the character (a number)
LightID is the light identification, like torch or halogen (without quotes!)

SetActorLight 1 torch
SetEnemyLight 3 red

New since version 3.1:
You can add light offset for each character, extending the commands above with the offset values (in pixels, first in x axis, then in y axis).
SetActorLight ActorID LightID OX OY
SetEnemyLight EnemyID LightID OX OY

SetActorLight 1 torch 0 24
SetEnemyLight 3 red -20 30

Another new plugin parameter is the Transfer Reset one. It you set it to ON, the ambient light is reset after every transfer (it will be reset to intensity = 100/white light).

If you want bigger/smaller lights, now you can change the size of lights without making changes to their images! You may use the new [light_size x] command:

[light_size 50] makes the light shrink to 50% of its size
[light_size 170] makes the light expand to 170% of its size

Another option is to add the size: x parameter to any light's definition (more details on the Custom Lights code). There's two new lights to demonstrate how it works: halogen_big and torch_big.

Version 3.0 added colored ambient light! You may use the same commands from before to set the ambient light, but you may use a number to set the intensity, or an hexadecimal color to set the color (without the # symbol).

If you place [ambient_light 00ff00] on a map's note, it will make the ambient light green. If you call the plugin command AmbientLight ff0000 60, it will smoothly change the ambient light color to red in 60 frames.

Speaking of smooth stuff, now you may have lights with smooth transition as well! Instead of using the regular [light x] command, try using the [smooth_light x y] command, where x is the light's name and y is the change in intensity per frame (an integer from 1 to 100).

Try this one, for example:
[smooth_light torch 5]

Note that you will only see the smooth transition when switching between event pages with and without lights. Please see the demo for a practical example!

The last feature version 3.0 added is ambient light state saving/loading. You may use the new SaveAmbientLight/LoadAmbientLight plugin commands to do that. They work in the following way:

SaveAmbientLight StateName
LoadAmbientLight StateName Time

StateName is the name given to the state (it can be anything!)
Time is the time to perform a smooth transition (it's optional, in frames)

SaveAmbientLight state1

Then later, call the following to go back:
LoadAmbientLight state1 60

Tutorial - New Features (version 4.0)
This version adds real-time shadows! In order for the system detect walls and cast shadows, you will need to use region tags to set the map's height. The height of a given tile will be the region tag divided by 10 and rounded to the lowest integer. Thus, if you use 24, 27 or 29, the height of that tile will be 2. If you use 11, 10 or 18, for example, the height of that tile will be 1. Please check the demo to see examples on how to use the region tags.

By default, all lights will cast shadows. If you want to control whether a light casts shadows or don't, use the command below in any event:
[light_shadows on/off] 

You can also set a new property on any light's definition:
cast_shadows: true/false

Offline Version
A pdf for this tutorial can be found here (thanks to New Quest Gaming).