Editing Set map details API

The '''set map details API''' can be used by map creators to assist in creating their [[map]].  This API can do the things that the built-in WarLight map UI can do, such as setting [[Territories|territory]] names, setting territory center points, defining the connections between territories, etc.

== Preparation ==

To use the API, you must first have uploaded your SVG file via the [[Map Making|normal process]].  After it's uploaded, click the button named "Get link for sharing" and you'll get a URL such as:

https://www.warlight.net/play?PreviewMap=5859

The number at the end of the URL is your map ID.  In the example shown, the map ID is 5859.

==Usage==

To enter the details of your map without using the UI, you POST some JSON to https://www.warlight.net/API/SetMapDetails

The beginning of the JSON should look like this:



  {
    "email": "your@email.com",
    "APIToken": "yourapitoken",
    "mapID": 5859,
    "commands": [
              ]
  }



Your WarLight account's e-mail address and API token are always required, as is the map ID you're modifying.  You may get your API token using the [[Get API Token API]].  You may only enter the ID of a map you own, and the map must be in development mode (the same restrictions apply to editing the map with the UI.)

Note that after updating a map with the API, your browser may need to be refreshed to see the changes reflected in the UI.

==Commands==

You can specify commands within the commands node shown above.  You may specify as many copies of each command as you need, and you do not need to specify every command.  

===Set Territory Name===

  { command: 'setTerritoryName', id: 12, name: 'Kamchatka' },
  { command: 'setTerritoryName', id: 34, name: 'Ukraine' }

This sets the name of a territory, similar to typing in its name in the left side after clicking on it.  Specify the territory id (from the Territory_ format of your SVG file) and the name you wish to set it to.

===Set Territory Center Point===
	
  { command: 'setTerritoryCenterPoint', id: 12, x: '43.34', y: '98.12' }
	
Specify the territory id and the coordinates of the center point.  Coordinates are measured from the top-left corner of the SVG file. 

===Specify Connections===

  { command: 'addTerritoryConnection', id1: 12, id2:34, wrap: "Normal" },
  { command: 'addTerritoryConnection', id1: 56, id2:78, wrap: "WrapHorizontally" }

Specify the two territory IDs as id1 and id2 attributes.  It does not matter which territory is 1 and which is 2, since all connections in WarLight are two-way. 

As the wrap attribute, specify either Normal, WrapHorizontally, or WrapVertically to tell WarLight whether or not the connections wrap around the edge of the map.

Connections cannot be removed via the API, only added.  If you accidentally add a mistaken connection, it can be removed through the UI or you can delete the map and start over.

===Add Bonus===	

  { command: 'addBonus',  name: "South America",  armies: 4, color: "#DD0000" }

Adding a [[bonus]] is similar to clicking the "Add new Bonus" button.  The new bonus will initially have no territories assigned, but you can use addTerritoryToBonus below to add territories.

The armies attribute specifies how many armies per turn the bonus is worth, and the color attribute supports six hex characters is in the format #RRGGBB.  The hash sign must be included and all six characters must be specified.

===Add Territory to Bonus===

  { command: 'addTerritoryToBonus', id:12, bonusName: "South America" }

This is equivalent to selecting the territory and checking the bonus name check-box.  The bonus must have already been created, either via addBonus above or via the UI.  Attributes specify the territory ID and the bonus name. The bonus name is case-sensitive, so be sure it's entered perfectly.

===Add Distribution Mode===

  { command: 'addDistributionMode', name: "Warlords" },
  { command: 'addDistributionMode', name: "Top vs Bottom", scenarios: ['Top', 'Bottom'] }

Just like making a bonus, this creates an empty distribution mode just as if you clicked "Add new Distribution" in the UI.  

There are two types: [[Normal Distribution|Normal]] and [[Scenario distributions]].  To create a normal distribution, just specify a name, as is shown in the first example above.

The second example shows how to create a scenario distribution.  When creating a scenario distribution, also specify the name of each scenario.  There must be at least two scenarios defined, although there can be more.

===Add Territory to a Distribution Mode===

  { command: 'addTerritoryToDistribution', id:12, distributionName: "Warlords" },
  { command: 'addTerritoryToDistribution', id:12, distributionName: "Top vs Bottom", scenario:"Top" }

To add a territory to a normal distribution, as is shown in the first example, just specify the territory id and distribution name.  The distribution name is case-sensitive, so be sure it's entered perfectly.


To add a territory to a scenario distribution, as is shown in the second example, specify the territory id, distribution name, and scenario name. 
	
[[Category:API]]