Scripting: Add API for Worlds

[eishiya]

At present, the only way for Tiled scripts to work with Worlds is to parse the .world file themselves. This is a hassle, especially for Worlds that use pattern-matching instead of explicitly defined maps. Working with maps in a World would be a lot more convenient if the scripting API provided access to the many functions of World that already exist on the C++ side, including opening/closing worlds, getting the current active world(s?), adding/removing maps, getting a list of maps and their rects, getting the rect for a given map, getting all maps in a given rect, and Signals for worlds loading/unloading/changing.

It looks like on the C++ side, most of the World methods work with map file paths. I think it would be good to preserve this, while also providing methods that accept/return TileMaps for convenience.

Example use cases:

• Automatically generate/populate map transition zone Objects based on map adjacency in the World.
• Populate a World automatically based on a system that the current pattern matching can't deal with, such as maps using sequential letters, or based on custom properties on the map.
• Populate map custom properties based on position in the World, e.g. the map's position on the in-game map, to avoid the need to parse the World in-engine.

[bjorn]

I think it would be good to preserve this, while also providing methods that accept/return TileMaps for convenience.

Currently the API implemented by #3859 does not provide such convenience methods. I considered adding this, but I wasn't sure whether it is a good idea, because:

• Not every map can be passed in (only those with valid fileName can be accepted), though this is a minor issue.
• When accessing World.maps, you get "map entry" objects with rects and file names, since the maps might not be loaded and the "rect" information is not part of the map.

So I think these convenience methods would make the API a little inconsistent, and the convenience is really very minor, compared to just doing addMap(map.fileName, rect).

[eishiya]

Makes sense. I think it'd fine if we can't get TileMaps directly from Worlds, but I'd still like to see addMap and removeMap overrides that take a TileMap, as I think that would make for scripts that look cleaner. They can return false or throw an error if the TileMap has no fileName.

Also, I'd love to see addMap(fileName, x, y) and addMap(TileMap, x, y) overrides that don't require a QRect and auto-calculate the bounds, for trivial adds, which I suspect most would be. Calculating the bounds isn't always trivial (especially for non-ortho maps), it'd be nice to offload that to Tiled when it's not directly relevant to the script's function, such as when just adding a bunch of maps to a World in a grid or something.

[bjorn]

@eishiya Hmm, good point about the bounds. Maybe it is worth it for the convenience after all.

[eishiya]

I had a brainfart and forgot that addMap(fileName, x, y) doesn't actually have the map open to do work with, so that one's probably too much to ask for, and adding maps via fileName should require a full rect. But addMap(TileMap, x, y) would still be great.