Fractal Architect 4 Help Index
Applies to:FA 4
Reference: Lua API Reference for Fractal Architect
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.
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.
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.
You can use Tweak Fractal Lua scripts in these parts of the app:
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.
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.
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.
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.
Fractal Architect 4 only supports using Lua scripts for:
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.
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.
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.
The library folders have two subfolders:
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.
For scripts in the Factory table, you can:
For scripts in the My Scripts table, you can:
For Variants scripts, the popover provides extra capabilities
You can create a set of multiple scripts to run (not just a single script).
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.
Select the script in the list to remove. Click the - button.
Click the Clear List button.
Fractal Architect has a builtin basic text editor that you can use to edit Lua scripts or Custom Variation’s C code.
Select a script in the My Scripts table. Click the Edit button to open the text 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.
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.
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.
Preview Button
Variant Button
Quicklook Button
XML Text Button
Info Button