Have you ever tried to save or send a position on the map with your addon? You might have noticed that this is not as easy as it sounds.
This library efficiently converts a position on any map into a global position that you can save or share. This is made possible by measuring maps once when they are encountered for the first time during a play session and only doing simple calculations afterwards.
Dependencies
Make sure to install the following required libraries in order to use LibGPS.
Quick Start
Add the necessary statements in your addon manifest to load the files:
Code:
## DependsOn: LibGPS>=30
NOTE: The >=30 tells the game to require AddOnVersion 30 or greater, which happens to be the first version with the 3.0 API and has nothing to do with the semantic version. It is simply a build number provided by the build script used to package the library.
In order to use the library you have to get an instance from the global variable:
Code:
local gps = LibGPS3
Next you can convert a position on the currently active map into a global position on the Tamriel map by calling LocalToGlobal.
For example you can convert the local player position into a global position with the following line of code:
Code:
local x, y = gps:LocalToGlobal(GetMapPlayerPosition("player"))
The resulting x and y can be saved, sent or whatever else you want to do with it.
NOTE: For some locations the global coordinates can be outside the bounds for normalized coordinates, for example Coldharbour has negative x coordinates as it is to the left of Tamriel in the global coordinate space.
After you have loaded or received a global position you just need to call GlobalToLocal to get the position on the current map.
Code:
local x, y = gps:GlobalToLocal(x, y)
Migrating from LibGPS2
LibGPS3 offers full backwards compatibility to LibGPS2 (see compatibility.lua), but it's still highly recommended to migrate to the new API.
In order to use the new API, simply access the library via the "LibGPS3" global variable instead of "LibGPS2" or LibStub.
Most functions stayed the same between v2 and v3, but there are a few breaking changes. The following list shows how to migrate those cases.
Renamed functions
Some function names have been changed to better reflect the return value.
- ClearCurrentMapMeasurements -> ClearCurrentMapMeasurement
- GetCurrentMapMeasurements -> GetCurrentMapMeasurement
- CalculateMapMeasurements -> CalculateMapMeasurement
Measurement object
GetCurrentMapMeasurement now returns an object with some convenience methods instead of a plain table. See the description below in the API reference for details on what it can do.
LocalToGlobal
The mapIndex return value has been removed as our understanding of what a map is has changed and it was deemed unnecessary for most use cases.
If you still need it, you can use GetCurrentMapMeasurement() to fetch the measurement object and retrieve it from there.
ZoneToGlobal
This method was used a long time ago to offer a way to migrate LibGPS1 coordinates. Since then it has become effectivly unnecessary and only causes confusion. As such it has been removed without replacement.
PanToMapPosition
This has become easily possible via ingame functionality since the time it was initially added to the library. Simply use "ZO_WorldMap_GetPanAndZoom():PanToNormalizedPosition(x, y)" instead.
OnLibGPS2MeasurementChanged callback
There is now a constant LIB_EVENT_STATE_CHANGED for the callback name, which should be used instead of the plain string.
API Reference
Here is a complete list of the functionality that is provided by LibGPS:
IsReady
Returns true as long as the player exists.
IsMeasuring
Returns true if the library is currently doing any measurements.
ClearMapMeasurements
Removes all cached measurement values.
Code:
lib:ClearMapMeasurements()
ClearCurrentMapMeasurement
Removes the cached measurement for the map that is currently active.
Code:
lib:ClearCurrentMapMeasurement()
GetCurrentMapMeasurement
Returns a measurement object for the active map or nil if the measurement could not be calculated for some reason.
See the description of the Measurement object for details.
Code:
Measurement measurement = lib:GetCurrentMapMeasurement()
GetMapMeasurementByMapId
Returns a measurement object for the requested map id or nil if the measurement could not be calculated for some reason.
See the description of the Measurement object for details.
Code:
Measurement measurement = lib:GetMapMeasurementByMapId(mapId)
GetCurrentMapParentZoneIndices
Returns the mapIndex, zoneIndex and zoneId of the parent zone for the currently set map.
Code:
number mapIndex, number zoneIndex, number zoneId = lib:GetCurrentMapParentZoneIndices()
CalculateMapMeasurement
Calculates the measurement for the current map and all parent maps.
This method does nothing if there is already a cached measurement for the active map.
Returns a boolean to indicate if the measurement was successful and a SetMapResultCode indicating if the map has changed independently of the actual result of the measurement.
Code:
boolean isSuccess, SetMapResultCode result = lib:CalculateMapMeasurement()
LocalToGlobal
Converts the given map coordinates on the current map into coordinates on the Tamriel map.
Returns x and y on the world map or nil if the measurements of the active map are not available.
Code:
number x, number y = lib:LocalToGlobal(number x, number y)
GlobalToLocal
Converts the given global coordinates into a position on the active map.
Returns x and y on the current map or nil if the measurements of the active map are not available.
Code:
number x, number y = lib:GlobalToLocal(number x, number y)
SetPlayerChoseCurrentMap
This function sets the current map as player chosen so it won't snap back to the previous map.
Code:
lib:SetPlayerChoseCurrentMap()
SetMapToRootMap
Sets the best matching root map on the given global position: Tamriel, Cold Harbour or Clockwork City and what ever will come.
Returns SET_MAP_RESULT_FAILED, SET_MAP_RESULT_MAP_CHANGED depending on the result of the API calls.
Code:
SetMapResultCode result = lib:SetMapToRootMap(number globalX, number globalY)
MapZoomInMax
Repeatedly calls ProcessMapClick on the given global position starting on the root map (using the function above) until nothing more would happen.
Returns SET_MAP_RESULT_FAILED, SET_MAP_RESULT_MAP_CHANGED or SET_MAP_RESULT_CURRENT_MAP_UNCHANGED depending on the result of the API calls.
Code:
SetMapResultCode result = lib:MapZoomInMax(number globalX, number globalY)
PushCurrentMap
This function stores information about how to return to the current map on a stack.
Code:
lib:PushCurrentMap()
PopCurrentMap
Switches to the last map that was put on the stack.
Returns SET_MAP_RESULT_FAILED, SET_MAP_RESULT_MAP_CHANGED or SET_MAP_RESULT_CURRENT_MAP_UNCHANGED depending on the result of the API calls.
Code:
SetMapResultCode result = lib:PopCurrentMap()
GetCurrentWorldSize
Returns the current size of Tamriel in world-units.
Code:
number scale = lib:GetCurrentWorldSize()
GetLocalDistanceInMeters
Returns the distance in meters of given local coords.
Code:
number distance = lib:GetLocalDistanceInMeters(number lx1, number ly1, number lx2, number ly2)
GetGlobalDistanceInMeters
Returns the distance in meters of given global coords.
Code:
number distance = lib:GetGlobalDistanceInMeters(number gx1, number gy1, number gx2, number gy2)
GetWorldGlobalRatio
Returns how much greater the level is compared to its size on the map.
Code:
number ratio = lib:GetWorldGlobalRatio()
GetGlobalWorldRatio
Returns how much smaller global scaled values must be to fit the current level.
Code:
number ratio = lib:GetGlobalWorldRatio()
lib.LIB_EVENT_STATE_CHANGED
This callback is fired on the global CALLBACK_MANAGER when a map measurement begins or ends and passes the same value as lib:IsMeasuring().
If you have a custom handler for player waypoints in EVENT_MAP_PING you may want to ignore these events while a measurement is active.
Code:
CALLBACK_MANAGER:RegisterCallback(lib.LIB_EVENT_STATE_CHANGED, function(boolean isMeasuring) end)
Measurement
This object returned by GetCurrentMapMeasurement() contains all the data about a map measurement and offers some convenience functions to interact with them.
GetId
Returns a unique id for the measurement which is used to store it in the saved variables. Details are implementation specific and may change between versions.
Code:
local id = measurement:GetId()
GetMapIndex
Returns the mapIndex or nil if the measured map doesn't have one.
Code:
local mapIndex = measurement:GetMapIndex()
GetZoneId
Returns the zoneId for the measurement. Keep in mind that a map can have multiple zoneIds within its borders and a zoneId can also span multiple maps.
Code:
local zoneId = measurement:GetZoneId()
GetScale
Returns the scale in the global coordinate space for the current map.
Code:
local scaleX, scaleY = measurement:GetScale()
GetOffset
Returns the offset in the global coordinate space for the current map.
Code:
local offsetX, offsetY = measurement:GetOffset()
IsValid
Returns true if the measurement contains valid data.
Code:
local valid = measurement:IsValid()
ToGlobal
Converts and returns global coordinates for a given local coordinate pair. Used by LocalToGlobal.
Code:
local gx, gy = measurement:ToGlobal(x, y)
ToLocal
Converts and returns local coordinates for a given global coordinate pair. Used by GlobalToLocal.
Code:
local x, y = measurement:ToLocal(gx, gy)
GetCenter
Returns the center of the measured map as global coordinates.
Code:
local cx, cy = measurement:GetCenter()
Contains
Returns true if the given global coordinates are inside the measured map.
Code:
local inside = measurement:Contains(gx, gy)
04/02/16, 04:01 AM
