Fractal Architect 4 Help Index

Using Lua Scripts


Applies to:FA 4

Reference: Lua API Reference for Fractal Architect

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 4 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.

Scripted Random tab
Scripted Random tab

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.

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.

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 4 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


Lua Make Random Script Selection Popover
Lua Make Random 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

For scripts in the Factory table, you can:

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.
3. Copy     Blue arrow button
This will copy the factory script into your My Scripts script library. The copy is fully editable.

My Scripts table

For scripts in the My Scripts table, you can:

1. Show Folder in Finder
this opens your My Scripts folder in the Finder.
2. Edit
This opens a editable text window with script’s contents.
3. +
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.
4. -
This will remove the selected script.
Lua Variants Script Selection Popover
Lua Variants Script Selection Popover

For Variants scripts, the popover provides extra capabilities

Custom Script List

You can create a set of multiple scripts to run (not just a single script).

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.

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


Lua Script Selection Popover
Lua Script Selection Popover

The Lua Tester window does 4 things:

  1. 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.

  2. You can type in arbitrary Lua commands into the bottom text input field and execute the commands one by one.

  3. 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.

  4. 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

home Preview Button
Open a new Preview window with the contents of the builtin Lua flame global variable.
variants Variant Button
Open a new Preview window with the contents of the builtin Lua flame global variable.
quicklook Quicklook Button
Open a new Preview window with the contents of the builtin Lua flame global variable.
xmltext XML Text Button
Open a new Preview window with the contents of the builtin Lua flame global variable.
info 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.