AvernumScript/Appendix/Basic Character Calls

void alert_char(short which_char_or_group)

 * Alerts the Creature/Group. This means that, if it is hostile, it will actively hunt the party down when they are nearby.

void award_char_xp(short which_char,short amount,short source_level)

 * Gives character which_char amount experience, adjusted as if it was gained by killing a creature of level source_level. You can’t give more than 1000 experience at any one time.

void award_party_xp(short amount,short source_level)

 * Gives each party member amount skill points, adjusted as if they were gained by killing a creature of level source_level. Source_level is relative level of party/monster giving experience. (1-10 for Beginner, 10-20 for Medium, 20-30 for High)

Note that a character can’t get more than 1000 experience in one lump.

short can_see_char(short which_char_or_group)

 * This can only be called in a creature or terrain script. Returns 1 if the creature/terrain spot whose script it is can see the given character or member of the given group, or 0 otherwise.

void change_char_xp(short which_char,short amt_to_change)

 * Changes experience character which_char by amount. Amt_to_change can be negative.

void change_pc_skill_pts(short which_char,short amt_to_change)

 * Changes the character which_char skill points by amt_to_change. Amt_to_change can be negative.

void change_spell_level(short which_char,short mage_or_priest,short which_spell,short amt_to_change)
Changes the skill character which_char knows spell which_spell by amt_to_change (which can be negative). If mage_or_priest is 0, changes mage spell. If 1, changes priest spell.

If the character is a party member, he or she can only learn the spell if his or her mage or priest spells skill is high enough. If the skill isn’t high enough, this call has no effect.

short char_attitude_to_char(short which_char,short char_to_evaluate)
Evaluates how character which_char feels about character char_to_evaluate. Returns 0 if the character likes the other character, 1 if the character is neutral about the other character, and 2 if the character hates the other character.

short char_has_trait(short which_char,short which_trait)
Returns 1 if character which_char has trait which_trait, 0 if it doesn’t. Traits are listed in the appendices. (in the original manual)

short char_ok(short which_char)
Returns 1 if this character is existing and alive, 0 otherwise.

short char_on_spot(short loc_x,short loc_y)
Checks if there is an NPC (a character not controlled by the player, numbers 6 or higher) on space {loc_x,loc_y}. Returns –1 if no character there. Otherwise, returns the number of the character there. If you also want to check for the presence of the player’s characters, use the call char_on_loc.

short char_status(short which_char)
Returns the current status of this character:

short creature_type(short which_char)
Returns the creature type of which_char.

void deduct_ap(short num_ap)
This can only be called in a creature script and only has effect in combat. Removes num_ap action points from the character whose script is running.

void end_combat_turn
This can only be called in a creature script and only has effect in combat. Removes all action points from the character. Note that this does NOT end the state. You need to call end right after this if you want to stop running script.

short enemies_nearby(short range)
This can only be called in a creature’s script. Returns the number of characters within range spaces that the character can see and which are hostile.

void erase_char(short which_char_or_group)
Makes the character/group stop existing. No treasure is dropped. The character’s killed flag is not set (so it can reappear when the party returns).

short friends_nearby(short range)
This can only be called in a creature’s script. Returns the number of characters within range spaces that the character can see and which are friendly.

short get_attitude(short which_char)
Returns the attitude of the character.

short get_char_skill_pts(short which_char)
Returns the character’s skill points.

short get_energy (short which_char)
Returns the character’s current spell energy. This call was added for Scenario Format Version 2, only use it with Mac version 1.1 or later or Windows version 1.0 or later.

short get_health(short which_char)
Returns the character’s current health.

short get_level(short which_char)
Returns the character’s level. Note: The ME paramater doesn't work with get_level. Use the my_number call instead.

short get_max_health(short which_char)
Returns the character’s maximum health.

short get_species(short which_char)
Returns the character’s species.

short get_spell_level(short which_char,short mage_or_priest,short which_spell)
Returns the skill level that character which_char knows spell which_spell. If mage_or_priest is 0, checks mage spell. If 1, checks priest spell.

short get_summon_level(short which_char)
Returns the summoning level of the current character (which can reveal whether it is summoned or not). The results are:

void give_recipe(short which_recipe)
Teaches the party recipe which_recipe. Recipes are listed in the appendices. (in original manual)

short has_recipe(short which_recipe)
Returns 1 if party knows alchemy recipe which_recipe, 0 if it doesn’t. Recipes are listed in the appendices.

void kill_char(short which_char_or_group, short death_type, short luck_helps)
Kills the character or every member of the group. Death_type determines the sort of death: If luck_helps is 1, the character’s luck can save it. If 0, there is no escape.

short my_ap
This can only be called in a creature script and only has effect in combat. Returns the character’s current number of action points.

short my_number
Can only be called in a creature script or terrain script. Returns this creature’s number (0 - 119) if in a creature script or the terrain script’s number (0 - 99) in a terrain script.

short party_can_see_loc(short loc_x,short loc_y)
This call only works correctly inside a town. Returns 1 if a party member can see location {loc_x,loc_y}, 0 otherwise.

short party_has_trait(short which_trait)
Returns 1 if some party member has trait which_trait, 0 if it doesn’t. Traits are listed in the appendices.

short party_size
Returns the number of living, present characters in the party.

void print_named_str(short which_char,char print_text)
Prints in the text area the name of character which_char, immediately followed by print_text.

Example: If character 17 is a Cute Puppy, the command print_named_str(17,” fires ray of doom.”);

puts the text “Cute Puppy fires ray of doom.” in the text area.

short random_party_member
Returns the number of a random character in the party (will be a number from 0 to 5).

void revive_party
Completely heals the party’s damage and restores all spell energy.

void set_attitude(short which_char_or_group,short which_attitude)
Sets the attitude of the character/group:

void set_char_alert(short which_char_or_group,short alert_level)
Sets the alert level of the Creature/Group which_char_or_group to value alert_level. If alert_level is 1, the characters are alerted and will, if hostile to the party, hunt the party down. If 0, they will no longer be alerted.

short set_char_script_mode(short which_char_or_group,short what_setting)
Adjusts when the scripts for the Creature/Group will be run by the game when the party is not nearby. (By default, the game does not call all the scripts all the time, to keep the game from slowing down.) Values for what_setting are: The default is always 0.

void set_char_trait(short which_char,short which_trait,short set_to)

 * Changes whether the character which_char, has the trait ''which_trait'.

Values for set_to are:

Values for which_trait can be found: here

Notes:
 * You should probably only use this ability to teach the character Ritual of Sanctification (trait 22). You really shouldn't mess with a character's other traits. This call only has a real effect on party members.

void set_creature_memory_cell(short which_char_or_group,short which_cell,short new_value)

 * Sets the memory cell which_cell of the creature or group which_char_or_group to the value new_value.

void set_level(short which_char_or_group,short what_level)

 * Changes the level of the creature or group which_char_or_group to level what_level. The character or character's health and statistics are Automatically adjusted to reflect their new level.

Notes:
 * You shouldn’t use this call on party members.
 * This call also completely heals and restores the character (or characters), so it should probably only be called when the party enters the area.(i.e. in the town script’s state INIT_STATE).

void set_mobility(short which_char_or_group,short mobile)

 * Sets whether the creature or group which_char_or_group can move or not.

Values for mobile are:

void set_name(short which_char_or_group,char new_name)

 * Sets the name of the creature or group which_char_or_group to name new_name.

Notes:
 * Maximum name length is 19 characters.

void set_special_ability(short which_char_or_group,short what_ability)

 * Changes the special ability of the creature of group which_char_or_group to special ability what_ability. The different special abilities are listed in the section on scripting creature types. If what_ability is 0, the creature gets no special ability.

void set_summon_level(short which_char_or_group,short new_level)

 * Sets the summoning level of creature or group which_char_or_group to new_level. Summoned creatures and illusions do not give experience or treasure when killed.

Values for new_level are:

short species_in_party(short which_species)

 * which_species is the number of a species.

Returns:

Values for which_species are:

Note:
 * This call does check any extra characters that are traveling with the party, so any species beyond those listed here will always return 0.