Add World scripting features

[dogboydog]

Fix #3539

Add UnloadAllWorlds action, exposed in World > Unload World when two or more worlds are loaded.

Added to scripting:

tiled.worldsChanged : Signal<void>;
tiled.worldLoaded : Signal<string>;
tiled.worldReloaded : Signal<string>;
tiled.worldUnloaded : Signal<string>;  
tiled.worldSaved : Signal<string>;
tiled.worlds : World[]; 

class WorldMapEntry {
  fileName : string;
  rect : rect;
} 

class WorldPattern {
  regExp: RegExp;
  multiplierX: number;
  multiplierY: number;
  offset: point;
  mapSize: size;
}

class World { 
  readonly maps : WorldMapEntry[];
  readonly patterns : WorldPattern[];
  allMaps() : WorldMapEntry[];
  mapsInRect(rect : rect) : WorldMapEntry[];
  containsMap(fileName : string) : boolean;
  setMapRect(fileName: string, rect : rect): void;
  setMapPos(map: TileMap, x: number, y: number): void;
  addMap(fileName: string, rect: rect): void;
  addMap(map: TileMap, x: number, y: number): void;
  removeMap(fileName: string): void;
  removeMap(map: TileMap): void;
  save(): boolean;
}

TODO

• Update version number for @since in new entries in tiled.d.ts
• Fix crash on tiled.worlds. I think the WorldDocument I'm creating is getting freed when worlds() returns in scriptmodule.cpp, but not sure where to save the references or if I'm right about the problem
• adding/removing maps from worlds
• Test and provide examples in below gist of methods on individual worlds returned from tiled.worlds

Test script
https://gist.github.com/dogboydog/42edb0886989467ec3671acdce4e749f#file-worldscripting

[bjorn]

Some initial comments, but to be continued next week. :-)

[bjorn]

Feedback to address:

• It is not possible to add maps to worlds that also use patterns. This need to be either supported or an error needs to be reported when trying to do this.
• Add overloads for addMap that take a Tiled::EditableMap*, with only a position (since this one can calculate the size automatically).

[eishiya]

• Add overloads for addMap that take a Tiled::EditableMap*, with only a position (since this one can calculate the size automatically).

If adding maps can be done with a TileMap, then I think removeMap(TileMap) should be available too. That one should be simpler since it just needs to check whether the TileMap has a fileName and use that.

[bjorn]

Another small thing: I think there should be a menu separator above the "Unload All Worlds" action.

[dogboydog]

I added addMap and removeMap which take EditableMap instances. I'm wondering if we should abstract away any references to mapIndex in any of these world scripting APIs and just have the user specify either an EditableMap or a file name. Thanks for your help with this.

[bjorn]

I'm wondering if we should abstract away any references to mapIndex in any of these world scripting APIs and just have the user specify either an EditableMap or a file name.

Yeah, I'll have a go at removing all the index-based API. If necessary one can compute the index by iterating world.maps anyway. Otherwise for completeness sake we'd have to provide an index, filename and map version of each function...

[eishiya]

Is using a QPoint instead of just x, y necessary? I feel like addMap(map, x, y) would be more convenient than addMap(map, Qt.point(x, y)).

[bjorn]

Alright, I think it's done and ready for merge. Would you give it a final round of review and testing, @dogboydog?

[dogboydog]

Thanks, I just gave it a try. I was able to run my example script and add and remove maps, call mapsInRect, containsMap, setMapPos. The signals seem to be firing as expected. It seems good to me.

[bjorn]

@dogboydog I've decided to still push a large change and remove most of the world-specific signals, readding some of them by emitting assetOpened, assetAboutToBeSaved and assetSaved also for worlds. I wasn't convinced the existing world-specific signals would be useful enough, and it could be hard to keep API compatibility when we change the way worlds are handled in the future.