Scripting

Introduction

Initial scripting capabilities have been added to Tiled. The API is still incomplete, but many actions can be automated either by interacting with any open assets or by triggering UI actions. Scripts can be run from the Console view and there is a script loaded on startup.

Startup Script

If present, a startup.js script is evaluated on startup. This script could define functions that can be called from the Console or can connect to signals to add functionality.

The location of the startup script depends on the platform. The file startup.js is searched for in the following locations:

Windows
C:/Users/<USER>/AppData/Local/Tiled/startup.js
C:/ProgramData/Tiled/startup.js
macOS
~/Library/Preferences/Tiled/startup.js
Linux
~/.config/tiled/startup.js
/etc/xdg/tiled/startup.js

Any file that exists will be evaluated. Changes made to startup scripts only take effect when restarting Tiled.

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.

Connecting to Signals

The script API provides signals to which functions can be connected. Currently, the tiled module has the most useful set of signals.

Properties usually will have related signals which can be used to detect changes to that property, but most of those are currently not implemented.

To connect to a signal, call its connect function and pass in a function object. In the following example, newly created maps automatically get their first tile layer removed:

tiled.assetCreated.connect(function(asset) {
    if (asset.layerCount > 0) {
        asset.removeLayerAt(0)
        tiled.log("assetCreated: Removed automatically added tile layer.")
    }
})

In some cases it will be necessary to later disconnect the function from the signal again. This can be done by defining the function separately and passing it into the disconnect function:

function onAssetCreated(asset) {
    // Do something...
}

tiled.assetCreated.connect(onAssetCreated)
// ...
tiled.assetCreated.disconnect(onAssetCreated)

API Reference

tiled module

The tiled module is the main entry point and provides properties, functions and signals which are documented below.

Properties

version : string [read-only] Currently used version of Tiled.
platform : string [read-only] Operating system. One of windows, macos, linux or unix (for any other UNIX-like system).
arch : string [read-only] Processor architecture. One of x64, x86 or unknown.
activeAsset : Asset Currently selected asset, or null if no file is open. Can be assigned any open asset in order to change the active asset.
openAssets : array [read-only] List of currently opened assets.

Functions

tiled.trigger(action : string) : void

This function can be used to trigger any registered action. This includes most actions you would normally trigger through the menu or by using their shortcut.

The following actions are currently available:

Action
About
AddExternalTileset
AutoMap
AutoMapWhileDrawing
BecomePatron
ClearRecentFiles
ClearView
Close
CloseAll
Copy
Cut
Delete
Documentation
EditCommands
Export
ExportAs
ExportAsImage
FullScreen
HighlightCurrentLayer
HighlightHoveredObject
LabelForHoveredObject
LabelsForAllObjects
LabelsForSelectedObjects
LoadWorld
MapProperties
NewMap
NewTileset
NoLabels
OffsetMap
Open
Paste
PasteInPlace
Preferences
Quit
Reload
ResizeMap
Save
SaveAll
SaveAs
ShowGrid
ShowTileAnimations
ShowTileObjectOutlines
SnapNothing
SnapToFineGrid
SnapToGrid
SnapToPixels
TilesetProperties
ZoomIn
ZoomNormal
ZoomOut
SelectAll
SelectInverse
SelectNone
CropToSelection
Autocrop
AddTileLayer
AddObjectLayer
AddImageLayer
AddGroupLayer
LayerViaCopy
LayerViaCut
GroupLayers
UngroupLayers
DuplicateLayers
MergeLayersDown
SelectPreviousLayer
SelectNextLayer
RemoveLayers
MoveLayersUp
MoveLayersDown
ToggleOtherLayers
ToggleLockOtherLayers
LayerProperties
DuplicateObjects
RemoveObjects

Actions that are checkable will toggle when triggered.

tiled.alert(text : string [, title : string]) : void
Shows a modal warning dialog to the user with the given text and optional title.
tiled.confirm(text : string [, title : string]) : bool
Shows a yes/no dialog to the user with the given text and optional title. Returns true or false.
tiled.prompt(label : string [, text : string [, title : string]]) : string
Shows a dialog that asks the user to enter some text, along with the given label and optional title. The optional text parameter provides the initial value of the text. Returns the entered text.
tiled.log(text : string) : void
Outputs the given text in the Console window as regular text.
tiled.error(text : string) : void
Outputs the given text in the Console window as error message (automatically gets “Error: ” prepended).
tiled.registerMapFormat(shortName : string, mapFormat : object) : void

Registers a new map format that can then be used to export maps to.

If a map format is already registered with the same shortName, the existing format is replaced. The short name can also be used to specify the format when using --export-map on the command-line, in case the file extension is ambiguous or a different one should be used.

The mapFormat object is expected to have the following members:

name : string Name of format as shown in the file dialog.
extension : string The file extension used by the format.
toString : function(map : Map, fileName : string) : string A function that returns the string representation of the given map, when saved to the given file name (useful for relative references).

Example that produces a simple JSON representation of a map:

var customMapFormat = {
    name: "Custom map format",
    extension: "custom",

    toString: function(map, fileName) {
        var m = {
            width: map.width,
            height: map.height,
            layers: []
        };

        for (var i = 0; i < map.layerCount; ++i) {
            var layer = map.layerAt(i);
            if (layer.isTileLayer) {
                var rows = [];
                for (y = 0; y < layer.height; ++y) {
                    var row = [];
                    for (x = 0; x < layer.width; ++x)
                        row.push(layer.cellAt(x, y).tileId);
                    rows.push(row);
                }
                m.layers.push(rows);
            }
        }

        return JSON.stringify(m);
    },
}

tiled.registerMapFormat("custom", customMapFormat)

Signals

tiled.assetCreated(asset : Asset)
A new asset has been created.
tiled.assetOpened(asset : Asset)
An asset has been opened.
tiled.assetAboutToBeSaved(asset : Asset)
An asset is about to be saved. Can be used to make last-minute changes.
tiled.assetSaved(asset : Asset)
An asset has been saved.
tiled.assetAboutToBeClosed(asset : Asset)
An asset is about to be closed.
tiled.activeAssetChanged(asset : Asset)
The currently active asset has changed.

Object

The base of most data types in Tiled. Provides the ability to associate custom properties with the data.

Properties

asset : Asset [read-only] The asset this object is part of, or null.
readOnly : bool [read-only] Whether the object is read-only.

Functions

Object.property(name : string) : variant

Returns the value of the custom property with the given name, or undefined if no such property is set on the object.

Note: Currently it is not possible to inspect the value of file properties.

Object.setProperty(name : string, value : variant) : void

Sets the value of the custom property with the given name. Supported types are bool, number and string. When setting a number, the property type will be set to either int or float, depending on whether it is a whole number.

Note: Support for color and file properties is currently missing.

Object.properties() : object
Returns all custom properties set on this object. Modifications to the properties will not affect the original object.
Object.setProperties(properties : object) : void
Replaces all currently set custom properties with a new set of properties.
Object.removeProperty(name : string) : void
Removes the custom property with the given name.

Asset

Inherits Object.

Represents any top-level data type that can be saved to a file. Currently either a Map or a Tileset.

All modifications made to assets and their contained parts create undo commands. This includes both modifying functions that are called as well as simply assigning to a writable property.

Properties

fileName : string [read-only] File name of the asset.
modified : bool [read-only] Whether the asset was modified after it was saved or loaded.

Map

Inherits Asset.

Properties

width : int [read-only] Width of the map in tiles (only relevant for non-infinite maps). Use resize to change it.
height : int [read-only] Height of the map in tiles (only relevant for non-infinite maps). Use resize to change it.
size : size [read-only] Size of the map in tiles (only relevant for non-infinite maps). Use resize to change it.
tileWidth : int Tile width (used by tile layers).
tileHeight: int Tile height (used by tile layers).
infinite : bool Whether this map is infinite.
hexSideLength : int Length of the side of a hexagonal tile (used by tile layers on hexagonal maps).
staggerAxis : int For staggered and hexagonal maps, determines which axis (X or Y) is staggered: 0 (X), 1 (Y).
orientation : int General map orientation: 0 (Unknown), 1 (Orthogonal), 2 (Isometric), 3 (Staggered), 4 (Hexagonal)
renderOrder : int Tile rendering order (only implemented for orthogonal maps): 0 (RightDown), 1 (RightUp), 2 (LeftDown), 3 (LeftUp)
staggerIndex : int For staggered and hexagonal maps, determines whether the even or odd indexes along the staggered axis are shifted. 0 (Odd), 1 (Even).
backgroundColor : color Background color of the map.
layerDataFormat : int The format in which the layer data is stored, taken into account by TMX, JSON and Lua map formats: 0 (XML), 1 (Base64), 2 (Base64Gzip), 3 (Base64Zlib), 4 (CSV)
selectedArea : SelectionArea The selected area of tiles.
layerCount : int [read-only] Number of top-level layers the map has.

Functions

Map.layerAt(index : int) : Layer
Returns a reference to the top-level layer at the given index. When the layer gets removed from the map, the reference changes to a standalone copy of the layer.
Map.removeLayerAt(index : int) : void
Removes the top-level layer at the given index. When a reference to the layer still exists, that reference becomes a standalone copy of the layer.
Map.removeLayer(layer : Layer) : void
Removes the given layer from the map. The reference to the layer becomes a standalone copy.
Map.insertLayerAt(index : int, layer : Layer) : void
Inserts the layer at the given index. The layer can’t already be part of a map.
Map.addLayer(layer : Layer) : void
Adds the layer to the map, above all existing layers. The layer can’t already be part of a map.
Map.resize(size : size [, offset : point [, removeObjects : bool = false]]) : void
Resizes the map to the given size, optionally applying an offset (in tiles)

Layer

Inherits Object.

Properties

name : string Name of the layer.
opacity : number Opacity of the layer, from 0 (fully transparent) to 1 (fully opaque).
visible : bool Whether the layer is visible (affects child layer visibility for group layers).
locked : bool Whether the layer is locked (affects whether child layers are locked for group layers).
offset : point Offset in pixels that is applied when this layer is rendered.
map : Map Map that this layer is part of (or null in case of a standalone layer).
isTileLayer : bool [read-only] Whether this layer is a TileLayer.
isObjectGroup : bool [read-only] Whether this layer is an ObjectGroup.
isGroupLayer : bool [read-only] Whether this layer is a group layer.
isImageLayer : bool [read-only] Whether this layer is an image layer.

TileLayer

Inherits Layer.

Properties

width : int [read-only] Width of the layer in tiles (only relevant for non-infinite maps).
height : int [read-only] Height of the layer in tiles (only relevant for non-infinite maps).
size : size [read-only] Size of the layer in tiles (has width and height members) (only relevant for non-infinite maps).

Functions

TileLayer.region() : region
Returns the region of the layer that is covered with tiles.
TileLayer.cellAt(x : int, y : int) : cell
Returns the value of the cell at the given position.

ObjectGroup

Inherits Layer.

The “ObjectGroup” is a type of layer that can contain objects. It will henceforth be referred to as a layer.

Properties

objectCount : int [read-only] Number of objects on this layer.
color : color Color of shape and point objects on this layer (when not set by object type).

Functions

ObjectGroup.objectAt(index : int) : MapObject
Returns a reference to the object at the given index. When the object is removed, the reference turns into a standalone copy of the object.
ObjectGroup.removeObjectAt(index : int) : void
Removes the object at the given index.
ObjectGroup.removeObject(object : MapObject) : void
Removes the given object from this layer. The object reference turns into a standalone copy of the object.
ObjectGroup.insertObjectAt(index : int, object : MapObject) : void
Inserts the object at the given index. The object can’t already be part of a layer.
ObjectGroup.addObject(object : MapObject) : void
Adds the given object to the layer. The object can’t already be part of a layer.

MapObject

Inherits Object.

Properties

id : int [read-only] Unique (map-wide) ID of the object.
name : string Name of the object.
type : string Type of the object.
x : number X coordinate of the object in pixels.
y : number Y coordinate of the object in pixels.
pos : point Position of the object in pixels (has x and y members).
width : number Width of the object in pixels.
height : number Height of the object in pixels.
size : size Size of the object in pixels (has width and height members).
rotation : number Rotation of the object in degrees clockwise.
visible : bool Whether the object is visible.
layer : ObjectGroup [read-only] Layer this object is part of (or null in case of a standalone object).
map : Map [read-only] Map this object is part of (or null in case of a standalone object).

Tileset

Inherits Asset.

Properties

name : string Name of the tileset.
tileWidth : int [read-only] Tile width for tiles in this tileset in pixels.
tileHeight : int [read-only] Tile Height for tiles in this tileset in pixels.
tileSize : size [read-only] Tile size for tiles in this tileset in pixels (has width and height members).
tileSpacing : int [read-only] Spacing between tiles in this tileset in pixels.
margin : int [read-only] Margin around the tileset in pixels (only used at the top and left sides of the tileset image).
tileOffset : point Offset in pixels that is applied when tiles from this tileset are rendered.
backgroundColor : color Background color for this tileset in the Tilesets view.

SelectedArea

Functions

SelectedArea.set(rect : rect) : void
Sets the selected area to the given rectangle.
SelectedArea.set(region : region) : void
Sets the selected area to the given region.
SelectedArea.add(rect : rect) : void
Adds the given rectangle to the selected area.
SelectedArea.add(region : region) : void
Adds the given region to the selected area.
SelectedArea.subtract(rect : rect) : void
Subtracts the given rectangle from the selected area.
SelectedArea.subtract(region : region) : void
Subtracts the given region from the selected area.
SelectedArea.intersect(rect : rect) : void
Sets the selected area to the intersection of the current selected area and the given rectangle.
SelectedArea.intersect(region : region) : void
Sets the selected area to the intersection of the current selected area and the given region.