$Id: misc-flags.txt 4720 2023-11-02 23:55:40Z dsb $

Miscellaneous Flags
===================
This is catch-all documentation for assorted methods and mechanisms that
can be passed special flags to control their behavior.


Object:getName()
----------------
  The Object:getName() method takes a single table argument, which can
  contain the following flags:
    force_qty:	If an integer value is provided here, it will be used as
		the object stack count.
    no_count:	If true, the returned name will not include a stack count
		or an "a/an/the" prefix.  Note that the name will still be
		pluralized as appropriate; to prevent this, combine this
		flag with 'force_qty=1'.
    force_id:	If true, the returned name will be constructed as though
		the object were identified.
    no_mods:	If true, the returned name will not include descriptions of
		weapon damage, armor AC or to-hit, to-damage or to-AC
		modifiers.
    no_pval:	If true, the returned name will not include the object's
		pval.
    no_inscr:	If true, the returned name will not include the pseudo-
		inscription for pseudo-ID'd objects or for object config-
		uration settings like notify-on-recharge.
    capitalize:	If true, the returned name will be capitalized.


Actor:getName()
---------------
  The Actor:getName() method takes a single table argument, which can
  contain the following flags:
    indef_art:		If true, the returned name will have an "a/an"
			prefix, unless the actor is a unique.
    def_art:		If true, the returned name will have a "the"
			prefix, unless the actor is a unique.
    plural:		If true, the returned name will be pluralized
			unless the actor is a unique.
    no_your:		If true, pets will not be described as "your Kobold".
    no_given_name:	If true and the actor has a name assigned by the
			player, the given name will be ignored.
    cite_given_name:	If true and the actor has a name assigned by the
			player, the given name will be included with the
			actor's base name.  If used in combination with
			'indef_art', returns e.g. "a Kobold named Steve";
			if used in combination with 'def_art', returns e.g.
			"the Kobold Steve"; if used with neither, returns
			e.g. "Steve the Kobold".  Implies 'no_your'.
    check_seen:		If true, returns 'something' if the player cannot
			see the actor [cf. Actor:canSee() and Actor:hasLOS()].
			Has no effect if the actor is the player.

Trap:getName()
--------------
  The Trap:getName() method takes a single table argument, which can
  contain the following flags:
    def_art:		If true, the returned name will have a "the"
			prefix, except as detailed below.
    show_setter:	If true, trapkit-based traps will show the trap
			setter's name if known, except for artifact
			trapkits.  This supercedes the 'def_art' flag if it
			is applied.

Object.resolve_flags{}
----------------------
  The Object module defines a static top-level table field named
  'resolve_flags', into which flags can be placed to influence the behavior
  of the next call to Object:resolve().

  NOTE:  Object.resolve_flags will be reset to a new empty table at the end
  of Object:resolve(); thus, any held references to Object.resolve_flags
  will be invalid after a call to Object:resolve() [or anything that calls
  Object:resolve(), notably Zone:makeEntity() and related methods.]

  The following flags are recognized:
    force_level:	Forces object resolution to be based on the
			specified level value instead of the current
			dungeon depth.  Note that the resolve level will be
			adjusted by +/-7 according to the player's luck
			whether or not this field is specified.
    force_good:		Forces the object to be at least {good}.
    force_great:	Forces the object to be at least {great}.
    force_power:	Forces the object to have the specified "goodness",
			as follows:
			  -2	{terrible}
			  -1	{cursed}
			   0	{average}
			   1	{good}
			   2	{great}
    force_ego:		Forces a weapon or ammo to have a particular ego.
			Value is the 'define_as' field of an ego definition,
			or a table of two such values.
    force_no_art:	Prevent the object from being randomly promoted to
			an artifact.
    force_randart_base:	Forces selection of an object suitable as a base on
			which to build a randart.
    force_no_chest:	Prevent selection of chests.  This is primarily
			used while generating the contents of chests.
    force_lite_fuel:	Forces a specified fuel level for fueled light
			sources.
    force_mimic_form:	Forces a Mimicry Cloak or Morphic Oil to have the
			specified mimicry form, specified by name.
    force_spell:	Forces a spellbook to have the specified spell,
			specified by talent ID.
    force_spell_type:	Forces a spellbook to have a random spell of the
			specified type.  Allowed values are 'MAGIC' or
			'SPIRITUALITY'.
    force_mon:		Forces an Actor-based object such as a hypnotized
			symbiote to be based on the specified Actor template.
    force_mon_id:	Forces an Actor-based object such as a Summoning
			totem or a corpse to be based on the specified
			Actor ID.

NPC.resolve_flags
-----------------
  The NPC module defines a static top-level table field named
  'resolve_flags', into which flags can be placed to influence the behavior
  of the next call to NPC:resolve().

  NOTE:  NPC.resolve_flags will be reset to a new empty table at the end of
  NPC:resolve(); thus, any held references to NPC.resolve_flags will be
  invalid after a call to NPC:resolve() [or anything that calls
  NPC:resolve(), notably Zone:makeEntity() and related methods.]

  The following flags are recognized:
    force_no_ego:	Prevents the NPC from being created with a random
			ego.
    use_ego:		Force the NPC to be created with the specified ego,
			if the NPC satisfies the ego's requirements.  The
			provided field value should be the value of the
			'define_as' field of the desired NPCEgo entity.
    force_ego:		Force the NPC to be created with the specified ego,
			disregarding the ego's requirements.  The provided
			field value should be the value of the 'define_as'
			field of the desired NPCEgo entity.
    no_gen_inven:	Do not generate the usual inventory for this NPC.
    			[cf. NPC:populateInitialInventory()]

Actor:die()
-----------
  The Actor:die() method provides some convenience hooks to cover some
  common applications of the engine's Actor:on_die() method:
    quest_on_die	The identifying tag of a quest.  If the player has
			the specified quest, the quest is not ended ('done'
			or 'failed' state) and the quest defines an
			:on_quest_mon_die() method, the method will be
			called with the dying Actor and the killer as
			parameters.
    achievement_on_die	The identifying tag of an achievement.  If present,
			world:gainAchievement() will be called with
			game.player as the 'src' parameter and the dying
			Actor as an additional info parameter.

Player:on_pickup_object()
-------------------------
  The Player:on_pickup_object() method provides some convenience hooks to
  cover some common applications of the engine's Object:on_pickup() method:
    quest_on_pickup		The identifying tag of a quest.  If the
				player has the specified quest, the quest
				is not ended ('done' or 'failed' state),
				and the quest defines an
				:on_quest_pickup_floor() method, the method
				will be called with the picked-up object as
				a parameter.
    achievement_on_pickup	The identifying tag of an achievement.  If
				present, world:gainAchievement() will be
				called with game.player as the 'src'
				parameter and the picked-up object as an
				additional info parameter.

Object:identify()
-----------------
  The Object:identify() method provides some convenience hooks to cover
  some common desired side effects of identifying an object:
    .on_identify(self, who)	Called when the object is identified or
				fully identified when it was previously
				unidentified.  'who' is the Actor on whose
				behalf :identify() is being called.  Note
				that this callback may be called more than
				once for an object if it is unidentified by
				an amnesia effect.

Zone:checkFilter()
------------------
  The Zone:checkFilter() method is used internally by Zone:makeEntity() and
  related methods to filter its choice of entities by provided parameters;
  it can also be usefully used to check a resolve()'d entity against a
  specified set of parameters.  In addition to the filter fields supported
  by engine.Zone.checkFilter() [q.v.], the module's :checkFilter() method
  is expanded to support the following fields:
    display		The entity's display character matches the provided
			single-character string.
    displays		The entity's display character is contained in the
			provided string.
    deep_flags		Specifies a set of nested flags that the provided
			entity must have.  For instance, the specification
			'deep_flags={g1={f1=true,f2=true}, g2={f3=true}}'
			applied to an entity e requires that e must have
			table fields e.g1 and e.g2, and that e.g1.f1,
			e.g1.f2 and e.g2.f3 must all be present and not
			false.
    talents		The entity must know all the talents in the
			provided list.  For resolve()'d entities, this will
			check ActorTalents:knowTalent(); for entity
			templates, it will look for a resolvers.talents()
			field and check therein.
    corpse_id		The entity must be a resolve()'d corpse object with
			a mon_id equal to the provided string.
    corpse_flags	The entity must be a resolve()'d corpse object
			whose associated actor template (via mon_id) matchs
			the provided flag specification, as per the
			'deep_flags' field above.
    corpse_talents	The entity must be a resolve()'d corpse object
			whose associated actor template (via mon_id) knows
			all the talents in the provided list, as per the
			'talents' field above.
    corpse_display	The entity must be a resolve()'d corpse object
			whose associated actor template's display character
			matches the provided single-chacter string, as per
			the 'display' field above.
    corpse_displays	The entity must be a resolve()'d corpse object
			whose associated actor template's display character
			is contained in the provided string, as per the
			'displays' field above.
