New in Tiled 1.3

Scripting¶

Introduction¶

Tiled can be extended with the use of JavaScript. Scripts can be used to implement custom map formats, custom actions and new tools. Scripts can also automate actions based on signals.

On startup, Tiled will execute any script files present in extensions. In addition it is possible to run scripts directly from the console. All scripts share a single JavaScript context.

Scripted Extensions¶

Extensions are placed in a system-specific location. This folder can be opened from the Plugins tab in the Preferences dialog.

Windows	`C:/Users/<USER>/AppData/Local/Tiled/extensions/`
macOS	`~/Library/Preferences/Tiled/extensions/`
Linux	`~/.config/tiled/extensions/`

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

Note

If your scripts depend on other scripts that you want to include rather than have them execute directly, they can be nested in another sub-directory.

When any loaded script is changed, the script engine is reinstantiated and the scripts are reloaded. This 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.

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`.
actions : [string] [read‑only]	Available actions for tiled.trigger().
menus : [string] [read‑only]	Available menus for tiled.extendMenu().
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.
mapEditor : Map Editor	Access the editor used when editing maps.
tilesetEditor : Tileset Editor	Access the editor used when editing tilesets.

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.

Use the tiled.actions property to get a list of all available actions.

Actions that are checkable will toggle when triggered.

tiled.executeCommand(name : string, inTerminal : bool) : void

Executes the first custom command with the given name, as if it was triggered manually. Works also with commands that are not currently enabled.

Raises a script error if the command is not found.

tiled.open(fileName : string) : Asset: Requests to open the asset with the given file name. Returns a reference to the opened asset, or null in case there was a problem.

tiled.close(asset : Asset) : bool: Closes the given asset without checking for unsaved changes (to confirm the loss of any unsaved changes, set activeAsset and trigger the “Close” action instead).

tiled.reload(asset : Asset) : Asset

Reloads the given asset from disk, without checking for unsaved changes. This invalidates the previous script reference to the asset, hence the new reference is returned for convenience. Returns null if reloading failed.

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.warn(text : string, activated : function) : void

Outputs the given text in the Console window as warning message and creates an issue in the Issues window.

When the issue is activated (with double-click or Enter key) the given callback function is invoked.

tiled.error(text : string, activated : function) : void

Outputs the given text in the Console window as error message and creates an issue in the Issues window.

When the issue is activated (with double-click or Enter key) the given callback function is invoked.

tiled.registerAction(id : string, callback : function) : Action

Registers a new action with the given id and callback (which is called when the action is triggered). The returned action object can be used to set (and update) various properties of the action.

Example:

var action = tiled.registerAction("CustomAction", function(action) {
    tiled.log(action.text + " was " + (action.checked ? "checked" : "unchecked"))
})

action.text = "My Custom Action"
action.checkable = true
action.shortcut = "Ctrl+K"

The shortcut will currently only work when the action is added to a menu using tiled.extendMenu().

tiled.registerMapFormat(shortName : string, mapFormat : object) : void

Registers a new map format that can then be used to open and/or save maps in that format.

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 properties:

name : string	Name of the format as shown in the file dialog.
extension : string	The file extension used by the format.
read : function(fileName : string) : TileMap	A function that reads a map from the given file. Can use TextFile or BinaryFile to read the file.
write : function(map : TileMap, fileName : string) : string \| undefined	A function that writes a map to the given file. Can use TextFile or BinaryFile to write the file. When a non-empty string is returned, it is shown as error message.
outputFiles : function(map : TileMap, fileName : string) : [string]	A function that returns the list of files that will be written when exporting the given map (optional).

Example that produces a simple JSON representation of a map:

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

    write: 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);
            }
        }

        var file = new TextFile(fileName, TextFile.WriteOnly);
        file.write(JSON.stringify(m));
        file.commit();
    },
}

tiled.registerMapFormat("custom", customMapFormat)

tiled.registerTilesetFormat(shortName : string, tilesetFormat : object) : void

Like registerMapFormat, but registers a custom tileset format instead.

The tilesetFormat object is expected to have the following properties:

name : string	Name of the format as shown in the file dialog.
extension : string	The file extension used by the format.
read : function(fileName : string) : Tileset	A function that reads a tileset from the given file. Can use TextFile or BinaryFile to read the file.
write : function(tileset : Tileset, fileName : string) : string \| undefined	A function that writes a tileset to the given file. Can use TextFile or BinaryFile to write the file. When a non-empty string is returned, it is shown as error message.

tiled.registerTool(shortName : string, tool : object) : object

Registers a custom tool that will become available on the Tools tool bar of the Map Editor.

If a tool is already registered with the same shortName the existing tool is replaced.

The tool object has the following properties:

name : string	Name of the tool as shown on the tool bar.
map : TileMap	Currently active tile map.
selectedTile : Tile	The last clicked tile for the active map. See also the `currentBrush` property of Map Editor.
preview : TileMap	Get or set the preview for tile layer edits.
tilePosition : point	Mouse cursor position in tile coordinates.
statusInfo : string	Text shown in the status bar while the tool is active.
enabled : bool	Whether this tool is enabled.
activated : function() : void	Called when the tool was activated.
deactivated : function() : void	Called when the tool was deactivated.
keyPressed : function(key, modifiers) : void	Called when a key was pressed while the tool was active.
mouseEntered : function() : void	Called when the mouse entered the map view.
mouseLeft : function() : void	Called when the mouse left the map view.
mouseMoved : function(x, y, modifiers) : void	Called when the mouse position in the map scene changed.
mousePressed : function(button, x, y, modifiers) : void	Called when a mouse button was pressed.
mouseReleased : function(button, x, y, modifers) : void	Called when a mouse button was released.
mouseDoubleClicked : function(button, x, y, modifiers) : void	Called when a mouse button was double-clicked.
modifiersChanged : function(modifiers) : void	Called when the active modifier keys changed.
languageChanged : function() : void	Called when the language was changed.
mapChanged : function(oldMap : TileMap, newMap : TileMap) : void	Called when the active map was changed.
tilePositionChanged : function() : void	Called when the hovered tile position changed.
updateStatusInfo : function() : void	Called when the hovered tile position changed. Used to override the default updating of the status bar text.
updateEnabledState : function() : void	Called when the map or the current layer changed.

Here is an example tool that places a rectangle each time the mouse has moved by 32 pixels:

var tool = tiled.registerTool("PlaceRectangles", {
    name: "Place Rectangles",

    mouseMoved: function(x, y, modifiers) {
        if (!this.pressed)
            return

        var dx = Math.abs(this.x - x)
        var dy = Math.abs(this.y - y)

        this.distance += Math.sqrt(dx*dx + dy*dy)
        this.x = x
        this.y = y

        if (this.distance > 32) {
            var objectLayer = this.map.currentLayer

            if (objectLayer && objectLayer.isObjectLayer) {
                var object = new MapObject(++this.counter)
                object.x = Math.min(this.lastX, x)
                object.y = Math.min(this.lastY, y)
                object.width = Math.abs(this.lastX - x)
                object.height = Math.abs(this.lastY - y)
                objectLayer.addObject(object)
            }

            this.distance = 0
            this.lastX = x
            this.lastY = y
        }
    },

    mousePressed: function(button, x, y, modifiers) {
        this.pressed = true
        this.x = x
        this.y = y
        this.distance = 0
        this.counter = 0
        this.lastX = x
        this.lastY = y
    },

    mouseReleased: function(button, x, y, modifiers) {
        this.pressed = false
    },
})

tiled.extendMenu(id : string, items : array | object) : void

Extends the menu with the given ID. Supports both a list of items or a single item. Available menu IDs can be obtained using the tiled.menus property.

A menu item is defined by an object with the following properties:

action : string	ID of a registered action that the menu item will represent.
before : string	ID of the action before which this menu item should be added (optional).
separator : bool	Set to `true` if this item is a menu separator (optional).

If a menu item does not include a before property, the value is inherited from the previous item. When this property is not set at all, the items are appended to the end of the menu.

Example that adds a custom action to the “Edit” menu, before the “Select All” action and separated by a separator:

tiled.extendMenu("Edit", [
    { action: "CustomAction", before: "SelectAll" },
    { separator: true }
]);

The “CustomAction” will need to have been registered before using tiled.registerAction().

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 TileMap 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.
isTileMap : bool [read‑only]	Whether the asset is a TileMap.
isTileset : bool [read‑only]	Whether the asset is a Tileset.

Functions¶

Asset.macro(text : string, callback : function) : value

Creates a single undo command that wraps all changes applied to this asset by the given callback. Recommended to avoid spamming the undo stack with small steps that the user does not care about.

Example function that changes visibility of multiple layers in one step:

tileMap.macro((visible ? "Show" : "Hide") + " Selected Layers", function() {
    tileMap.selectedLayers.forEach(function(layer) {
        layer.visible = visible
    })
})

The returned value is whatever the callback function returned.

TileMap¶

Inherits Asset.

Properties¶

width : int	Width of the map in tiles (only relevant for non-infinite maps).
height : int	Height of the map in tiles (only relevant for non-infinite maps).
size : size [read‑only]	Size of the map in tiles (only relevant for non-infinite maps).
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 : StaggerAxis	For staggered and hexagonal maps, determines which axis (X or Y) is staggered.
orientation : Orientation	General map orientation
renderOrder : RenderOrder	Tile rendering order (only implemented for orthogonal maps)
staggerIndex : StaggerIndex	For staggered and hexagonal maps, determines whether the even or odd indexes along the staggered axis are shifted.
backgroundColor : color	Background color of the map.
layerDataFormat : LayerDataFormat	The format in which the layer data is stored, taken into account by TMX, JSON and Lua map formats.
layerCount : int [read‑only]	Number of top-level layers the map has.
tilesets : [Tileset]	The list of tilesets referenced by this map. To determine which tilesets are actually used, call usedTilesets().
selectedArea : SelectionArea	The selected area of tiles.
currentLayer : Layer	The current layer.
selectedLayers : [Layer]	Selected layers.
selectedObjects : [MapObject]	Selected objects.

TileMap.Orientation
TileMap.Unknown
TileMap.Orthogonal
TileMap.Isometric
TileMap.Staggered
TileMap.Hexagonal

TileMap.LayerDataFormat
TileMap.XML
TileMap.Base64
TileMap.Base64Gzip
TileMap.Base64Zlib
TileMap.Base64Zstandard
TileMap.CSV

TileMap.RenderOrder
TileMap.RightDown
TileMap.RightUp
TileMap.LeftDown
TileMap.LeftUp

TileMap.StaggerAxis
TileMap.StaggerX
TileMap.StaggerY

TileMap.StaggerIndex
TileMap.StaggerOdd
TileMap.StaggerEven

Functions¶

new TileMap(): Constructs a new map.

TileMap.autoMap([rulesFile : string]) : void

Applies Automapping using the given rules file, or using the default rules file is none is given.

This operation can only be applied to maps loaded from a file.

TileMap.autoMap(region : region | rect [, rulesFile : string]) : void

Applies Automapping in the given region using the given rules file, or using the default rules file is none is given.

This operation can only be applied to maps loaded from a file.

TileMap.setSize(width : int, height : int) : void

Sets the size of the map in tiles. This does not affect the contents of the map.

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 : TileMap	Map that this layer is part of (or `null` in case of a standalone layer).
selected : bool	Whether the layer is selected.
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 GroupLayer.
isImageLayer : bool [read‑only]	Whether this layer is an ImageLayer.

TileLayer¶

Inherits Layer.

Note that while tile layers have a size, the size is generally ignored on infinite maps. Even for fixed size maps, nothing in the scripting API stops you from changing the layer outside of its boundaries and changing the size of the layer has no effect on its contents. If you want to change the size while affecting the contents, use the resize function.

Properties¶

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

Functions¶

new TileLayer([name : string]): Constructs a new tile layer, which can be added to a TileMap.
TileLayer.region() : region: Returns the region of the layer that is covered with tiles.
TileLayer.resize(size : size, offset : point) : void: Resizes the layer, erasing the part of the contents that falls outside of the layer’s new size. The offset parameter can be used to shift the contents by a certain distance in tiles before applying the resize.
TileLayer.cellAt(x : int, y : int) : cell: Returns the value of the cell at the given position. Can be used to query the flags and the tile ID, but does not currently allow getting a tile reference.
TileLayer.flagsAt(x : int, y : int) : int: Returns the flags used for the tile at the given position.
TileLayer.tileAt(x : int, y : int) : Tile: Returns the tile used at the given position, or null for empty spaces.

TileLayer.edit() : TileLayerEdit: Returns an object that enables making modifications to the tile layer.

ObjectGroup¶

Inherits Layer.

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

Properties¶

objects : [MapObject] [read‑only]	Array of all objects on this layer.
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¶

new ObjectGroup([name : string]): Constructs a new object layer, which can be added to a TileMap.
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.

GroupLayer¶

Inherits Layer.

Properties¶

layerCount : int [read‑only]

Number of child layers the group layer has.

Functions¶

new GroupLayer([name : string]): Constructs a new group layer.
GroupLayer.layerAt(index : int) : Layer: Returns a reference to the child layer at the given index.
GroupLayer.removeLayerAt(index : int) : void: Removes the child layer at the given index. When a reference to the layer still exists and this group layer isn’t already standalone, that reference becomes a standalone copy of the layer.
GroupLayer.removeLayer(layer : Layer) : void: Removes the given layer from the group. If this group wasn’t standalone, the reference to the layer becomes a standalone copy.
GroupLayer.insertLayerAt(index : int, layer : Layer) : void: Inserts the layer at the given index. The layer can’t already be part of a map.
GroupLayer.addLayer(layer : Layer) : void: Adds the layer to the group, above all existing layers. The layer can’t already be part of a map.

ImageLayer¶

Inherits Layer.

Properties¶

transparentColor : color	Color used as transparent color when rendering the image.
imageSource : url	Reference to the image rendered by this layer.

MapObject¶

Inherits Object.

Properties¶

id : int [read‑only]	Unique (map-wide) ID of the object.
shape : int	Shape 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.
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.
polygon : Polygon	Polygon of the object.
text : string	The text of a text object.
font : Font	The font of a text object.
textAlignment : Alignment	The alignment of a text object.
wordWrap : bool	Whether the text of a text object wraps based on the width of the object.
textColor : color	Color of a text object.
tile : Tile	Tile of the object.
tileFlippedHorizontally : bool	Whether the tile is flipped horizontally.
tileFlippedVertically : bool	Whether the tile is flipped vertically.
selected : bool	Whether the object is selected.
layer : ObjectGroup [read‑only]	Layer this object is part of (or `null` in case of a standalone object).
map : TileMap [read‑only]	Map this object is part of (or `null` in case of a standalone object).

MapObject.Shape
MapObject.Rectangle
MapObject.Polygon
MapObject.Polyline
MapObject.Ellipse
MapObject.Text
MapObject.Point

Functions¶

new MapObject([name : string]): Constructs a new map object, which can be added to an ObjectGroup.

Tileset¶

Inherits Asset.

Properties¶

name : string	Name of the tileset.
image : string	The file name of the image used by this tileset. Empty in case of image collection tilesets.
tiles: [Tile] [read‑only]	Array of all tiles in this tileset. Note that the index of a tile in this array does not always match with its ID.
terrains: [Terrain] [read‑only]	Array of all terrains in this tileset.
tileCount : int	The number of tiles in this tileset.
tileWidth : int	Tile width for tiles in this tileset in pixels.
tileHeight : int	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.
isCollection : bool	Whether this tileset is a collection of images.
selectedTiles : [Tile]	Selected tiles (in the tileset editor).

Functions¶

new Tileset([name : string])

Constructs a new tileset.

Tileset.tile(id : int) : Tile

Returns a reference to the tile with the given ID. Raises an error if no such tile exists. When the tile gets removed from the tileset, the reference changes to a standalone copy of the tile.

Note that the tiles in a tileset are only guaranteed to have consecutive IDs for tileset-image based tilesets. For image collection tilesets there will be gaps when tiles have been removed from the tileset.

Tileset.setTileSize(width : int, height : int) : void

Sets the tile size for this tileset. If an image has been specified as well, the tileset will be (re)loaded. Can’t be used on image collection tilesets.

Tileset.addTile() : Tile

Adds a new tile to this tileset and returns it. Only works for image collection tilesets.

Tileset.removeTiles(tiles : [Tile]) : void

Removes the given tiles from this tileset. Only works for image collection tilesets.

Tile¶

Inherits Object.

Properties¶

id : int [read‑only]	ID of this tile within its tileset.
width : int [read‑only]	Width of the tile in pixels.
height : int [read‑only]	Height of the tile in pixels.
size : size [read‑only]	Size of the tile in pixels (has `width` and `height` members).
type : string	Type of the tile.
imageFileName : string	File name of the tile image (when the tile is part of an image collection tileset).
terrain : Terrains	An object specifying the terrain at each corner of the tile.
probability : number	Probability that the tile gets chosen relative to other tiles.
objectGroup : ObjectGroup	The ObjectGroup associated with the tile in case collision shapes were defined. Returns `null` if no collision shapes were defined for this tile.
frames : [frame]	This tile’s animation as an array of frames.
animated : bool [read‑only]	Indicates whether this tile is animated.
tileset : Tileset [read‑only]	The tileset of the tile.

Tile.Flags
Tile.FlippedHorizontally
Tile.FlippedVertically
Tile.FlippedAntiDiagonally
Tile.RotatedHexagonal120

Tile.Corner
Tile.TopLeft
Tile.TopRight
Tile.BottomLeft
Tile.BottomRight

Functions¶

Tile.terrainAtCorner(corner : Corner) : Terrain: Returns the terrain used at the given corner.
Tile.setTerrainAtCorner(corner : Corner, Terrain) : void: Sets the terrain used at the given corner.

Terrain¶

Inherits Object.

Properties¶

id : int [read‑only]	ID of this terrain.
name : string	Name of the terrain.
imageTile : Tile	The tile representing the terrain (needs to be from the same tileset).
tileset : Tileset [read‑only]	The tileset of the terrain.

TileLayerEdit¶

This object enables modifying the tiles on a tile layer. Tile layers can’t be modified directly for reasons of efficiency. The apply() function needs to be called when you’re done making changes.

An instance of this object is created by calling TileLayer.edit().

Properties¶

target : TileLayer [read‑only]	The target layer of this edit object.
mergeable : bool	Whether applied edits are mergeable with previous edits. Starts out as `false` and is automatically set to `true` by apply().

Functions¶

TileLayerEdit.setTile(x : int, y : int, tile : Tile [, flags : int = 0]) : void: Sets the tile at the given location, optionally specifying tile flags.

TileLayerEdit.apply() : void: Applies all changes made through this object. This object can be reused to make further changes.

SelectedArea¶

Properties¶

boundingRect : rect [read‑only]

Bounding rectangle of the selected area.

Functions¶

SelectedArea.get() : region: Returns the selected region.
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.

Action¶

An action that was registered with tiled.registerAction(). This class is used to change the properties of the action. It can be added to a menu using tiled.extendMenu().

Properties¶

checkable : bool	Whether the action can be checked.
checked : bool	Whether the action is checked.
enabled : bool	Whether the action is enabled.
icon : string	File name of an icon.
iconVisibleInMenu : bool	Whether the action should show an icon in a menu.
id : string [read‑only]	The ID this action was registered with.
shortcut : QKeySequence	The shortcut (can be assigned a string like “Ctrl+K”).
text : string	The text used when the action is part of a menu.
visible : bool	Whether the action is visible.

Functions¶

Action.trigger() : void: Triggers the action.
Action.toggle() : void: Changes the checked state to its opposite state.

Map Editor¶

Properties¶

currentBrush : TileMap	Get or set the currently used tile brush.
currentMapView : Map View [read‑only]	Access the current map view.
tilesetsView : Tilesets View [read‑only]	Access the Tilesets view.

Map View¶

The view displaying the map.

Properties¶

scale : number

Get or set the scale of the view.

Functions¶

MapView.centerOn(x : number, y : number) : void: Centers the view at the given location in screen coordinates.

Tilesets View¶

Properties¶

currentTileset : Tileset

Access or change the currently displayed tileset.

Tileset Editor¶

Properties¶

collisionEditor : Tile Collision Editor

Access the collision editor within the tileset editor.

Tile Collision Editor¶

Properties¶

selectedObjects : [MapObject]	Selected objects.
view : [Map View]	The map view used by the Collision Editor.

Functions¶

TileCollisionEditor.focusObject(object : MapObject) : void: Focuses the given object in the collision editor view and makes sure its visible in its objects list. Does not automatically select the object.

Basic Types¶

Some types are provided by the Qt Scripting Engine and others are added based on the needs of the data types above. In the following the most important ones are documented.

Alignment¶

Qt.Alignment
Qt.AlignLeft	0x0001
Qt.AlignRight	0x0002
Qt.AlignHCenter	0x0004
Qt.AlignJustify	0x0008
Qt.AlignTop	0x0020
Qt.AlignBottom	0x0040
Qt.AlignVCenter	0x0080
Qt.AlignCenter	Qt.AlignVCenter \| Qt.AlignHCenter

Font¶

family : string	The font family.
pixelSize : int	Font size in pixels.
bold : bool	Whether the font is bold.
italic : bool	Whether the font is italic.
underline : bool	Whether the text is underlined.
strikeOut : bool	Whether the text is striked through.
kerning : bool	Whether to use kerning when rendering the text.

cell¶

A cell on a TileLayer.

Properties

tileId : int	The local tile ID of the tile, or -1 if the cell is empty.
empty : bool	Whether the cell is empty.
flippedHorizontally : bool	Whether the tile is flipped horizontally.
flippedVertically : bool	Whether the tile is flipped vertically.
flippedAntiDiagonally : bool	Whether the tile is flipped anti-diagonally.
rotatedHexagonal120 : bool	Whether the tile is rotated by 120 degrees (for hexagonal maps, the anti-diagonal flip is interpreted as a 60-degree rotation).

Frames¶

An array of frames, which are objects with the following properties:

tileId : int	The local tile ID used to represent the frame.
duration : int	Duration of the frame in milliseconds.

rect¶

Qt.rect(x, y, width, height) can be used to create a rectangle.

Properties

x : int	X coordinate of the rectangle.
y : int	Y coordinate of the rectangle.
width : int	Width of the rectangle.
height : int	Height of the rectangle.

region¶

Properties

boundingRect : rect [read‑only]

Bounding rectangle of the region.

point¶

Qt.point(x, y) can be used to create a point object.

Properties

x : number	X coordinate of the point.
y : number	Y coordinate of the point.

size¶

Qt.size(width, height) can be used to create a size object.

Properties

width : number	Width.
height : number	Height.

Polygon¶

A polygon is not strictly a custom type. It is an array of objects that each have an x and y property, representing the points of the polygon.

To modify the polygon of a MapObject, change or set up the polygon array and then assign it to the object.

Terrains¶

An object specifying the terrain for each corner of a tile:

topLeft : Terrain

topRight : Terrain

bottomLeft : Terrain

bottomRight : Terrain

TextFile¶

The TextFile object is used to read and write files in text mode.

When using TextFile.WriteOnly, you need to call commit() when you’re done writing otherwise the operation will be aborted without effect.

Properties

filePath : string [read‑only]	The path of the file.
atEof : bool [read‑only]	True if no mode data can be read.
codec : string	The text codec.

TextFile.OpenMode
TextFile.ReadOnly	0x0001
TextFile.WriteOnly	0x0002
TextFile.ReadWrite	TextFile.ReadOnly \| TextFile.WriteOnly
TextFile.Append

Functions

new TextFile(fileName : string [, mode : OpenMode = ReadOnly]): Opens a text file in the given mode.
TextFile.readLine() : string: Reads one line of text from the file and returns it. The returned string does not contain the newline characters.
TextFile.readAll() : string: Reads all data from the file and returns it.
TextFile.truncate() : void: Truncates the file, that is, gives it the size of zero, removing all content.
TextFile.write(text : string) : void: Writes a string to the file.
TextFile.writeLine(text : string) : void: Writes a string to the file and appends a newline character.
TextFile.commit() : void: Commits all written text to disk. Should be called when writing to files in WriteOnly mode. Failing to call this function will result in cancelling the operation, unless safe writing to files is disabled.
TextFile.close() : void: Closes the file. It is recommended to always call this function as soon as you are finished with the file.

BinaryFile¶

The BinaryFile object is used to read and write files in binary mode.

When using BinaryFile.WriteOnly, you need to call commit() when you’re done writing otherwise the operation will be aborted without effect.

Properties

filePath : string [read‑only]	The path of the file.
atEof : bool [read‑only]	True if no mode data can be read.
size : number	The size of the file (in bytes).
pos : number	The position that data is written to or read from.

BinaryFile.OpenMode
BinaryFile.ReadOnly	0x0001
BinaryFile.WriteOnly	0x0002
BinaryFile.ReadWrite	BinaryFile.ReadOnly \| BinaryFile.WriteOnly

Functions

BinaryFile.resize(qint64 size) : void: Sets the file size (in bytes). If size is larger than the file currently is, the new bytes will be set to 0; if size is smaller, the file is truncated.
BinaryFile.seek(qint64 pos) : void: Sets the current position to pos.
BinaryFile.read(qint64 size) : ArrayBuffer: Reads at most size bytes of data from the file and returns it as an ArrayBuffer.
BinaryFile.readAll() : ArrayBuffer: Reads all data from the file and returns it as an ArrayBuffer.
BinaryFile.write(data : ArrayBuffer) : void: Writes data into the file at the current position.
BinaryFile.commit() : void: Commits all written data to disk. Should be called when writing to files in WriteOnly mode. Failing to call this function will result in cancelling the operation, unless safe writing to files is disabled.
BinaryFile.close() : void: Closes the file. It is recommended to always call this function as soon as you are finished with the file.