Go to Landmark Hooks
====================
So, your addon has grid features (or perhaps actors or traps) that you
would like to have listed in the landmarks list.  Well, first off, thanks
for helping to make this addon more useful. ;)  We provide the following
hooks that your addon can use to interact with our assembly of the list of
landmarks on the level:

Landmark:gridType
-----------------
  Invoked near the end of grid_landmark_type() in Go to Landmark's hooks
  file if it has so far been unable to determine a landmark type for a
  given grid.
  self is:	The 'class' superclass
  data{} fields:
    grid	The Grid object being examined.
    x, y	The x/y map coordinates of the grid on the map.
    type	Initially unset.  Your hook may set this field to a string
		tag representing the landmark type for this grid; supported
		values are described in the Landmark:categories hook below.

Landmark:listEntry
------------------
  Invoked near the end of landmark_entry() in Go to Landmark's hooks file
  to assemble the data for an entry in the landmarks list.
  self is:	The 'class' superclass
  data{} fields:
    entity	The Grid, Actor or Trap object for which an entry is being
		assembled.
    type	A string tag identifying the landmark type.  Supported
		values are described in the Landmark:categories hook below.
    x, y	The x/y map coordinates of the entity on the map.
    dist	Estimated distance from the player to the entity on the
		map.
    dir		A string describing the approximate direction from the
		player to the entity on the map.  May be nil if the
		direction cannot be estimated.
    name	The text to be displayed in the landmark list for this
		entry.  Your hook may modify this field in place to set a
		suitable entry text.
    lev		Optional landmark-type-specific "level" for the entity.
		For zone-change landmarks, for instance, this is the
		minimum level for the zone, if available; for level-change
		landmarks, it is -1 for up stairs and 1 for down stairs.
		Landmark types that have a level value will typically be
		sorted by level.  Your hook may modify this field in place
		to set a suitable level value.
    est_dist(s, with_dir)
		A convenience method for creating entry texts.  Returns the
		provided string argument 's' with the common suffix
		describing location and estimated distance, as seen in
		other landmark entries.  If the 'with_dir' argument is true
		and an approximate direction to the landmark can be
		estimated, it will also be included in the returned string.

Landmark:categories
-------------------
  Invoked near the beginning of show_landmark_list() in Go to Landmark's
  hooks file, before assembling a list of landmarks for the first time.
  Will only be invoked once.  Can be used to add new landmark categories.
  self is:	The 'class' superclass
  data{} fields:
    categories	The shared table of landmark categories.  The format is
		described below.  Your hook may add new values to this
		table.

  The category table's keys are string tags identifying landmark types, as
  used in the 'type' field of the Landmark:gridType and Landmark:listEntry
  hooks; the value for each tag is a table describing the category, with
  the following allowed fields:

    name	The text to use for the category header.  Required.
    by_dist	If present, landmarks in this category will be sorted by
		distance from the player.
    by_xy	If present, landmarks in this category will be sorted by 
		x coordinate, and by y coordinate for landmarks with the
		same x coordinate.
    before	An optional string tag identifying a landmark type.  If the
		specified landmark category is defined, this category will
		be sorted before the specified one; otherwise, this
		category will be sorted to the end.
    after	An optional string tag identifying a landmark type.  If the
		specified landmark category is defined, this category will
		be sorted after the specified one; otherwise, this category
		will be sorted to the end.

  The initial supported tags for landmark categories are:

    town	Towns/bases.
    zone	Zones.
    store	Stores.  Sorted by distance.
    lev_change	Level exits.  Sorted by distance.
    vault_door	Vault entrances.  Sorted by distance.
    glyph	Glyphs.  Sorted by x/y.
    portal	Portals.  Sorted by center x/y.
    mark	Remembered landmarks.  Sorted by distance.
    npcs	People.  Sorted by distance.
    misc	Miscellaneous.  Sorted by distance.

$Id: hooks.txt 5202 2025-05-07 19:57:42Z dsb $
