Laine at 21:03, 11 June 2007

Laine — Mon, 11 Jun 2007 21:03:03 GMT

New page

==Files==

/def/descriptor/special_attack.c
/lib/descriptors/special_attack.h
/std/autonomon.c

==Description==

Special attack descriptors are used by the /std/autonomon special attack
mechanism; they describe a simplistic special combat maneuver that the
character can perform. This document explains the significance of each
of the fields in the descriptor; for information on how to specify the
descriptor and so on, see the general information in 'man descriptors'.

Fields below which can be given as closures receive either standard
arguments or damage arguments. Standard arguments are 1) the opponent,
2) the special attack descriptor, and 3) the character. Damage arguments
are 1) the opponent, 2) the resolved limb target in use, which will be
either integer limb target, possibly -1 (Null) for the entire body, or an
array of integer limb targets, 3) the special attack descriptor, and
4) the character. All closures are expected to return a value that could
be specified as a static value for the field.

===Public Fields===

Special_Attack_Name: A descriptive name for the special attack, used when
it's necessary to address the special attack by name. Presently, this is
mainly relevant to things like 'show attacks', 'perform <special attack>',
and 'stop/start attacking with <special attack>', and is mainly used on
special attacks defined at the race level.

Special_Attack_Actuation: An actuation, as defined in /lib/combat.h and
/def/actuation, or an array of actuations. If supplied, these will be
used for automatically determining the conditions necessary for the special
attack to take place and constructing a message for it.

Special_Attack_Vector: An attack vector, as defined in /lib/combat.h and
/def/vector. If supplied, this will be used as part of determining the
message for the special attack and whether it can be defended against.
If not supplied, the default vector for the damage type or damage combo
lappropriate to Special_Attack_Type will be used.

Special_Attack_Skill: A single skill, an array of skills, or a mapping of
skill to int/float weights. If supplied, this specifies the main skills
which are used to determine whether the attack hits its target. If not
supplied, the attack always hits and cannot be defended against. This
should always be supplied!

Special_Attack_Speak: Text which the autonomon must speak in order for the
special attack to take place.

Special_Attack_Language: The language in which the Special_Attack_Speak
text must be spoken.

Special_Attack_Power: Used to specify the power level of the special attack
in an abstract fashion. See /lib/descriptors/special_attack.h for the list
of possible values for this field. ALWAYS USE THE MACROS! When this
field is specified, damage and other effects will be apportioned based on
the power level of the attack, adjusted according to the autonomon's
special attack damage rating if a Special_Attack_Skill was specified,
and so on. NOTE: All damage amounts (whether from Special_Attack_Power,
Special_Attack_Damage, or Special_Attack_Modifier) are apportioned into
special effects (pain, stunning, slowing, etc.) according to the tendency
of the attack's damage types to cause each; for example, photonic damage
tends to cause blinding, while sonic damage tends to cause stunning.

Special_Attack_Damage: A randomizable amount of damage caused by the
special attack. This damage, along with any damage calculated for the
the attack based on Special_Attack_Power, will be subject to normal
attack-damage randomization, meaning it will vary between 10% and 100%
of its capacity. May be a closure, which receives damage arguments. It
is preferable to avoid using this field and rely on Special_Attack_Power.

Special_Attack_Modifier: A constant amount of damage caused by the special
attack. Will not be subject to normal attack-damage randomization. May
be a closure, which receives damage arguments. It is preferable to avoid
using this field and rely on Special_Attack_Power.

Special_Attack_Type: The damage type caused by special attack. Defaults
to ({ "magical" }). Basic values may be string or array; may also be a
closure, which receives damage arguments.

Special_Attack_Target: The limb or limbs targeted by the special attack.
Defaults to Special_Attack_Target_Hit_Limb; it is almost always appropriate
to avoid using this field and rely on the default. The meaning of
different possible values are:

-1: Divide damage proportionally among all the target's limbs.
-2: Hit one of the target's non-amputated limbs using random selection
weighted by relative limb size. This may also be given as the
macro Special_Attack_Target_Hit_Limb.
other integer: Assumed to be a limb type from limbs.h. Targets the
first non-amputated limb of the specified type, or the entire body
if none are available. Special_Attack_Flag_Limb_Target_Preset,
below, causes this to be interpreted as a limb index instead.
string: Interpreted as a limb name. Targets the first non-amputated
limb with the specified name, or the entire body if none is
available.
int array: Interpreted as an array of limb types. Each element will
result in a lookup of the first non-amputated limb of the given
type, and damage will be divided proportionally among those limbs
present. If none of the limb types in the array are available,
the entire body will be targeted.
string array: As int array, but interpreting the elements as limb names
rather than limb types.
closure: Will be called with standard arguments, and is expected to
return one of the values above.

Special_Attack_Chance: The percentage chance that the special attack will
be in the character's usable attack list in a given combat round. Must be
a non-negative integer. See /lib/descriptors/special_attack.h for various
sample value macros for this, such as Special_Attack_Chance_Occasional
and Special_Attack_Chance_Somewhat_Frequent; it is strongly preferable to use
one of these macros if one appropriate to your application is available,
but using a literal integer value is acceptable if none of the macros do
what you need.

Special_Attack_Message: The message associated with the special attack.
It is usually appropriate to avoid using this field and rely on the message
that will be automatically generated by the _Vector, _Actuation, and _Type
fields. Should be specified as a message array (as per 'man message'), in
which any occurrence of the exact and entire string "%e" will be replaced
with the opponent and "%l" will be replaced with the string name of the
limb or limbs targeted. A degenerate form specified only using a string is
supported for compatibility purposes, but is deprecated for use in new
code. May be a closure, which will be called with damage arguments.
to override, the actuation, vector, and damage type information will be
used to automatically construct a message.

Special_Attack_Stun: A randomizable amount of stunning that can be
inflicted by the special attack. The actual amount of stun calculated from
this setting, if specified, will be 10% to 100% of the value given. Is
handled as a stun specification to do_damage() and is subject to the rules
applicable per that function (notably, that the secondary effects are
aborted if the main damage portion of the attack has no effect). May be
a closure, which will be called with damage arguments. It is usually
appropriate to avoid using this field and rely on stunning calculated from
the _Power field's interaction with the _Type field.

Special_Attack_Blind: A randomizable amount of blinding that can be
inflicted by the special attack. The actual amount of blinding calculated
from this setting, if specified, will be 10% to 100% of the value given.
Is handled as a blinding specification to do_damage() and is subject to the
rules applicable per that function. May be a closure, which will be called
with damage arguments. It is usually appropriate to avoid using this field
and rely on blinding calculated from the _Power field's interaction with
the _Type field.

Special_Attack_Deafen: A randomizable amount of deafening that can be
inflicted by the special attack. The actual amount of deafening calculated
from this setting, if specified, will be 10% to 100% of the value given.
Is handled as a deafening specification to do_damage() and is subject to
the rules applicable per that function. May be a closure, which will be
called with damage arguments. It is usually appropriate to avoid using
this field and rely on deafening calculated from the _Power field's
interaction with the _Type field.

Special_Attack_Numb: A randomizable amount of numbing that can be inflicted
by the special attack. The actual amount of numbing calculated from this
setting, if specified, will be 10% to 100% of the value given. Is handled
as a numbing specification to do_damage() and is subject to the rules
applicable per that function. May be a closure, which will be called with
damage arguments. It is usually appropriate to avoid using this field and
rely on numbing calculated from the _Power field's interaction with the
_Type field.

Special_Attack_Slow: A randomizable amount of slowing that can be inflicted
by the special attack. The actual amount of slowing calculated from this
setting, if specified, will be 10% to 100% of the value given. Is handled
as a slowing specification to do_damage() and is subject to the rules
applicable per that function. May be a closure, which will be called with
damage arguments. It is usually appropriate to avoid using this field and
rely on slowing calculated from the _Power field's interaction with the
_Type field.

Special_Attack_Poison: A randomizable amount of poisoning that can be
inflicted by the special attack. The actual amount of poisoning calculated
from this setting, if specified, will be 10% to 100% of the value given.
Is handled as a poisoning specification to do_damage() and is subject to
the rules applicable per that function. May be a closure, which will be
called with damage arguments. It is usually appropriate to avoid using
this field and rely on poisoning calculated from the _Power field's
interaction with the _Type field.

Special_Attack_Caust: A caust specification (c.f. 'man caust') associated
with the special attack. If present, when the special attack occurs, the
caust descriptor will be copied with deep_copy() and modified as follows:
1) the Caust_Damage will be set to half the damage calculated for the
special attack (from Special_Attack_Damage and Special_Attack_Modifier),
2) the Caust_Type will be set the same as the Special_Attack_Type, 3) the
Caust_Aggressor will be set to the character, and 3) the Caust_Target will
be set to the limbs being hit by the special attack, with the flag
Caust_Flag_Target_Preset turned on unless the entire body is being
targeted. The modified copy of the caust descriptor will then be added
to the opponent.

Special_Attack_Condition: A condition descriptor which will be evaluated
on the character performing the special attack, or a closure which, if
specified, will be called with standard arguments. If the condition
descriptor evaluation or closure returns False, the special attack will
not be used at that time. Generally, common condition macros from
/lib/conditions.h are used for this setting.

Special_Attack_From: A field specifying where the special attack comes
from, used by the code that automatically constructs special attack
messages based on _Actuation, _Vector, _Type, and so on. Can be anything
that would be valid as an element of a message array, such as this_object()
in a character for a special attack originating from the character in
general, "nowhere" for a special attack coming from nowhere, or
({ 'r', 0, "eyes" }) for a special attack coming from a character's eyes
(please note: test your special attack and use ({ 's', 0, "eyes" }) if
needed to make the character's name show up). If an appropriate object
or limb can be found in the specification, the Attack_Weapon field of
attack descriptors generated by the special attack will be set accordingly.

Special_Attack_Appearance: A descriptive field usable to override the
appearance of the special attack calculated based on _Vector and _Type.

Special_Attack_Energy_Costs: An array of specifications for energy cost
descriptors defining the energy costs to use the special attack. The
default is as if ({({ Energy_Spiritual, 10 })}) were given.

Special_Attack_Placeholder: A presently unused field.

Special_Attack_Strike: A field accepting an int or float value affecting
the accuracy of the special attack. See /lib/descriptors/special_attack.h
for a list of sample values for this field. It is preferable to use one
of these if any appropriate to your application is available, but it is
acceptable to specify a literal value if none of the macros does what you
want.

Special_Attack_Activity: The cost in activity points to perform the special
attack. Defaults to 15 if the attack is being defined from an autonomon
object, 0 otherwise. Must be a positive integer.

Special_Attack_Size: A field accepting an int value specifying the size of
the special attack. It is more often than not appropriate to avoid using
this field and rely on the default value for the vector used. See
/lib/descriptors/special_attack.h for a list of sample values for this
field; it is preferable to use one of these if any appropriate to your
application is available, but it is acceptable to specify a literal value
if none of the macros does what you want.

Special_Attack_Speech: The speech command (designated using one of the
Speech_Command_X macros from the speech descriptor) using which the
Special_Attack_Speak text is spoken; defaults to Speech_Command_Say.

Special_Attack_Flags: Specifies flag values from among these:

Special_Attack_Flag_Appearance_Plurality: When using the _Appearance
field, specifies that your given _Appearance is plural. Specifying
this flag then allows grammar related to the appearance of the special
attack to be constructed correctly. Will cause attack descriptors
generated by the special attack to have Attack_Flag_Pluralize_Vector
turned on.

Special_Attack_Flag_Bypass_Armour: Causes the special attack to ignore
armour and related defenses. Will cause attack descriptors generated
by the special attack to have Attack_Flag_Bypass_Armour turned on.

Special_Attack_Flag_Untreatable: Causes wounds from the special attack
to not flag affected limbs as treatable. Will cause attack descriptors
generated by the special attack to have Attack_Flag_Untreatable turned
on.

Special_Attack_Flag_Inflict_Mental_Disorder: Causes the special attack,
if successful, to cause a randomly selected mental disorder to the
target. Will cause attack descriptors generated by the special attack
to have Attack_Flag_Inflict_Mental_Disorder turned on.

Special_Attack_Flag_Accidental: Causes the special attack to be treated
as accidental. Will cause attack descriptors generated by the special
attack to have Attack_Flag_Accidental turned on.

Special_Attack_Flag_Definite_Article: Causes the appearance of the
special attack to be described using the definite article rather than
the indefinite ("the" rather than "a" or "an") if an article is used.

Special_Attack_Flag_From_Separate: In the case where the _Actuation
in use is a direct manipulation of the vector (e.g. Vector_Spit,
Vector_Release; anything with set_actuation_vector_manipulating(True)),
the default behavior in the presence of a _From field is to have the
_From as the subject of the actuation, i.e. the _From is doing the
spitting or releasing or what-have-you. This flag suppresses this
behavior, causing the character to still be performing the vector,
described as being from the _From field.

Special_Attack_Flag_Pluralize_Vector: Causes the appearance of the
special attack to be calculated using the plural case of the vector,
e.g. "beams" rather than "beam", "arcs" rather than "arc". Will cause
attack descriptors generated by the special attack to have
Attack_Flag_Pluralize_Vector turned on.

Special_Attack_Flag_Limb_Target_Preset: Causes an integer _Target
value to be interpreted as an already-determined limb index on the
target, rather than a limb type to be found.

Special_Attack_Flag_Disjoint_Limb_Selection: Causes the special attack
to be able to hit non-adjacent limbs when striking multiple limbs on a
target. Will cause attack descriptors generated by the special attack
to have Attack_Flag_Disjoint_Limb_Selection turned on.

Special_Attack_Flag_Combine_Message: If specified, the _Message field
is combined with the message content generated automatically rather
than replacing it.

Special_Attack_Flag_Message_Elide_From: If specified, the _From field
does not affect generated messages, meaning it is only used to find
the Attack_Weapon value to use.

Special_Attack_Flag_Suppress_Result_Description: If specified, causes
the special attack to not have an attack result description ("connects
solidly", "barely connects" and so on) in its message content. Will
cause attack descriptors generated by the special attack to have
Attack_Flag_Suppress_Result_Description turned on.

==See Also==

[[man descriptors|descriptors(mechanisms)]], [[man add special attack|add_special_attack(lfun)]],
[[man set special attacks|set_special_attacks(lfun)]], [[man query special attacks|query_special_attacks(lfun)]],
[[man remove special attack|remove_special_attack(lfun)]], [[man message|message(lfun)]], [[man caust|caust(descriptors)]], [[man damage types|damage_types(build)]]

Man special attack - Revision history

Laine at 21:03, 11 June 2007