Using Lua Scripts

Applies to:FA 5

Lua Scripting

Lua is a small, powerful scripting programming language designed to be embedded into applications. You can use it both to create new fractals or modify existing fractals. You don’t have to learn Lua scripting to get full use of the app, but some of you will want to write your own scripts or convert scripts written for Apophysis and JWildfire to Lua.

Especially from the Apophysis community there are hundreds of Apophysis Pascal scripts that can be converted to Lua. Its not hard to convert either Apophysis Pascal or JWildfire Java scripts to Lua.

Please acknowledge the original authors of any scripts you convert in your script comments. Its their hard work that made the script possible.

Mapping Fractals to Lua Tables

Fractals have very complex data models with lots of fields and components to be specified.
See: Lua API Reference for Fractal Architect for complete documentation.

Using Lua scripts you can modify any of these components.

Because of this complexity, many scripts will use one of the app’s builtin Lua functions to create a blank fractal, which creates a fractal from a template. Then, you would simply set a handful of parameters to customize the templated fractal.

Making New Fractals With Lua

Welcome Screen (Scripted Random tab): Use the Choose Main Script button to select a make fractal script that will be run to create new fractals.

On the main Welcome to Fractal Architect 5 window, there is a new tab named Scripted Random. Click on that tab to open the Scripted Random working area.

First, you need to select a Main script to produce random fractals with. Do that with the Choose Main Script. It will open the Lua Script Selection Popover.

See: Lua Script Selection/Management Popover.

You can optionally add a Tweak script to modify the newly created Random fractals. Do that with the Optional Tweak Script. It will also open the Lua Script Selection Popover, however only scripts used for tweaking fractals will be shown.

For example, you can select the grayscaleColors script to create grayscale images, instead of the normal random color palettes.

Do unselect a tweak script, just click the Select None to Run button.

Tweaking Fractals With Lua

You can use Tweak Fractal Lua scripts in these parts of the app:

1. Welcome Screen (Scripted Random tab): Use the Optional Tweak Script button to select a tweak script that will be applied to any fractal created by the main Make Fractal script.

2. Variants Editor: Use the Optional Tweak Script button to select a tweak script that will be applied to each fractal created by the Variants editor. Note: You must also select the Lua Script Variant option or the next batch of variants will not utilize a tweak script.

2. Super Variants Editor: Use the Optional Tweak Script button to select a tweak script that will be applied to each fractal created by the Super Variants editor.

3. Welcome Screen (Make New tab) - Random Generation Settings: Use the Optional Tweak Script button to select a tweak script that will be applied to every new random fractal.

Saving Any Fractal as a Lua Script

Fractals can now be saved as a Lua script.

Use the Create Lua Script for Fractal context menu item to save the fractal as a Lua script. It will have a big ugly Uuid as its name (which you can override at the point of saving) or leave the name as is, to remind you that it was created for temporary usage.

There are 2 reasons you might want to save a fractal as a Lua script:

Many powerful scripts in FA 5 can invoke another Lua script to either create a layered fractal, add sub-flames instances, or for splicing fractals.
You might want to modify the script by randomizing the fractal’s parameters. This is a fast way to create a new Make Random script.

These saved scripts are saved as new Main scripts (not variant tweak scripts).

Saving “Make New” Settings as a New Lua Main Script

Go to the main Welcome screen > Make New tab > Random Generation Settings popover. Here you setup the random fractal generator.

You can save these settings as a new main Lua script by clicking on the
Save as Lua Script button.

Later, you can choose that same script on the main Welcome screen > Scripted Random tab.

Factory Scripts vs. My Scripts

My Scripts are Lua scripts created by you and are fully editable. You can copy Factory scripts into your My Scripts library and this copy will be editable. You are in fact encouraged to play with the builtin Factory scripts (once they have been copied) and try different parameter value ranges, add new fractal variation types, and learn how to do Lua fractal scripting.

Factory scripts are Lua scripts included with the application. The app treats them everywhere as readonly. The intent is for you to not edit these scripts directly. App updates might include script changes that would overwrite your script changes, if the app allowed factory scripts to be edited.

Copying & Editing a Factory Script

To make a Factory script editable, you need to first copy it into your My Scripts script library, and then select the copied script and open the builtin text editor.

First, select the Factory script you want to copy. Then click the Copy button (the blue right arrow button). That will make copy of the script into your My Scripts library.

Select the the script in the My Scripts table and then click the Edit button.

Creating a New My Scripts script

Click on the + button to create a new blank script.

Double click the new Unnamed script with mouse. This makes the name editable. Type the new script name.

Click the Edit button to open the builtin text editor.

Deleting a Script From My Scripts

Select the script to delete from the My Scripts table. Click the - button to delete the script.

Note: Factory scripts cannot be deleted using the app.

Make Random Scripts vs. Tweak (Variants) Scripts

Fractal Architect 5 only supports using Lua scripts for:

1. Making new Fractals: The scripts all populate a set of new Lua tables, comprising all the parameters for a new fractal), and set the app’s global Lua flame variable with the new fractal.; In the initial release, the scripts all just create a single fractal. To create a batch of new fractals, the script is executed many times, one per new fractal.
2. Tweaking existing Fractals: Tweak scripts modify the current fractal defined by the app’s global flame variable and change one or more of its parameter definitions.; In the initial release, the scripts all just modify a single fractal. To modify a batch of fractals, the script is executed many times, one per fractal.

Script Libraries

The builtin factory scripts are held inside the app’s runtime container. Apple puts app’s containers inside a hidden directory so they are not intended to hold your important files or your own scripts. App updates might overwrite existing factory scripts.

The My Scripts library is initially also inside the app container, but only because the app can’t create arbitrary folders without you directing the app to do so. It highly encouraged that you choose a new folder for My Scripts at a location you choose.

See: Choose Folder for My Scripts button below and use it to create a folder to hold your My Scripts collection. That new folder location will be saved as an app Preference item. It will also copy Lua scripts from inside the app’s hidden container folder into your new folder.

Script Libraries Sub-Folders

The library folders have two subfolders:

makeRandom folder: Holds the Make Fractal scripts.
makeVariants folder: Holds the Tweak scripts.

Lua Script Selection/Management Popover

With most of the fractals, click either Choose Main Script or Choose Tweak Script to open this popover panel.

This panel allows you to select a Lua script to run or to stop running a Lua script by unselecting it (Select None to Run).

FA 5 now supports scripts that have input argument values (that you enter through another panel). There is also a family of scripts that also support picking of varpars (variation instances and their parameter value ranges) .

Lua Main Script Selection Popover — Lua **Main** Script Selection Popover

The most important function of this window is to select one Lua script to run.
When you click on a script name in either the Factory or My Scripts table, the scripts name and which table you click on will be shown in the Run This One: summary at the top of the popover window.

If you want no script to be chosen, click on the Select None to Run button.

Factory table (1st table)

For scripts in the Factory table, you can:

1. Name Search Field: Narrow the script list to those containing the text in the search field .
2. Show Folder in Finder: this opens the Factory scripts folder in the Finder.
3. Show Script: This opens a read only text window with script’s contents. To change the script, first copy it ton the My Scripts (right) table. You can edit the copy.
4. Script Arguments: This opens a popover panel where you can enter the values for the selected script’s arguments. See Script Arguments;

Make an Editable Copy of a Factory Script

Factory scripts cannot be edited. They may be updated by future updates or releases of Fractal Architect.

So, the app allows you to create an editable copy of them.

Copy Button Blue arrow button: This will copy the factory script into your My Scripts script library. The copy is fully editable.

My Scripts table (2nd table)

For scripts in the My Scripts table, you can:

1. Name Search Field: Narrow the script list to those containing the text in the search field .
2. Show Folder in Finder: this opens your My Scripts folder in the Finder.
3. Edit: This opens a editable text window with script’s contents.
4. +: This allows you to add a new script, initially named “Unnamed”. You can click on the script name in the table and rename the script.
5. -: This will remove the selected script.
6. Script Arguments: This opens a popover panel where you can enter the values for the selected script’s arguments. See Script Arguments;

Lua Tweak Script Selection Popover — Lua **Tweak** Script Selection Popover

For Variants scripts, the popover provides extra capabilities

Creating a Custom Script List (3rd table)

You can easily create a list of multiple scripts to run (not just a single script). The list is held in the 3rd table from the left.

Adding a Script to the Script List: Click on the script you want to add. Next, click the Add Selected Script to List button.; The scripts will be executed in the same order as they are shown in the table.

Removing a Script from the Script List: Select the script in the list to remove. Click the - button.

Clearing the Script List: Click the Clear List button.

Up / Down buttons: Changes position of the selected script in the list.; Changes the order of execution.

Save List as new Script: Creates a new Lua script that is equivalent to the list of scripts.; Saves the list’s scripts and their script argument values.

Script Arguments: This opens a popover panel where you can enter the values for the selected script’s arguments. See Script Arguments;

Factory Scripts by Category (4th Table)

Here are the Factory scripts again, grouped by category.

1. Show Folder in Finder: this opens the Factory scripts folder in the Finder.
2. Show Script: This opens a read only text window with script’s contents. To change the script, first copy it ton the My Scripts (right) table. You can edit the copy.
3. Script Arguments: This opens a popover panel where you can enter the values for the selected script’s arguments. See Script Arguments;

Input Args Summary Table

This small table shows either the configured input arguments or configured varpars for the currently selected Lua script.

Script Args: Shows the configured input argument settings.
Variations: Shows the configured input carper settings.

Lua Script’s Input Arguments

Many of the builtin scripts included with Fractal Architect, have input arguments. The values of those input arguments will change what the script does.

The script should state what its input arguments are (if any) in comments. But sometimes the script writer forgets to document them.

How it Works

The FA 5 app Lua runtime, passes to all Lua scripts, these two different Lua tables holding input arguments (by convention).

args: Table for input arguments.
varpars: Table holding configured varpars.

So if you configure, for example, the scale argument with value of 1.5,
this is passed to the Lua script:

	args.scale = 1.5

The script’s code should have a section that loads its input arguments, passed to it by FA 5.

So, lets look at some examples of actual Lua script code fragments that read input arguments.

Example: 1 input argument, named scale with default value of 2.

	if args.scale == nil then
		args.scale = 2.
	end

If the user did not specify a value for the scale argument, then its value is set to the default 2. Otherwise, the script uses the value set by the user in the app.

Script Arguments Can Also Be Lua Expressions

Script arguments are not limited to numeric values or text strings, they can be Lua expressions.

So this Lua expression:

	2.5 + 4.0 * math.random()

is the same as a random number that is between 2.5 and 6.5.

Configuring Script Arguments

Fractal Architect 5 now provides the capability for a script to have optional input arguments (with default values).

The Script Arguments Panel has 3 tabs:

Setup Varpars: This tab lets you create a list of varpars, which are a list of variations and their random parameter value ranges.

Script Args: This tab lets you specify the values for the selected script’s input arguments.

The Script: This tab lets you see the actual Lua script.; Input arguments are always, by convention, contained in the Lua args table.

Script Args Tab

The idea here is add rows to the table for each of the script’s input arguments. Input arguments are always, by convention, contained in the Lua args table.

The [The Script] tab allows you to see the script itself, so you can discover if it uses input arguments or not. Many scripts do not use them.

Script name: Shows the name of the script you are configuring.

+ Button: Adds a new row to the table. The placeholder text is key for the arg and value for its value.; Override these placeholder settings with the actual argument name and its value.

- Button: Removes the selected table row.

+ My Script Arg: Adds a row to the table, with script for the arg name and the Lua script’s base name for the arg value.; It presents an Open File popover showing My Script Lua script files.

+ Factory Arg: Adds a row to the table, with script for the arg name and the Lua script’s base name for the arg value.; It presents an Open File popover showing Factory Lua script files.

Save As Preference: This saves the input argument configuration for this Lua script as a Preference.

Special support for Script input arguments

Several groups of Lua scripts, in FA 5, now invoke other Lua scripts that are specified as input arguments. Typically, which script(s) are invoked, are configured through one or more input arguments.

By convention, if the parent script invokes just one child script, it would use an input argument name of script.

If the parent script invokes multiple child scripts, the corresponding argument names would be script1, script2 and so forth.

Setup Varpars Tab

FA 5 provides a group of Lua scripts, which insert one or more variations, plus their parameter value ranges, into transforms.

These scripts all expect to be passed a varpars table from the FA 5 Lua runtime.

Script Arguments -- Setup Varpars — Script Arguments – Setup Varpars

Script name: Shows the name of the script you are configuring.

Save As Preference: This saves the input varpars configuration for this Lua script as a Preference.

Left Pane: Variations Checkbox List: Click the checkboxes for the variation types you want to use.

Right Pane: Variation Weights and Their Parameter Values: Allows you to set random value ranges for the variations’ weights and their parameters.

The Script Tab

This tab shows the actual Lua script so you can see what input arguments it uses.

Script name: Shows the name of the script you are configuring.

Builtin Text Editor

Fractal Architect has a builtin basic text editor that you can use to edit Lua scripts or Custom Variation’s C code.

How to Use the Builtin Text Editor

Select a script in the My Scripts table. Click the Edit button to open the text editor.

Features of the Builtin Lua Script Editor

This is a very basic text editor. It has Find & Replace capability using the Find button.

You can do a test compile of the Lua script by clicking the Check Syntax button.
If there are no syntax issues, it will popup a message saying “Lua Syntax OK”.
If syntax errors are found, only first syntax error will be shown in the message.

Using You Own Favorite Text Editor

You can use your own favorite text editor too. Use the Show Folder in Finder to open the My Scripts library folder.

With the popular editor TextMate, you would then drag a file icon, for the file you want to edit, with the mouse and drop it onto the TextMate icon in the Dock.

Lua Tester Window

The Lua Tester window does 4 things:

All print() function output from any Lua script run by the app (anywhere in the app) is displayed here. So if you are developing a Make New fractal script and want to see some calculated result, put a print() function call in the script. When you run the script, its output will be shown here.
You can type in arbitrary Lua commands into the bottom text input field and execute the commands one by one.
Test Make new fractal Lua scripts. When you run these scripts here with the Run File button, it will create a new fractal and put it into the Lua flame global variable.
Test Tweak (Variant) Lua scripts. When you run these scripts here with the Run File button, it will take the Lua flame global variable and modify it.

Lua Tester User Interface Elements

Preview Button: Open a new Preview window with the contents of the builtin Lua flame global variable.
Variant Button: Open a new Preview window with the contents of the builtin Lua flame global variable.
Quicklook Button: Open a new Preview window with the contents of the builtin Lua flame global variable.
XML Text Button: Open a new Preview window with the contents of the builtin Lua flame global variable.
Info Button: Open a new Preview window with the contents of the builtin Lua flame global variable.
Clear Log Button: Clears out the Lua console text.
Drag & Drop Fractals Here: Drag from a fractal anywhere on the app and drop it onto this hot spot. That sets the global flame Lua variable to the dropped fractal.
Run File Button: Select a Lua script file and run it.
Top Text Multi-Line Field: Holds all print() output from Lua scripts and Lua error/status messages.
Bottom Text Input Field: Type Lua statements here and you can interactively execute them.