TODO explain the scripting editor.

Lua API

Scripting inside scenes is based on Lua5.3. All base APIs are available, which can be accessed under lua.org/manual/5.3.

Execution Order

When a filter is constructed, the content of the script is executed. Use this behaviour in order to set up constant values. After that the following functions are called on appropriate occasion:

• scene_activated() is called every time the scene gets activated. Place reoccuring initializations here.
• update() is called on every scene update (40 times per second). Place your filter behaviour here

Global variables

Every configured input and output port is mapped as a global variable of the same type. These are also updated once per cycle. Besides that, the following global variables have a special meaning:

• output: This global variable is a two dimensional array. The first dimension is interpreted as the universe id to output to. The second one defines the channel. For example output[1][3] = 255 would set channel 3 of universe 1 to 255.

Additional Functions

Besides the Lua standard library, the following functions are avaiable:

Color Manipulation

Color object properties can be accessed and manipulated using the ["r"], ["g"], ["b"], ["h"], ["s"], ["i"] indices of the object. Hue is a float in the range 0 to 360, while saturation and intensity are in the range 0 to 1. For debugging purposes, a humand readable representation can be accessed using ["str"]. Besides this, a few helper functions are available, accepting color objects or tables as input:

• Color() constructs and returns a new color object. Using this constructor is faster and more convinient than providing a table. It is possible to use no arguments or to provide h, s, i arguments.
• hsi_to_rgb(color) Converts pixel data type to three dimensional array of color values. Ussage: r, g, b = hsi_to_rgb(my_color)
• hsi_to_rgbw(color) Converts pixel data type to four dimensional array of color values. Ussage: r, g, b, w = hsi_to_rgbw(my_color)
• mix_color_rgb_additive(color1, color2) Mix two colors together using the additive rgb algorithm. Ussage: new_color = mix_color_rgb_additive(color1, color2)
• mix_color_rgb_normative(color1, color2) Mix two colors together using the normative rgb algorithm. Ussage: new_color = mix_color_rgb_normative(color1, color2)
• mix_color_hsi(color1, color2, distance_obediance=true) Mix two colors together using the HSI avarage algorithm. The third parameter is optional (defaulting to true) and indicates if distant colors should get their brightness reduced once they’re mixed. Ussage: new_color = mix_color_hsi(color1, color2)
• mix_color_interleaving Mix two colors based on a given range from 0.0 to 1.0. If 0 is provided the first color will be returned, if 0.5 is given an even mixture of both and in case of 1 the second color. Usage: new_color = mix_color_interleaving(color1, color2, range)

Event Management

The API provides an enum event_type with content SINGLE_TRIGGER, START, RELEASE, ONGOING_EVENT and INVALID.

• get_events Returns a list of events currently active. Usage: events = get_events()
• has_event Returns true if an event with the provided event sender is currently active. Usage: if has_event(target_sender) then
• insert_event Inserts an event constructed from the supplied parameters. Usage:
  • insert_event(sender_id, event_type, args): Insert a new event. Sender should be optained using the get_event_sender method.
  • insert_event(sender_id, args): The selected event type defaults to event_type.SINGLE_TRIGGER in this case.
  • insert_event(sender_id): The argument string is left empty in this case.
  • insert_event(): The sender is the default lua sender with function = 0.
• get_event_sender Get the event sender ID. The specification of the function is optional and defaults to 0. Usage: get_event_sender(function) or get_event_sender()
• get_all_event_senders Returns a list of all available event senders. Usage: senders = get_all_event_senders()
• find_event_sender(id: str, function: int = 0) Get the id of the required event sender (optionally with specified function). This will raise an exception if the name was not found.

Scene Management

Scenes have a unique ID used to identify them, which is fixed by the show file. Besides this, scenes have an index which is unique to the object live time of the show file in fish and is considered to be random. In order to manage the running scenes, the following functions are available:

• get_scene_count() Returns the number of loaded scenes. This method returns 0 if something wen’t wrong.
• get_own_scene_id() Get the scene ID of the current scene.
• get_own_scene_index() Get the scene Index of the current scene.
• switch_to_scene(scene_id) Switch to the scene with the specified ID.
• get_default_scene_id() Get the ID of the default scene.