Source

1. Markup: *
   =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: <pre> 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 = "", </pre> :'''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 <pre> 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 = {} </pre> :'''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 :'''mouseClickCallback'''This 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 :'''subTypes'''This 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: <pre> zoneId = 0, worldX = 0, worldY = 0, zoneX = 0, zoneY = 0, </pre> :'''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 ==
2. Markup Type: *

   The type of markup for this entry. Click here for details.

   WikiCreoleBBCodeSafe HTMLPlain TextMarkdownTextileCurse Wiki (Deprecated)