Record and Preview
Record your manual canvas actions to generate automation code automatically. Preview runs show results with visual badges before you commit any changes to the design.
Record mode captures your manual canvas actions — placing entities, moving objects, changing properties — and converts each action to a ScapieraScript code snippet. This is the lowest barrier to automation: do the task once manually and capture it as reusable code.
Preview mode runs an automation in a sandboxed non-destructive pass. New entities are shown with blue NEW badges. Entities that would be deleted are shown with red strikethrough badges. No changes are applied to the canvas until you click Apply.
Both Record and Preview are accessed from the Editor toolbar in the IDE Layout (Row 2).
Start recording
In the IDE Layout, click the Record button (red circle icon) in the Editor toolbar Row 2.
When recording starts:
- The Record button turns solid red
- A red pulse indicator appears in the status bar at the bottom of the canvas
- A Transcript pane opens in the left pane of the IDE (replacing the code editor temporarily)
- The canvas becomes fully interactive
You are now in recording mode. Every action you perform on the canvas is captured.
Perform actions on the canvas
With recording active, perform the design actions you want to automate:
- Place entities — select a tool (plant, shape, etc.) and click the canvas to place entities
- Move entities — select and drag entities to new positions
- Resize entities — use the selection handles to resize
- Change properties — open the Inspector and change entity properties (materials, dimensions, names, layers)
- Select entities — click to select, rubber-band to multi-select
As you perform each action, the Transcript pane in the IDE shows the corresponding code snippet for that action. Each snippet is shown as a labeled card.
Up to 500 snippets can be captured in a single recording session. The transcript shows a counter at the top.
For placement automations (e.g. placing plants in a row), record placing just two or three plants at specific positions — then edit the captured code to replace the hardcoded positions with a loop.
Review the transcript
While recording (or after stopping), the Transcript pane shows each captured action as a code snippet card. Each card shows:
- A short human-readable label describing the action (e.g. "Placed Lavandula angustifolia at (5.2, 3.1)")
- The corresponding ScapieraScript code for that action
- A checkbox to include or exclude the snippet from the saved automation
You can:
- Deselect snippets you do not want to include (e.g. undo actions, accidental clicks)
- Reorder snippet cards by dragging (though the execution order should match the recorded order for most automations)
- Edit individual snippets inline by clicking the code text
After saving, open the code editor and add --@param annotations to any hardcoded values. This turns a one-off recording into a reusable flexible automation.
Stop recording and save
Click Stop (the square icon that replaces the Record button while recording is active) to end the recording session.
After stopping:
- The Transcript pane shows the full list of captured snippets
- A Save as Automation button appears at the top of the Transcript pane
- Click Save as Automation to create a new automation from the selected snippets
The new automation opens in the code editor with all selected snippet code assembled into a main() function. The automation is automatically saved to the My Automations library.
You can also click Copy all snippets to copy the raw code to the clipboard and paste it into an existing automation.
Generalise the captured code
Open the collapsible Code section in the Editor tab to see and edit the saved source. Replace hardcoded entity IDs with garden.find.* lookups and literal coordinates with --@param parameters or calculated offsets. This turns a session-specific recording into an automation that works correctly on any project. Adding --@param annotations also makes those values appear as editable fields in the parameter form above the code, so non-technical team members can adjust them without touching the code.
For placement automations, record placing two or three entities at fixed positions, then replace the coordinates with a loop. The recording gives you the correct garden.place.* call signature (for example garden.place.plant) — you only need to add the iteration logic.
Preview the automation before committing
Click Preview in the Editor tab to run a non-destructive trial of the automation. Changes are applied to the canvas immediately so you can inspect the result in 2D and 3D — but nothing is saved to the project yet. When you are satisfied, click Apply to persist the changes. If the result is not what you expected, click Cancel to discard everything and leave the canvas exactly as it was before the preview.
Record → Save → Preview → Apply is the recommended iteration loop. Capture the task once manually, save it, confirm the result looks right in preview, then commit only when you are happy.
Recording captures up to 500 snippets per session. When the limit is reached, recording stops automatically and a comment is appended noting that the limit was hit. If your workflow is longer, record it in multiple shorter sessions and merge the saved sources in the code editor.
Recorded snippets are drafts, not production-ready code. Entity IDs are captured from the live session and will not match IDs in other projects or after entities are deleted and re-created. Always generalise the captured source with garden.find.* calls before sharing or reusing an automation.
Frequently Asked Questions
Does recording capture Undo actions?
No. Undo actions during recording are intentionally ignored. Only forward canvas actions — place, move, resize, delete, property change — produce snippets. If you undo a step mid-recording, that action simply does not appear in the captured output.
What appears in the Recording panel for unsupported actions?
Actions that cannot be represented as executable Lua — such as UI mode changes or panel interactions — are silently skipped and produce no output. Actions that are recognised but lack enough public data to emit a full call appear as a -- (recorded: description) comment placeholder. These comments are useful as reminders of what happened but need to be replaced with real code before the automation runs.
What is the difference between Preview and a normal Run?
A normal Run applies changes immediately and permanently adds them to the project's undo history (reversible with Ctrl/Cmd+Z). Preview holds the changes in a local state on the canvas and waits for your decision — click Apply to flush them to the project, or Cancel to discard them entirely with no undo step required.
Can I preview an automation that has parameters?
Yes. Fill in the parameter form fields in the Editor tab before clicking Preview. The preview run uses the current parameter values exactly as a normal run would. You can adjust parameters and re-run Preview as many times as you like before committing with Apply.
Is there a limit to how many times I can preview before applying?
No. You can run Preview repeatedly, each time with different parameter values, to compare outcomes. Only one preview result can be pending Apply or Cancel at a time — starting a new Preview automatically discards the previous pending result.