Formatter scripts

As noted in the introduction, formatter scripts are used to format data before outputting it to the livestream. A formatter script will replace a certain keyword (here id) that is surround with percent signs.

Formatter scripts are Lua scripts that are located in the ScriptFormatters directory, both built-in and custom created. Go to the GitHub repository to view the built-in and example formatter scripts.

Note
Unless specified otherwise, you need to refer to formatter scripts by its id surrounded with percent signs (e.g. %formatter% instead of just formatter). This is done to provide consistency with the configuration window of the plugin.

File structure

Every formatter script has to have a certain list of globals defined, otherwise the script will not load.

Note
Every global is required, unless otherwise specified.

id string The id that is used to uniquely identify a script. This id is also used to refer from other scripts in e.g. hooks and getvar().

name string The name is used in the configuration window of the plugin to provide a better understanding for users what the script actually represents.

category table of strings (optional) Formatter scripts are categorized into submenus. This will prevent cluttering of the selection menu in the configuration window. The script is categorized first-to-last entry from the given table. If this global is not defined, the script will be placed in the root category.

hooks table of strings (optional) A script can hook onto (a.k.a. subscribe to) the event when another value changes. This can be the value of another variable or formatter script or a built-in variable. When a change occurs, update() will be called. This table should contain ids of other scripts or built-in variables.

update() function This is the main entry point of the script. In this function the script needs to return its updated value. Please note that it is not recommended to update the value of a formatter script every frame. This will cause the plugin to update the imaged version of the text at a very high rate which may cause a major frame rate drop in OBS.

Exposed globals

A formatter script can call certain globals that provide more functionality than Lua itself:

localvar(id, value) function Gets or sets a local variable of the script. This can be used to preserve variables throughout the lifetime of the plugin, since every defined local or global in the script will vanish after each run.
id: An unique id to identify the variable with.
value: The value of the variable to set; use nil or omit if you want to get a variable instead.
Returns the value of the variable if value is nil; nil otherwise.

getcurrent() function Gets the current cached value of the executing script.

getvar(id) function Gets the cached value of another variable script or a built-in variable. Note that you cannot get the value of a formatter script through this function. Use gettext(id) if you want to do this.
id: The id of the variable script or built-in variable.
Returns the cached value.

gettext(id) function Gets the cached value of another formatter script.
id: The id of the formatter script without the surrounding percent signs.
Returns the cached value.

timestamp() function Gets the current Unix timestamp. Since Lua has no built-in support for getting the current time, this has been wrapped in C#. The returned value might include both whole and fractional seconds.

getdate(timestamp) function Gets a date as a table. This makes working with dates in scripts a lot easier.
timestamp: The Unix timestamp.
Returns a table with the following keys: year, month, day, day_of_week, day_of_year, hour, minute, second, millisecond. Note that day_of_week is a number from 0 to 6 (Sunday to Saturday).