Code Editor

All automations follow a standard structure:

```lua --@name My Automation --@description A short description of what this does

function main() -- Your automation code here end ```

The --@name and --@description annotations set the automation's display name and description in the My Automations tab. The main() function is the entry point — execution starts here when you click Run.

All GardenlyScript API methods are available inside main(). Press Ctrl+Space to see completions. The API is organized into namespaces:

• garden.entities — query and create entities
• garden.selection — control canvas selection
• garden.layers — manage layers
• garden.measurement — compute geometric measurements
• garden.ui — show messages and dialogs
• math, string, table — standard Lua libraries

The --@param annotation syntax declares input parameters that appear as form controls in the Parameters section of the Editor sidebar and IDE right pane.

Annotation format: ``lua --@param name type label [default] [options] ``

Examples: ``lua --@param spacing number "Plant spacing (m)" 1.0 min=0.3 max=5.0 --@param plantName string "Plant species" "Rosa canina" --@param layer dropdown "Target layer" "Planting" options=layers --@param includeLabels boolean "Add name labels" true ``

Supported types: number, string, boolean, dropdown, color.

For dropdown type, options=layers populates the dropdown with current project layer names. Custom static options use options="Option A,Option B,Option C".

Declared parameters are available in main() as local variables with the same name as the annotation's first word.

When an automation run produces a runtime error, the code editor highlights the error location:

• The line that caused the error shows a ruby-red left border in the gutter
• The status bar at the bottom of the editor shows the error message and line number (e.g. Line 12: attempt to index a nil value (local 'entity'))
• The Output tab in the right pane shows the full stack trace

Common error patterns:

• attempt to index a nil value — a variable expected to hold an entity or object is nil; check that garden.entities.findByName() returned a result before accessing its properties
• attempt to perform arithmetic on a string — a parameter value that should be a number is being passed as a string; check the --@param type annotation
• undefined global — a function or variable name is misspelled; check for typos

Fix the highlighted line and click Run again to retest.

Press Ctrl+Space anywhere in the code editor to open the auto-complete suggestions panel.

The suggestions are context-aware:

• After typing garden., the panel shows all top-level API namespaces
• After typing garden.entities., the panel shows all entity methods
• After opening a method call, the panel shows the method signature and parameter types

Each suggestion shows:

• Method name (bold)
• Parameter list with types
• A one-line description

Press Enter or Tab to accept a suggestion. Press Escape to dismiss.

Auto-complete also suggests Lua built-ins (string.format, table.insert, math.floor, etc.) and any local variables declared earlier in the same function scope.

Switch to the How do I… tab in the Automation panel to browse the full GardenlyScript API reference without leaving the editor.

The API reference tab shows all namespaces and methods with signatures, parameter descriptions, and code examples. Click Insert into script on any example to paste it at your cursor position in the Code editor.

Press Ctrl+Enter while the editor is focused to run the automation immediately — this is identical to clicking the Run button in the toolbar. The source is saved automatically before each run; there is no separate Save button. To test changes non-destructively, press Ctrl+Shift+Enter to start a Preview run: mutations are applied to the canvas but not persisted to the project until you click Apply. Click Cancel to revert the preview and restore the canvas to its state before the test.