HereBeDragons-2.0 is a Map Math library, allowing you to compute and transform coordinates, distances and angles between any related points in the game and on the map.

Coordinate Systems

HereBeDragons supports two basic coordinate systems, local zone coordinates, and world coordinates.

Zone Coordinates are the typical 0 to 1 coordinates usually used by players to express their position in game (typically multiplied by 100, ie. 0-100), which represents the position on the zones in-game map, 0/0 representing the upper left corner.

World Coordinates are absolute coordinates within the current continent or instance. They are not tied to a zone, but to the entire continent/instance. These types of coordinates are well suited for distance calculation and generally any addon use - they are however not very "human friendly".

HereBeDragons internally primary deals with World Coordinates, but offers various utility functions to convert between both coordinate systems as required.

Special handling is required when dealing with the Azeroth World Map (ie. the overview map of all continents on Azeroth), since there is no one instance/continent that represents it fully. See api/Azeroth World Map for details. 

Map/Zone Identifiers

HereBeDragons-2.0 identifies maps/zones using the new "UI Map ID" introduced in WoW 8.0. Every single map has its own ID, as well as every floor in dungeons/raids, and every micro dungeon.

API

Map Info

The Map Info API functions return information about a map without requiring to use the stateful in-game API

HBD:GetLocalizedMap(uiMapID)

Get the localized name of the map

 

HBD:GetZoneSize(uiMapID)

Get the physical size of a zone, in yards

Return Values

width

Zone Width in Yards

height

Zone Height in Yards

HBD:GetAllMapIDs()

Get a table with all known UI Map IDs

Coordinate Transformation

These API functions are used to transform coordinates between different coordinate systems, or between zones

HBD:GetWorldCoordinatesFromZone(x, y, zone)

Get the World Coordinates to the specified zone coordinates

Parameters

x

X coordinates in the zone coordinate system (0-1)

y

Y coordinates in the zone coordinate system (0-1)

zone

UiMapID of the zone

Return Values

x

X coordinate in the World Coordinate system

y

Y coordinate in the World Coordinate system

instance

Instance ID of the World Coordinate system

HBD:GetWorldCoordinatesFromAzerothWorldMap(x, y, instance)

Get the World Coordinates to the specified Azeroth world map coordinates

Parameters

x

X coordinates in the zone coordinate system (0-1)

y

Y coordinates in the zone coordinate system (0-1)

instance

InstanceID of the continent these coordinates belong to

Return Values

x

X coordinate in the World Coordinate system

y

Y coordinate in the World Coordinate system

instance

Instance ID of the World Coordinate system

HBD:GetZoneCoordinatesFromWorld(x, y, zone, allowOutOfBounds)

Get the Zone Coordinates to the specified World Coordinates, within the specified zone.
Note: It is the callers responsibility to ensure the x/y coordinates are in the same instance/continent as the zone.

Parameters

x

X coordinates in the World Coordinate system

y

Y coordinates in the World Coordinate system

zone

UiMapID of the zone of the destination zone coordinate system

allowOutOfBounds

If true, do not clip the coordinates into the 0-1 range if the point is outside of the current map.

Return Values

x

X coordinate in the Zone Coordinate system

y

Y coordinate in the Zone Coordinate system

HBD:GetAzerothWorldMapCoordinatesFromWorld(x, y, instance, allowOutOfBounds)

Get the Azeroth World Map Coordinates to the specified World Coordinates, within the specified continent instance.

Parameters

x

X coordinates in the World Coordinate system

y

Y coordinates in the World Coordinate system

instance

InstanceID of the continent these coordinates belong to

allowOutOfBounds

If true, do not clip the coordinates into the 0-1 range if the point is outside of the current map.

Return Values

x

X coordinate in the Zone Coordinate system

y

Y coordinate in the Zone Coordinate system

HBD:TranslateZoneCoordinates(x, y, oZone, dZone, allowOutOfBounds)

Translate the coordinates between two Zone Coordinate systems

Parameters

x

X coordinate in the origin zone

y

Y coordinate in the origin zone

oZone

UiMapID of the origin zone

dZone

UiMapID of the destination zone

allowOutOfBounds

If true, do not clip the coordinates into the 0-1 range if the point is outside of the destination map.

Return Values

x

X coordinate in the destination Zone Coordinate system

y

Y coordinate in the destination Zone Coordinate system

HBD:GetWorldDistance(instanceID, oX, oY, dX, dY)

Calculate the distance between two points in the same World Coordinate system (ie. the same instance)

Parameters

instanceID

Instance ID of the World Coordinate system (currently unused)

oX

X coordinate of the origin point

oY

Y coordinate of the origin point

dX

X coordinate of the destination point

dY

Y coordinate of the destination point

Return values

distance

Distance in yards

deltaX

Delta of the X coordinate in yards

deltaY

Delta of the Y coordinate in yards

HBD:GetZoneDistance(oZone, oX, oY, dZone, dX, dY)

Calculate the distance between two points in different zones.
Note: Both zones need to be on the same continent for this function to return valid values.

Parameters

oZone

UiMapID of the origin zone

oX

X coordinate of the origin point

oY

Y coordinate of the origin point

oZone

UiMapID of the destination zone

dX

X coordinate of the destination point

dY

Y coordinate of the destination point

Return values

distance

Distance in yards

deltaX

Delta of the X coordinate in yards

deltaY

Delta of the Y coordinate in yards

HBD:GetWorldVector(instanceID, oX, oY, dX, dY)

Calculate a vector between the two points in the World Coordinate system

Parameters

instanceID

Instance ID of the World Coordinate system (currently unused)

oX

X coordinate of the origin point

oY

Y coordinate of the origin point

dX

X coordinate of the destination point

dY

Y coordinate of the destination point

Return values

angle

The angle between the two points, in radians

distance

The distance in yards

Unit Position

HBD:GetUnitWorldPosition(unitID)

Get the world position of any unit eligible for UnitPosition (player, party, raid only)

Return values

x

X coordinate of the units position

y

Y coordinate of the units position

instance

instance ID of the World Coordinate system the unit is in

HBD:GetPlayerWorldPosition()

Retrieve the world position of the player.
Same as calling HBD:GetUnitWorldPosition("player")

HBD:GetPlayerZone()

Retrieve the zone information the player is currently in.

This functions is independent of the world map and does not rely on the world map to retrieve the players current position.

Return values

currentPlayerUiMapID

The UiMapID of the zone

currentPlayerUiMapType

Type of the current map

HBD:GetPlayerZonePosition()

Retrieve the zone information the player is currently in.

This functions is independent of the world map and does not rely on the world map to retrieve the players current position.

Return values

x

X zone coordinate of the player

y

Y zone coordinate of the player

currentPlayerUiMapID

The UiMapID of the zone

currentPlayerUiMapType

Type of the current map

Callbacks

HereBeDragons exports callbacks using the CallbackHandler library. You can register for any callback using a call like this: HBD.RegisterCallback("MyAddon", "PlayerZoneChanged", function() .. end)

PlayerZoneChanged(currentPlayerUiMapID, currentPlayerUiMapType)

Fires when the active zone map changes, passes the same arguments as calling HBD:GetPlayerZone() would return