Astrolabe

Astrolabe is an embeddable library for placing icons on the Minimap, and on World Maps. Icons that are placed on the Minimap using Astrolabe are placed in a special buffer and their positions are continuously updated for player movement, based on the world map coordinates provided when the icon was initially placed. Icons remain in this buffer until they are removed.

General Notes

• a coordinate data point consists of 4 numbers: continent, zone and xPos and yPos (with TOPLEFT being the 0,0 point and BOTTOMRIGHT being the 1,1 point)
• continent 0 is the world of Azeroth, 1 is Kalimdor, 2 is Eastern Continent, 3 is Outland, 4 is Northrend, 5 is The Maelstrom, 6 is Pandaria
• a zone of 0 or nil indicates that you want the continent itself (this value is generally, but not guaranteed to be, ignored when continent == 0)
• a floor of 0 or nil indicates are equivalent in specifying that you want no floor, or the zone itself if the zone has Micro-Dungeon maps

Minimap Icon Positioning System

Astrolabe includes a system that AddOns can utilize to place icons on the Minimap frame, using World Map Coordinates, without having to worry about the details of translating the world map position information into the Minimap's frame of reference, or having to deal with the details of constantly updating the position of such icons as the player moves around in the game world.

Adding/Updating Icons

To get Astrolabe to start managing an icon, use the PlaceIconOnMinimap API function. You can pass this function any anchorable UI widget, and a valid World Map Point. This function adds the icon to the position management buffer. Icons in the management buffer are automatically anchored to the Minimap, and this anchor is updated regularly as the player moves through the game world. If the position specified when the icon was added to the buffer is off the edge of the Minimap, then the icon will be anchored along the edge of the Minimap.

To update the position that an icon is placed at, simply call PlaceIconOnMinimap again with the icon and a new position.

Removing Icons

To remove an icon from the position management buffer, just call RemoveIconFromMinimap with the icon that you wish to remove.

To clear all icons from the buffer, call RemoveAllMinimapIcons. CAUTION: this removes all icons managed by Astrolabe, not just yours.

Icons can also be automatically removed from the buffer for any of the following reasons:

• PLAYER_LEAVING_WORLD fires
• the location of the player changes such that there is no longer any meaningful way to relate the icon's specified position to the player's current position

Technical Details

Astrolabe manages the position of icons in its buffer by way of using pre-calculated data, and a series of calculations to translate world map coordinates into distances relative to the player's current position. Internally Astrolabe works in game yards. Minimap icon positions are updated every frame, but the number of icons actually updated each frame is varied depending on the client's current frame rate. The number of icons updated each frame is determined by the current frame rate multiplied by the MinimapUpdateMultiplier variable. For the regular, incremental update cycle, there is a hard cap on the number of icons updated each frame of 50. For the full recalculation update, the final number is also multiplied by 2.

Most updates will consist of a call to UpdateMinimapIconPositions, which performs only an incremental update on icons which are currently in the positioning buffer. The other update function, CalculateMinimapIconPositions, is called when certain events occur, and performs a complete re-calculation of all icon positions from their provided world map position. These events include the re-activation of the update cycle, PLAYER_ENTERING_WORLD or MINIMAP_UPDATE_ZOOM firing, and an upgrade of the library.

The update cycle itself is tied to the Visible state of a frame that is parented to the Minimap frame of the default UI. This means that whenever the Minimap is not visible then the Astrolabe update cycle is not running. The update cycle is restarted whenever this frame's OnShow handler fires. The update frame is hidden whenever there is no valid player position available.

World Map Monitor

Astrolabe has a system that monitors the visible status of known World Map frames, and avoids actively calling WoW client API functions that fire WORLD_MAP_UPDATE while any such frames are visible. This system utilizes a global table called "WorldMapDisplayFrames" to keep allow AddOns that create new world map frames to easily allow this system to learn about them. The WorldMapFrame in the default UI is, of course, monitored by this system by default.

Providing Compatibility

AddOns that create a new frame that is sensitive to the WORLD_MAP_UPDATE event, in such a way that its firing is disruptive to the AddOn's normal operation, can add this frame to the global table WorldMapDisplayFrames using table.insert(). This will cause Astrolabe to avoid causing WORLD_MAP_UPDATE to fire when it is attempting to update the positions of icons it is managing. This means that if the current map zoom does not show a valid position for the player, the update cycle will be halted until all monitored frames are hidden.

Public API

Astrolabe » API

General Utility Functions

ComputeDistance( m1, f1, x1, y1, m2, f2, x2, y2 ) - takes two sets of coordinates and computes the distances between them in game yards

GetCurrentPlayerPosition() - returns the player's current position on the world map

GetUnitPosition( unit, noMapChange ) - returns a world map position for the specified unit

GetMapID( continent, zone ) - returns the map ID that corresponds to the specified Zone Index

GetMapInfo( mapID, floor ) - returns information about a given map

GetNumFloors( mapID, floor ) - returns the number of floors a map has

TranslateWorldMapPosition( M, F, xPos, yPos, nM, nF ) - calculates world map coordinates for another zone

Minimap Icon Placement

GetDirectionToIcon( icon ) - returns the direction from the player to the icon

GetDistanceToIcon( icon ) - returns the distance to the icon as computed at the last buffer update

IsIconOnEdge( icon ) - returns true if the icon is currently placed along the edge of the Minimap

PlaceIconOnMinimap( icon, map ID, floor, xPos, yPos ) - places an icon on the Minimap and adds it to the positioning buffer

Register_OnEdgeChanged_Callback( func, ident ) - registers a function to be called whenever the set of icons placed along the edge of the Minimap changes

RemoveIconFromMinimap( icon ) - hides the icon and removes it from the positioning buffer

RemoveAllMinimapIcons() - hides and removes all icons from the positioning buffer

Debug Methods

These methods should generally not be used during the normal functioning of an AddOn. They are publically available for various reasons, including being useful for debugging purposes.

CalculateMinimapIconPositions( reset ) - performs a complete update of all icons in the positioning buffer

RemoveAllMinimapIcons() - hides and removes all icons from the positioning buffer

UpdateMinimapIconPositions() - performs an incremental update of all icons in the positioning buffer

World Map Icon Placement

PlaceIconOnWorldMap( worldMapFrame, icon, continent, zone, xPos, yPos ) - places an icon on the specified world map frame

Events

Astrolabe currently monitors the following client generated events and takes the specified actions for each one.

MINIMAP_UPDATE_ZOOM

• calls Astrolabe:CalculateMinimapIconPositions() if the positioning system is currently active

PLAYER_LEAVING_WORLD

• removes ALL icons from the positioning buffer
• disables updates of the Minimap Icon Positioning System until the next PLAYER_ENTERING_WORLD event

PLAYER_ENTERING_WORLD

• starts the Minimap Icon Positioning System update cycle
• if the update system is currently active then Astrolabe:CalculateMinimapIconPositions() is called

ZONE_CHANGED_NEW_AREA

• starts the Minimap Icon Positioning System update cycle

Handler Scripts

OnEvent( frame, event ) -

OnUpdate( frame, elapsed ) -

OnShow( frame ) -

AllWorldMapsHidden() -

Uses of Astrolabe

The following is a list of AddOns that use Astrolabe.

• Gatherer
• Town Guard
• TomTom
• Nauticus
• SimpleCoords
• QuestHelper
• Recipe Radar
• Intel
• ZoneDefense
• HandyNotes
• WIM
• DropCount
• Archy - Archaeology Assistant
• FlightHUD

Source Code

Astrolabe's source code repository can be found here: http://svn.esamynn.org/astrolabe/

The trunk/ is generally stable, and fit for regular use. Development that may destabilize stuff is generally done in a branch.

I generally DO NOT recommend using Subversion externals to include Astrolabe's code in your own project. However, if you insist on doing so, please be sure to specify a specific revision in your externals property.