EG-Overlay Markerpack Format#

EG-Overlay’s marker module houses data in SQLite databases. This is a departure from the set of XML files that have become standard with other overlays, however the change is intentional.

Why SQLite?#

Some markerpack developers have created packs that are much larger than the original author of the XML pack format likely intended. This creates challenges, forcing overlays to either load an entire pack into memory, suffer undesirable performance when changing maps or refreshing marker data, or performing one time optimizations of the data.

Using SQLite databases fall into that last category, and while it isn’t as transparent to users as optimizing XML, it is the most straightforward way to achieve desirable performance while sticking to EG-Overlay’s core vision: being light weight and out of the way.

SQLite databases will take up more hard disk space than a zip compressed ‘TaCO’ pack, but they are still a single file and the additional disk usage is much less than the RAM usage it is being traded for.

SQLite Database Structure#

Each markerpack is stored in a single SQLite database. For simplicity, the files should still have the .db file extension, but there is nothing that enforces this.

The markers.package module implements the raw data access to the database.

Tables#

markerpack#

The main table of a markerpack. This contains general information about the markerpack and is also used to validate that this database is a markerpack when it is loaded.

Columns

Name

Type

Description

version

INTEGER

The markerpack database version. Currently, the only valid value is 1.

Version History

Version

Notes

0.1.0

Added

categories#

Categories are a grouping of markers, trails, and other categories.

Each category has a typeid. This is the Name attribute from the TaCO XML format.

The typeid of a category is hierarchical and will contain the full ‘path’ of the category. This means that if a top level category with a typeid of ‘foo’ contains a category ‘bar’, the second category’s typeid will be 'foo.bar'.

Columns

Name

Type

Description

typeid

TEXT

Primary Key. The typeid of the category.

parent

TEXT

Foreign Key. The typeid of this category’s parent. NULL if this category has no parent.

active

BOOL

TRUE if this category is active, meaning it should be displayed.

seq

INTEGER

A number indicating what order categories should be shown in a UI.

Version History

Version

Notes

0.1.0

Added

categoryprops#

Category properties may affect the behavior of the category, all ancestors (children, etc.) and any contained markers and trails.

See Properties.

Columns

Name

Type

Description

id

INTEGER

Primary Key. Internal ID.

category

TEXT

Foreign Key. The category typeid.

proprety

TEXT

The property name, ie. behavior or alpha.

value

ANY

The property value. This can be any type.

Version History

Version

Notes

0.1.0

Added

markers#

A marker is a location to be displayed within the GW2 scene.

Columns

Name

Type

Description

id

INTEGER

Primary Key. Internal ID.

type

TEXT

Foreign Key. The categories.typeid this marker belongs to.

mapid

INTEGER

The MapID this marker is displayed on.

Version History

Version

Notes

0.1.0

Added

markerprops#

Marker properties. Marker properties affect how a marker is shown and other behavior. If a marker does not define a property, the value defined on the categories it belongs to or any parents will take effect instead.

See Properties.

Columns

Name

Type

Description

id

INTEGER

Primary Key. Internal ID.

marker

INTEGER

Foreign Key. markers.id.

property

TEXT

The property name.

value

ANY

The property value.

Version History

Version

Notes

0.1.0

Added

trails#

Trails are linear markers showing a route between multiple points.

Columns

Name

Type

Description

id

INTEGER

Primary Key. Internal ID.

type

TEXT

Foreign Key. The categories.typeid this trail belongs to.

mapid

INTEGER

The MapID this marker is displayed on.

Version History

Version

Notes

0.1.0

Added

trailprops#

Trail properties. Trail properties affect how a marker is shown and other behavior. If a trail does not define a property, the value defined on the categories it belongs to or any parents will take effect instead.

See Properties.

Columns

Name

Type

Description

id

INTEGER

Primary Key. Internal ID.

trail

INTEGER

Foreign Key. trails.id.

property

TEXT

The property name.

value

ANY

The property value.

Version History

Version

Notes

0.1.0

Added

trailcoords#

Trail points.

Columns

Name

Type

Description

id

INTEGER

Primary Key. Internal ID.

seq

INTEGER

The sequence or order this point occurs at in the trail.

trail

INTEGER

Foreign Key. trails.id.

x

REAL

X map coordinate, in meters.

Y

REAL

Y map coordinate, in meters.

Z

REAL

Z map coordinate, in meters.

Note

Even though GW2 uses inches for map coordinates, markers data is still stored in meters, which is what the MumbleLink info reports. This also keeps the coordinates consistent with other marker formats.

Version History

Version

Notes

0.1.0

Added

datafiles#

Data files are binary data that accompanies a markerpack. This is generally image files used as textures for markers or trails, but could be any binary data.

Columns

Name

Type

Description

path

TEXT

Primary Key. A relative path identifying the ‘file.’

data

BLOB

The binary Data

Version History

Version

Notes

0.1.0

Added

Properties#

categories, markers, and trails can all have arbitrary properties assigned to them. The properties documented below are recognized by the markers module. Other properties can be stored for use by marker authors or other EG-Overlay modules.

Important

Property names are stored in lower case and the markers.package operates on properties in a case insensitive manner. In other words, a property named name is considered the same as Name or NAME.

categoryname#

The name displayed within the UI for a category. This name may also be displayed on tooltips for markers.

type:

string

Version History

Version

Notes

0.1.0

Added

isseparator#

If this value is present and 1, the category will be treated as a separator or header and used for display only. This means users will not be able to interact with it and any markers or trails assigned to it will be ignored.

type:

integer

Version History

Version

Notes

0.1.0

Added

color#

The color tinting of the marker or trail.

type:

string

default:

#FFFFFF

The color value is expected to be a string containing a 24bit integer RGB color in hexadecimal format preceded by a #. This is the format commonly used in CSS. Example: #FF0000 for red.

Version History

Version

Notes

0.1.0

Added

alpha#

The transparency of a marker or trail. From 0.0 to 1.0

type:

float

default:

1.0

Note

This is the minimum transparency a marker or trail will be displayed. Markers and trails may be displayed more transparent based on other settings.

Version History

Version

Notes

0.1.0

Added

xpos#

X map position, in meters.

type:

float

default:

0.0

Version History

Version

Notes

0.1.0

Added

ypos#

Y map position, in meters.

type:

float

default:

0.0

Version History

Version

Notes

0.1.0

Added

zpos#

Z map position, in meters.

type:

float

default:

0.0

Version History

Version

Notes

0.1.0

Added

heightoffset#

The distance above or below the given ypos that the marker will be shown, in meters. This is used to offset the marker so that it does not cover the item it is marking.

type:

float

default:

1.5

Version History

Version

Notes

0.1.0

Added

iconsize#

A ratio controlling how large the marker icon is drawn. By default, each marker is displayed 80 inches wide (in map units). An iconsize of 2 causes the marker to be drawn 160 inches wide.

type:

float

default:

1.0

Version History

Version

Notes

0.1.0

Added

iconfile#

The path identifying the datafile that contains the icon that will be displayed for the marker.

type:

string

Version History

Version

Notes

0.1.0

Added

texture#

The path identifying the datafile that contains the texture that will be used to display the trail.

type:

string

Version History

Version

Notes

0.1.0

Added

fadenear#

The distance from the player where a marker or trail will begin to fade to transparent. This value is ignored, and the marker/trail will never fade if it is below 0.

type:

float

default:

-1.0

Version History

Version

Notes

0.1.0

Added

fadefar#

The distance from the player where a marker/trail will become completely transparent. If fadenear is -1.0 or if this value is less than fadenear it will be ignored and markers/trails will never fade.

type:

float

default:

-1.0

Version History

Version

Notes

0.1.0

Added

minimapvisibility / mapvisibility#

minimapvisibility and mapvisibility control if a marker/trail is displayed on the (mini)map.

Important

If either value is 1 the marker/trail is displayed on both the minimap and map. EG-Overlay does not distinguish between the two.

type:

integer

default:

1

Version History

Version

Notes

0.1.0

Added

ingamevisibility#

This value controls if a marker/trail is visible within the 3d game scene.

type:

integer

default:

1

Version History

Version

Notes

0.1.0

Added

mapdisplaysize#

The size a marker should be displayed on the (mini)map, in continent units. Because this is in continent units, it will be scaled with the map as the player zooms in/out.

type:

float

default:

20

Version History

Version

Notes

0.1.0

Added

trailscale#

A ratio controlling how wide a trail is displayed. A value of 1.0 results in trails drawn 40 inches wide (map units), while 2.0 would result in a trail 80 inches wide.

type:

float

default:

1.0

Version History

Version

Notes

0.1.0

Added

iswall#

Controls how the trail is rendered. Normally trails are drawn so that the texture is facing up/down. If this value is 1 the trail will be drawn vertically instead.

type:

integer

Version History

Version

Notes

0.1.0

Added