Add a createMap() macro function

[kwvanderlinde]

Identify the Bug or Feature request

Implements #3505

Description of the Change

First up there is some supporting refactoring to bring paint string parsing and asset ID/URL parsing into FunctionUtil. DrawingFunctions and its children, and LookupTableFunction now use these common methods instead of using their own. These will also be used by createMap().

Second is a tweak to MapTool.addZone() to fix an edge case I encountered while testing createMap(). In the case that we replace the default map, there were two undesirable effects of how we did the replacement:

1. On the client adding the map, the new map would not be set as current, leaving the client on no map. Otherwise things work fine, the client just has to be manually switched to the new map before they can see anything.
2. On a connected client receiving the new map, an NPE could result. Since we delete the default map first, then send the new map, there is a short time where the client has no maps at all.

The behaviour is now changed so that we add the new map first, then delete the default map. We also always force a map change on the originating client if adding the map results in deleting the default map.

Third is a change to getInfo("map") / getInfo("zone") to include more information via new keys. The new keys hold info that will be useful when calling createMap(), so I wanted easy access to these values. The new keys are:

• "lighting style"
• "has fog"
• "ai rounding"
• "background paint"
• "fog paint"
• "map asset"

Finally is the main change: createMap(). This trusted macro function builds brand new maps given only a name and some options. This will allow add-ons and other macros to create new maps from nothing, which can then be populated using existing macros, e.g., createToken(), etc. The createMap() function supports every option in the Map Properties dialog, and also every meaningful property returned by getInfo("map") (inlcuding the newly added ones). I aimed for alignment between createMap() keys and getInfo("map") keys to make it easier to build a configuration object for use with createMap(). The documentation notes below detail the exact set of keys that are supported in the configuration.

Possible Drawbacks

Should be none

Documentation Notes

createMap

Usage

createMap(name)
createMap(name, config)

Parameters

• name The name of the new map.
• config A JSON object of options to apply to the new map.

config parameter
config is a JSON Object that can contain any of the following fields. Field names are case-sensitive, and all fields are optional:

• display name: defaults to none
• player visible: defaults to user preferences
• vision type: defaults to user preferences
• vision distance: defaults to user preferences
• lighting style: defaults to "OVERTOP"
• background paint: defaults to built-in Grass
• fog paint: defaults to black
• has fog: defaults to user preferences (TODO Implement it)
• map asset: defaults to none
• grid: JSON object, see below

The grid value is another JSON object, with these optional keys:

• type: defaults to user preferences
• color: defaults to user preferences
• units per cell: defaults to user preferences
• size: defaults to user preferences
• x offset: defaults to 0
• y offset: defaults to 0

Examples

[h: vNewMapId = createMap("New Map", json.set("{}",
        "display name", "Display Name",
        "player visible", json.true,
        "vision type", "NIGHT",
        "vision distance", 600,
        "lighting style", "OVERTOP",
        "has fog", json.true,
        "ai rounding", "CELL_UNIT",
        "grid", json.set("{}",
                "type", "Square",
                "color", "#FF0000",
                "units per cell", 20,
                "size", 200,
                "x offset", 7,
                "y offset", 11
        ),
        "background paint", "asset://da1712226dac0f02c4a9a57ab772856b",
        "fog paint", "asset://d3e430bd9f1e380ec749c42e060f015b",
        "map asset", "asset://014aaa10a10b5ddcbbe006f3c22188c2"
))]

Release Notes

• Fixed a NullPointerException that could result when creating a new map in a blank campaign with connected clients.
• Added the following keys to the result of getInfo("map")/getInfo("zone"): "lighting style", "has fog", "ai rounding", "background paint", "fog paint", "map asset"
• Added createMap(name, [config]) function to create new maps with configurable options.

---

This change is 

[Azhrei]

Thanks for the doc; I'll get it added to the wiki. 👍 Just like your other pending PR, they'll be "proposed" until they make it into a release after testing. Thanks again!