Editor scripting documentation

Version: beta

FUNCTIONS
editor.bob() run bob the builder program
editor.browse() open a URL in the default browser or a registered application
editor.bundle.assoc() immutably set a key to value in a table
editor.bundle.assoc_in() immutably set a value to a nested path in a table
editor.bundle.check_box() helper function for creating a check box component
editor.bundle.check_boxes_grid_row() create a grid row for the common boolean settings
editor.bundle.command() create bundle command definition
editor.bundle.common_variant_grid_row() create a grid row for the common variant setting
editor.bundle.config() get bundle config, optionally showing a dialog to edit the config
editor.bundle.config_schema() helper function for constructing prefs schema for new bundle dialogs
editor.bundle.create() create bob bundle
editor.bundle.desktop_variant_grid_row() create a grid row for the desktop variant setting
editor.bundle.dialog() helper function for creating a bundle dialog component
editor.bundle.external_file_field() helper function for creating an external file field component
editor.bundle.grid_row() return a 2-element array that represents a single grid row in a bundle dialog
editor.bundle.make_to_string_lookup() make stringifier function that first performs the label lookup in a provided table
editor.bundle.output_directory() get bundle output directory, optionally showing a directory selection dialog
editor.bundle.select_box() helper function for creating a select box component
editor.bundle.set_element_check_box() helper function for creating a check box for an enum value of set config key
editor.bundle.texture_compression_grid_row() create a grid row for the texture compression setting
editor.can_get() check if you can get this property so editor.get() won't throw an error
editor.can_set() check if "set" action with this property won't throw an error
editor.create_directory() create a directory if it does not exist, and all non-existent parent directories.
editor.delete_directory() delete a directory if it exists, and all existent child directories and files.
editor.execute() execute a shell command.
editor.external_file_attributes() query information about file system path
editor.get() get a value of a node property inside the editor.
editor.open_external_file() open a file in a registered application
editor.prefs.get() get preference value
editor.prefs.is_set() check if preference value is explicitly set
editor.prefs.schema.array() array schema
editor.prefs.schema.boolean() boolean schema
editor.prefs.schema.enum() enum value schema
editor.prefs.schema.integer() integer schema
editor.prefs.schema.keyword() keyword schema
editor.prefs.schema.number() floating-point number schema
editor.prefs.schema.object() heterogeneous object schema
editor.prefs.schema.object_of() homogeneous object schema
editor.prefs.schema.set() set schema
editor.prefs.schema.string() string schema
editor.prefs.schema.tuple() tuple schema
editor.prefs.set() set preference value
editor.resource_attributes() query information about a project resource
editor.save() persist any unsaved changes to disk
editor.transact() change the editor state in a single, undoable transaction
editor.tx.set() create a set transaction step.
editor.ui.button() button with a label and/or an icon
editor.ui.check_box() check box with a label
editor.ui.component() convert a function to a UI component.
editor.ui.dialog() dialog component, a top-level window component that can't be used as a child of other components
editor.ui.dialog_button() dialog button shown in the footer of a dialog
editor.ui.external_file_field() input component for selecting files from the file system
editor.ui.grid() layout container that places its children in a 2D grid
editor.ui.heading() a text heading
editor.ui.horizontal() layout container that places its children in a horizontal row one after another
editor.ui.icon() an icon from a predefined set
editor.ui.integer_field() integer input component based on a text field, reports changes on commit (Enter or focus loss)
editor.ui.label() label intended for use with input components
editor.ui.number_field() number input component based on a text field, reports changes on commit (Enter or focus loss)
editor.ui.open_resource() open a resource, either in the editor or in a third-party app
editor.ui.paragraph() a paragraph of text
editor.ui.resource_field() input component for selecting project resources
editor.ui.scroll() layout container that optionally shows scroll bars if child contents overflow the assigned bounds
editor.ui.select_box() dropdown select box with an array of options
editor.ui.separator() thin line for visual content separation, by default horizontal and aligned to center
editor.ui.show_dialog() show a modal dialog and await a result
editor.ui.show_external_directory_dialog() show a modal OS directory selection dialog and await a result
editor.ui.show_external_file_dialog() show a modal OS file selection dialog and await a result
editor.ui.show_resource_dialog() show a modal resource selection dialog and await a result
editor.ui.string_field() string input component based on a text field, reports changes on commit (Enter or focus loss)
editor.ui.use_memo() a hook that caches the result of a computation between re-renders.
editor.ui.use_state() a hook that adds local state to the component.
editor.ui.vertical() layout container that places its children in a vertical column one after another
http.request() perform an HTTP request
json.decode() decode JSON string to Lua value
json.encode() encode Lua value to JSON string
pprint() pretty-print a Lua value
CONSTANTS
editor.bundle.abort_message error message the signifies bundle abort that is not an error
editor.bundle.common_variant_schema prefs schema for common bundle variants
editor.bundle.desktop_variant_schema prefs schema for desktop bundle variants
editor.editor_sha1 a string, SHA1 of Defold editor
editor.engine_sha1 a string, SHA1 of Defold engine
editor.platform editor platform id.
editor.prefs.SCOPE.GLOBAL "global"
editor.prefs.SCOPE.PROJECT "project"
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

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.browse()

editor.browse(url)

Open a URL in the default browser or a registered application

PARAMETERS

url string http(s) or file URL

editor.bundle.assoc()

editor.bundle.assoc(table,key,value)

Immutably set a key to value in a table

PARAMETERS

table table the table
key any the key
value any the value

RETURNS

table table New table if it should be changed by assoc, or the input table otherwise

editor.bundle.assoc_in()

editor.bundle.assoc_in(table,keys,value)

Immutably set a value to a nested path in a table

PARAMETERS

table table the table
keys any[ ] the keys
value any the value

RETURNS

table table New table if it should be changed by assoc_in, or the input table otherwise

editor.bundle.check_box()

editor.bundle.check_box(config,set_config,key,text,[rest_props])

Helper function for creating a check box component

PARAMETERS

config table config table
set_config function config setter
key string config key for the selected value
text string check box label text
[rest_props] table extra props for editor.ui.check_box

RETURNS

check_box component UI component

editor.bundle.check_boxes_grid_row()

editor.bundle.check_boxes_grid_row(config,set_config)

Create a grid row for the common boolean settings

PARAMETERS

config table config map with common boolean keys
set_config function config setter

RETURNS

row component[ ] grid row

editor.bundle.command()

editor.bundle.command(label,id,fn,[rest])

Create bundle command definition

PARAMETERS

label string Command label, as presented in the UI
id string Command id, e.g. "bundle-my-platform", used for re-bundling
fn function bundle function, will receive a requested_dialog boolean argument
[rest] table extra keys for the command definition, e.g. active

editor.bundle.common_variant_grid_row()

editor.bundle.common_variant_grid_row(config,set_config)

Create a grid row for the common variant setting

PARAMETERS

config table config map with variant key
set_config function config setter

RETURNS

row component[ ] grid row

editor.bundle.config()

editor.bundle.config(requested_dialog,prefs_key,dialog_component,[errors_fn])

Get bundle config, optionally showing a dialog to edit the config

PARAMETERS

requested_dialog boolean whether the user explicitly requested a dialog
prefs_key string preference key used for loading the bundle config
dialog_component component UI component for the dialog, will receive config and (optional) errors props
[errors_fn] function error checking predicate, takes config as an argument; if returns truthy value, it will be passed as a prop to dialog_component

RETURNS

config any

editor.bundle.config_schema()

editor.bundle.config_schema(variant_schema,[properties])

Helper function for constructing prefs schema for new bundle dialogs

PARAMETERS

variant_schema schema bundle variant schema
[properties] table, nil extra config properties

RETURNS

schema schema full bundle schema, defines a project-scoped object schema with the following keys:
variant
the provided variant schema
texture_compression string
either enabled, disabled or editor
with_symbols boolean
build_report boolean
liveupdate boolean
contentless boolean

editor.bundle.create()

editor.bundle.create(config,output_directory,extra_bob_opts)

Create bob bundle

PARAMETERS

config table bundle config
output_directory string bundle output directory
extra_bob_opts table extra bob opts, presumably produced from config

editor.bundle.desktop_variant_grid_row()

editor.bundle.desktop_variant_grid_row(config,set_config)

Create a grid row for the desktop variant setting

PARAMETERS

config table config table with variant key
set_config function config setter

RETURNS

row component[ ] grid row

editor.bundle.dialog()

editor.bundle.dialog(heading,config,hint,error,rows)

Helper function for creating a bundle dialog component

PARAMETERS

heading string dialog heading text
config table config map with common boolean keys
hint string, nil dialog hint text
error string, nil dialog error text
rows component[ []] grid rows of UI elements, dialog content

RETURNS

dialog component UI component

editor.bundle.external_file_field()

editor.bundle.external_file_field(config,set_config,key,[error],[rest_props])

Helper function for creating an external file field component

PARAMETERS

config table config map with common boolean keys
set_config function config setter
key string config key for the set
[error] string error message
[rest_props] table extra props for editor.ui.external_file_field

RETURNS

external_file_field component UI component

editor.bundle.grid_row()

editor.bundle.grid_row(text,content)

Return a 2-element array that represents a single grid row in a bundle dialog

PARAMETERS

text string, nil optional string label
content component, component[ ] either a single UI component, or an array of components (will be laid out vertically)

RETURNS

row component[ ] a single grid row

editor.bundle.make_to_string_lookup()

editor.bundle.make_to_string_lookup(table)

Make stringifier function that first performs the label lookup in a provided table

PARAMETERS

table table table from values to their corresponding string representation

RETURNS

to_string function stringifier function

editor.bundle.output_directory()

editor.bundle.output_directory(requested_dialog,output_subdir)

Get bundle output directory, optionally showing a directory selection dialog

PARAMETERS

requested_dialog boolean whether the user explicitly requested a dialog
output_subdir string output subdir, usually a platform name

editor.bundle.select_box()

editor.bundle.select_box(config,set_config,key,options,to_string,[rest_props])

Helper function for creating a select box component

PARAMETERS

config table config table
set_config function config setter
key string config key for the selected value
options any[ ] select box options
to_string function option stringifier
[rest_props] table extra props for editor.ui.select_box

RETURNS

select_box component UI component

editor.bundle.set_element_check_box()

editor.bundle.set_element_check_box(config,set_config,key,element,text,[error])

Helper function for creating a check box for an enum value of set config key

PARAMETERS

config table config map with common boolean keys
set_config function config setter
key string config key for the set
element string enum value in the set
text string check box label text
[error] string error message

RETURNS

check_box component UI component

editor.bundle.texture_compression_grid_row()

editor.bundle.texture_compression_grid_row(config,set_config)

Create a grid row for the texture compression setting

PARAMETERS

config table config map with texture_compression key
set_config function config setter

RETURNS

row component[ ] grid row

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

value boolean

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

value boolean

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

value any property value

editor.open_external_file()

editor.open_external_file(path)

Open a file in a registered application

PARAMETERS

path string file path

editor.prefs.get()

editor.prefs.get(key)

Get preference value The schema for the preference value should be defined beforehand.

PARAMETERS

key string dot-separated preference key path

RETURNS

value any current pref value or default if a schema for the key path exists, nil otherwise

editor.prefs.is_set()

editor.prefs.is_set(key)

Check if preference value is explicitly set The schema for the preference value should be defined beforehand.

PARAMETERS

key string dot-separated preference key path

RETURNS

value boolean flag indicating if the value is explicitly set

editor.prefs.schema.array()

editor.prefs.schema.array(opts)

array schema

PARAMETERS

opts table Required opts:
item schema
array item schema
Optional opts:
default item[]
default value
scope string
preference scope; either:
  • editor.prefs.SCOPE.GLOBAL: same preference value is used in every project on this computer
  • editor.prefs.SCOPE.PROJECT: a separate preference value per project

RETURNS

value schema Prefs schema

editor.prefs.schema.boolean()

editor.prefs.schema.boolean([opts])

boolean schema

PARAMETERS

[opts] table Optional opts:
default boolean
default value
scope string
preference scope; either:
  • editor.prefs.SCOPE.GLOBAL: same preference value is used in every project on this computer
  • editor.prefs.SCOPE.PROJECT: a separate preference value per project

RETURNS

value schema Prefs schema

editor.prefs.schema.enum()

editor.prefs.schema.enum(opts)

enum value schema

PARAMETERS

opts table Required opts:
values any[]
allowed values, must be scalar (nil, boolean, number or string)
Optional opts:
default any
default value
scope string
preference scope; either:
  • editor.prefs.SCOPE.GLOBAL: same preference value is used in every project on this computer
  • editor.prefs.SCOPE.PROJECT: a separate preference value per project

RETURNS

value schema Prefs schema

editor.prefs.schema.integer()

editor.prefs.schema.integer([opts])

integer schema

PARAMETERS

[opts] table Optional opts:
default integer
default value
scope string
preference scope; either:
  • editor.prefs.SCOPE.GLOBAL: same preference value is used in every project on this computer
  • editor.prefs.SCOPE.PROJECT: a separate preference value per project

RETURNS

value schema Prefs schema

editor.prefs.schema.keyword()

editor.prefs.schema.keyword([opts])

keyword schema A keyword is a short string that is interned within the editor runtime, useful e.g. for identifiers

PARAMETERS

[opts] table Optional opts:
default string
default value
scope string
preference scope; either:
  • editor.prefs.SCOPE.GLOBAL: same preference value is used in every project on this computer
  • editor.prefs.SCOPE.PROJECT: a separate preference value per project

RETURNS

value schema Prefs schema

editor.prefs.schema.number()

editor.prefs.schema.number([opts])

floating-point number schema

PARAMETERS

[opts] table Optional opts:
default number
default value
scope string
preference scope; either:
  • editor.prefs.SCOPE.GLOBAL: same preference value is used in every project on this computer
  • editor.prefs.SCOPE.PROJECT: a separate preference value per project

RETURNS

value schema Prefs schema

editor.prefs.schema.object()

editor.prefs.schema.object(opts)

heterogeneous object schema

PARAMETERS

opts table Required opts:
properties table<string, schema>
a table from property key (string) to value schema
Optional opts:
default table
default value
scope string
preference scope; either:
  • editor.prefs.SCOPE.GLOBAL: same preference value is used in every project on this computer
  • editor.prefs.SCOPE.PROJECT: a separate preference value per project

RETURNS

value schema Prefs schema

editor.prefs.schema.object_of()

editor.prefs.schema.object_of(opts)

homogeneous object schema

PARAMETERS

opts table Required opts:
key schema
table key schema
val schema
table value schema
Optional opts:
default table
default value
scope string
preference scope; either:
  • editor.prefs.SCOPE.GLOBAL: same preference value is used in every project on this computer
  • editor.prefs.SCOPE.PROJECT: a separate preference value per project

RETURNS

value schema Prefs schema

editor.prefs.schema.set()

editor.prefs.schema.set(opts)

set schema Set is represented as a lua table with true values

PARAMETERS

opts table Required opts:
item schema
set item schema
Optional opts:
default table<item, true>
default value
scope string
preference scope; either:
  • editor.prefs.SCOPE.GLOBAL: same preference value is used in every project on this computer
  • editor.prefs.SCOPE.PROJECT: a separate preference value per project

RETURNS

value schema Prefs schema

editor.prefs.schema.string()

editor.prefs.schema.string([opts])

string schema

PARAMETERS

[opts] table Optional opts:
default string
default value
scope string
preference scope; either:
  • editor.prefs.SCOPE.GLOBAL: same preference value is used in every project on this computer
  • editor.prefs.SCOPE.PROJECT: a separate preference value per project

RETURNS

value schema Prefs schema

editor.prefs.schema.tuple()

editor.prefs.schema.tuple(opts)

tuple schema A tuple is a fixed-length array where each item has its own defined type

PARAMETERS

opts table Required opts:
items schema[]
schemas for the items
Optional opts:
default any[]
default value
scope string
preference scope; either:
  • editor.prefs.SCOPE.GLOBAL: same preference value is used in every project on this computer
  • editor.prefs.SCOPE.PROJECT: a separate preference value per project

RETURNS

value schema Prefs schema

editor.prefs.set()

editor.prefs.set(key,value)

Set preference value The schema for the preference value should be defined beforehand.

PARAMETERS

key string dot-separated preference key path
value any new pref value to set

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

http.request()

http.request(url,[opts])

Perform an HTTP request

PARAMETERS

url string request URL
[opts] table Additional request options, a table with the following keys:
method string
request method, defaults to "GET"
headers table
request headers, a table with string keys and values
body string
request body
as string
Response body converter, either "string" or "json"

RETURNS

response table HTTP response, a table with the following keys:
status integer
response code
headers table
response headers, a table where each key is a lower-cased string, and each value is either a string or an array of strings if the header was repeated
body string, any, nil
response body, present only when as option was provided, either a string or a parsed json value

json.decode()

json.decode(json,[options])

Decode JSON string to Lua value

PARAMETERS

json string json data
[options] table A table with the following keys:
all boolean
if true, decodes all json values in a string and returns an array

json.encode()

json.encode(value)

Encode Lua value to JSON string

PARAMETERS

value any any lua value that may be represented as JSON

pprint()

pprint(value)

Pretty-print a Lua value

PARAMETERS

value any any lua value to pretty-print

Constants

editor.bundle.abort_message

Error message the signifies bundle abort that is not an error

editor.bundle.common_variant_schema

prefs schema for common bundle variants

editor.bundle.desktop_variant_schema

prefs schema for desktop bundle variants

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.prefs.SCOPE.GLOBAL

"global"

editor.prefs.SCOPE.PROJECT

"project"

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