Lighting Scripts

## What are Light Scripts ?

Lighting scripts are a formatted way of entering instructions to a light to transition between different colors. In addition to controlling the color you can also control the duration, type and looping of each light.

You can a add light script to a light prop in two ways.

1. You can add it as property to the light that you want to change. Select the light you want to change in the viewport. In the Properties window hit  to add a new variable to the properties that is a string type. It must be named "LightScript"
2. You can add one via a trigger under Do>Props>Transition Light. In order of the trigger system to be aware of the light you need to put a dummy interaction it. This is done by hitting the hammer in the Properties and selecting "Dummy Interaction" from the drop down on the subsequent window.

Both the triggerable version and the properties version can be overidden by trigger with a new light script for a given light.

## Color Input Options

Two formats are supported for entering color values.

### Hexadecimal

This format is the common one for HTML color codes that will be familiar to anyone that has done some web design. This is a good site to pick your a color and this is a good site to narrow down to a spectrum of a given color once you have chosen a color from the first site, both sites show you colors in a hexadecimal format.

### RGBA

Which stands for Red Green Blue and Alpha. This is the format the SRR editor uses for directional and ambient lighting. The alpha value is essentially how transparent it is. To get the values for colors in this format simply create a region then click on a color in the region properties to bring up a color picker and set it to what you wish.

## Formatting Light Scripts

The formatting for light scripts needs to be exact. If it is not entered correctly the script will not work. As mentioned above we can control if a light loops or not, duration of transition and color value. First let's explore a light script with a single grouping with both color input options and then finish up with how to handle multiple groupings in a light script after that.

Below is an example of a light script using Hexadecimal formatting. Note how we use a colon to separate the given elements of a light script grouping.

Now we will break down the three parts shown above and explain what they do.

### Transition types

First the word "cubic". As mentioned above we can control how the transitions work and this where we tell the editor to transition from its current color to the color in the light script.

There are four different types of common transitions (which technically speaking are interpolations).

 bounce | Bounces around against the ceiling of the new value. Provides some irregularity as the new value is approached

### Duration

In the above example "5" is the duration. This defines the number of seconds over which the light transitions to its new value.

### Color Value

In the above example our Color Value is 00FF00 which is the new color in hexadecimal format. If we wanted to write the same script in R,G,B,A format we would do it like this:

`(cubic:5:255,255,0,255)`
### Groupings

Groupings are additional transition points you would like the light to transition through. If only one grouping is present then the light will transition from its existing values as set in its editor properties to the new value indicated in the light script. There is an example below which would transition the light from its original value to the first group in the script and then on to the second. You can have as many groupings in a light script as you would like. The semicolon at the end of the color value marks the end of that color grouping. The space between the color value and the next grouping is optional but is recommend to improve readability.

`cubic:5:00FF00; cubic:5:8E0000`
### Looping

To make a transition repeat simply add the word loop with a semicolon at the beginning of the script. You must have more than one grouping in the script for looping to function, such as in the example below.

`loop; cubic:5:00FF00; cubic:5:8E0000`
Note that there is a semicolon after loop, but once again the space after the semicolon is optional.

# Performance Considerations

There is no limit, more or less, to the number of groupings within a script; it's just instructions the engine uses. As a general rule, the "max" number of changing lights at any one time should never exceed 50. Also, as with all lights things get pricey on tiles where multiple lights overlap. So if you have multiple lights changing AND overlapping expect performance issues, perhaps game breaking ones. As always with the editor just because you can do something does not always mean you should.