Since Tiled 1.3

Scripting

Introduction

Tiled can be extended with the use of JavaScript. See the Tiled Scripting API for a reference of all available functionality.

TypeScript definitions of the API are available as the @mapeditor/tiled-api NPM package, which can provide auto-completion in your editor. The API reference is generated based on these definitions.

On startup, Tiled will execute any script files present in extension folders. In addition it is possible to run scripts directly from the console, as well as to evaluate a script file from the command-line. All scripts share a single JavaScript context.

Note

A few example scripts and links to existing Tiled extensions are provided at the Tiled Extensions repository: https://github.com/mapeditor/tiled-extensions

JavaScript Host Environment

Tiled uses the JavaScript engine shipping with Qt’s QML module. The QML runtime generally implements the 7th edition of the standard, with some additions. See the JavaScript Host Environment documentation for details.

It may also be helpful to check out the List of JavaScript Objects and Functions that are available.

Note

The full scripting API and support for ECMAScript 7 features are only available for Tiled builds based on Qt 5.12 or later. This currently excludes the Windows XP and snap releases before Tiled 1.8.1.

Scripted Extensions

Extensions can be placed in a system-specific or project-specific location.

The system-specific folder can be opened from the Plugins tab in the Preferences dialog. The usual location on each supported platform is as follows:

Windows

C:/Users/<USER>/AppData/Local/Tiled/extensions/

macOS

~/Library/Preferences/Tiled/extensions/

Linux

~/.config/tiled/extensions/

The project-specific folder defaults to “extensions”, relative to the directory of the .tiled-project file, but this can be changed in the Project Properties.

Warning

Since Tiled 1.7, project-specific extensions are only enabled by default for projects you created. When opening any other project, a popup will notify you when the project has a scripted extensions directory, allowing you to enable extensions for that project.

Always be careful when enabling extensions on projects you haven’t created, since extensions have access to your files and can execute processes.

An extension can be placed either directly in an extensions directory, or in a sub-directory. All scripts files found in these directories are executed on startup.

Since Tiled 1.8

When using the .mjs extension, script files are loaded as JavaScript modules. They will then be able to use the import and export statements to split up their functionality over multiple JavaScript files. Such extensions also don’t pollute the global scope, avoiding potential name collisions between different extensions.

When any loaded script is changed or when any files are added/removed from the extensions directory, the script engine is automatically reinstantiated and the scripts are reloaded. This way there is no need to restart Tiled when installing extensions. It also makes it quick to iterate on a script until it works as intended.

Apart from scripts, extensions can include images that can be used as the icon for scripted actions or tools.

Console View

In the Console view (View > Views and Toolbars > Console) you will find a text entry where you can write or paste scripts to evaluate them.

You can use the Up/Down keys to navigate through previously entered script expressions.

Since Tiled 1.9

Command Line

To execute a script (.js) or to load a module (.mjs) from the command-line, you can pass the --evaluate option (or -e), followed by the file name. Tiled will quit after executing the script.

The UI will not be instantiated while evaluating scripts on the command-line. This means functions that rely on the UI being present will do nothing and some properties will be null. However, scripts are able to load and save maps and tilesets through the available formats (see tiled.mapFormats and tiled.tilesetFormats), as well as to make any modifications to these assets.

Any additional non-option arguments passed after the script file name are available to the script as tiled.scriptArguments.

If you want to evaluate several scripts, use --evaluate for each file. Note that evaluating the same JavaScript module (.mjs) does not work, since modules are loaded only once.

API Reference

See the Tiled Scripting API.

The following global variable is currently not documented in the generated documentation, since it conflicts with nodejs types:

__filename

The file path of the current file being evaluated. Only available during initial evaluation of the file and not when later functions in that file get called. If you need it there, copy the value to local scope.