Documentation › Modules › Vitals.em

File: Vitals.em

Functions for working with mobile vitals.

Last modified: 07/30/2026

File Constants

//Apply*Damage constants
const DAMAGE_USE_REPSYS  := 1;
const DAMAGE_NO_REPSYS   := 0;
const DAMAGE_NO_SHOW     := 0;
const DAMAGE_SHOW        := 1;
const DAMAGE_USE_DEFAULT := 2;
//RecalcVital constants
const RECALC_INTRINSIC_MOD    := 1;
const RECALC_NO_INTRINSIC_MOD := 0;
const RECALC_VITALS           := 1;
const RECALC_NO_VITALS        := 0;

ApplyDamage( attackable, damage, userepsys := DAMAGE_USE_REPSYS, send_damage := DAMAGE_USE_DEFAULT )#

Parameters

attackable Character/Item Reference
damage Real (0.0 to 30000.0)
userepsys Integer (optional, default DAMAGE_USE_REPSYS)
send_damage Integer (optional, default DAMAGE_USE_DEFAULT)

Explanation

Decreases a character's hit points, after reducing damage due to armor.
For Attackable items the hps are lowered, if no controlscript exists once the hp reqches 0 the item gets destroyed.
Note vitals.em constants for userepsys:
const DAMAGE_USE_REPSYS  := 1;
const DAMAGE_NO_REPSYS   := 0;
const DAMAGE_NO_SHOW     := 0;
const DAMAGE_SHOW        := 1;
const DAMAGE_USE_DEFAULT := 2;
DAMAGE_USE_DEFAULT uses the SendDamagePacket setting from combat.cfg
(Old notes:) The steps taken are as follows: A piece of armor is chosen randomly, based on probabilities in ARMRZONE.CFG. Damage is reduced by 50% to 100% of the armor's AR. Remaining damage is halved. "I'm Hit" animation is played. Damage is applied. Mobile is killed if hit points are now zero. Invokes Reputation system effects.

Return values

Real damage applied to mobile on success

Errors

  • "Invalid parameter type"
  • "Damage is out of range"

Related

ApplyRawDamage( Attackable, Hits, userepsys := DAMAGE_USE_REPSYS, send_damage := DAMAGE_USE_DEFAULT )#

Parameters

Attackable Character/Item Reference
Hits Integer (0..65535)
userepsys Integer (optional, default DAMAGE_USE_REPSYS)
send_damage Integer (optional, default DAMAGE_USE_DEFAULT)

Explanation

Decreases a character's hit points. If this causes hit points to drop to zero, kills the character.
For Attackable items the hps are lowered, if no controlscript exists once the hp reqches 0 the item gets destroyed.
Note Armor is ignored.
Invokes Reputation system effects.
Note vitals.em constants for userepsys:
const DAMAGE_USE_REPSYS  := 1;
const DAMAGE_NO_REPSYS   := 0;
const DAMAGE_NO_SHOW     := 0;
const DAMAGE_SHOW        := 1;
const DAMAGE_USE_DEFAULT := 2;
DAMAGE_USE_DEFAULT uses the SendDamagePacket setting from combat.cfg

Return values

1 on success

Errors

  • none (returns 0 on invalid parameter)

Related

ConsumeMana( who, spellid )#

Parameters

who Character Reference
spellid Integer

Explanation

Consumes amount of "Mana" for "who" for the spell as defined in spells.cfg
Note spells.cfg files define spells and spell ids.
Consumes from "Mana" vital.

Return values

1 on success

Errors

  • "Invalid parameter"
  • "No such spell"
  • "Spell ID out of range"

Related

Related config

ConsumeVital( who, vital, hundredths )#

Parameters

who Character Reference
vital String (vital name)
hundredths Integer

Explanation

Consumes an amount of vital "vital" in hundreths. for example, ConsumeVital(who, "Stamina", 100) consumes one point of stamina.

Return values

1 on consume success or 0 on failure (insufficient value for the vital)

Errors

  • "Invalid parameter type" including if vital was not found as a vital name

Related

Related config

GetVital( character, vitalname )#

Parameters

character Character Reference
vitalname String (vital name)

Explanation

Gets the current value of "vitalname" on "character".

Return values

Integer current value of the vital on success or Error

Errors

  • "Invalid parameter type" including if vitalname was not found as a vital

Related

Related config

GetVitalMaximumValue( character, vitalname )#

Parameters

character Character Reference
vitalname String (vital name)

Explanation

Gets the maximum value of "vitalname" on "character"

Return values

Integer maximum value of the vital on success or Error

Errors

  • "Invalid parameter type" including if vitalname was not found as a vital

Related

Related config

GetVitalName( alias_name )#

Parameters

alias_name String

Explanation

Returns the real vital name from an alias

Return values

String

Errors

  • "Invalid parameter type"

Related

Related config

GetVitalRegenRate( character, vitalname )#

Parameters

character Character Reference
vitalname String (vital name)

Explanation

Returns the regeneration rate for "vitalname" on "character"

Return values

Integer regeneration rate of the vital on success

Errors

  • "Invalid parameter type" including if vitalname was not found as a vital

Related

Related config

HealDamage( Character, Hits )#

Parameters

Character Character Reference
Hits Integer (0..255)

Explanation

Increases a character's hit points, up to the character's maximum.
Note Invokes Reputation system effects.

Return values

1 if some part of the damage could be healed.

Errors

  • "Invalid parameter"

Related

RecalcVitals( character, calc_attribute := RECALC_INTRINSIC_MOD, calc_vital := RECALC_VITALS )#

Parameters

character Character Reference
calc_attribute Integer/String (attribute name)
calc_vital Integer/String (vital name)

Explanation

if default values are passed recalculates regen rates and maximum values from the exported functions in vitals.cfg for all vitals on a mobile and the intrinsic modifier from the exported functions in attributes.cfg for all attributes
if calc_attribute is set to RECALC_NO_INTRINSIC_MOD it skips the recalculation of attributes
if calc_attribute is set to an attribute name it only calculates for given attribute
if calc_vital is set to RECALC_NO_VITALS it skips the recalculation of vitals
if calc_vital is set to an vital name it only calculates for given vital
Note vitals.em constants:
const RECALC_INTRINSIC_MOD    := 1;
const RECALC_NO_INTRINSIC_MOD := 0;
const RECALC_VITALS           := 1;
const RECALC_NO_VITALS        := 0;

Return values

1 on success

Errors

  • "Mobile must be online."
  • "Invalid parameter type"
  • "Vital not defined: {given name}"
  • "Attribute not defined: {given name}"

Related

Related config

SetVital( character, vitalname, value )#

Parameters

character Character Reference
vitalname String (vital name)
value Integer (in hundreths)

Explanation

Sets the current value for "vitalname" on "character" in hundreths.

Return values

1 on success

Errors

  • "Invalid parameter type" including if vitalname was not found as a vital

Related

Related config