mapeditor / mapeditor/tiled

Scripting: `tiled.open()` and `Asset.save()` in scripts executed via CLI

Open
#4,095 4 comments 0 reactions 1 assignee View on GitHub

@PoonamMehan is already working on this.

Since Mar 6, 2026.

Dominant language
C++
Stars
12.9k
Forks
2k
Avg merge
4h 27m
Merged PRs (30d)
8

Description

When running scripts via command line interface, there is no good way to open and save Tiled assets. Such scripts are responsible for opening any Assets mentioned in their arguments, or may choose which Assets they'd like to open (e.g. all the Assets in a Project), but the only method available to open Assets seems to be via MapFormat/TilesetFormat. The only other option is to run a scripted exporter via `--export-map/tileset`, where Tiled will handle loading the (single) initial asset for you.

In addition, it's a common task to modify some asset via a script and to then save it, but once again, the only option to save an Asset in a script run via CLI is MapFormat/TilesetFormap, one can't simply `map.save()` like one can in the GUI.

Allowing more of the GUI-only methods to be usable in CLI mode would make it much easier to write scripts that can work both via CLI and via GUI. Aside from making the aforementioned methods available, it would also be convenient if there was some way to have Tiled load the Asset(s) listed in parameters instead of just passing the paths along to the script, and allowing scripts to use `tiled.activeAsset` and/or `tiled.openAssets` to get at those loaded Assets; this would allow many scripts written for the GUI to work via CLI without any changes, since those properties are the main way scripts choose the Assets to work on.

As a counterpart to `tiled.open()`, `tiled.close()` should also be made available, so that memory use can be kept in check for scripts that process many Assets.

This is not a critical feature since all the functionality is technically available via MapFormat/TilesetFormat. Making these GUI-only features available via CLI will just make scripting more straightforward rather than more capable. However, though it seems minor, I think this difference in approach to opening and saving files is significant enough that it discourages people from writing scripts that can work both in the GUI and via CLI. I think we'd see more widely useful scripts if the differences between the two modes were restricted to truly GUI-specific functionality like Automapping.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.