$Id: hooks.txt 4610 2023-06-25 15:33:57Z dsb $

T2 Module Hooks
===============
Hooks are a standard T-Engine mechanism by which addons can influence
engine or module behavior.  See <http://te4.org/wiki/Hooks> for more
information on using hooks and for a list of hooks implemented by the
T-Engine.

The T2 module defines the following hooks:


T2:load
-------
  Invoked by load.lua after loading all module data.
  self is:	Unspecified.
  data{} fields:
    None.

T2:runBegin
-----------
  Invoked at the start of the Game:run() method.  Not much will be set up
  at this point.
  self is:	Unspecified.
  data{} fields:
    None.

T2:runReady
-----------
  Invoked at the end of the Game:run() method.  Game state and the UI will
  be set up at this point.
  self is:	Unspecified.
  data{} fields:
    None.

Birther:newPlayer
-----------------
  Invoked by the Birther dialog after a new player has been created and
  before it is placed on the map in Bree.  NOTE:  Entity:resolve() has not
  yet been called on the player at this point.
  self is:	The Birther dialog from which the new player is being
		placed.
  data{} fields:
    player:	The player Entity that was just created.

Actor:actBase
-------------
  Invoked by Actor:actBase() for each actor once every normal-speed player
  turn.
  self is:	The Actor being processed.
  data{} fields:
    None.

Actor:move
----------
  Invoked by Actor:move() when the actor moves (or attempts to).
  self is:	The Actor that just moved (or attempted to).
  data{} fields:
    moved:	True if the actor actually moved, or attempted to.
    forced:	True if the actor was forced to move by something.
    x, y:	The actor's new location.
    ox, oy:	The actor's previous location.

Actor:levelup
-------------
  Invoked after Actor:levelup() when an actor levels up.
  self is:	The actor that just leveled up.
  data{} fields:
    actor:	The actor that just leveled up.
    newlev:	True if the actor is gaining a new level; false if the
		actor is regaining a lost level.

Actor:levelupPost
-----------------
  Invoked after Actor:levelupPost() when an actor levels up.  The primary
  difference between this hook and Actor:levelup is that if the actor
  levels up multiple levels from a single experience gain (typically a kill
  of a high-level monster by a low-level player), this hook will only be
  triggered once, after all level-ups have been processed.  In addition,
  this hook will only be triggered if the actor actually gained at least
  one new level.
  self is:	The actor that just leveled up.
  data{} fields:
    actor:	The actor that just leveled up.

GameOptions:tiles
-----------------
  Invoked by GameOptions:alterOption() when build a list of tilesets for
  the player to choose from.
  self is:	The GameOptions dialog.
  data{} fields:
    list:	The list of tilesets built so far; your hook may add its
		own entries here.  Tileset entries are of the form
		{ name='Your tileset name', value='tileset-name' }; the
		'value' field should match the subdirectory name
		data/gfx/<tileset-name> in which the tileset's tile images
		live.

Game:alterGameMenu
------------------
  Invoked from the standard <Esc> keybind while building the game menu.
  self is:	The current Game object.
  data{} fields:
    menu:	The list of game menu actions.  Your hook may modify this
		in place.  Entries should be of the form:
		  { 'Entry name', function() --[[do stuff]] end }
    unregister:	A callback function that will close the game menu dialog.
		Your entries' callback functions may call this function as
		needed.

Game:enterLevel
---------------
  Invoked near the end of Game:changeLevel(), after the new level has been
  created and the player has entered it but just before fates and level
  feelings are handled.
  self is:	Unspecified.
  data{} fields:
    zone:	The Zone the player is in or has entered.
    level:	The Level the player has just entered.
    lev:	The numerical depth of the level, not adjusted by
		Zone:level_adjust_level().
    old_zone:	The Zone the player just left, or nil if the player changed
		levels within the current zone.
    old_lev:	The numerical depth of the level the player just left, not
		adjusted by Zone:level_adjust_level().
    params:	The extra parameters passed to Game:changeLevel(), if any.

Game:levelFeeling
-----------------
  Invoked near the end of Game:changeLevel(), just after fates are checked
  and just before the level feeling is logged.  The intended use case is
  for the hook to print via game.log() some entry message for the level.
  self is:	Unspecified.
  data{} fields:
    zone:	The Zone the player is in or has entered.
    level:	The Level the player has just entered.
    lev:	The numerical depth of the level, not adjusted by
		Zone:level_adjust_level().

MapGenerator:T2DungeonLevel:firstRoom
-------------------------------------
  Invoked by T2DungeonLevel:layoutMap() just before rooms are created, to
  allow for the creation of a special first room [hence the name].
  self is:	The MapGenerator in progress.
  data{} fields:
    gen:	The MapGenerator in progress.
    gx, gy:	Room-grid coordinates for the room.  Your hook should call
		gen:roomAlloc() to convert these to map coordinates for the
		center of the room [and to, well, allocate a room].
    lev:	The 'lev' parameter passed to layoutMap().
    old_lev:	The 'old_lev' parameter passed to layoutMap().
    spots:	If your room defines spots, your hook should append them to
		this table for inclusion in the level map.
    done:	True if some other hook has already generated the first
		room.  Your hook should do nothing if this is true;
		otherwise, if your hook successfully creates a room, it
		should set this field to true.
    no_down:	Your hook may set this field to true to signal to the level
		generator that it should not place any down stairs on the
		level.  In this case, it is your hook's responsibility to
		ensure that its generated room contains a down stair as
		necessary.

MapGenerator:Static:subgenRegister
----------------------------------
  Invoked by Static:generate() to allow for submaps to overlaid on the map.
  self is:	The MapGenerator in progress.
  data{} fields:
    mapfile:	The filename of the map being loaded.
    list:	A list of submap specifications.  Your hook should append
		its submap specification(s) to the end of this list.

  A submap specification is a table with the following fields:
    x, y:	The location where the submap should be added.
    w, h:	The width and height of the submap to be added.
    overlay:	If true, the submap will be added to the map via
		Map:overlay() [q.v.]; if false, the submap will be added
		via Map:import() [q.v.].
    generator:	The class name of the map generator to use to generate the
		submap.  Typically you would use
		'mod.class.generator.map.Static' for static submaps, but
		this is not required.
    data:	The 'data' table parameter passed to the map generator.
		For static submaps, for instance, this would include a
		'map' field specifying the map filename.

    [NOTE:  This is functionally identical to the
     'MapGeneratorStatic:subgenRegister' hook used by the engine's
     engine.generator.map.Static map generator.  Although our Static
     generator extends the engine's Static generator, it overrides the
     :generate() method, so that the engine's hook is not called --- which
     is why our hook is provided instead.]

ActorGenerator:T2LevelFilteredActors:generate
---------------------------------------------
  Invoked by T2LevelFilteredActors:generate() after placing all other
  actor in normal level generation, including the level guardian if any.
  self is:	The actor generator in progress.
  data{} fields:
    gen:	The actor generator in progress.

CharacterSheet:dumpLine
-----------------------
  Invoked by CharacterSheet:dump() to collect description lines to add to
  the character sheet.
  self is:	The CharacterSheet dialog from which the character sheet is
		being built.
  data{} fields:
    lines:	The description lines collected so far.  Your hook should
		append its line(s), if any, to this table.

UseItemMenu:generate
--------------------
  Invoked by UseItemDialog:generateList() while generating the list of
  options to show in the dialog.
  self is:	The UseItemDialog being built.
  data{} fields:
    actor:	The UseItemDialog's target Actor.
    object:	The UseItemDialog's target Object.
    inven:	The actor inventory that contains the object, or nil if the
		object is on the floor.
    item:	The index into the inventory (or floor object stack) at
		which the object resides.
    floor:	True if the object is on the floor.
    menu:	The action list being generated (see below).

  To add an entry to the dialog, your hook should append a table entry to
  data.menu{} with the following fields:

    name:	The action description to show in the dialog list.
    callback:	A callback function implementing this entry's action, as
		described below.

  The entry's callback() function will be called with the following
  arguments:

    actor:	The Actor that is using the object.
    object:	The Object being used
    inven:	The actor inventory that contains the object, or nil if the
		object is on the floor.
    item:	The index into the inventory (or floor object stack) at
		which the object resides.
    floor:	True if the object is on the floor.
    on_use:	A finishing callback from UseItemDialog.  Your action
		callback should call this function after it is finished,
		with the following parameters:
		  inven:	As passed to your action callback.
		  floor:	As passed to your action callback.
		  item:		As passed to your action callback.
		  object:	As passed to your action callback.
		  stop:		True if the inventory dialog that generated
				this UseItemDialog should be closed by the
				finishing callback.

  See the file 'use-item-dialog.txt' in this directory for other ways of
  influencing UseItemDialog.

DebugDialog:generate
--------------------
  Invoked by DebugDialog:generateList() while generating the list of
  actions to show in the dialog
  self is:	The DebugDialog being built.
  data{} fields:
    menu:	The action list being generated (see below).

  To add an entry to the dialog, your hook should append a table entry to
  data.menu{} with the following fields:

    name:	The action description to show in the dialog list.
    action:	An optional callback function implementing this entry's
		action.  The callback will be called with no arguments.
    dialog:	An optional dialog name; selecting this entry will bring up
		a dialog of the specified type.  The dialog's definition
		should be placed via overload/ in the 'mod.dialogs.debug'
		section, where the module's own debug dialogs are.

  The entry should define either 'action' or 'dialog'; if both are defined,
  'dialog' takes precedence, and if neither are defined, the entry will do
  nothing.

T2:Credits:text
---------------
  Invoked by CreditsDialog:init() while building the Credits dialog.
  self is:	The CreditsDialog being built.
  data{} fields:
    text:	The credits text that will be displayed in the dialog.
		Your hook may modify this text in place, typically by
		appending suitable credits for your addon.
