Laine at 19:26, 11 June 2007

2007-06-11T19:26:00Z

New page

==Files==

/mod/character/caust.c
/def/descriptor/caust.c
/lib/descriptors/caust.h

==Description==

Caust descriptors are used by the caust system for livings. You will want
to be familiar with the general properties of descriptors, as described in
'man descriptors'. 'man add_caust' describes the most common interface to
the caust system.

===Public Fields===

Caust_Damage: The amount of damage to do to the body when the caust is
active, as determined by the Caust_Interval setting. Negative amounts will
ignore armour.

Caust_Type: The damage type, such as ({ "fire" }) or ({ "slashing",
"crushing" }). Supplying array damage types, even for a single type, is
recommended. Defaults to ({ "poison" }).

Caust_Duration: The number of heartbeats the caust normally lasts for.
Defaults to 20.

Caust_Interval: The caust is only active every Caust_Interval heartbeats.
Defaults to 1.

Caust_Aggressor: The object initiating the combat, if any. (As with
do_damage().)

Caust_Source: The object actually doing the damage, if any. (As with
do_damage().)

Caust_Endurance: "Damage" to the subject's endurance. Negative amounts
will restore endurance.

Caust_Spell_Points: "Damage" to the subject's spell points. Negative
amounts will restore spell points.

Caust_Stun: Stunning to inflict along with damage.

Caust_Blind: Blinding to inflict along with damage.

Caust_Deafen: Deafening to inflict along with damage.

Caust_Agonize: Pain to inflict along with damage.

Caust_Target: Defines the limb targeting for the caust. Works similiarly
to the same argument in set_spell() unless Caust_Flag_Target_Preset is set.
Defaults to Chest. Examples of how target settings are used:

Special_Attack_Target_Hit_Limb (same as numeric value -2)
hit a randomly selected limb on each instance, determined with
the function get_limb_hit() if an aggressor is supplied, or with
query_random_present_limb() if not

Null (same as numeric value -1)
hit the entire body, dividing damage among limbs
proportionally to their sizes

Limb_Type_Head
hit a head type limb

({ Limb_Type_Left_Hand, Limb_Type_Left_Arm })
hit a left hand type limb and a left arm type limb, dividing damage
proportionally to their sizes

({ Limb_Type_Foot, Limb_Type_Leg })
hit a foot type limb and a leg type limb, dividing damage
proportionally to their sizes

"left tentacle"
hit a limb named "left tentacle"

In each case, when looking for a limb, the system will first look for a
limb that is either functional or disabled, and if one is not found, will
look for a limb that is amputated. If a valid limb is still not found,
the damage will be applied to the full body (i.e. as if -1 had been
specified).

Caust_Degenerative: Causes the damage to decrease by the value given for
this field each time the caust is active, until it hits zero or the
duration expires, whichever comes first. A negative value will cause the
damage to increase rather than degenerate.

Caust_Message_Chance: Determines whether the subject will receive the
Caust_Maintain_Message when the caust is active. If a closure, will be
called with 1) the subject and 2) the caust descriptor as arguments; if
the return value is true, the message will be displayed. If an integer,
is interpreted in !random(n) fashion; for example, a Caust_Message_Chance
of 8 means the messages has a 1 in 8 chance of happening each time the
caust is active.

Caust_Maintain_Message: The message sent to the subject on every instance
that the Caust_Message_Chance succeeds. Can be a string, in which case
only the subject will receive the message. Can also be an array, which
will be passed to message() and so displayed to all present; 0 will be
replaced with the body, as usual, and "%l" will be replaced with the limb
or limbs struck. Defaults to ({ 0, ({ "look", 0, "feel" }), "sick" }).
Set to 0 for no message.

Example:

Caust_Maintain_Message : ({({ 's', 0, "%l" }), "burns fiercely" })
will translate to something like:
The orc guard's right leg burns fiercely.

Caust_Start_Message: The message sent when the caust is first applied.
Uses exactly the same rules as Caust_Maintain_Message. Defaults to
"You have been poisoned!". Set to 0 for no message.

Caust_End_Message: The message sent when the caust expires or is removed.
Uses the same rules as Caust_Maintain_Message. Defaults to "You are no
longer poisoned.". Set to 0 for no message.

Caust_Merge_Message: The message sent when the caust is merged with another
similar caust. Uses the same rules as Caust_Maintain_Message. Default is
no message.

Caust_Flags: Flags associated with the caust. These are:

Caust_Flag_Armour_Effective: If this flag is present, armour counts
against the caust. Otherwise, armour is ignored.

Caust_Flag_Cumulative: Prevents the system from attempting to merge
your caust with other, similar ones. If this is not set to true, the
system will try to combine sufficiently similar causts into a single
definition, adding their durations and so forth. Often this should
be exactly what you want to happen.

Caust_Flag_Treatable: If this flag is present, damage inflicted by the
caust makes the limbs affected eligible to be treated by first aid.
Otherwise, the damage is not considered treatable.

Caust_Flag_Target_Preset: If True, the target setting is interpreted
to already contain limb indices, and so is not processed by looking
up limb types. This is how you can apply a caust to a limb that has
already been selected by other means. Examples of how target settings
will be interpreted if Caust_Flag_Target_Preset is on:
0 : hit limb index 0
1 : hit limb index 1
({ 5, 6 }) : hit limb indices 5 and 6, dividing damage among
limbs proportionally to their sizes

===Internal Fields===

Caust_Counter: This is the counter used for causts with Caust_Intervals
higher than 1. Do not interfere with this field.

Caust_Initiator: This is the string object name of the object which
applied the caust to the subject. Use Caust_Query(dxr, Caust_Initiator)
to access it. Do not set this field.

Caust_Tag: The tag for the descriptor system.

===Caust Behavior in Conjunction with Severed Limbs===

A caust will check to see if limbs it is targeting have been amputated.
This causes two behaviors. First, any limbs that have been amputated will
not be described in messages; as a corollary, if all limbs targeted have
been amputated, no messages will be sent, including end messages. Second,
if all limbs targeted have been amputated, the caust will terminate (or
will not begin at all, if this is the case when add_caust() is first
called). As indicated by the first item, this termination will be silent.
This is considered desirable behavior because if, for example, your arm is
on fire, receiving a message that indicates your arm has been amputated is
sufficient reason to stop worrying about your arm being on fire, and it
would not be particularly useful to also receive a message about the fire
going out.

Neither of the above concerns apply to causts applied to an entire body
(target of -1), since individual limbs are not mentioned in messages for
those ("%l" elements are replaced with the word "body"), and at least
one limb will always remain.

Even when limbs have been severed, damage continues to behave as if
divided between the entire target list. This is so that damage behavior
remains predictable, rather than a situation arising where much more
damage than you had intended is done to a single remaining limb out of
a target list. This applies to full-body damage in the same way as to
that with specific limb targets.

===Complete List of Conditions Resulting in Caust Termination===

* The living creature already has the maximum number of causts applied. (Caust is never applied.)
* The aggressor is prevented from initiating aggression against the target. (Caust is never applied.)
* The damage setting is zero. (Caust is never applied.)
* The number of heartbeats specified in the duration has elapsed.
* The damage setting has been reduced to nothing by degeneration.
* All limbs targeted by the caust have been amputated. (Caust terminates or never starts.)
* The caust is removed by remove_caust() or remove_causts(). Various events, notably including incarnos death, remove all causts.

==See Also==

[[man descriptors|descriptors(mechanisms)]], [[man add caust|add_caust(lfun)]], [[man remove caust|remove_caust(lfun)]], [[man remove causts|remove_causts(lfun)]]

Man caust - Revision history

Laine at 19:26, 11 June 2007