Scripting: Allow scripts to work with Tile Stamps #3342

Scripts currently have no way to create, delete, or use Tile Stamps and their Variants. Would be nice if they could. My use cases:

Automating the creation of stamps and variants from a map. For example, I might design a bunch of different trees in one map, and use a script that turns every M x N region of that map into a single stamp with variants, so that I can stamp those trees at random. Adding a bunch of variants by hand is quite tedious.

A script that lets me easily randomize the transformation (flipping, rotation) or a single tile or multi-tile stamp when painting, by temporarily creating a stamp with variants, so that all the existing tile-painting tools can benefit.

The scripting API would need to provide ways to do the following:

1. Create a new Stamp, taking a TileMap as a source.
   • Should Tile Stamps be able to exist without being added to the Tile Stamps panel? If so, then they should have a constructor, e.g. newStamp = new TileStamp(map);. If they can only exist via the Tile Stamps panel, then something like newStamp = tiled.createTileStamp(map); would be more appropriate.
2. Create a new stamp Variation from a map, e.g. variant= newStamp.addVariation(anotherMap);
3. Get a variation from a stamp, e.g. variant = newStamp.getVariation(0), where 0 is a variation index.
4. Delete a Variation from a stamp.
   • If simple Stamps are treated as just having a single Variation, that might simplify editing and deleting variants, as there would be no functional difference between a stamp with and without variants. As far as I can tell, this is how it already works internally.
5. Delete a stamp, including all its variants.
   • This is only relevant for stamps added to the Tile Stamps panel as Tile Stamps that exist only script-side will be garbage collected, so it should probably be something like tiled.deleteTileStamp(newStamp);
6. Assign a new map to a given stamp/Variation, replacing the old one, e.g. newStamp.setTileMap(0, newMap), where the 0 is a variation index.
7. Get the map associated with a stamp or variant, for possible modification, e.g. newStamp.getTileMap(0), where 0 is the variation index. I suspect that with how most of the Tiled API works, the modified map will need to be re-assigned to actually modify the stamp.
8. Assign a probability to a given variant, e.g. newStamp.setProbability(0, 0.3).
9. Get a list of all stamps that are currently in the Tile Stamps panel, e.g. a tiled.tileStamps array. I think direct access to this array (as opposed to a function that makes a copy of it) would be best, so that it updates when stamps are created or deleted.
10. Assign a stamp or Variation to tiled.mapEditor.currentBrush, so that it works the same as clicking a stamp or variation in the Tile Stamps panel - if a stamp with multiple variations is assigned, painting with the brush should randomly select one of the variations. For simplicity, I think assigning a specific Variation should be the same as assigning that variation's map - that is, currentBrush will always be either a map or a stamp.
11. A way to see whether tiled.mapEditor.currentBrush is currently a TileMap or a TileStamp, since it'll need to support both now. TileMap already has isTileMap, so perhaps simply that being false/undefined would be enough, in which case, no additional work is needed.

In my examples above, I used a bunch of methods on TileStamp to access and deal with the Variations, similar to how WangColors are handled now. It would be also be fine to have a TileStampVariation class that contains the map and probability, and have the TileStamp just be a container. Go with whichever is easier to implement!