Merge pull request #3859 from dogboydog/3539_script_worlds

 Add World scripting features

NEWS.md

@@ -1,6 +1,7 @@
 ### Unreleased
 
 * Added --project command-line parameter for use when exporting (#3797)
+* Scripting: Added API for working with worlds (#3539)
 * JSON format: Fixed tile order when loading a tileset using the old format
 * tmxrasterizer: Added --hide-object and --show-object arguments (by Lars Luz, #3819)
 * tmxrasterizer: Added --frames and --frame-duration arguments to export animated maps as multiple images (#3868)

docs/scripting-doc/index.d.ts

@@ -1131,6 +1131,151 @@ declare class Project extends TiledObject {
   readonly fileName: string;
 }
 
+/**
+ * Details of a map that is added to a {@link World}.
+ *
+ * @since 1.10.3
+ */
+declare class WorldMapEntry {
+  /**
+   * File name of the map.
+   */
+  fileName : string;
+
+  /**
+   * A rect describing the location and dimensions of the map within the World.
+   */
+  rect : rect;
+} 
+
+/**
+ * Patterns added to a {@link World}, which are used to automatically match
+ * maps. See the [Using Pattern
+ * Matching](https://doc.mapeditor.org/en/stable/manual/worlds/#using-pattern-matching)
+ * section in the manual for more information.
+ *
+ * @since 1.10.3
+ */
+declare class WorldPattern {
+  /** 
+   * The regular expression pattern used to match maps in the world.
+   */
+  regExp: RegExp;
+
+  /**
+   * Multiplied by the first number (x) in the regular expression to determine
+   * the map's position in the world.
+   */
+  multiplierX: number;
+
+  /**
+   * Multiplied by the second number (y) in the regular expression to determine
+   * the map's position in the world.
+   */
+  multiplierY: number;
+
+  /**
+   * After calculating the map's position in the world using x and y in its 
+   * regular expression and the associated multipliers, this offset is added
+   * to determine the final position.
+   */
+  offset: point;
+
+  /**
+   * The size of the map in pixels.
+   *
+   * Used to support showing only directly neighboring maps when a world is
+   * loaded. For more information, see the [Showing Only Direct
+   * Neighbors](https://doc.mapeditor.org/en/stable/manual/worlds/#showing-only-direct-neighbors)
+   * section in the manual.
+   */
+  mapSize: size;
+}
+
+/**
+ * A world defined in a .world file, which is a JSON file that tells
+ * Tiled which maps are part of the world and at what location.
+ *
+ * See the [Working with
+ * Worlds](https://doc.mapeditor.org/en/stable/manual/worlds/) page in the
+ * manual for more information.
+ *
+ * @since 1.10.3
+ */
+declare class World extends Asset {
+  /**
+   * The maps that are explicitly added to this world. It does not include
+   * those maps which match due to patterns defined on the world.
+   */
+  readonly maps : WorldMapEntry[];
+
+  /**
+   * The patterns that are configured for this map. These patterns will be used
+   * to automatically match maps in your project.
+   */
+  readonly patterns : WorldPattern[];
+
+  /**
+   * Returns all maps that are part of this world, either directly referenced
+   * or matched by one of the patterns.
+   */
+  allMaps() : WorldMapEntry[];
+
+  /**
+   * Returns any maps that intersect with the given {@link rect}. This is a
+   * filtered version of the results from {@link allMaps}.
+   */
+  mapsInRect(rect : rect) : WorldMapEntry[];
+
+  /**
+   * Returns true if this world contains a map with the given fileName.
+   * @param fileName The file name of the map to check for.
+   */
+  containsMap(fileName : string) : boolean;
+
+  /**
+   * Change the position and size of a map within this world.
+   * @param fileName The file name of the map to change the position and size for.
+   * @param rect The new rect describing the position and size of the map.
+   */
+  setMapRect(fileName: string, rect : rect): void;
+
+  /**
+   * Change the position of a map within this world.
+   * @param map The TileMap of which to change the position.
+   * @param x The x position of the map in the world, in pixels.
+   * @param y The y position of the map in the world, in pixels.
+   */
+  setMapPos(map: TileMap, x: number, y: number): void;
+
+  /**
+   * Add a map to this world.
+   * @param fileName The file name of the map to add to this world.
+   * @param rect A Qt.rect specifying the position and size of the map to add.
+   */
+  addMap(fileName: string, rect: rect): void;
+
+  /**
+   * Add a map to this world. The map size in pixels will be set automatically.
+   * @param map The TileMap instance to add to the world.
+   * @param x The x position of the map in the world, in pixels.
+   * @param y The y position of the map in the world, in pixels.
+   */
+  addMap(map: TileMap, x: number, y: number): void;
+
+  /**
+   * Remove a map from this world.
+   * @param fileName The file name of the map to remove.
+   */
+  removeMap(fileName: string): void;
+
+  /**
+   * Remove a map from this world.
+   * @param map The TileMap instance to remove from this world.
+   */
+  removeMap(map: TileMap): void;
+}
+
 /**
  * Defines the font used to render objects which have {@link MapObject.shape}
  * set to {@link MapObject.Text}.
@@ -1325,6 +1470,19 @@ declare class MapObject extends TiledObject {
   constructor(shape: MapObjectShape, name? : string)
 }
 
+/**
+ * The top-level assets supported by Tiled. Not all of these assets have
+ * associated editors.
+ *
+ * @since 1.10.3
+ */
+declare enum AssetType {
+  TileMap = 1,
+  Tileset,
+  Project,
+  World,
+}
+
 /**
  * Represents any top-level data type that can be saved to a file.
  *
@@ -1369,6 +1527,13 @@ declare class Asset extends TiledObject {
    */
   readonly isTileset: boolean;
 
+  /**
+   * The type of this asset.
+   *
+   * @since 1.10.3
+   */
+  readonly assetType: AssetType;
+
   /**
    * Creates a single undo command that wraps all changes applied to this
    * asset by the given callback. Recommended to avoid spamming the undo
@@ -1402,6 +1567,23 @@ declare class Asset extends TiledObject {
    * @note The undo system is only enabled for assets loaded in the editor!
    */
   redo(): void;
+
+  /**
+   * Save this asset to disk. Returns true if the asset was saved successfully.
+   *
+   * Errors are reported by the UI. When an editor is open for this asset, this
+   * editor is activated when an error is reported.
+   *
+   * Only supported with the editor running, not when running scripts on the
+   * CLI. Also, the asset should already have an associated file.
+   *
+   * To save assets to a specific file or in a different format, use {@link
+   * tiled.mapFormat} or {@link tiled.tilesetFormat}. This is currently not
+   * supported for worlds.
+   *
+   * @since 1.10.3
+   */
+  save(): boolean;
 }
 
 /**
@@ -4369,6 +4551,36 @@ declare namespace tiled {
    * The {@link activeAsset} has changed.
    */
   export const activeAssetChanged: Signal<Asset>;
+
+  /**
+   * A list of all currently loaded {@link World|worlds}.
+   * @since 1.10.3
+   */
+  export const worlds : World[];
+
+  /**
+   * Load a world contained in a .world file in the path fileName.
+   * @since 1.10.3
+   */
+  export function loadWorld(fileName : string) : void;
+
+  /**
+   * Unload a world contained in a .world file in the path fileName.
+   * @since 1.10.3
+   */
+  export function unloadWorld(fileName : string) : void;
+
+  /**
+   * Unload all currently loaded worlds.
+   * @since 1.10.3
+   */
+  export function unloadAllWorlds() : void;
+
+  /**
+   * Signal emitted when any world is loaded, unloaded, reloaded or changed.
+   * @since 1.10.3
+   */
+  export const worldsChanged : Signal<void>;
 }
 
 /**

src/libtiled/libtiled.qbs

@@ -179,8 +179,8 @@ DynamicLibrary {
         "varianttomapconverter.h",
         "wangset.cpp",
         "wangset.h",
-        "worldmanager.cpp",
-        "worldmanager.h",
+        "world.cpp",
+        "world.h",
     ]
 
     Group {

src/libtiled/logginginterface.cpp

@@ -188,6 +188,7 @@ SelectCustomProperty::SelectCustomProperty(QString fileName,
         id = static_cast<const WangColor*>(object)->colorIndex();
         break;
     case Object::ProjectType:
+    case Object::WorldType:
         break;
     }
 }

src/libtiled/object.h

@@ -51,6 +51,7 @@ class TILEDSHARED_EXPORT Object
         WangSetType         = 0x040,
         WangColorType       = 0x080,
         ProjectType         = 0x100,
+        WorldType           = 0x200,
     };
 
     explicit Object(TypeId typeId, const QString &className = QString())