Making your runes/infusions work with Enhanced Object Compare
=============================================================

So, your addon defines new runes and infusions, and you'd like to arrange
that they can be compared via this addon's <ctrl>-comparison.  Well, first
off, thanks for helping to make this addon more useful. ;)  The good news
is that you probably won't need to do anything at all -- we internally use
a text comparison rig based on the levelup dialog's display of a talent's
description with comparisons based on current vs. next talent level, so it
should adapt automatically to your inscription's talent text.

The one situation in which you might want to intervene is if you want
certain values in the compared description to be highlighted as "good" if
they're smaller and "bad" if they're bigger, like we do for the die-at
threshold of heroism infusions.  You can provide a hint to that effect to
the comparison system using the 'ToME:Compare:reverseHints' hook defined
below.

ToME:Compare:reverseHints
-------------------------
  Called from Object:inscriptionDelta() to build a table of callbacks that
  will be used to determine whether a particular string should be
  highlighted as "good" or "bad".
  self is:	The 'class' superclass
  data{} fields:
    callbacks	A table of callbacks, keyed by the 'inscription_talent'
		value of the associated inscription object.  Your hook may
		add callbacks to this table for your inscriptions.

  Callbacks should be defined as follows:

    callback(who, t, data)
    ----------------------
      Parameters:
	who	The Actor being used for comparison.
	t	The talent definition table for the inscription.
	data	Relevant inscription data, as returned by
		ActorInscription:getInscriptionData() [q.v.].

      The callback should return a list of string tokens in the talent
      description corresponding to numeric values that should be treated as
      "reversed" in the comparison text (good if they are negative, bad if
      they are positive).  Examples for the game's built-in inscriptions
      can be found in this addon's hooks/load.lua.



Adding objects to the comparison candidates list
================================================
Another thing your addon might do is add new inventory slots, and it's
often useful for the player to <Ctrl>-compare an object to items wielded in
your new slot.  If the object being compared would normally be wielded in
your new inventory (as determined by Object:wornInven() and
Actor:getObjectOffSlot()), it should be picked up as usual; if not, you can
help us along by providing extra information via the
'ToME:Compare:buildCandidateList:slots' and
'ToME:Compare:buildCandidateList:extra' hooks below.

ToME:Compare:buildCandidateList:slots
-------------------------------------
  Called from Object:buildCandidateList() while building the comparison
  candidate list.  This hook is for adding inventory slots that the game
  would not normally recognize as suitable for the provided object, such
  ast the Tail slot for mecharachnids.
  self is:	[to be determined]
  data{} fields:
    object	The Object being compared.
    actor	The Actor whose inventory is being examined.
    slots	A list of numeric inventory slot identifiers (of the
		general form data.Inventory.INVEN_SOMETHING) that will be
		searched for comparison candidates.  Your hook may append
		slots to this list.
    Inventory	The engine.interface.ActorInventory package, for caller
		convenience.

ToME:Compare:buildCandidateList:extra
-------------------------------------
  Called from Object:buildCandidateList() while building the comparison
  candidate list.  This hook is for adding objects that are not actually in
  an inventory slot, but could still be usefully compared with the provided
  object, such as a steamsaw in Metaphasic Spin.
  self is:	[to be determined]
  data{} fields:
    object	The Object being compared.
    actor	The Actor whose inventory is being examined.
    cands	A list of candidate comparison objects.  Your hook may
		append candidates to this list.  Each candidate should be a
		list with two entries:  the object to be compared, and a
		name for the simulated inventory slot to be used in the
		comparison description.
    Inventory	The engine.interface.ActorInventory package, for caller
		convenience.


$Id: hooks.txt 5317 2026-02-02 04:45:21Z dsb $
