Editor scripting documentation
Version: alpha
Functions
editor.bob()
editor.bob([options],[...commands])
Run bob the builder program
For the full documentation of the available commands and options, see the bob manual.
PARAMETERS
[options] |
table |
table of command line options for bob, without the leading dashes (-- ). You can use snake_case instead of kebab-case for option keys. Only long option names are supported (i.e. output , not o ). Supported value types are strings, integers and booleans. If an option takes no arguments, use a boolean (i.e. true ). If an option may be repeated, you can use an array of values. |
[...commands] |
string |
bob commands, e.g. "resolve" or "build" |
EXAMPLES
Print help in the console:
editor.bob({help = true})
Bundle the game for the host platform:
local opts = {
archive = true,
platform = editor.platform
}
editor.bob(opts, "distclean", "resolve", "build", "bundle")
Using snake_cased and repeated options:
local opts = {
archive = true,
platform = editor.platform,
build_server = "https://build.my-company.com",
settings = {"test.ini", "headless.ini"}
}
editor.bob(opts, "distclean", "resolve", "build")
editor.can_get()
editor.can_get(node,property)
Check if you can get this property so editor.get()
won't throw an error
PARAMETERS
node |
string, userdata |
Either resource path (e.g. "/main/game.script" ), or internal node id passed to the script by the editor |
property |
string |
Either "path" , "text" , or a property from the Outline view (hover the label to see its editor script name) |
RETURNS
editor.can_set()
editor.can_set(node,property)
Check if "set"
action with this property won't throw an error
PARAMETERS
node |
string, userdata |
Either resource path (e.g. "/main/game.script" ), or internal node id passed to the script by the editor |
property |
string |
Either "path" , "text" , or a property from the Outline view (hover the label to see its editor script name) |
RETURNS
editor.create_directory()
editor.create_directory(resource_path)
Create a directory if it does not exist, and all non-existent parent directories.
Throws an error if the directory can't be created.
PARAMETERS
resource_path |
string |
Resource path (starting with / ) of a directory to create |
EXAMPLES
editor.create_directory("/assets/gen")
editor.delete_directory()
editor.delete_directory(resource_path)
Delete a directory if it exists, and all existent child directories and files.
Throws an error if the directory can't be deleted.
PARAMETERS
resource_path |
string |
Resource path (starting with / ) of a directory to delete |
EXAMPLES
editor.delete_directory("/assets/gen")
editor.execute()
editor.execute(command,[...],[options])
Execute a shell command.
Any shell command arguments should be provided as separate argument strings to this function. If the exit code of the process is not zero, this function throws error. By default, the function returns nil
, but it can be configured to capture the output of the shell command as string and return it — set out
option to "capture"
to do it.
By default, after this shell command is executed, the editor will reload resources from disk.
PARAMETERS
command |
string |
Shell command name to execute |
[...] |
string |
Optional shell command arguments |
[options] |
table |
Optional options table. Supported entries: - boolean
reload_resources : make the editor reload the resources from disk after the command is executed, default true - string
out : standard output mode, either: -
"pipe" : the output is piped to the editor console (this is the default behavior). -
"capture" : capture and return the output to the editor script with trailing newlines trimmed. -
"discard" : the output is discarded completely. - string
err : standard error output mode, either: -
"pipe" : the error output is piped to the editor console (this is the default behavior). -
"stdout" : the error output is redirected to the standard output of the process. -
"discard" : the error output is discarded completely. |
RETURNS
result |
nil, string |
If out option is set to "capture" , returns the output as string with trimmed trailing newlines. Otherwise, returns nil . |
EXAMPLES
Make a directory with spaces in it:
editor.execute("mkdir", "new dir")
Read the git status:
local status = editor.execute("git", "status", "--porcelain", {
reload_resources = false,
out = "capture"
})
editor.external_file_attributes()
editor.external_file_attributes(path)
Query information about file system path
PARAMETERS
path |
string |
External file path, resolved against project root if relative |
RETURNS
attributes |
table |
A table with the following keys: path string - resolved file path
exists boolean - whether there is a file system entry at the path
is_file boolean - whether the path corresponds to a file
is_directory boolean - whether the path corresponds to a directory
|
editor.get()
editor.get(node,property)
Get a value of a node property inside the editor.
Some properties might be read-only, and some might be unavailable in different contexts, so you should use editor.can_get()
before reading them and editor.can_set()
before making the editor set them.
PARAMETERS
node |
string, userdata |
Either resource path (e.g. "/main/game.script" ), or internal node id passed to the script by the editor |
property |
string |
Either "path" , "text" , or a property from the Outline view (hover the label to see its editor script name) |
RETURNS
editor.resource_attributes()
editor.resource_attributes(resource_path)
Query information about a project resource
PARAMETERS
resource_path |
string |
Resource path (starting with / ) of a resource to look up |
RETURNS
value |
table |
A table with the following keys:exists boolean - whether a resource identified by the path exists in the project
is_file boolean - whether the resource represents a file with some content
is_directory boolean - whether the resource represents a directory
|
editor.save()
editor.save()
Persist any unsaved changes to disk
PARAMETERS
None
editor.transact()
editor.transact(txs)
Change the editor state in a single, undoable transaction
PARAMETERS
txs |
transaction_step[ |
] An array of transaction steps created using editor.tx.* functions |
editor.tx.set()
editor.tx.set(node,property,value)
Create a set transaction step.
When the step is transacted using editor.transact()
, it will set the node's property to a supplied value
PARAMETERS
node |
string, userdata |
Either resource path (e.g. "/main/game.script" ), or internal node id passed to the script by the editor |
property |
string |
Either "path" , "text" , or a property from the Outline view (hover the label to see its editor script name) |
value |
any |
A new value for the property |
RETURNS
result |
transaction_step |
A transaction step |
editor.ui.button()
editor.ui.button(props)
Button with a label and/or an icon
PARAMETERS
props |
table |
Optional props: on_pressed function - button press callback, will be invoked without arguments when the user presses the button
text string - the text
text_alignment string - text alignment within paragraph bounds; either:
editor.ui.TEXT_ALIGNMENT.LEFT editor.ui.TEXT_ALIGNMENT.CENTER editor.ui.TEXT_ALIGNMENT.RIGHT editor.ui.TEXT_ALIGNMENT.JUSTIFY
icon string - predefined icon name; either:
editor.ui.ICON.OPEN_RESOURCE editor.ui.ICON.PLUS editor.ui.ICON.MINUS editor.ui.ICON.CLEAR
enabled boolean - determines if the input component can be interacted with
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.check_box()
editor.ui.check_box(props)
Check box with a label
PARAMETERS
props |
table |
Optional props: value boolean - determines if the checkbox should appear checked
on_value_changed function - change callback, will receive the new value
text string - the text
text_alignment string - text alignment within paragraph bounds; either:
editor.ui.TEXT_ALIGNMENT.LEFT editor.ui.TEXT_ALIGNMENT.CENTER editor.ui.TEXT_ALIGNMENT.RIGHT editor.ui.TEXT_ALIGNMENT.JUSTIFY
issue table - issue related to the input; table with the following keys (all required):
severity string - either
editor.ui.ISSUE_SEVERITY.WARNING or editor.ui.ISSUE_SEVERITY.ERROR message string - issue message, will be shown in a tooltip
tooltip string - tooltip message, shown on hover
enabled boolean - determines if the input component can be interacted with
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.component()
editor.ui.component(fn)
Convert a function to a UI component.
The wrapped function may call any hooks functions (editor.ui.use_*
), but on any function invocation, the hooks calls must be the same, and in the same order. This means that hooks should not be used inside loops and conditions or after a conditional return statement.
The following props are supported automatically:
grow boolean
- determines if the component should grow to fill available space in a
horizontal
or vertical
layout container row_span integer
- how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid
container. column_span integer
- how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid
container.
PARAMETERS
fn |
function |
function, will receive a single table of props when called |
RETURNS
value |
function |
decorated component function that may be invoked with a props table create component |
editor.ui.dialog()
editor.ui.dialog(props)
Dialog component, a top-level window component that can't be used as a child of other components
PARAMETERS
props |
table |
Required props: title string - OS dialog window title
Optional props: header component - top part of the dialog, defaults to
editor.ui.heading({text = props.title}) content component - content of the dialog
buttons component[] - array of
editor.ui.dialog_button(...) components, footer of the dialog. Defaults to a single Close button
|
RETURNS
value |
component |
UI component |
editor.ui.dialog_button()
editor.ui.dialog_button(props)
Dialog button shown in the footer of a dialog
PARAMETERS
props |
table |
Required props: text string - button text
Optional props: result any - value returned by
editor.ui.show_dialog(...) if this button is pressed default boolean - if set, pressing
Enter in the dialog will trigger this button cancel boolean - if set, pressing
Escape in the dialog will trigger this button enabled boolean - determines if the button can be interacted with
|
RETURNS
value |
component |
UI component |
editor.ui.external_file_field()
editor.ui.external_file_field(props)
Input component for selecting files from the file system
PARAMETERS
props |
table |
Optional props: value string - file or directory path; resolved against project root if relative
on_value_changed function - value change callback, will receive the absolute path of a selected file/folder or nil if the field was cleared; even though the selector dialog allows selecting only files, it's possible to receive directories and non-existent file system entries using text field input
title string - OS window title
filters table[] - File filters, an array of filter tables, where each filter has following keys:
description string - string explaining the filter, e.g.
"Text files (.txt)" extensions string[] - array of file extension patterns, e.g.
".txt" , "." or "game.project"
issue table - issue related to the input; table with the following keys (all required):
severity string - either
editor.ui.ISSUE_SEVERITY.WARNING or editor.ui.ISSUE_SEVERITY.ERROR message string - issue message, will be shown in a tooltip
tooltip string - tooltip message, shown on hover
enabled boolean - determines if the input component can be interacted with
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.grid()
editor.ui.grid(props)
Layout container that places its children in a 2D grid
PARAMETERS
props |
table |
Optional props: children component[][] - array of arrays of child components
rows table[] - array of row option tables, separate configuration for each row:
grow boolean - determines if the row should grow to fill available space
columns table[] - array of column option tables, separate configuration for each column:
grow boolean - determines if the column should grow to fill available space
padding string, number - empty space from the edges of the container to its children; either:
editor.ui.PADDING.NONE editor.ui.PADDING.SMALL editor.ui.PADDING.MEDIUM editor.ui.PADDING.LARGE - non-negative number, pixels
spacing string, number - empty space between child components, defaults to
editor.ui.SPACING.MEDIUM ; either: editor.ui.SPACING.NONE editor.ui.SPACING.SMALL editor.ui.SPACING.MEDIUM editor.ui.SPACING.LARGE - non-negative number, pixels
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.heading()
editor.ui.heading(props)
A text heading
PARAMETERS
props |
table |
Optional props: text string - the text
text_alignment string - text alignment within paragraph bounds; either:
editor.ui.TEXT_ALIGNMENT.LEFT editor.ui.TEXT_ALIGNMENT.CENTER editor.ui.TEXT_ALIGNMENT.RIGHT editor.ui.TEXT_ALIGNMENT.JUSTIFY
color string - semantic color, defaults to
editor.ui.COLOR.TEXT ; either: editor.ui.COLOR.TEXT editor.ui.COLOR.HINT editor.ui.COLOR.OVERRIDE editor.ui.COLOR.WARNING editor.ui.COLOR.ERROR
word_wrap boolean - determines if the lines of text are word-wrapped when they don't fit in the assigned bounds, defaults to true
style string - heading style, defaults to
editor.ui.HEADING_STYLE.H3 ; either: editor.ui.HEADING_STYLE.H1 editor.ui.HEADING_STYLE.H2 editor.ui.HEADING_STYLE.H3 editor.ui.HEADING_STYLE.H4 editor.ui.HEADING_STYLE.H5 editor.ui.HEADING_STYLE.H6 editor.ui.HEADING_STYLE.DIALOG editor.ui.HEADING_STYLE.FORM
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.horizontal()
editor.ui.horizontal(props)
Layout container that places its children in a horizontal row one after another
PARAMETERS
props |
table |
Optional props: children component[] - array of child components
padding string, number - empty space from the edges of the container to its children; either:
editor.ui.PADDING.NONE editor.ui.PADDING.SMALL editor.ui.PADDING.MEDIUM editor.ui.PADDING.LARGE - non-negative number, pixels
spacing string, number - empty space between child components, defaults to
editor.ui.SPACING.MEDIUM ; either: editor.ui.SPACING.NONE editor.ui.SPACING.SMALL editor.ui.SPACING.MEDIUM editor.ui.SPACING.LARGE - non-negative number, pixels
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.icon()
editor.ui.icon(props)
An icon from a predefined set
PARAMETERS
props |
table |
Required props: icon string - predefined icon name; either:
editor.ui.ICON.OPEN_RESOURCE editor.ui.ICON.PLUS editor.ui.ICON.MINUS editor.ui.ICON.CLEAR
Optional props: alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.integer_field()
editor.ui.integer_field(props)
Integer input component based on a text field, reports changes on commit (Enter
or focus loss)
PARAMETERS
props |
table |
Optional props: value any - value
on_value_changed function - value change callback, will receive the new value
issue table - issue related to the input; table with the following keys (all required):
severity string - either
editor.ui.ISSUE_SEVERITY.WARNING or editor.ui.ISSUE_SEVERITY.ERROR message string - issue message, will be shown in a tooltip
tooltip string - tooltip message, shown on hover
enabled boolean - determines if the input component can be interacted with
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.label()
editor.ui.label(props)
Label intended for use with input components
PARAMETERS
props |
table |
Optional props: text string - the text
text_alignment string - text alignment within paragraph bounds; either:
editor.ui.TEXT_ALIGNMENT.LEFT editor.ui.TEXT_ALIGNMENT.CENTER editor.ui.TEXT_ALIGNMENT.RIGHT editor.ui.TEXT_ALIGNMENT.JUSTIFY
color string - semantic color, defaults to
editor.ui.COLOR.TEXT ; either: editor.ui.COLOR.TEXT editor.ui.COLOR.HINT editor.ui.COLOR.OVERRIDE editor.ui.COLOR.WARNING editor.ui.COLOR.ERROR
tooltip string - tooltip message, shown on hover
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.number_field()
editor.ui.number_field(props)
Number input component based on a text field, reports changes on commit (Enter
or focus loss)
PARAMETERS
props |
table |
Optional props: value any - value
on_value_changed function - value change callback, will receive the new value
issue table - issue related to the input; table with the following keys (all required):
severity string - either
editor.ui.ISSUE_SEVERITY.WARNING or editor.ui.ISSUE_SEVERITY.ERROR message string - issue message, will be shown in a tooltip
tooltip string - tooltip message, shown on hover
enabled boolean - determines if the input component can be interacted with
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.open_resource()
editor.ui.open_resource(resource_path)
Open a resource, either in the editor or in a third-party app
PARAMETERS
resource_path |
string |
Resource path (starting with / ) of a resource to open |
editor.ui.paragraph()
editor.ui.paragraph(props)
A paragraph of text
PARAMETERS
props |
table |
Optional props: text string - the text
text_alignment string - text alignment within paragraph bounds; either:
editor.ui.TEXT_ALIGNMENT.LEFT editor.ui.TEXT_ALIGNMENT.CENTER editor.ui.TEXT_ALIGNMENT.RIGHT editor.ui.TEXT_ALIGNMENT.JUSTIFY
color string - semantic color, defaults to
editor.ui.COLOR.TEXT ; either: editor.ui.COLOR.TEXT editor.ui.COLOR.HINT editor.ui.COLOR.OVERRIDE editor.ui.COLOR.WARNING editor.ui.COLOR.ERROR
word_wrap boolean - determines if the lines of text are word-wrapped when they don't fit in the assigned bounds, defaults to true
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.resource_field()
editor.ui.resource_field(props)
Input component for selecting project resources
PARAMETERS
props |
table |
Optional props: value string - resource path (must start with
/ ) on_value_changed function - value change callback, will receive either resource path of a selected resource or nil when the field is cleared; even though the resource selector dialog allows filtering on resource extensions, it's possible to receive resources with other extensions and non-existent resources using text field input
title string - dialog title, defaults to
"Select Resource" extensions string[] - if specified, restricts selectable resources in the dialog to specified file extensions; e.g.
{"collection", "go"} issue table - issue related to the input; table with the following keys (all required):
severity string - either
editor.ui.ISSUE_SEVERITY.WARNING or editor.ui.ISSUE_SEVERITY.ERROR message string - issue message, will be shown in a tooltip
tooltip string - tooltip message, shown on hover
enabled boolean - determines if the input component can be interacted with
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.scroll()
editor.ui.scroll(props)
Layout container that optionally shows scroll bars if child contents overflow the assigned bounds
PARAMETERS
props |
table |
Required props: content component - content component
Optional props: grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.select_box()
editor.ui.select_box(props)
Dropdown select box with an array of options
PARAMETERS
props |
table |
Optional props: value any - selected value
on_value_changed function - change callback, will receive the selected value
options any[] - array of selectable options
to_string function - function that converts an item to a string, defaults to
tostring issue table - issue related to the input; table with the following keys (all required):
severity string - either
editor.ui.ISSUE_SEVERITY.WARNING or editor.ui.ISSUE_SEVERITY.ERROR message string - issue message, will be shown in a tooltip
tooltip string - tooltip message, shown on hover
enabled boolean - determines if the input component can be interacted with
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.separator()
editor.ui.separator(props)
Thin line for visual content separation, by default horizontal and aligned to center
PARAMETERS
props |
table |
Optional props: orientation string - separator line orientation,
editor.ui.ORIENTATION.VERTICAL or editor.ui.ORIENTATION.HORIZONTAL ; either: editor.ui.ORIENTATION.VERTICAL editor.ui.ORIENTATION.HORIZONTAL
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.show_dialog()
editor.ui.show_dialog(dialog)
Show a modal dialog and await a result
PARAMETERS
dialog |
component |
a component that resolves to editor.ui.dialog(...) |
RETURNS
value |
any |
dialog result, the value used as a result prop in a editor.ui.dialog_button({...}) selected by the user, or nil if the dialog was closed and there was no cancel = true dialog button with result prop set |
editor.ui.show_external_directory_dialog()
editor.ui.show_external_directory_dialog([opts])
Show a modal OS directory selection dialog and await a result
PARAMETERS
[opts] |
table |
path string - initial file or directory path used by the dialog; resolved against project root if relative
title string - OS window title
|
RETURNS
value |
string, nil |
either absolute directory path or nil if user canceled directory selection |
editor.ui.show_external_file_dialog()
editor.ui.show_external_file_dialog([opts])
Show a modal OS file selection dialog and await a result
PARAMETERS
[opts] |
table |
path string - initial file or directory path used by the dialog; resolved against project root if relative
title string - OS window title
filters table[] - File filters, an array of filter tables, where each filter has following keys:
description string - string explaining the filter, e.g.
"Text files (*.txt)" extensions string[] - array of file extension patterns, e.g.
"*.txt" , "*.*" or "game.project"
|
RETURNS
value |
string, nil |
either absolute file path or nil if user canceled file selection |
editor.ui.show_resource_dialog()
editor.ui.show_resource_dialog([opts])
Show a modal resource selection dialog and await a result
PARAMETERS
[opts] |
table |
extensions string[] - if specified, restricts selectable resources in the dialog to specified file extensions; e.g.
{"collection", "go"} selection string - either
"single" or "multiple" , defaults to "single" title string - dialog title, defaults to
"Select Resource"
|
RETURNS
value |
string, string[ |
|nil] if user made no selection, returns nil . Otherwise, if selection mode is "single" , returns selected resource path; otherwise returns a non-empty array of selected resource paths. |
editor.ui.string_field()
editor.ui.string_field(props)
String input component based on a text field, reports changes on commit (Enter
or focus loss)
PARAMETERS
props |
table |
Optional props: value any - value
on_value_changed function - value change callback, will receive the new value
issue table - issue related to the input; table with the following keys (all required):
severity string - either
editor.ui.ISSUE_SEVERITY.WARNING or editor.ui.ISSUE_SEVERITY.ERROR message string - issue message, will be shown in a tooltip
tooltip string - tooltip message, shown on hover
enabled boolean - determines if the input component can be interacted with
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
editor.ui.use_memo()
editor.ui.use_memo(compute,[...])
A hook that caches the result of a computation between re-renders.
See editor.ui.component
for hooks caveats and rules. If any of the arguments to use_memo
change during a component refresh (checked with ==
), the value will be recomputed.
PARAMETERS
compute |
function |
function that will be used to compute the cached value |
[...] |
...any |
args to the computation function |
RETURNS
values |
...any |
all returned values of the compute function |
EXAMPLES
local function increment(n)
return n + 1
end
local function make_listener(set_count)
return function()
set_count(increment)
end
end
local counter_button = editor.ui.component(function(props)
local count, set_count = editor.ui.use_state(props.count)
local on_pressed = editor.ui.use_memo(make_listener, set_count)
return editor.ui.text_button {
text = tostring(count),
on_pressed = on_pressed
}
end)
editor.ui.use_state()
editor.ui.use_state(init,[...])
A hook that adds local state to the component.
See editor.ui.component
for hooks caveats and rules. If any of the arguments to use_state
change during a component refresh (checked with ==
), the current state will be reset to the initial one.
PARAMETERS
init |
any, function |
local state initializer, either initial data structure or function that produces the data structure |
[...] |
...any |
used when init is a function, the args are passed to the initializer function |
RETURNS
state |
any |
current local state, starts with initial state, then may be changed using the returned set_state function |
set_state |
function |
function that changes the local state and causes the component to refresh. The function may be used in 2 ways: - to set the state to some other data structure: pass the data structure as a value
- to replace the state using updater function: pass a function to
set_state — it will be invoked with the current state, as well as with the rest of the arguments passed to set_state after the updater function. The state will be set to the value returned from the updater function |
EXAMPLES
local function increment(n)
return n + 1
end
local counter_button = editor.ui.component(function(props)
local count, set_count = editor.ui.use_state(props.count)
return editor.ui.text_button {
text = tostring(count),
on_pressed = function()
set_count(increment)
end
}
end)
editor.ui.vertical()
editor.ui.vertical(props)
Layout container that places its children in a vertical column one after another
PARAMETERS
props |
table |
Optional props: children component[] - array of child components
padding string, number - empty space from the edges of the container to its children; either:
editor.ui.PADDING.NONE editor.ui.PADDING.SMALL editor.ui.PADDING.MEDIUM editor.ui.PADDING.LARGE - non-negative number, pixels
spacing string, number - empty space between child components, defaults to
editor.ui.SPACING.MEDIUM ; either: editor.ui.SPACING.NONE editor.ui.SPACING.SMALL editor.ui.SPACING.MEDIUM editor.ui.SPACING.LARGE - non-negative number, pixels
alignment string - alignment of the component content within its assigned bounds, defaults to
editor.ui.ALIGNMENT.TOP_LEFT ; either: editor.ui.ALIGNMENT.TOP_LEFT editor.ui.ALIGNMENT.TOP editor.ui.ALIGNMENT.TOP_RIGHT editor.ui.ALIGNMENT.LEFT editor.ui.ALIGNMENT.CENTER editor.ui.ALIGNMENT.RIGHT editor.ui.ALIGNMENT.BOTTOM_LEFT editor.ui.ALIGNMENT.BOTTOM editor.ui.ALIGNMENT.BOTTOM_RIGHT
grow boolean - determines if the component should grow to fill available space in a
horizontal or vertical layout container row_span integer - how many rows the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container. column_span integer - how many columns the component spans inside a grid container, must be positive. This prop is only useful for components inside a
grid container.
|
RETURNS
value |
component |
UI component |
Constants
editor.editor_sha1
A string, SHA1 of Defold editor
editor.engine_sha1
A string, SHA1 of Defold engine
editor.platform
Editor platform id.
A string
, either:
- "x86_64-win32"
- "x86_64-macos"
- "arm64-macos"
- "x86_64-linux"
editor.ui.ALIGNMENT.BOTTOM
"bottom"
editor.ui.ALIGNMENT.BOTTOM_LEFT
"bottom-left"
editor.ui.ALIGNMENT.BOTTOM_RIGHT
"bottom-right"
editor.ui.ALIGNMENT.CENTER
"center"
editor.ui.ALIGNMENT.LEFT
"left"
editor.ui.ALIGNMENT.RIGHT
"right"
editor.ui.ALIGNMENT.TOP
"top"
editor.ui.ALIGNMENT.TOP_LEFT
"top-left"
editor.ui.ALIGNMENT.TOP_RIGHT
"top-right"
editor.ui.COLOR.ERROR
"error"
editor.ui.COLOR.HINT
"hint"
editor.ui.COLOR.OVERRIDE
"override"
editor.ui.COLOR.TEXT
"text"
editor.ui.COLOR.WARNING
"warning"
editor.ui.HEADING_STYLE.DIALOG
"dialog"
editor.ui.HEADING_STYLE.FORM
"form"
editor.ui.HEADING_STYLE.H1
"h1"
editor.ui.HEADING_STYLE.H2
"h2"
editor.ui.HEADING_STYLE.H3
"h3"
editor.ui.HEADING_STYLE.H4
"h4"
editor.ui.HEADING_STYLE.H5
"h5"
editor.ui.HEADING_STYLE.H6
"h6"
editor.ui.ICON.CLEAR
"clear"
editor.ui.ICON.MINUS
"minus"
editor.ui.ICON.OPEN_RESOURCE
"open-resource"
editor.ui.ICON.PLUS
"plus"
editor.ui.ISSUE_SEVERITY.ERROR
"error"
editor.ui.ISSUE_SEVERITY.WARNING
"warning"
editor.ui.ORIENTATION.HORIZONTAL
"horizontal"
editor.ui.ORIENTATION.VERTICAL
"vertical"
editor.ui.PADDING.LARGE
"large"
editor.ui.PADDING.MEDIUM
"medium"
editor.ui.PADDING.NONE
"none"
editor.ui.PADDING.SMALL
"small"
editor.ui.SPACING.LARGE
"large"
editor.ui.SPACING.MEDIUM
"medium"
editor.ui.SPACING.NONE
"none"
editor.ui.SPACING.SMALL
"small"
editor.ui.TEXT_ALIGNMENT.CENTER
"center"
editor.ui.TEXT_ALIGNMENT.JUSTIFY
"justify"
editor.ui.TEXT_ALIGNMENT.LEFT
"left"
editor.ui.TEXT_ALIGNMENT.RIGHT
"right"
editor.version
A string, version name of Defold