- Overview
- Align - (align.h)
- Atomic - (atomic.h)
- ConfigFile - (configfile.h)
- Extension - (extension.h)
- Font - (font.h)
- FontCollection - (fontcollection.h)
- Hash - (hash.h)
- JobSystem - (jobsystem.h)
- Resource - (resource.h)
- Strings - (dstrings.h)
- TextLayout - (text_layout.h)
- Window - (window.h)
- Overview
- Array - (array.h)
- dmAndroid - (android.h)
- dmBuffer - (buffer.h)
- dmConditionVariable - (condition_variable.h)
- dmConfigFile - (configfile_gen.hpp)
- dmConnectionPool - (connection_pool.h)
- dmCrypt - (crypt.h)
- dmDDF - (ddf.h)
- dmDoubleLinkedList - (double_linked_list.h)
- dmEngine - (extension.hpp)
- dmExtension - (extension_gen.hpp)
- dmFileDescriptor - (file_descriptor.h)
- comp_collection_factory.h
- comp_factory.h
- comp_gui.h
- comp_model.h
- gui.h
- property.h
- render_constants.h
- res_data.h
- res_font.h
- res_light.h
- dmGui - (gui.h)
- dmHid - (hid.h)
- dmHttpClient - (http_client.h)
- dmImage - (image.h)
- dmIntersection - (intersection.h)
- dmMath - (math.h)
- dmMemory - (memory.h)
- dmMessage - (message.h)
- dmMutex - (mutex.h)
- dmPhysics - (physics.h)
- dmProfile - (profile.h)
- dmRender - (render.h)
- dmSocket - (socket.h)
- dmSound - (sound.h)
- dmSpinlock - (spinlock.h)
- dmSSLSocket - (sslsocket.h)
- dmStaticAssert - (static_assert.h)
- dmSys - (sys.h)
- dmThread - (thread.h)
- dmTime - (time.h)
- dmTransform - (transform.h)
- dmURI - (uri.h)
- dmUtf8 - (utf8.h)
- dmVMath - (vmath.h)
- dmWebServer - (webserver.h)
- editor - (editor.apidoc)
- engine - (engine_doc.h)
- Hashtable - (hashtable.h)
- Log - (log.h)
- ObjectPool - (object_pool.h)
- Overview
- b2d
- b2d.body
- base
- bit
- buffer
- builtins
- camera
- collectionfactory
- collectionproxy
- coroutine
- crash
- debug
- factory
- font
- go
- graphics
- gui
- html5
- http
- image
- io
- json
- label
- liveupdate
- math
- model
- msg
- os
- package
- particlefx
- physics
- profiler
- render
- resource
- socket
- sound
- sprite
- string
- sys
- table
- tilemap
- timer
- types
- vmath
- window
- zlib
- Overview
- adinfo - (extension-adinfo)
- admob - (extension-admob)
- adpf - (extension-adpf)
- camera - (extension-camera)
- crazygames - (extension-crazygames)
- crypt - (extension-crypt)
- facebook - (extension-facebook)
- fmod - (extension-fmod)
- fontgen - (extension-fontgen)
- gpgs - (extension-gpgs)
- gui - (extension-spine)
- iac - (extension-iac)
- iap - (extension-iap)
- instantapp - (extension-googleplayinstant)
- ironsource - (extension-ironsource)
- networkinfo - (extension-network-info)
- odin - (extension-odin)
- pad - (extension-pad)
- permissions - (extension-permissions)
- poki_sdk - (extension-poki-sdk)
- push - (extension-push)
- realtime - (extension-photon-realtime)
- review - (extension-review)
- rive - (extension-rive)
- safearea - (extension-safearea)
- shop - (extension-xsolla)
- siwa - (extension-siwa)
- spine - (extension-spine)
- steam - (extension-steam)
- websocket - (extension-websocket)
- webview - (extension-webview)
- zendesk - (extension-zendesk)
Editor
Editor scripting documentation
| Namespace: | editor |
| Include: | #include <engine/docs/editor.apidoc> |
| FUNCTIONS | |
|---|---|
| void editor.bob (table options, string ...commands) | run bob the builder program |
| void editor.browse (string url) | open a URL in the default browser or a registered application |
| boolean editor.can_add (stringuserdata node, string property) | check if editor.tx.add() (as well as editor.tx.clear() and editor.tx.remove()) transaction with this property won't throw an error |
| boolean editor.can_get (stringuserdata node, string property) | check if you can get this property so editor.get() won't throw an error |
| boolean editor.can_reorder (stringuserdata node, string property) | check if editor.tx.reorder() transaction with this property won't throw an error |
| boolean editor.can_reset (stringuserdata node, string property) | check if editor.tx.reset() transaction with this property won't throw an error |
| boolean editor.can_set (stringuserdata node, string property) | check if editor.tx.set() transaction with this property won't throw an error |
| command editor.command (table opts) | create an editor command |
| void editor.create_directory (string resource_path) | create a directory if it does not exist, and all non-existent parent directories. |
| void editor.create_resources (string[ resources) | create resources (including non-existent parent directories). |
| void editor.delete_directory (string resource_path) | delete a directory if it exists, and all existent child directories and files. |
| string editor.execute (string command, string ..., table options) | execute a shell command. |
| table editor.external_file_attributes (string path) | query information about file system path |
| any editor.get (stringuserdata node, string property) | get a value of a node property inside the editor. |
| void editor.open_external_file (string path) | open a file in a registered application |
| any editor.prefs.get (string key) | get preference value |
| boolean editor.prefs.is_set (string key) | check if preference value is explicitly set |
| schema editor.prefs.schema.array (table opts) | array schema |
| schema editor.prefs.schema.boolean (table opts) | boolean schema |
| schema editor.prefs.schema.enum (table opts) | enum value schema |
| schema editor.prefs.schema.integer (table opts) | integer schema |
| schema editor.prefs.schema.keyword (table opts) | keyword schema |
| schema editor.prefs.schema.number (table opts) | floating-point number schema |
| schema editor.prefs.schema.object (table opts) | heterogeneous object schema |
| schema editor.prefs.schema.object_of (table opts) | homogeneous object schema |
| schema editor.prefs.schema.one_of (table opts) | one of schema |
| schema editor.prefs.schema.password (table opts) | password schema |
| schema editor.prefs.schema.set (table opts) | set schema |
| schema editor.prefs.schema.string (table opts) | string schema |
| schema editor.prefs.schema.tuple (table opts) | tuple schema |
| void editor.prefs.set (string key, any value) | set preference value |
| string[ editor.properties (stringuserdata node) | list property names for a node. |
| table editor.resource_attributes (string resource_path) | query information about a project resource |
| void editor.save () | persist any unsaved changes to disk |
| void editor.transact (transaction_step[ txs) | change the editor state in a single, undoable transaction |
| void editor.tx.add (stringuserdata node, string property, any value) | create a transaction step that will add a child item to a node's list property when transacted with editor.transact(). |
| transaction_step editor.tx.clear (stringuserdata node, string property) | create a transaction step that will remove all items from node's list property when transacted with editor.transact(). |
| transaction_step editor.tx.remove (stringuserdata node, string property, stringuserdata child_node) | create a transaction step that will remove a child node from the node's list property when transacted with editor.transact(). |
| transaction_step editor.tx.reorder (stringuserdata node, string property, table child_nodes) | create a transaction step that reorders child nodes in a node list defined by the property if supported (see editor.can_reorder()) |
| transaction_step editor.tx.reset (stringuserdata node, string property) | create a transaction step that will reset an overridden property to its default value when transacted with editor.transact(). |
| transaction_step editor.tx.set (stringuserdata node, string property, any value) | create transaction step that will set the node's property to a supplied value when transacted with editor.transact(). |
| component editor.ui.button (table props) | button with a label and/or an icon |
| component editor.ui.check_box (table props) | check box with a label |
| function editor.ui.component (function fn) | convert a function to a UI component. |
| component editor.ui.dialog (table props) | dialog component, a top-level window component that can't be used as a child of other components |
| component editor.ui.dialog_button (table props) | dialog button shown in the footer of a dialog |
| component editor.ui.external_file_field (table props) | input component for selecting files from the file system |
| component editor.ui.grid (table props) | layout container that places its children in a 2D grid |
| component editor.ui.heading (table props) | a text heading |
| component editor.ui.horizontal (table props) | layout container that places its children in a horizontal row one after another |
| component editor.ui.icon (table props) | an icon from a predefined set |
| component editor.ui.image (table props) | an image |
| component editor.ui.integer_field (table props) | integer input component based on a text field, reports changes on commit (Enter or focus loss) |
| component editor.ui.label (table props) | label intended for use with input components |
| component editor.ui.number_field (table props) | number input component based on a text field, reports changes on commit (Enter or focus loss) |
| void editor.ui.open_resource (string resource_path) | open a resource, either in the editor or in a third-party app |
| component editor.ui.paragraph (table props) | a paragraph of text |
| component editor.ui.resource_field (table props) | input component for selecting project resources |
| component editor.ui.scroll (table props) | layout container that optionally shows scroll bars if child contents overflow the assigned bounds |
| component editor.ui.select_box (table props) | dropdown select box with an array of options |
| component editor.ui.separator (table props) | thin line for visual content separation, by default horizontal and aligned to center |
| any editor.ui.show_dialog (component dialog) | show a modal dialog and await a result |
| nil editor.ui.show_external_directory_dialog (table opts) | show a modal OS directory selection dialog and await a result |
| nil editor.ui.show_external_file_dialog (table opts) | show a modal OS file selection dialog and await a result |
| string[ editor.ui.show_resource_dialog (table opts) | show a modal resource selection dialog and await a result |
| component editor.ui.string_field (table props) | string input component based on a text field, reports changes on commit (Enter or focus loss) |
| ...any editor.ui.use_memo (function compute, ...any ...) | a hook that caches the result of a computation between re-renders. |
| function editor.ui.use_state (anyfunction init, ...any ...) | a hook that adds local state to the component. |
| component editor.ui.vertical (table props) | layout container that places its children in a vertical column one after another |
| table http.request (string url, table opts) | perform an HTTP request |
| response http.server.external_file_response (string path, integer status, table<string,string> headers) | create HTTP response that will stream the content of a file defined by the path |
| response http.server.json_response (any value, integer status, table<string,string> headers) | create HTTP response with a JSON value |
| response http.server.resource_response (string resource_path, integer status, table<string,string> headers) | create HTTP response that will stream the content of a resource defined by the resource path |
| response http.server.response (integer status, table<string,string> headers, string body) | create HTTP response |
| route http.server.route (string path, string method, string as, table openapi, function handler) | create route definition for the editor's HTTP server |
| void json.decode (string json, table options) | decode JSON string to Lua value |
| void json.encode (any value) | encode Lua value to JSON string |
| message localization.and_list (any[ items) | create a message pattern that renders a list with the "and" conjunction (for example: a, b, and c) once it is stringified |
| message localization.concat (any[ items, nilbooleannumberstringmessage separator) | create a message pattern that concatenates values (similar to table.concat) and performs the actual concatenation when stringified |
| message localization.message (string key, table vars) | create a message pattern for a localization key defined in an .editor_localization file; the actual localization happens when the returned value is stringified |
| message localization.or_list (any[ items) | create a message pattern that renders a list with the "or" conjunction (for example: a, b, or c) once it is stringified |
| void pprint (any value) | pretty-print a Lua value |
| tiles tilemap.tiles.clear (tiles tiles) | remove all tiles |
| table tilemap.tiles.get_info (tiles tiles, integer x, integer y) | get full information from a tile at a particular coordinate |
| integer tilemap.tiles.get_tile (tiles tiles, integer x, integer y) | get a tile index at a particular coordinate |
| function tilemap.tiles.iterator (tiles tiles) | create an iterator over all tiles in a tiles data structure |
| tiles tilemap.tiles.new () | create a new unbounded 2d grid data structure for storing tilemap layer tiles |
| tiles tilemap.tiles.remove (tiles tiles, integer x, integer y) | remove a tile at a particular coordinate |
| tiles tilemap.tiles.set (tiles tiles, integer x, integer y, integertable tile_or_info) | set a tile at a particular coordinate |
| void zip.pack (string output_path, table opts, stringtable entries) | create a ZIP archive |
| void zip.unpack (string archive_path, string target_path, table opts, table paths) | extract a ZIP archive |
| string zlib.deflate (string buf) | deflate (compress) a buffer |
| string zlib.inflate (string buf) | inflate (decompress) a buffer |
Functions
editor.bob
void editor.bob(table options, string ...commands)
Run bob the builder program For the full documentation of the available commands and options, see the bob manual.
PARAMETERS
table |
options |
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. |
string |
...commands |
bob commands, e.g. "resolve" or "build" |
EXAMPLES
Print help in the console:editor.bob({help = true})
local opts = {
archive = true,
platform = editor.platform
}
editor.bob(opts, "distclean", "resolve", "build", "bundle")
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
void editor.browse(string url)
Open a URL in the default browser or a registered application
PARAMETERS
string |
url |
http(s) or file URL |
editor.can_add
boolean editor.can_add(stringuserdata node, string property)
Check if editor.tx.add() (as well as editor.tx.clear() and editor.tx.remove()) transaction with this property won't throw an error
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) |
RETURNS
boolean |
editor.can_get
boolean editor.can_get(stringuserdata node, string property)
Check if you can get this property so editor.get() won't throw an error
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) |
RETURNS
boolean |
editor.can_reorder
boolean editor.can_reorder(stringuserdata node, string property)
Check if editor.tx.reorder() transaction with this property won't throw an error
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) |
RETURNS
boolean |
editor.can_reset
boolean editor.can_reset(stringuserdata node, string property)
Check if editor.tx.reset() transaction with this property won't throw an error
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) |
RETURNS
boolean |
editor.can_set
boolean editor.can_set(stringuserdata node, string property)
Check if editor.tx.set() transaction with this property won't throw an error
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) |
RETURNS
boolean |
editor.command
command editor.command(table opts)
Create an editor command
PARAMETERS
table |
opts |
A table with the following keys:
|
RETURNS
command |
EXAMPLES
Print Git history for a file:editor.command({
label = "Git History",
query = {
selection = {
type = "resource",
cardinality = "one"
}
},
run = function(opts)
editor.execute(
"git",
"log",
"--follow",
"." .. editor.get(opts.selection, "path"),
{reload_resources=false})
end
})
editor.create_directory
void editor.create_directory(string 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
string |
resource_path |
Resource path (starting with /) |
EXAMPLES
editor.create_directory("/assets/gen")
editor.create_resources
void editor.create_resources(string[ resources)
Create resources (including non-existent parent directories). Throws an error if any of the provided resource paths already exist
PARAMETERS
string[ |
resources |
] Array of resource paths (strings starting with /) or resource definitions, lua tables with the following keys:
|
EXAMPLES
Create a single resource from template:editor.create_resources({
"/npc.go"
})
editor.create_resources({
"/npc.go",
"/levels/1.collection",
"/levels/2.collection",
})
editor.create_resources({
{"/npc.script", "go.property('hp', 100)"}
})
editor.delete_directory
void editor.delete_directory(string 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
string |
resource_path |
Resource path (starting with /) |
EXAMPLES
editor.delete_directory("/assets/gen")
editor.execute
string editor.execute(string command, string ..., table 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
string |
command |
Shell command name to execute |
string |
... |
Optional shell command arguments |
table |
options |
Optional options table. Supported entries:
|
RETURNS
nil |
If out option is set to "capture", returns the output as string with trimmed trailing newlines. Otherwise, returns 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")
local status = editor.execute("git", "status", "--porcelain", {
reload_resources = false,
out = "capture"
})
editor.external_file_attributes
table editor.external_file_attributes(string path)
Query information about file system path
PARAMETERS
string |
path |
External file path, resolved against project root if relative |
RETURNS
table |
A table with the following keys:
|
editor.get
any editor.get(stringuserdata node, string 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
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) |
RETURNS
any |
property value |
editor.open_external_file
void editor.open_external_file(string path)
Open a file in a registered application
PARAMETERS
string |
path |
file path |
editor.prefs.get
any editor.prefs.get(string key)
Get preference value The schema for the preference value should be defined beforehand.
PARAMETERS
string |
key |
dot-separated preference key path |
RETURNS
any |
current pref value or default if a schema for the key path exists, nil otherwise |
editor.prefs.is_set
boolean editor.prefs.is_set(string key)
Check if preference value is explicitly set The schema for the preference value should be defined beforehand.
PARAMETERS
string |
key |
dot-separated preference key path |
RETURNS
boolean |
flag indicating if the value is explicitly set |
editor.prefs.schema.array
schema editor.prefs.schema.array(table opts)
array schema
PARAMETERS
table |
opts |
Required opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.boolean
schema editor.prefs.schema.boolean(table opts)
boolean schema
PARAMETERS
table |
opts |
Optional opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.enum
schema editor.prefs.schema.enum(table opts)
enum value schema
PARAMETERS
table |
opts |
Required opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.integer
schema editor.prefs.schema.integer(table opts)
integer schema
PARAMETERS
table |
opts |
Optional opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.keyword
schema editor.prefs.schema.keyword(table opts)
keyword schema A keyword is a short string that is interned within the editor runtime, useful e.g. for identifiers
PARAMETERS
table |
opts |
Optional opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.number
schema editor.prefs.schema.number(table opts)
floating-point number schema
PARAMETERS
table |
opts |
Optional opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.object
schema editor.prefs.schema.object(table opts)
heterogeneous object schema
PARAMETERS
table |
opts |
Required opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.object_of
schema editor.prefs.schema.object_of(table opts)
homogeneous object schema
PARAMETERS
table |
opts |
Required opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.one_of
schema editor.prefs.schema.one_of(table opts)
one of schema
PARAMETERS
table |
opts |
Required opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.password
schema editor.prefs.schema.password(table opts)
password schema A password is a string that is encrypted when stored in a preference file
PARAMETERS
table |
opts |
Optional opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.set
schema editor.prefs.schema.set(table opts)
set schema
Set is represented as a lua table with true values
PARAMETERS
table |
opts |
Required opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.string
schema editor.prefs.schema.string(table opts)
string schema
PARAMETERS
table |
opts |
Optional opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.schema.tuple
schema editor.prefs.schema.tuple(table opts)
tuple schema A tuple is a fixed-length array where each item has its own defined type
PARAMETERS
table |
opts |
Required opts:
|
RETURNS
schema |
Prefs schema |
editor.prefs.set
void editor.prefs.set(string key, any value)
Set preference value The schema for the preference value should be defined beforehand.
PARAMETERS
string |
key |
dot-separated preference key path |
any |
value |
new pref value to set |
editor.properties
string[ editor.properties(stringuserdata node)
List property names for a node.
The result is context-sensitive and can vary by node/resource type and editor state. Returned names are readable with editor.get(node, property). Mutating capabilities are per-property; use editor.can_set(), editor.can_reset(), editor.can_add(), and editor.can_reorder() to check which operations are supported.
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
RETURNS
string[ |
] sorted unique editor property names available in the current context |
editor.resource_attributes
table editor.resource_attributes(string resource_path)
Query information about a project resource
PARAMETERS
string |
resource_path |
Resource path (starting with /) |
RETURNS
table |
A table with the following keys:
|
editor.transact
void editor.transact(transaction_step[ txs)
Change the editor state in a single, undoable transaction
PARAMETERS
transaction_step[ |
txs |
] An array of transaction steps created using editor.tx.* functions |
editor.tx.add
void editor.tx.add(stringuserdata node, string property, any value)
Create a transaction step that will add a child item to a node's list property when transacted with editor.transact().
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) | |||
any |
value |
Added item for the property, a table from property key to either a valid editor.tx.set()-able value, or an array of valid editor.tx.add()-able values |
editor.tx.clear
transaction_step editor.tx.clear(stringuserdata node, string property)
Create a transaction step that will remove all items from node's list property when transacted with editor.transact().
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) |
RETURNS
transaction_step |
A transaction step |
editor.tx.remove
transaction_step editor.tx.remove(stringuserdata node, string property, stringuserdata child_node)
Create a transaction step that will remove a child node from the node's list property when transacted with editor.transact().
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) | |||
string |
child_node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
child_node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
RETURNS
transaction_step |
A transaction step |
editor.tx.reorder
transaction_step editor.tx.reorder(stringuserdata node, string property, table child_nodes)
Create a transaction step that reorders child nodes in a node list defined by the property if supported (see editor.can_reorder())
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) | |||
table |
child_nodes |
array of child nodes (the same as returned by editor.get(node, property)) in new order |
RETURNS
transaction_step |
A transaction step |
editor.tx.reset
transaction_step editor.tx.reset(stringuserdata node, string property)
Create a transaction step that will reset an overridden property to its default value when transacted with editor.transact().
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) |
RETURNS
transaction_step |
A transaction step |
editor.tx.set
transaction_step editor.tx.set(stringuserdata node, string property, any value)
Create transaction step that will set the node's property to a supplied value when transacted with editor.transact().
PARAMETERS
string |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor | userdata |
node |
Either resource path (e.g. "/main/game.script"), or internal node id passed to the script by the editor |
string |
property |
Either "path", "text", or a property from the Outline view (hover the label to see its editor script name) | |||
any |
value |
A new value for the property |
RETURNS
transaction_step |
A transaction step |
editor.ui.button
component editor.ui.button(table props)
Button with a label and/or an icon
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.check_box
component editor.ui.check_box(table props)
Check box with a label
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.component
function editor.ui.component(function 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
horizontalorverticallayout 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
gridcontainer. 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
gridcontainer.
PARAMETERS
function |
fn |
function, will receive a single table of props when called |
RETURNS
function |
decorated component function that may be invoked with a props table create component |
editor.ui.dialog
component editor.ui.dialog(table props)
Dialog component, a top-level window component that can't be used as a child of other components
PARAMETERS
table |
props |
Required props:
|
RETURNS
component |
UI component |
editor.ui.dialog_button
component editor.ui.dialog_button(table props)
Dialog button shown in the footer of a dialog
PARAMETERS
table |
props |
Required props:
|
RETURNS
component |
UI component |
editor.ui.external_file_field
component editor.ui.external_file_field(table props)
Input component for selecting files from the file system
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.grid
component editor.ui.grid(table props)
Layout container that places its children in a 2D grid
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.heading
component editor.ui.heading(table props)
A text heading
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.horizontal
component editor.ui.horizontal(table props)
Layout container that places its children in a horizontal row one after another
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.icon
component editor.ui.icon(table props)
An icon from a predefined set
PARAMETERS
table |
props |
Required props:
|
RETURNS
component |
UI component |
editor.ui.image
component editor.ui.image(table props)
An image
PARAMETERS
table |
props |
Required props:
|
RETURNS
component |
UI component |
editor.ui.integer_field
component editor.ui.integer_field(table props)
Integer input component based on a text field, reports changes on commit (Enter or focus loss)
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.label
component editor.ui.label(table props)
Label intended for use with input components
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.number_field
component editor.ui.number_field(table props)
Number input component based on a text field, reports changes on commit (Enter or focus loss)
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.open_resource
void editor.ui.open_resource(string resource_path)
Open a resource, either in the editor or in a third-party app
PARAMETERS
string |
resource_path |
Resource path (starting with /) |
editor.ui.paragraph
component editor.ui.paragraph(table props)
A paragraph of text
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.resource_field
component editor.ui.resource_field(table props)
Input component for selecting project resources
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.scroll
component editor.ui.scroll(table props)
Layout container that optionally shows scroll bars if child contents overflow the assigned bounds
PARAMETERS
table |
props |
Required props:
|
RETURNS
component |
UI component |
editor.ui.select_box
component editor.ui.select_box(table props)
Dropdown select box with an array of options
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.separator
component editor.ui.separator(table props)
Thin line for visual content separation, by default horizontal and aligned to center
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.show_dialog
any editor.ui.show_dialog(component dialog)
Show a modal dialog and await a result
PARAMETERS
component |
dialog |
a component that resolves to editor.ui.dialog(...) |
RETURNS
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
nil editor.ui.show_external_directory_dialog(table opts)
Show a modal OS directory selection dialog and await a result
PARAMETERS
table |
opts |
|
RETURNS
string |
either absolute directory path or nil if user canceled directory selection |
nil |
either absolute directory path or nil if user canceled directory selection |
editor.ui.show_external_file_dialog
nil editor.ui.show_external_file_dialog(table opts)
Show a modal OS file selection dialog and await a result
PARAMETERS
table |
opts |
|
RETURNS
string |
either absolute file path or nil if user canceled file selection |
nil |
either absolute file path or nil if user canceled file selection |
editor.ui.show_resource_dialog
string[ editor.ui.show_resource_dialog(table opts)
Show a modal resource selection dialog and await a result
PARAMETERS
table |
opts |
|
RETURNS
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. |
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
component editor.ui.string_field(table props)
String input component based on a text field, reports changes on commit (Enter or focus loss)
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
editor.ui.use_memo
...any editor.ui.use_memo(function compute, ...any ...)
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
function |
compute |
function that will be used to compute the cached value |
...any |
... |
args to the computation function |
RETURNS
...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
function editor.ui.use_state(anyfunction init, ...any ...)
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
any |
init |
local state initializer, either initial data structure or function that produces the data structure | function |
init |
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
any |
current local state, starts with initial state, then may be changed using the returned set_state function |
function |
function that changes the local state and causes the component to refresh. The function may be used in 2 ways:
|
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
component editor.ui.vertical(table props)
Layout container that places its children in a vertical column one after another
PARAMETERS
table |
props |
Optional props:
|
RETURNS
component |
UI component |
http.request
table http.request(string url, table opts)
Perform an HTTP request
PARAMETERS
string |
url |
request URL |
table |
opts |
Additional request options, a table with the following keys:
|
RETURNS
table |
HTTP response, a table with the following keys:
|
http.server.external_file_response
response http.server.external_file_response(string path, integer status, table<string,string> headers)
Create HTTP response that will stream the content of a file defined by the path
PARAMETERS
string |
path |
External file path, resolved against project root if relative |
integer |
status |
HTTP status code, an integer, default 200 |
table<string,string> |
headers |
HTTP response headers, a table from lower-case header names to header values |
RETURNS
response |
HTTP response value, userdata |
http.server.json_response
response http.server.json_response(any value, integer status, table<string,string> headers)
Create HTTP response with a JSON value
PARAMETERS
any |
value |
Any Lua value that may be represented as JSON |
integer |
status |
HTTP status code, an integer, default 200 |
table<string,string> |
headers |
HTTP response headers, a table from lower-case header names to header values |
RETURNS
response |
HTTP response value, userdata |
http.server.resource_response
response http.server.resource_response(string resource_path, integer status, table<string,string> headers)
Create HTTP response that will stream the content of a resource defined by the resource path
PARAMETERS
string |
resource_path |
Resource path (starting with /) |
integer |
status |
HTTP status code, an integer, default 200 |
table<string,string> |
headers |
HTTP response headers, a table from lower-case header names to header values |
RETURNS
response |
HTTP response value, userdata |
http.server.response
response http.server.response(integer status, table<string,string> headers, string body)
Create HTTP response
PARAMETERS
integer |
status |
HTTP status code, an integer, default 200 |
table<string,string> |
headers |
HTTP response headers, a table from lower-case header names to header values |
string |
body |
HTTP response body |
RETURNS
response |
HTTP response value, userdata |
http.server.route
route http.server.route(string path, string method, string as, table openapi, function handler)
Create route definition for the editor's HTTP server
PARAMETERS
string |
path |
HTTP URI path, starts with /; may include path patterns ({name} for a single segment and {*name} for the rest of the request path) that will be extracted from the path and provided to the handler as a part of the request |
string |
method |
HTTP request method, default "GET" |
string |
as |
Request body converter, either "string" or "json"; the body will be discarded if not specified |
table |
openapi |
Optional OpenAPI Operation Object for this route method, exposed from /openapi.json. Must follow https://spec.openapis.org/oas/v3.0.3.html#operation-object. |
function |
handler |
Request handler function, will receive request argument, a table with the following keys:
http.server.response() function |
RETURNS
route |
HTTP server route |
EXAMPLES
Receive JSON and respond with JSON:http.server.route(
"/json", "POST", "json",
function(request)
pprint(request.body)
return 200
end
)
http.server.route(
"/users/{user}/orders",
function(request)
print(request.user)
end
)
http.server.route(
"/files/{*file}",
function(request)
local attrs = editor.external_file_attributes(request.file)
if attrs.is_file then
return http.server.external_file_response(request.file)
elseif attrs.is_directory then
return 400
else
return 404
end
end
)
json.decode
void json.decode(string json, table options)
Decode JSON string to Lua value
PARAMETERS
string |
json |
json data |
table |
options |
A table with the following keys:
|
json.encode
void json.encode(any value)
Encode Lua value to JSON string
PARAMETERS
any |
value |
any Lua value that may be represented as JSON |
localization.and_list
message localization.and_list(any[ items)
Create a message pattern that renders a list with the "and" conjunction (for example: a, b, and c) once it is stringified
PARAMETERS
any[ |
items |
] array of values; each value may be nil, boolean, number, string, or another message instance |
RETURNS
message |
a userdata value that, when stringified with tostring(), will produce a localized text according to the currently selected language in the editor |
localization.concat
message localization.concat(any[ items, nilbooleannumberstringmessage separator)
Create a message pattern that concatenates values (similar to table.concat) and performs the actual concatenation when stringified
PARAMETERS
any[ |
items |
] array of values; each value may be nil, boolean, number, string, or another message instance | ||||||||||||
nil |
separator |
optional separator inserted between values; defaults to an empty string | boolean |
separator |
optional separator inserted between values; defaults to an empty string | number |
separator |
optional separator inserted between values; defaults to an empty string | string |
separator |
optional separator inserted between values; defaults to an empty string | message |
separator |
optional separator inserted between values; defaults to an empty string |
RETURNS
message |
a userdata value that, when stringified with tostring(), will produce a localized text according to the currently selected language in the editor |
localization.message
message localization.message(string key, table vars)
Create a message pattern for a localization key defined in an .editor_localization file; the actual localization happens when the returned value is stringified
PARAMETERS
string |
key |
localization key defined in an .editor_localization file |
table |
vars |
optional table with variables to be substituted in the localized string that uses ICU Message Format syntax; keys must be strings; values must be either nil, boolean, number, string, or another message instance |
RETURNS
message |
a userdata value that, when stringified with tostring(), will produce a localized text according to the currently selected language in the editor |
localization.or_list
message localization.or_list(any[ items)
Create a message pattern that renders a list with the "or" conjunction (for example: a, b, or c) once it is stringified
PARAMETERS
any[ |
items |
] array of values; each value may be nil, boolean, number, string, or another message instance |
RETURNS
message |
a userdata value that, when stringified with tostring(), will produce a localized text according to the currently selected language in the editor |
pprint
void pprint(any value)
Pretty-print a Lua value
PARAMETERS
any |
value |
any Lua value to pretty-print |
tilemap.tiles.clear
tiles tilemap.tiles.clear(tiles tiles)
Remove all tiles
PARAMETERS
tiles |
tiles |
unbounded 2d grid of tiles |
RETURNS
tiles |
unbounded 2d grid of tiles |
tilemap.tiles.get_info
table tilemap.tiles.get_info(tiles tiles, integer x, integer y)
Get full information from a tile at a particular coordinate
PARAMETERS
tiles |
tiles |
unbounded 2d grid of tiles |
integer |
x |
x coordinate of a tile |
integer |
y |
y coordinate of a tile |
RETURNS
table |
full tile information table with the following keys:
|
tilemap.tiles.get_tile
integer tilemap.tiles.get_tile(tiles tiles, integer x, integer y)
Get a tile index at a particular coordinate
PARAMETERS
tiles |
tiles |
unbounded 2d grid of tiles |
integer |
x |
x coordinate of a tile |
integer |
y |
y coordinate of a tile |
RETURNS
integer |
1-indexed tile index of a tilemap's tilesource |
tilemap.tiles.iterator
function tilemap.tiles.iterator(tiles tiles)
Create an iterator over all tiles in a tiles data structure When iterating using for loop, each iteration returns x, y and tile index of a tile in a tile map
PARAMETERS
tiles |
tiles |
unbounded 2d grid of tiles |
RETURNS
function |
iterator |
EXAMPLES
Iterate over all tiles in a tile map:local layers = editor.get("/level.tilemap", "layers")
for i = 1, #layers do
local tiles = editor.get(layers[i], "tiles")
for x, y, i in tilemap.tiles.iterator(tiles) do
print(x, y, i)
end
end
tilemap.tiles.new
tiles tilemap.tiles.new()
Create a new unbounded 2d grid data structure for storing tilemap layer tiles
PARAMETERS
RETURNS
tiles |
unbounded 2d grid of tiles |
tilemap.tiles.remove
tiles tilemap.tiles.remove(tiles tiles, integer x, integer y)
Remove a tile at a particular coordinate
PARAMETERS
tiles |
tiles |
unbounded 2d grid of tiles |
integer |
x |
x coordinate of a tile |
integer |
y |
y coordinate of a tile |
RETURNS
tiles |
unbounded 2d grid of tiles |
tilemap.tiles.set
tiles tilemap.tiles.set(tiles tiles, integer x, integer y, integertable tile_or_info)
Set a tile at a particular coordinate
PARAMETERS
tiles |
tiles |
unbounded 2d grid of tiles | |||
integer |
x |
x coordinate of a tile | |||
integer |
y |
y coordinate of a tile | |||
integer |
tile_or_info |
Either 1-indexed tile index of a tilemap's tilesource or full tile information table with the following keys:
| table |
tile_or_info |
Either 1-indexed tile index of a tilemap's tilesource or full tile information table with the following keys:
|
RETURNS
tiles |
unbounded 2d grid of tiles |
zip.pack
void zip.pack(string output_path, table opts, stringtable entries)
Create a ZIP archive
PARAMETERS
string |
output_path |
output zip file path, resolved against project root if relative | |||
table |
opts |
compression options, a table with the following keys:
| |||
string |
entries |
entries to compress, either a string (relative path to file or folder to include) or a table with the following keys:
| table |
entries |
entries to compress, either a string (relative path to file or folder to include) or a table with the following keys:
|
EXAMPLES
Archive a file and a folder:zip.pack("build.zip", {"build", "game.project"})
zip.pack("build.zip", {
{"build/wasm-web", "."},
{"configs/prod.json", "config.json"}
})
zip.pack("build.zip", {method = zip.METHOD.STORED}, {
"build",
"resources"
})
zip.pack("build.zip", {
{"assets", method = zip.METHOD.STORED},
"build/wasm-web"
})
zip.pack("build.zip", {
"build",
{"../secrets/auth-key.txt", "auth-key.txt"}
})
zip.unpack
void zip.unpack(string archive_path, string target_path, table opts, table paths)
Extract a ZIP archive
PARAMETERS
string |
archive_path |
zip file path, resolved against project root if relative |
string |
target_path |
target path for extraction, defaults to parent of archive_path if omitted |
table |
opts |
extraction options, a table with the following keys:
|
table |
paths |
entries to extract, relative string paths |
EXAMPLES
Extract everything to a build dir:zip.unpack("build/dev/resources.zip")
zip.unpack(
"build/dev/resources.zip",
"build/dev/tmp",
)
zip.unpack(
"build/dev/resources.zip",
{on_conflict = zip.ON_CONFLICT.OVERWRITE}
)
zip.unpack(
"build/dev/resources.zip",
{"config.json"}
)
zlib.deflate
string zlib.deflate(string buf)
Deflate (compress) a buffer
PARAMETERS
string |
buf |
buffer to deflate |
RETURNS
string |
deflated buffer |
zlib.inflate
string zlib.inflate(string buf)
Inflate (decompress) a buffer
PARAMETERS
string |
buf |
buffer to inflate |
RETURNS
string |
inflated buffer |
Constants
editor.platform
Editor platform id.
A string, either:
- "x86_64-win32"
- "x86_64-macos"
- "arm64-macos"
- "x86_64-linux"