Automation Overview
Automate repetitive design tasks with scripts and visual programs. Place rows of plants, apply material rules, generate design variations, and measure your design — all without manual clicks.
The Automation panel provides scripting and visual programming tools for creating reusable design operations. Automations run on the canvas and can place entities, modify properties, loop over selections, calculate measurements, and generate design variations.
Open the Automation panel from the Automation icon in the top bar.
The panel has three tabs:
- My Automations — your library of saved automations, with run, edit, and template access
- Editor — write or edit automation code and flows (compact sidebar or full IDE)
- Help — the "How do I…" tab with example prompts and documentation
Automations are written in ScapieraScript (Lua-based). You can write code directly in the code editor, build programs visually with the flow editor, or record your manual canvas actions and convert them to code.
Open the Automation panel
Click the Automation icon in the top bar (or use the keyboard shortcut shown in the Input Help panel — ? icon in the status bar).
The Automation panel slides in from the right side of the canvas. The panel opens on the My Automations tab by default.
If this is your first time opening the panel, a welcome card and the Template Gallery are shown in the My Automations tab.
What automations can do
Automations run against the current design canvas and can perform any of these operations:
- Place entities — add plants, shapes, structures, text, and other entity types at specified positions
- Modify properties — change entity materials, dimensions, names, layers, or any inspector property
- Loop over selections — iterate over all entities of a type, a named selection, or entities on a specific layer
- Calculate measurements — measure areas, lengths, distances, and counts from entities on the canvas
- Generate variations — create multiple versions of a design element with parametric inputs
- Query the design — find entities by type, name, layer, proximity, or spatial relationship
Automations do not run at design time automatically — they run when you click Run (unless configured with an On Select or On Place trigger).
Three ways to create an automation
There are three ways to create an automation:
1. Use a template — browse the Template Gallery in the My Automations tab and create a copy of a ready-made automation. Templates cover common tasks: planting rows, grid placement, material application, and more.
2. Write code — use the code editor in the IDE layout to write ScapieraScript (Lua) directly. Full API access, syntax highlighting, and auto-complete for all ScapieraScript methods.
3. Record — click Record in the Editor toolbar and perform actions on the canvas. The recorder captures each action as a code snippet. Stop recording to review and save the captured code as an automation.
All three methods produce a saved automation in the My Automations library.
Recording is the fastest way to get started if you are not comfortable writing code — perform the task manually once, record it, and then edit the captured snippets to make the automation flexible (e.g. replace hardcoded positions with parameters).
Understand the Help tab
The Help tab in the Automation panel provides contextual documentation and example prompts.
The main feature of the Help tab is the How do I… input. Type a plain-language description of what you want to automate (e.g. "place 10 plants evenly spaced along a path") and the Help system returns:
- A code snippet showing how to achieve this in ScapieraScript
- A description of the relevant API methods used
- Links to the full API reference for each method
The Help tab is a useful first stop when writing a new automation — use it to discover the relevant API methods before building out a full script.
Use the Help tab with specific questions rather than vague ones. "How do I place plants in a grid pattern" produces more useful results than "How do I place plants".
Build or edit in the Editor
Open the Editor tab (or click Edit on any automation card) to run, preview, and adjust an automation in the compact sidebar. To build or edit the program itself, click Edit script (or the Maximize icon in the panel header) to open the expanded IDE. The expanded IDE adds the Visual flow editor and — on the Studio tier — a Code tab with Lua syntax highlighting, API auto-complete, and an Output panel that shows console messages and run-time errors.
Preview before applying changes
Instead of Run, click Preview to execute the automation in preview mode. Preview applies the result to the canvas without persisting it to the project, so you can review placement and counts before accepting. Click Apply to commit the preview result, or Cancel to discard it and return the canvas to its previous state.
Use the Help tab as an in-IDE reference
The Help tab provides two sections: the API Reference and the Lua Guide. The API Reference lists every ScapieraScript namespace and method with its signature, parameter descriptions, return type, and a copy-paste code example. Click Insert next to an example to paste it directly at the cursor in the Editor. The Lua Guide is a compact Lua 5.5 quick-reference covering variables, tables, loops, functions, and error handling — useful if you are new to Lua syntax.
Search the API Reference using action words such as "place plant" or "find by type" to jump straight to the relevant method rather than browsing namespace by namespace.
Automations run on the currently active canvas page only. To run an automation across multiple pages, switch to each page in turn and run the automation again. All changes remain undoable with Ctrl/Cmd+Z regardless of how many entities the automation touches.
Automations run in a sandboxed environment — an error in a script does not corrupt your design. If a run produces unexpected results, use Ctrl/Cmd+Z to undo all changes made by that run in a single step.
Frequently Asked Questions
Can automations be shared with other team members on the same project?
Yes. Automations are saved per project, so all team members with access to the project can see and run automations in the My Automations library. To reuse an automation in a different project, export it as a .lua file from the ⋯ menu in the Editor, then paste the source into a blank automation in the target project.
Is ScapieraScript the same as standard Lua?
ScapieraScript is Lua 5.5 with a Scapiera-specific API layer on top. Standard Lua syntax, data structures (tables, strings, numbers), and control flow (if, for, while, functions) work as documented in the Lua 5.5 reference. The additional ScapieraScript methods — for placing entities, querying the canvas, measuring distances, and so on — live under the garden.* namespaces and are documented in the Help tab's API Reference.
Do I need to know how to code to use Automation?
No. The Template Gallery provides ready-made automations for the most common tasks — you can run them as-is or adjust their parameters without writing any code. The Record feature lets you capture manual canvas actions and convert them to code automatically. Writing ScapieraScript from scratch unlocks the full power of the system, but it is not required to get value from Automation.
What can an automation NOT do?
Automations run within the current design canvas and cannot access the file system, write files directly, send network requests, or change project settings such as the unit system or page setup. Each run is initiated manually by clicking Run or Preview — unless you configure an event trigger (for example On entity placed or On selection changed), in which case the automation fires automatically when that canvas event occurs.
Will running an automation break my design if something goes wrong?
No. All entity changes made by an automation are wrapped in a single undo transaction. If the script errors partway through, any partial changes are rolled back automatically. If the run completes but the result is not what you wanted, press Ctrl/Cmd+Z once to undo the entire automation run in one step.