Under Heavy Construction

I've tried to get a good start on an API to let other addons add, edit, delete and otherwise access all kinds of functionality relating to custom map pins all from one source. It's still under development, if you have any suggestions on improving it or adding to it or your looking for something specific please let me know and I can see if it can be accomodated, and I hope you find it useful as another tool to develop great warhammer addons

Design Philosophy

A few basic concepts that guided the design of MapMonster and the API.

First, the player should be able to add, edit or delete any map pin at any time, which means even if your addon created the map pin for the player it is still completely under their control and they can do whatever they want with it whenever they want.

Second, regardless of what happens to any other addon that uses map pins though the MapMonster API, the pin data and the game map should not be compromised, missing or malfunction in any way.

Third, the pin data must be at least minimally protected from accidental corruption by other addons that could break MapMonster and cause the loss of the pin data for all addons that use the MapMonster API.

Data Structures

Map Pins

Each map pin is a standard LUA table containing the following keys:

 id        = 0,
 pinType   = "",
 subType   = "",
 label     = L"",
 note      = {L""},
 isLocked  = false,
 isPrivate = false,
 zoneId    = 0,
 worldX    = 0,
 worldY    = 0,
 zoneX     = 0,
 zoneY     = 0,
 Data      = 0,
 modified  = "",

id This is a unique numerical identifier for each pin, this is set automatically and not changeable

pinType This is the pin type this pin belongs to

subType This is the pin sub type this pin belongs to

label This is a wstring label for the pin, used as the first line of the tooltip and editor, also in comparison operation when looking for similar pin

note This is a table of wstrings for any extra details to show in the editor and tooltip

isLocked Boolean flag to lock the pin and prevent any further editing, including pin merging

isPrivate Boolean flag to signal if this pin should be shared with other or not

zoneId,worldX,worldY,zoneX,zoneY These field describe the position in the world

Data This key is to hold any data your addon needs to store with the map pin itself, best used like a database foreign key but can be anything, only keep what you have to with the pin

modified Datestamp using LibDateTime of the time this pin was created or updated

Pin Type

Each pin type contains the following keys

 id = ""
 label = L"",
 defaultSubType = "",
 radius = 1500,
 isLocked = false,
 isPrivate = false,
 mapIcon = { 
     texture = "EA_HUD_01",
     scale = 0.65,
     slice = "RvR-Flag",
     tintColor = { r = 0,
                   g = 0,
                   b = 0, }
     },
 mouseClickCallback = "",
 editCallback = "",
 deleteCallback = "",
 mergeHandler = "",
 subTypes = {}

id A string id identifying this pin type

label A wstring label for this pin type, used in the various menus including the filters

defaultSubType The default sub type used when creating a pin is no subtype is specified

radius When saving pins of this type they must be within this radius of the existing pin to be eligible to merge

isLocked When creating pins of this type this is the default lock status of new pins

isPrivate When creating pins of this type this is the default privacy status of new pins

mapIcon This is a table with some optional keys in defining which icon to use when displaying pins of this type on the map

texture This is a string identifying the WH texture to use for the icon

scale Map pins are displayed in as a 28 x 28 icon on the map, use this scale value to fit the texture within that space

slice If the texture require a slice, such a icons from the Tome of Knowledge, the slice can be specified here

tintColor If the texture is tintable you can supply the r/g/b values as a table here, built in WH colors such as DefaultColor.RED can be used here

mouseClickCallbackThis is a string value naming the function in your addon you wish to call when someone clicks on a map pin of this type, the function is called with only one argument which is a copy of the pin the user clicked on

editCallback This is a string value of the function in your addon to call when a pin of this type is edited, again called with just one argument, a copy of the edited pin

deleteCallback This is a string value of the function in your addon to call when a pin of this type is deleted, called with just one argument, a copy of the pin deleted. Please note the pin has already been deleted and does not exist anymore, only a copy of the pin data was sent to your function

mergeHandler This is a string value of the function in your addon to call when two pins are being merged. It is up to your addon to handle merging the data you have stored in the pin, it expects you to return a table of data to store which will completely replace the data that was there previously, if you wish to block the merging and force the new pin to save seperately you can return false instead

subTypesThis is a table of all the sub types registered for this pin type

Sub Types

All sub types follow the same structure as a pin type with the exception that all keys, except id and label, are optional, and they don't contain subTypes or defaultSubTypes. If a sub type does not contain a given key the value from the pin type is used, sub types keys override the pin type keys of the same name

Position Table

All function expecting a position as a single argument expects a table containing one or more of the following keys:

zoneId = 0,
worldX = 0,
worldY = 0,
zoneX = 0,
zoneY = 0,

zoneId This is the id of the zone this position is describing

worldX, worldY Always expected together to describe a position in the world, these coordinates are taken from game events and more accurate then zone positions that must be calculated from user gathered data, world positions are always available when in-game even when the zone or instance has no map

zoneX, zoneY Always expected together to describe a position in the world, these are the coordinates you see on your zone map and must be calculated for a player based on world coordinates, zone coordinates are not available for all zone since several zones have no maps

Since a pin contains those expected position keys you can simply use an entire pin as a position and the functions will use what keys they find

API Functions

General Functions

MapMonsterAPI.CheckVersion(major, minor)

MapMonsterAPI.GetError()

Player Related Functions

MapMonsterAPI.GetPlayerPosition()

MapMonsterAPI.GetPlayerDirection()

Navigation Related Functions

MapMonsterAPI.GetDirection(fromPosition, toPosition) Changed in 0.3.6

MapMonsterAPI.GetDistance(fromPosition, toPosition) Changed in 0.3.6

Zone Related Functions

MapMonsterAPI.GetZoneData(zoneId)

MapMonsterAPI.WorldToZone(worldPos)

MapMonsterAPI.ZoneToWorld(zonePos)

MapMonsterAPI.ZoneToShortZone(zonePos)

MapMonsterAPI.ValidateWorldPos(dirtyPos)

MapMonsterAPI.ValidateZonePos(dirtyPos)

MapMonsterAPI.ValidatePosition(dirtyPos, posType)

Pin Type Related Functions

MapMonsterAPI.CreatePinType(newPinType, pinTypeOptions, makeDefault)

MapMonsterAPI.CreatePinSubType(pinType, newPinSubType, subTypeOptions)

MapMonsterAPI.PinTypeIsRegistered(checkPinType, checkPinSubType)

MapMonsterAPI.GetPinTypes()

MapMonsterAPI.DeletePinType(pinType, subType)

MapMonsterAPI.GetPinTypeOptions(pinType, subType)

MapMonsterAPI.GetPinTypeOption(pinType, subType, optionKey)

MapMonsterAPI.SetPinTypeOption( pinType, subType, optionKey, optionValue )

MapMonsterAPI.DeletePinTypeOption( pinType, subType, optionKey )

Map Pin Related Functions

MapMonsterAPI.CreatePin(pinType, subType, label, pinPos, note, addonData, merge)

MapMonsterAPI.CreatePinAtPlayer(pinType, subType, label, note, addonData, merge)

MapMonsterAPI.GetPin(pinId)

MapMonsterAPI.DeletePin(pinId)

MapMonsterAPI.GetPinProperty(pinId, propertyKey)

MapMonsterAPI.SetPinProperty(pinId, propertyKey, propertyValue, updateDatestamp) Changed in 0.3.2

MapMonsterAPI.LockPin(pinId)

MapMonsterAPI.UnlockPin(pinId)

MapMonsterAPI.GetPinsByType(pinType, subType) New in 0.3.2

MapMonsterAPI.GetPinsForZone(zoneId)

MapMonsterAPI.GetPinsForZoneBySubType(zoneId, pinType, subType, unlockedOnly)

MapMonsterAPI.HighlightMapPin(pinId) New in 0.3.2

Map Pin Editor Window Functions

MapMonsterAPI.OpenPinAddWindow(zonePos, pinType) New in 0.3.8

MapMonsterAPI.OpenPinEditorWindow(pinId) New in 0.3.8

MapMonsterAPI.OpenPinDisplayWindow(pinId) New in 0.3.8

Error Codes

Entirely new error codes and string in 0.3.2 MapMonster errors and Pin editor now using AceLocale. Translations for the table below gladly accepted for all languages.

Error Code Table

-- Missing Data

ERRMSG[101] = "** No zone mapping data found for this zone. For more information on contributing map data please visit the MapMonster page on curse.com"

ERRMSG[102] = "Too early for position info. World not finished loading"

ERRMSG[103] = "Zone data not found."

ERRMSG[104] = "Zone has no map"

ERRMSG[105] = "Pin not found"

ERRMSG[106] = "Icon data not found for subType"

-- Missing Arguments

ERRMSG[201] = "No position table supplied"

ERRMSG[202] = "Zone Id not found in position table"

ERRMSG[203] = "World coordinates not found in position table"

ERRMSG[204] = "Zone coordinates not found in position table"

ERRMSG[205] = "Incomplete mapIcon definition, texture and scale required"

ERRMSG[206] = "Missing pin data. Must supply two sets of pin data for merging"

ERRMSG[207] = "Pin type not found."

ERRMSG[208] = "Pin type and/or sub type not found"

ERRMSG[209] = "Missing pin type label"

ERRMSG[210] = "Missing pin id"

ERRMSG[211] = "Missing position data. Must supply world coordinate tables for two points for distance calculations"

-- Invalid Arguments

ERRMSG[301] = "Invalid pin property name"

ERRMSG[302] = "Invalid value type for pin property"

ERRMSG[303] = "Invalid pinType option name"

ERRMSG[304] = "Invalid value type for pin type option"

ERRMSG[305] = "Invalid value type. Map icon texture slice must be a string"

ERRMSG[306] = "Invalid tint definition. Map icon texture tint must be a table with r, g, and b keys"

ERRMSG[307] = "Invalid pin type name, must be string"

ERRMSG[308] = "Invalid pin type name, can only contain alphanumeric characters"

ERRMSG[309] = "Invalid pin sub type name, must be string"

ERRMSG[310] = "Invalid pin sub type name, can only contain alphanumeric characters"

ERRMSG[311] = "Invalid pin type or sub type option"

ERRMSG[312] = "Invalid validation type must be \"world\" or \"zone\""

ERRMSG[313] = "Invalid position table. World and zone coordinates do not describe the same location"

ERRMSG[314] = "Invalid position. Coordinates out of bounds for zone"

ERRMSG[315] = "Invalid version numbers"

-- Invalid operation

ERRMSG[401] = "Invalid delete operation. Can ONLY delete options from a pin sub type"

ERRMSG[402] = "Invalid delete operation. Cannot delete multiple options at the same time"

ERRMSG[403] = "Invalid delete operation. Pin is locked"

ERRMSG[404] = "Invalid edit operation. Pin is locked"

ERRMSG[405] = "Invalid direction operation. Cannot plot the direction between zones"

ERRMSG[406] = "Invalid editor mode - Should never see this error. Please report it."

-- Failed operation

ERRMSG[501] = "PinType already registered"

ERRMSG[502] = "PinSubType already registered"

-- General

ERRMSG[601] = "MapMonsterAPI Unavailable"

ERRMSG[602] = "MapMonster minor version out of date"

ERRMSG[603] = "MapMonster major version out of date"

Editor Window String Table

-- Editor Labels

T["Map Monster Pin Editor"] = L"Map Monster Pin Editor"

T["New Map Monster Pin"] = L"New Map Monster Pin"

T["Map Monster Pin Viewer"] = L"Map Monster Pin Viewer"

T["Name:"] = L"Name:"

T["Pin Type:"] = L"Pin Type:"

T["Sub Type:"] = L"Sub Type:"

T["Zone:"] = L"Zone:"

T["Position:"] = L"Position:"

T["X:"] = L"X:"

T["Y:"] = L"Y:"

T["Options:"] = L"Options:"

T["Notes:"] = L"Notes:"

T["Datestamp:"] = L"Datestamp:"

T["World:"] = L"World:"

T["Locked"] = L"Locked"

T["Private"] = L"Private"

T["Save"] = L"Save"

T["Reset"] = L"Reset"

T["Cancel"] = L"Cancel"

T["Close"] = L"Close"

-- Messages

T["SuccessAlert"] = L"MapMonster Pin Successfully Saved!"

T["FailedAlert"] = L"MapMonster Pin Update Failed!"

T["NotFoundAlert"] = L"MapMonster Pin Not Found!"

very not finished check back later