Blades of Avernum Script Reference
From Wikibooks, the open-content textbooks collection
Introduction
This is a reference guide for the Blades of Avernum Avernumscript language. Blades of Avernum is a role playing game made by Spiderweb Software, more information can be found at the Avernum Web Site. This document is basically the calls section of the Blades of Avernum Editor Appendices put in an online, easily browsable form.
All credit goes to Jeff Vogel, creator of the software and writer of the original documentation. This is just the documentation he wrote in a different format.
General notes about scripting
which_char - Many calls expect to be given a value for which_char. This expects the number of a character, which will be from 0 to 119. (Note that you are not entering the character’s Character ID or the personality. To find the number of a character, in the editor, select the character and look at the number in the first description line.) If you use such a call in a creature script, if you enter a value of -1 for which_char, the function will act on the creature whose script is running. In such a case, you can also enter ME for which_char. This does the same thing.
which_char_or_group - When a call expects a value for which_char_or_group, it wants the number of a character or group. This is exactly like which_char, except for one difference: the call can also act on every member of a group. If you want to have the call act on group x, give which_char_or_group a value of 1000 + x. (And remember that group 0 is always the party.)
The Most Important Calls
You should pay special attention to these calls. They are the calls you will use the most frequently to write your special encounters.
This call is the way to begin a conversation.
void begin_talk_mode(short start_node)
This call lets you block containers and spaces from the party.
void block_entry(short do_blockage)
These two calls let you easily reward the party.
void change_coins(short coin_amount) short reward_give(short which_item)
These two calls let you see if a character exists and instantly make a new one.
short char_ok(short which_char) short spawn_creature(short which_char)
Every scenario must use this call. Otherwise, the party can never escape.
void end_scenario(short party_won)
The best call to display some simple text to the player is:
void message_dialog(char text1,char text2)
This call enables you to customize your outdoor encounters.
void outdoor_enc_result(short which_result)
These are the two primary calls for setting and checking Stuff Done flags.
void set_flag(short a,short b,short new_value) short get_flag(short a,short b)
These two calls enable you to instantly customize creatures in your towns:
void set_name(short which_char_or_group,char new_name) void set_level(short which_char_or_group,short what_level)
This call lets you jump around special scripts easily.
void set_state_continue(short new_state)
Basic Script and IO Calls
print_big_str(string str,short num_to_print,string str2)
Like print_str, but prints a more customized piece of text. Prints, on one line, the text str, followed by the number num_to_print, followed by the text str2.
Example: print_big_str(“You are hit for “, 10000, “ damage.”); prints “You are hit for 10000 damage.” to the text window.
print_big_str_num(string str,short num,string str2,short color)
Like print_big_str, but gives the text a different color. Colors are listed in the description of print_str_color.
void block_entry(short do_blockage)
This very important call prevents the character from accessing the terrain spot/area that called the script. If called from a special encounter triggered by walking, this call prevents the party/character from entering the space. If called when searching a container, blocks the party from being able to get the item inside. If do_blockage is 1, the call blocks entry. If it is 0, allows entry, and undoes any earlier uses of this call with do_blockage equal to 1.
void end()
If called in a script, immediately stops running the script. If called in the code of a dialogue node, also ends the conversation.
short get_ran(short num_dice,short min,short max)
Returns a random number. The game generates num_dice random numbers, each is from min to max. It then adds them up and returns the sum.
Example: get_ran(3,1,4) returns a random number from 3-12 (or 1-4 + 1-4 + 1-4).
short get_selected_char()
Returns the number of the character currently selected in the party roster area (which will be from 0 to 3).
short is_combat()
Returns 1 if party is in combat mode, 0 otherwise.
short is_outdoor()
Returns 1 if party is in outdoor mode, 0 otherwise. (Being in a combat outdoors is NOT outdoor mode.)
short is_town()
Returns 1 if party is in town mode, 0 otherwise.
void play_sound(short which_sound)
Plays the sound which_sound. Sounds are listed in the appendices. If the number of the sound is positive, it stops the action while the sound plays. If negative, the sound plays while the game continues.
void print_str(string to_print)
Displays the given text in the game’s text area. The maximum allowable length of text is 70 characters.
void print_str_color(string to_print,short color)
Like print_str, but also gives the text a different color. Values for color are:
| 0 | Black |
| 1 | Red (Usually used for errors.) |
| 2 | Blue |
| 3 | Magenta |
| 4 | Green |
void run_scenario_script(short which_node)
Immediately runs the scenario script at state which_node. Once the scenario script stops running, the script that made this call continues running normally.
void run_town_script(short which_node)
Immediately runs the current town script at state which_node. Once the scenario script stops running, the script that made this call continues running normally. You can only make this call from dialogue, creature, or terrain scripts.
void set_incidental_sound(short on_or_off)
Sets whether incidental sounds (birds chirping, etc.) are played in the background. If on_or_off is 1, turns them off. If 0, turns them back on. If turned off, they stay off until this call turns them on again.
void set_state(short new_state)
Changes the state of the script to new_state and immediately stops running the script. Has no effect in a dialogue script or in the states INIT_STATE, DEAD_STATE, or other predefined state types (except START_STATE).
void set_state_continue(short new_state)
Exactly like set_state, except that it doesn’t stop running the script.
Note: set_state_continue does work in some other predefined states, possibly all of them.
Campaign and Scenario Calls
These are the functions for manipulating the scenario variables and the Stuff Done flags. For information on Stuff Done flags and the meaning of SDF(a,b), read the chapter on scripting basics (in original documentation).
void clear_quest(short which_quest)
Resets the quest which_quest (which can be from 0 to 99). It is as if it was never given. No text message is displayed.
void end_scenario(short party_won)
Immediately terminates the scenario and returns the party to the title screen. If party_won is 1, the party’s won scenarios value is incremented. If 0, not.
If party_won is 2, the party is taken out of the scenario and the number of scenarios the party is recorded as having played is not incremented. (You probably usually won’t want to use this.)
short get_flag(short a,short b)
Identical to get_sdf.
short get_sdf(short a,short b)
Returns SDF(a,b).
void inc_flag(short a,short b,short how_much)
Changes SDF(a,b) by how_much (which can be negative). Note the legal range of values for a flag is 0..255.
void set_flag(short a,short b,short new_value)
Sets SDF(a,b) to be new_value.
void toggle_quest(short which_quest,short start_or_finish)
Toggles whether the party is doing quest number which_quest (which can be from 0 to 99) or not. If start_or_finish is 1, and the party has not completed this quest, the quest is started and appears on the party’s quest list. If start_or_finish is 0 and the party is currently on the quest, the quest is marked as finished and removed from the quest list.
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:
| 0 | Doesn’t exist |
| 1 | Alive and OK |
| 2 | Dead |
| 3 | Dust |
| 4 | Stoned |
| 5 | Fled |
| 11 | Party split up, character alive but not present |
| 12 | Party split up, character dead but not present |
| 13 | Party split up, character dust but not present |
| 14 | Party split up, character stoned but not present |
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.
| 3 | Friendly to party |
| 4 | Neutral |
| 10 | Hostile A |
| 11 | Hostile B |
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:
| 0 | Not summoned. Real creature. |
| 1 | Summoned, but will not disappear over time. |
| 100-199 | Summoned. Subtract 100 from amount to get number of turns until it disappears. |
| 200-299 | Illusion. Subtract 200 from amount to get number of turns until it disappears. |
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:
| 2 | Dead |
| 3 | Dust |
| 4 | Stoned |
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:
| 3 | Friendly to party |
| 4 | Neutral |
| 10 | Hostile A |
| 11 | Hostile B |
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:
| 0 | call every 8 moves, but not if party is far away |
| 1 | Call every 8 moves, even if party is far away |
| 2 | Call every move, but not if party is far away |
| 3 | Call every move, even if party is far away |
The default is always 0.
void set_char_trait(short which_char,short which_trait,short set_to)
For character which_char, changes whether the character has trait which_trait. If set_to is 0, takes the trait away. If set_to is 1, gives the trait. Traits are listed in the appendices.
Note that 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)
For the character or each member of the group, sets the value of memory cell which_cell to new_value.
void set_level(short which_char_or_group,short what_level)
Changes the level of the Creature/Group to what_level. Automatically adjusts the character’s statistics and health to reflect the new level. This call also completely heals and restores the character, so it should probably only be called when the party enters the area (i.e. in the town script’s state INIT_STATE).
You shouldn’t use this call on party members.
void set_mobility(short which_char_or_group,short mobile)
Sets whether the Creature/Group can move or not. 1 is yes, 0 is no.
void set_name(short which_char_or_group,char new_name)
Sets the name of the character/group to new_name. 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/Group to 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/Group to new_level. Summoned creatures and illusions do not give experience or treasure when killed. The legal values are:
| 0 | Not summoned. Real creature. |
| 1 | Summoned, but will not disappear over time. |
| 100-199 | Summoned. Subtract 100 from amount to get number of turns until it disappears. |
| 200-299 | Illusion. Subtract 200 from amount to get number of turns until it disappears. |
short species_in_party(short which_species)
which_species is the number of a species (most often, 2 for nephil or 3 for slith). This call returns 1 if one of the characters in the party is alive and that species, 0 otherwise.
This call does check any extra characters that are traveling with the party.
Item, Special Item and Gold Calls
void change_coins(short coin_amount)
Changes the number of coins the party has by coin_amount (which can be negative).
If the number is negative, then coins are taken away. If the party doesn't have enough coins, no coins are taken.
void change_spec_item(short which_item,short how_many)
Changes the amount of special item which_item the party has by how_many (which can be negative if you want to take some of an item away). If you try to take away more of the item than the party has, the party is left with 0 of the item.
void char_give_item(short which_char_or_group,short which_item)
Tries to give to the Creature/Group an item of type which_item. If you call char_give_item for a group, gives one of the item to each group member.
The item will not automatically be identified. If the character doesn’t have enough space to take the item, nothing happens and the game gives a “can’t take the item” message.
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 char_has_item(short which_char,short which_item)
Returns 1 if character which_char has an item of type which_item, 0 otherwise.
short char_has_item_of_class_equip(chart char_num,short which_class,short take_item)
Returns 1 if a party member has an item with special class which_class and the item is equipped, 0 otherwise. If take_item is 1, one of the items is taken. If 0, it isn’t.
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.
void char_take_item(short which_char_or_group,short which_item)
Takes from the Creature/Group one item of type which_item (or, if it has charges, 1 charge). If a group is given, takes one of the item from each member of the group.
short coins_amount()
Returns the number of coins the party has.
short has_item(short which_item)
Returns 1 if a party member has an item of type which_item, 0 otherwise.
short has_item_of_class(short which_class,short take_item)
Returns 1 if a party member has an item with special class which_class (this is set in the scenario item script), 0 otherwise. If take_item is 1, one of the items is taken. If 0, it isn’t.
short has_num_of_item(short which_item)
Returns how many items which_item the party has, 0 otherwise.
If the items in question have charges, this call returns the total number of charges.
short has_special_item(short which_item)
Returns the number of the special item which_item the party has, 0 if they don’t have any.
short item_of_class_on_spot(short loc_x,short loc_y,short what_class)
Returns 1 if there is an item of special class what_class on town space {loc_x,loc_y}, 0 otherwise. If what_class is -1, returns 1 if any item is on the space, 0 otherwise.
void move_item_on_spot(short loc_x,short loc_y,short dest_x,short dest_y)
Takes all items sitting on town spot {loc_x,loc_y} and moves them to {dest_x,dest_y}. If dest_x is a negative value, the items on the space are simply destroyed.
short pay_coins(short coin_amount)
Tries to take coin_amount coins from the party. Returns 0 if party doesn’t have enough, 1 if they do.
void put_item_on_spot(short loc_x,short loc_y,short what_item)
Places an item of type what_item on town space {loc_x,loc_y}. If that spot is a container, the item won’t be contained inside it.
short reward_give(short which_item)
Tries to give item of number which_item to party. If the party can’t hold it, tries to put it at their feet (which only works indoors). If this fails, returns 0. Otherwise, returns 1.
short take_all_of_item(short which_item)
Takes all of item which_item from party, and returns the number of items taken. If the item given has charges, returns the total number of charges taken.
short take_all_of_item_class(short which_class,short gold_to_pay)
Takes from the party all items of special class which_class and, for each item taken, gives the party gold_to_pay gold. Returns 1 if the party had some items of that type, 0 otherwise. If the item taken has charges, gives the amount of gold for each charge taken.
void take_item(short which_item)
Searches through the party’s inventory until it finds an item of type which_item and takes it (or, if it has charges, takes one of them).
short take_item_of_class_on_spot(short loc_x,short loc_y,short what_class)
Returns 1 if there is an item of special class what_class on town space {loc_x,loc_y}, 0 otherwise. If there was an item of that type on the spot, destroys one of it (or, if item has charges, takes 1 charge). If what_class is -1, destroys all items on the spot and returns TRUE if an item destroyed.
void take_num_of_item(short which_item,short num_to_take)
Takes num_to_take items of type which_type from the party. If the item has charges, takes that many charges. If the party has less than num_to_take items of that type, all are taken.
void take_special_item(short which_item)
Takes 1 of special item which_item from party. If party has none of that special item, does nothing.
Location and Distance Calls
Note that none of these functions are meant to be used in outdoors mode. They will not return proper values.
Also, if you are writing a creature or terrain script, be sure to look up the calls my_loc_x and my_loc_y.
short char_loc_x(short which_char)
Returns the x coordinate of the character which_char.
short char_loc_y(short which_char)
Returns the y coordinate of the character which_char.
short char_dist_to_loc(short which_char,short x, short y)
Returns the distance of character which_char from location {x,y}. Note that which_char can't be a group.
(Editor's note: Using "ME" here, or -1, from a creature script doesn't seem to work right. It gave me a distance number, but didn't give me the distance from the creature whose script was running. I had to use the creature's number. Further note: the way to do this is using my_number.)
short char_on_loc(short x, short y)
Returns the number of the character on space {x,y}. If there is no character there, returns -1. Unlike char_on_spot, this call also checks if one of the player’s characters is there.
short dist_to_waypoint(short which_char,short which_point)
Returns the distance of character which_char from waypoint which_point. Note that which_char can't be a group.
short group_dist_to_loc(short which_group,short x, short y)
Returns the distance of closest character in group which_group to the location {x,y}. Remember that group 0 is the party (in case you want to see who in the party is closest to a point). If the group is empty, the distance returned is 10000.
short my_dist_from_start()
This call can only be made from a creature script. Returns the character’s distance, in spaces, from where it started.
Statistic and Damage Functions
void alter_stat(short which_char_or_group,short which_stat,short how_much)
For character which_char, changes statistic which_stat by how_much. You can’t increase a statistic above 100.
How_much can be negative. Skills 0-3 can’t be taken below 1 by this call, and no skill can be taken below 0.
void change_char_energy(short which_char_or_group,short energy_amount)
Changes spell energy for the Creature/Group by energy_amount. This can’t raise a character over its normal energy maximum.
void change_char_health(short which_char_or_group,short heal_amount)
Changes the health of the Creature/Group by heal_amount. This can’t raise a character over its normal health maximum.
short char_with_highest_skill(short which_skill)
Returns the number of the party member with the highest level of the skill which_skill. Returns -1 if no character has any of the skill.
void damage_char(short which_char_or_group,short damage_amount,short damage_type)
Does damage_amount damage of type damage_type to the Creature/Group.
Damage types - 0 - weapon, 1 - fire, 2 - poison, 3 - general magic, 4 - unblockable, 5 - cold, 6 – acid
void damage_near_loc(short loc_x,short loc_y,short damage_amount,short radius,short damage_type)
Does damage_amount damage of type damage_type to all characters visible to and within radius spaces of location {loc_x,loc_y}. This does not work outdoors.
Damage types - 0 - weapon, 1 - fire, 2 - poison, 3 - general magic, 4 - unblockable, 5 - cold, 6 - acid
short get_char_status(short which_char,short which_status)
Returns the current value of status which_status for character which_char.
short get_highest_skill(short which_skill)
Returns value of the skill which_skill for the party member who has the most for that skill.
short get_skill_total(short which_skill)
Returns the sum of all the party members' values of skill which_skill.
short get_stat(short which_char,short which_stat)
Returns the current value of statistic which_stat for character which_char. This takes into account all bonuses for items, etc.
short get_stat_levels_bought(short char_num,short which_stat)
Returns the number of levels of statistic which_stat for character which_char that the character has actually bought at a trainer. This will be less than the current value of the statistic. For non-player characters, this will always end up being 0.
void heal_char(short which_char_or_group,short heal_amount)
Heals heal_amount damage for the Creature/Group.
short party_has_status(short which_status)
Returns 1 if one party member has a positive value for status which_status, 0 otherwise.
This is most useful when checking for Featherfall (status 24) or Flying (status 25);
short party_member_has_skill(short which_skill)
Returns 1 if a party member has at least 1 level of skill which_skill, 0 otherwise.
void restore_energy_char(short which_char_or_group,short energy_amount)
Restores energy_amount spell energy for the Creature/Group.
void restore_pc(short which_char)
Completely heals the character of all bad effects (including death or dust). If called in town, places the character next to the party. Removes the curse from all equipped cursed items.
void set_char_status(short which_char_or_group,short which_status,short how_much,short is_forced,short give_update)
Changes status which_status for character/group which_char_or_group by amount how_much. If is_forced is 1, the status is always changed by the full amount. If is_forced is 0 then, for negative statuses, the character’s resistances apply.
If is_forced is 0 and give_update is 0, no text message about status change is given. Otherwise, it is. If the status change is forced, however, no text update is given and give_update is ignored.
void set_party_status(short which_status,short how_much,short give_update)
Changes status which_status for every character in the party by amount how_much. For negative statuses, character resistances apply (to force a change, use the set_char_status call). If give_update is 0, no text message about status change is given. Otherwise, it is.
void status_near_loc(short loc_x,short loc_y,short status_amount,short radius,short status_type)
Change status status_type by amount status_amount to all characters visible to and within radius spaces of location {loc_x,loc_y}. This does not work outdoors. All appropriate resistances apply ... if you try to change the amount of poison for the nearby characters, their poison resistance will help them.
void waypoint_damage_party(short which_waypoint,short in_range,short out_range,short damage_amount,short damage_type)
Does damage_amount damage of damage_type type to all characters near a visible waypoint which_waypoint. Only affects creatures which are at least in_range spaces and at most out_range spaces from the waypoint.
Damage types - 0 - weapon, 1 - fire, 2 - poison, 3 - general magic, 4 - unblockable, 5 - cold, 6 - acid
Animation and SFX Functions
There are a variety of special effects that can be put on characters and terrain spots. Once the effects are placed, to actually display the animation, call run_animation or run_animation_sound. All of the available effects, explosions, and sparkles are listed in the appendices.
None of these calls have any effect outdoors.
void put_boom_on_char(short which_char,short which_sfx,short random_shift)
Places explosion which_sfx on character which_char. If random_shift is 0, effect appears directly on character. If 1, the explosion is shifted slightly in a random direction.
void put_boom_on_space(short loc_x,short loc_y,short which_sfx,short random_shift)
Exactly like put_boom_on_char, but makes the effect appear in terrain spot {loc_x,loc_y}.
void put_effect_on_char(short which_char,short which_sfx,short num_effects,short float_mode)
Places effect which_sfx on character which_char. num_effects is the number of effect graphics that appear, and float_mode determines how they behave:
| 0 | Appear above character and fall. |
| 1 | Appear below character and rise. |
| 2 | Hang in midair. |
void put_effect_on_space(short loc_x,short loc_y,short which_sfx,short num_effects,short float_mode)
Exactly like put_effect_on_char, but makes the effect appear in terrain spot {loc_x,loc_y}.
void put_jagged_zap(short source_x,short source_y,short dest_x,short dest_y,short color_scheme)
Exactly like put_straight_zap, but the bolt is jagged. Values for color_scheme are in listed in put_straight_zap.
void put_sparkles_on_char(short which_char,short which_sfx,short num_sparkles)
Places sparkle which_sfx on character which_char. num_sparkles is the number of effect graphics that appear.
void put_sparkles_on_space(short loc_x,short loc_y,short which_sfx,short num_sparkles)
Exactly like put_effect_on_char, but makes the effect appear in terrain spot {loc_x,loc_y}.
void put_straight_zap(short source_x,short source_y,short dest_x,short dest_y,short color_scheme)
Places a straight bolt of lightning running from {source_x,source_y} to {dest_x,dest_y}. Values for color_scheme are
| 0 | Fire ray |
| 1 | Ice ray |
| 2 | Death ray |
| 3 | Green ray |
| 4 | White ray |
| 5 | Black ray |
| 6 | Blue ray |
the bolt does not appear until one of the run_animation calls is used.
void run_animation()
Pauses the game and plays all animations you have created. Note that none of the above calls will draw anything on its own. You need to use this call to run any animations.
void run_animation_sound(short which_sound)
Like run animation, but also plays sound which_sound. Sounds are listed in the appendices. The sound plays while the animation runs.
Scenario Initialization Calls
These calls are all meant to be made in the scenario script, either in the state LOAD_SCEN_STATE or START_SCEN_STATE. They can, however, be made anywhere.
void add_item_to_shop(short which_shop,short which_item,short how_many)
This call should be made in the state START_SCEN_STATE. This places 1 or more of an item in store which_shop (which can be from 0 to 129). Normally, the item placed is which_item (which is numbered 0 - 499, and how_many copies of the item are put in the store. If there are more than 500 of an item put in the store, the store has an infinite number.
Any given shop can only have 25 items in stock.
However, if you pick certain high values of which_item, you can put into the store things besides items (like spells).
Not only objects can be in stores. You can also have spells, alchemy recipes, and skills. The meanings of the values of which_item are:
| 0 - 499 | Item |
| 2000 + x | Mage spell x (x is from 0 to 19). how_many is the highest level of the spell that can be bought in the store. |
| 3000 + x | Priest spell x (x is from 0 to 19). how_many is the highest level of the spell that can be bought in the store. |
| 4000 + x | Alchemy recipe x (x is from 0 to 19). how_many should be 1. |
| 5000 + x | Skill x. Each purchase gives the character 1 level of the skill. how_many is the maximum number of levels of the skill that can be bought. |
Note that, in all cases, you will want to put a number above 0 for how_many. If you don't, the item will disappear from the store.
void create_boat(short which_boat,short which_town,short loc_x,short loc_y,short others_property)
This call should be made in the state START_SCEN_STATE. Initializes boat which_boat (which can be from 0 to 29). Places the boat in town which_town in space {loc_x,loc_y}. If others_property is 0, the party can enter the boat. If 1, the boat must be set as party property by a script before the party can use it.
void create_horse(short which_horse,short which_town,short loc_x,short loc_y,short others_property)
This call should be made in the state START_SCEN_STATE. Initializes horse which_horse (which can be from 0 to 29). Places the horse in town which_town in space {loc_x,loc_y}. If others_property is 0, the party can mount the horse. If 1, the horse must be set as party property by a script before the party can use it.
void init_quest(short which_quest,string quest_name,string quest_desc)
This call should be made in the state LOAD_SCEN_STATE. It sets the name of quest which_quest to quest_name and the description text to quest_desc. The name can be at most 29 characters long and the description can be at most 199 characters long. The quests are numbered from 0 to 99.
void init_special_item(short which_item,string item_name,string item_desc)
This call should be made in the state LOAD_SCEN_STATE. It sets the name of special item which_item to item_name and the description text to item_desc. The name can be at most 29 characters long and the description can be at most 199 characters long. The special items are numbered from 0 to 59.
void set_creature_type_level(short which_type,short what_level)
Sets the level of creature type which_type to level what_level. This is the only call that changes creature types (normally these changes are made in a different script). It is provided because, to balance a scenario, you will probably want to adjust the levels of some creature types.
Boats and Horses
The values which_horse and which_boat are always from 0 to 29.
short in_boat()
Returns -1 if party is not in a boat. Otherwise, returns the number of the boat they’re in (from 0 to 29).
short in_horse()
Returns -1 if party is not on a horse. Otherwise, returns the number of the horse they’re on (from 0 to 29).
void set_boat_property(short which_boat,short party_property)
Changes property status of boat which_boat
short set_boat_range_property(short first_boat,short last_boat)
Finds one boat in the range from first_boat to last_boat that isn’t the party’s property and make’s it the party’s property. Returns the number of the boat that was made the party’s property, or -1 if there was no existing boat in the range that the party didn’t own.
void set_horse_property(short which_horse,short party_property)
Changes property status of horse which_horse. If party_property is 0, party can’t use the horses. If party_property is 1, they can.
short set_horse_range_property(short first_horse,short last_horse)
Sets one horse in range from first_horse to last_horse that isn’t the party’s property to be the party’s property. Returns the number of the horse that was made the party’s property, or -1 if there was no existing horse in the range that the party didn’t own.
Event Calls
short day_event_happened(short which_event)
Returns -1 if the event which_event (which is from 0 to 9) has not happened, or the day it happened if it has happened.
void set_event_happened(short which_event,short what_day)
Records that event which_event (a number from 0 to 9) happened on day what_day (you’ll probably pass what_day_of_scenario()) to this.
Town Calls
These calls have to do with towns and their status (whether they have been visited, are visible, etc.). Any calls that refer to the current town will do nothing if the party is not in town mode. To learn more about visibility, crime levels, etc., read the chapters on editing and scripting towns.
For calls that expect a value for which_town, if you pass the value ME (or -1), the town the party is currently in is used.
void activate_hidden_group(short which_group)
When town is entered, characters with a hidden group value do not appear. This call makes all characters with the hidden group value of which_group appear. If the spot where the creature would appear is blocked, the game finds a clear nearby spot.
void change_crime_level(short how_much)
Changes the level of crimes committed in the current town by how_much (which can be negative).
void change_outdoor_location(short what_section_x,short what_section_y,short loc_in_sector_x, short loc_in_sector_y)
Changes the party's location in the outdoors. It moves them to location {loc_in_sector_x,loc_in_sector_y} in section X = what_section_x, Y = what_section_y. It can only be used in a town script. It is used, for example, when the party enters a portal in a town that is meant to carry them to a town a long distance away.
void clear_town()
Sets the current town to be destroyed. When next entered, the only creatures that will be present are ones set to only be there when town destroyed.
short current_town()
Returns the town the party is currently in. This call should not be used in outdoor mode.
short current_town_size()
Returns the size of the town the party is in (0 - 64x64, 1 - 48x48, 2 - 32x32).
void enable_add_chars(short can_add)
Sets whether the player can add new characters to his or her party in this town. Defaults behavior is that the player is not able to add characters when a new town is entered. This call needs to be used to enable adding characters every time the town is entered (probably in the state INIT_STATE).
If can_add is 1, the player can add new characters. If 0, player can no longer add new characters.
You should probably enable the player to add characters in at least the starting town.
short get_crime_level()
Returns the level of crimes that have been committed by the party in the current town.
void make_town_hostile()
Sets the town permanently to hostile (this can be undone with the call set_town_status). Sets all friendly characters to hostile.
void move_to_new_town (short new_town,short loc_x,short loc_y)
Immediately takes the party out of combat mode and moves them to town new_town, starting at {loc_x,loc_y}.
This call only works when called indoors. It will only function if called in a special encounter triggered by walking on a space. It won’t work in creature, terrain, or dialogue scripts.
short num_killed_in_town(short which_town)
Returns the number of hostile creatures that have been killed in town which_town.
void place_monster(short loc_x,short loc_y,short monst_type,short not_worth_xp)
Makes a monster of type monst_type appear at {loc_x,loc_y}. It is hostile to the party. The game has 34 slots reserved for wandering monsters and creatures made using the place_monster function.
If not_worth_xp is 0, than the creature is a normal creature. If not_worth_xp is 1, the creature drops no items and awards no experience when killed. If not_worth_xp is 2, the creature is considered to be summoned. It drops no items, isn't worth xp, and disappears a few turns later.
The summoned creature uses its default script.
void set_crime_tolerance(short tolerance)
Sets the crime level the town will endure before it goes hostile. This call needs to be made each time the party enters the town.
void set_items_not_property()
Sets all items in the current town to not be someone else’s property (so the party can now get them without penalty).
void set_town_status(short which_town,short new_status)
Manually sets town which_town to status new_status. For values of new_status, see description of function town_status.
void set_town_visibility(short which_town,short town_visible)
Sets whether town which_town is visible and can be entered when party is outdoors. If town_visible is 1, party can see. Otherwise, is not visible. When the scenario is started, all towns default to being visible.
short spawn_creature(short which_char)
Makes one of the town’s creatures appear. which_char is the number the creature would have in the game that is not a party member (so it is between 6 and 119). If that creature is not currently alive, it becomes alive, at that creature’s spawning point. Returns 1 if a creature appears, 0 otherwise.
Example: The first creature you place in a town would be creature 6 in the game. If you use the call spawn_creature(6), this creature would appear in the game, unless it is already alive.
short teleport_party(short new_loc_x,short new_loc_y,short fade_type)
mode -
| 0 | Full teleport flash |
| 1 | No teleport flash |
| 2 | Only fade flash |
short town_status(short which_town)
Returns the status of which_town. Status values are:
| 0 | Never been entered. |
| 1 | Party has entered. |
| 2 | Party has entered, town hates. |
| 3 | Town has been destroyed. |
Note: the call town_status only works when passed the valus -1 (for the current town). So town_status(-1) will return the status of the current town, but town_status([any other number]) won't work correctly.
void turn_off_training(short turn_off)
Every town defaults to let the party train in it. If you don’t want the party to be able to train in the current town, use this call. If turn_off is 1, the party can’t train in this town. If it is 0, they can.
Outdoor Calls
These calls are all only useful when outdoors. For more information (and to learn how outdoor sections are numbered) )read the chapter on the outdoors.
void create_out_spec_enc(short which_enc)
Creates a copy of the special encounter which_enc (which is from 0 to 3) next to the party.
short current_out_section()
Returns the number of the outdoor section the party is currently in.
void eliminate_outdoor_enc(short stuff_done_1, short stuff_done_2)
Used to destroy groups of creatures outdoors. Each outdoor encounter can have a Stuff Done flag set which eliminates the encounter (makes it not appear). This call is given {stuff_done_1, stuff_done_2}, which are the two coordinates of a Stuff Done flag. This call eliminates all outdoor encounters whose elimination Stuff Done flag is {stuff_done_1, stuff_done_2}.
void out_move_party(short loc_x,short loc_y)
Relocates the party to space {loc_x,loc_y} in the current outdoor section.
short outdoor_enc_exists(short stuff_done_1, short stuff_done_2)
Used to check if a particular group of creatures wandering outdoors exists. Each outdoor encounter can have a Stuff Done flag set which eliminates the encounter (makes it not appear). This call is given stuff_done_1, stuff_done_2, which are the two coordinates of a Stuff Done flag. This call returns 1 if there is currently an existing group of outdoor creatures with a matching Stuff Done flag which eliminates it.
void outdoor_enc_result(short which_result)
This call only has an effect when it is called as a result of the party encountering a group of creatures outdoors. It determines whether the party will have to fight the encounter or not. The meanings of which_result are as follows:
| 0 | Fight as normal |
| 1 | Don’t have to fight |
| 2 | Don’t have to fight, encounter disappears, but can reappear later |
| 3 | Don’t have to fight, encounter disappears, sets the encounter’s defeat Stuff Done flag (if it has one) to 1. (So it disappears forever.) |
void place_out_spec_enc(short which_enc,short where_x,short where_y)
Creates a copy of the special encounter which_enc (which is from 0 to 3) at the location {where_x,where_y} in the current outdoor section.
void set_out_fight_town_loaded(short which_town)
This call only has an effect when it is called as a result of the party encountering a group of creatures outdoors. It sets the town terrain that is loaded for the fight to take place in. which_town is the town that is loaded when party fights an outdoor combat on this terrain type. If which_town 0-999, loads the town in the current scenario. If 1000 + x, loads town x in the file Blades of Avernum Out Fight
The Passage of Time
Time in Blades of Avernum is measured in “ticks”. At the beginning of a scenario, the number of ticks that have elapsed is 0. Every turn that passes in town or every round of combat that ends increases the number of ticks by 1. Every turn that passes outdoors increases the number of ticks by 10 (5 if on a horse).
There are 5000 ticks in a day. The first eighth and last eighth of every 5000 tick period are nighttime.
There are 280 days in each year (numbered 0 to 279). There are eight months in the year, each of which have 35 days.
void force_start_day(short which_day)
lets you manually set the day of the year the scenario starts. Which_day is normally 0 to 279. If which_day is –1, the scenario has no dates.
short get_current_tick()
Gets the number of ticks (i.e. turns/combat rounds) that have elapsed since the scenario began. This will be a number from 0 to 29999, and wraps around to 0 when past 29999.
void set_ticks_forward(short num_ticks)
Manually changes the number of ticks that have happened since the scenario started (because the party sleeps, for example). num_ticks can be negative.
short tick_difference(short time1,short time2)
Returns the number of turns difference between time1 (the earlier time) and time2 (the later time).
short what_day_of_scenario()
Returns how many days have passed since the current scenario began.
short what_day_of_year()
Returns what day of the year it is (a number from 0 to 279).
Miscellaneous Special Calls
void create_text_bubble(string bubble_text)
This call only has an effect when called from a creature or terrain script. Creates a text bubble with text bubble_text above the creature/terrain spot for a short time. The text can be at most 38 characters long. This call has no effect if called in combat.
If you pass empty text (i.e. create_text bubble("")), the current text bubble is removed. Also, if there is already a text bubble on the creature/terrain spot, this call is ignored.
void drop_item(short which_item)
This call only has an effect when called from a creature or terrain script. Creates an item of type which_item and puts it on the ground on the creature location or terrain spot. Even if the space has a container, the item will not be marked as contained.
short get_char_who_stepped_on()
This call is only used for custom terrain and floor types which call a state in the scenario script when stepped on (when the floor/terrain type’s special property is set to 8).
If in town mode, returns –1 (the whole party is considered to have stepped on the space). If in combat mode, returns the number of the character who stepped on the space.
void make_wandering_monst()
Immediately spawns a group of wandering monsters. You can use this function in town or outside.
void put_object_on_waypoint(short which_object,short which_point)
Creates an item of type which_item and puts it on the ground on waypoint which_point. Even if the space has a container, the item will not be marked as contained.
short run_bash_door(short difficulty)
This call only has an effect when called from a terrain script. Has the party member with the highest strength bash the object, and requires a strength of at least difficulty to succeed. Returns 1 if success, 0 otherwise.
short run_pick_lock(short difficulty)
This call only has an effect when called from a terrain script. Has the party member with a lockpick and the highest Tool Use attempt to manipulate the object, and requires a Tool Use (plus bonuses from items) of at least difficulty to succeed. Returns 1 if success, 0 otherwise.
short set_ter_script_mode(short which_script,short what_setting)
For terrain script which_script, sets how often it is run. Values for what_setting are:
| 0 | call every 8 moves, but not if party is far away |
| 1 | Call every 8 moves, even if party is far away |
| 2 | Call every move, but not if party is far away |
| 3 | Call every move, even if party is far away |
void set_terrain_memory_cell(short which_ter_script,short which_cell,short new_value)
For terrain script which_ter_script, sets cell memory which_cell to new_value.
void text_bubble_on_char(short which_char, string bubble_text)
Creates a text bubble with text bubble_text above creature which_char. The text can be at most 38 characters long. This call will create a text bubble if called in combat. However, you shouldn't make a text bubble in combat unless a cutscene is happening.
If you pass empty text, the current text bubble is removed. Also, if there is already a text bubble on the creature/terrain spot, this call is ignored.
Terrain Checking and Modification
Only a few of these calls can be used outdoors. In this case, {x,y} is a location in the current outdoor section. The rest of the calls only work in town mode. It is specifically noted if a call can be used outdoors.
Note that outdoor terrain is reloaded every time a save file outdoors is loaded. Changes made by set_terrain will then be erased. Bear this in mind when altering outdoor terrain.
void change_blocked(short x, short y,short blocked)
Change whether a space in town is blocked. If blocked, NPCs will not step on it and the party will not be placed onto it when the party enters a level or ends combat. If blocked is 0, the space becomes not blocked. If 1, the space becomes blocked.
Note that this does not affect if the floor or terrain in that space is set to be blocked.
This call does not work outdoors.
short get_floor(short x,short y)
Returns the floor type at {x,y}. This call can be used outdoors.
short get_height(short x,short y)
Returns the height at {x,y}. This call can be used outdoors.
short get_terrain(short x,short y)
Returns the terrain type at {x,y}. This call can be used outdoors.
void flip_terrain(short x,short y)
Change the terrain at spot {x,y} to its te_swap_terrain value (set in the object definition script). For example, sets a closed gate at {x,y} to be an open gate. If no te_swap_terrain value has been set for the terrain type at {x,y}, does nothing. This function will not work properly outdoors.
short is_blocked(short x,short y)
Returns 1 if the given space is designated as blocked, and 0 otherwise. Note this doesn’t check if the floor or terrain type in that space is blocked, just if the space was made blocked in the editor. This call doesn’t work outdoors.
short is_field_on_space(short x,short y,short field_type)
Returns 1 if a field of type field_type is on space {x,y}, 0 otherwise. The field types are:
| 0 | Sleep cloud |
| 1 | Fire wall |
| 2 | Antimagic |
| 3 | Stinking cloud |
| 4 | Ice wall |
| 5 | Blade wall |
| 6 | Quickfire |
short is_object_on_space(short x,short y,short object_type)
Returns 1 if an item of type object_type is sitting on space {x,y}, 0 otherwise. The object types are:
| 0 | Web |
| 1 | Barrel |
| 2 | Crate |
| 3 | Fire barrier |
| 4 | Force barrier |
| 5 | NE/SW Mirror |
| 6 | NW/SE Mirror |
short is_stain_on_space(short x,short y,short stain_type)
Returns 1 if a stain of type stain_type is on space {x,y}, 0 otherwise. Stain types are as follows:
| 0 | Small blood |
| 1 | Medium blood |
| 2 | Large blood |
| 3 | Small slime |
| 4 | Large slime |
| 5 | Dried blood |
| 6 | Bones |
| 7 | Rocks |
void put_field_on_space(short x,short y,short field_type)
Places a field of type field_type on space {x,y}. Field types are listed above. If field_type is -1, removes all fields from the space.
void put_object_on_space(short x,short y,short object_type)
Places an object of type object_type on space {x,y}, 0 otherwise. Object types are listed above. If object_type is -1, removes all objects from the space.
void put_stain_on_space(short x,short y,short stain_type)
Places a stain of type stain_type on space {x,y}. Stain types are listed above. If stain_type is -1, removes all stains from the space.
void set_floor(short x,short y,short floor_type)
Sets the floor type at {x,y} to floor_type. This call can be used outdoors.
void set_height(short x,short y,short height)
Sets the height type at {x,y} to new_height. This call can be used outdoors.
void set_terrain(short x,short y,short ter_type)
Sets the terrain type at {x,y} to ter_type. This call can be used outdoors.
void swap_floor(short x,short y,short floor_1,short floor_2)
If the terrain at spot {x,y} is floor_1, turns it to floor_2. otherwise, if it is terrain_2, turns it to floor_1. This function will not work properly outdoors.
void swap_terrain(short x,short y,short terrain_1,short terrain_2)
If the terrain at spot {x,y} is terrain_1, changes it to terrain_2. otherwise, if it is terrain_2, turns it to terrain_1. This function will not work properly outdoors.
Dialog Calls
void add_string(short which_string)
This call only works when called inside the code portion of a dialogue node. Sets the string which_string (which is from 1 to 8) to be displayed. This only has an effect if the string was already hidden by the remove_string or clear_strings calls.
void begin_shop_mode(char shop_name,char shop_desc,short which_shop,short price_adjust,short sell_adjustment)
Immediately puts the party in shopping mode, buying from which_shop, which has name shop_name and description shop_desc. price_adjust is a number from 0 to 6 determining how expensive the shop items are (0 - cheaper, 6 - more expensive). sell_adjustment is either -1 (which means the shop doesn’t buy items) or 0 to 6, a number which determines how much the shop pays for items (0 means the store pays more, 6 means pays less).
void begin_talk_mode(short start_node)
Begins talking mode, starting at node start_node. This should not be called while outdoors, or while entering or leaving town.
(Advanced detail: If a conversation is started from a creature or terrain script, there is a Done button in the Dialogue area (so the player can leave the conversation at any time). Otherwise, there will be no Done button, and the conversation can only end when the player reaches the end of a talking thread.)
short character_talking_to()
This call only functions when called while in talk mode. Returns the number of the character the party is currently talking to.
void clear_strings()
This call only works when called inside the code portion of a dialogue node. Hides all strings, so none of them are displayed. After this call is used, you should use the add_string call at least once, so the player doesn’t see an empty screen.
short current_personality()
This call only functions when called while in talk mode. Returns the number of the personality the player is talking to.
void remove_string(short which_string)
Hides string which_string (which is from 1 to 8), so it is not shown to the party when the dialogue node is displayed.
void set_char_dialogue_pic(short which_char_or_group,short which_sheet,short which_icon)
Gives the Creature/Group a dialogue picture, which will appear in the talk corner when they are talked to. This should probably be called when the town is entered. Dialogue pictures are placed in a sheet by themselves with no frame, and it is recommended that they are no larger than 64 x 64. The number of the graphic resource is which_sheet. which_icon is not used and should be left at 0. For more information, read Chapter 4.5.
Basic Dialog Box Calls
All of these calls are used to set up and display dialog boxes, where the player is given a host of options to select from. The dialog box you will build can have up to 6 chunks of text and 3 choices (each with text you provide).
To display a dialog box more complicated than just a chunk of text and an OK button (for this, use the message_dialog call), follow these steps:
- Call reset_dialog. This cleans up all the text and choices, and sets the first of the three choices to OK.
- Fill in the text you want to appear. Use the call add_dialog_str once for each line of text in the dialog.
- Set the text for up to three choices, using the call add_dialog_choice.
- Use the call run_dialog to make your dialog box appear and wait for the player’s choice. The call will return which of the three choices the player made (1 for 1st choice, 2 for 2nd, and 3 for 3rd). Call run_dialog(1) if you want there to be a Record button, and run_dialog(0) otherwise.
reset_dialog()
Erases all previous dialog box settings. Clears all text and all buttons, and then sets first button to say “OK”.
void add_dialog_choice(short which_option,char choice_text)
Adds a choice to the bottom of the dialog. which_option is the choice to add (0 to 2) and choice_text is the text for the choice (which can be up to 255 characters).
reset_dialog_preset_options(short dialog_options)
Resets dialog box, and then sets buttons and dialog text to one of a list of presets. The meanings of dialog_options are:
| 0 | Empty text, button 1 - ok |
| 1 | Empty text, button 1 - leave it, button 2 - take it |
| 2 | Text for a lever, button 1 - leave, button 2 - pull |
| 3 | Text for a portal, button 1 - leave, button 2 - enter |
| 4 | Text for a button, button 1 - leave it, button 2 - push |
| 5 | Text for stairs, button 1 - leave, button 2 - climb |
| 6 | Text for scrolls, button 1 - leave, button 2 - read |
| 7 | Text for a book, button 1 - leave, button 2 - read |
| 8 | Text for a wheel, button 1 - leave, button 2 - turn it |
| 9 | Text for a trapdoor, button 1 - leave, button 2 - climb |
| 10 | Text for a trap, button 1 - leave, button 2 - disarm |
void add_dialog_str(short which_str,char new_text,short indent)
Sets a line of text for the dialog you are about to display. which_str is the line of text to set (from 0 to 5), new_text is the text string (which can be up to 255 characters), and indent is the number of pixels to indent the line (usually 0).
void message_dialog(char text1,char text2)
This call does two different things depending on whether it is used in or out of dialogue mode.
If not called from dialogue mode, simply displays a dialog box with the text text1 and text2, and the option to select OK. This dialog box will have a Record button.
If called from a dialogue node (or from a town or scenario script called by that dialogue node), this call forces the next text the character says to be text1, followed by text2. Each of these pieces of text can be at most 255 characters long. (This option is provided mainly to provide backward compatibility with Blades of Exile. This sort of call was how custom dialogue text was set in Blades of Exile, but Blades of Avernum has far superior ways to do it.)
short run_dialog(short record_button)
Actually displays the dialog box you have created using the previous functions. Expects the player to choose an option and then returns what was chosen (which will be 1, 2, or 3). If record_button is 1, there will be a button in the dialog box which records the displayed text in the journal. If record_button is 0, the text can’t be recorded.
Advanced Dialog Box Calls
void check_text_response_match(char match_text)
Checks to see if the last text entered by the player (when you called get_text_response) matches the text match_text. If so, the next time you call got_text_match, it will return 1. Otherwise, it will return 0. Note that the checking is not case sensitive, so “FRED”, “Fred”, and “fred” are considered to all match each other.
short get_selected_pc()
Returns the number of the last character selected by run_select_a_pc, or -1 if no character has been selected.
Note that, whenever a script is called and starts to run, the last character selected is reset to -1. So, for example, if the party stepped on a space and triggered a town script and the very first call was get_selected_pc, the call would return -1, no matter what scripts had done earlier.
void get_text_response(char top_text)
Brings up a dialog box asking the player to enter a chunk of text. The text top_text will appear on the dialog box above the text entry field. To then check to see if the player entered a certain word or phrase, use the calls check_text_response_match and got_text_match.
short got_text_match()
Returns 1 if the text entered by the player when you last called get_text_response matches the text checked for last time you called check_text_response_match, 0 otherwise.
void large_draw_pic_dialog(short what_pic,char label_text)
Brings up a dialog box that displays a large graphic (up to 400x400 pixels) you provide. The graphic will be labeled by the text label_text, which will be at the top. This text can be, at most, 100 characters long. The graphic that is displayed is sheet what_pic.
short run_select_a_pc(short select_mode)
Displays to the player a dialog box showing all of his or her party members. The player can either select a party member or the cancel button. The call returns 1 if the party selected a character, and 0 if the player hit Cancel. The character the player selected can be recovered using the call get_selected_pc.
The select_mode field determines what characters are made available for selection:
| 0 | Only living, present party members |
| 1 | Any party member, even a dead one |
If select_mode is 2, no dialog box is displayed. Instead, the choice the player made in any previous calls to run_select_a_pc is set to -1 (no character selected).
void small_draw_pic_dialog(short what_pic,char label_text)
Brings up a dialog box that displays a small graphic (up to 200x200 pixels) you provide. The graphic will be labeled by the text label_text, which will be at the top. This text can be, at most, 50 characters long. The graphic that is displayed is sheet what_pic.
Terrain Script and Creature Script Calls
These calls can only be made from a creature or terrain script. Note that none of these functions should ever be called outdoors.
short can_see_loc(short loc_x, short loc_y)
Returns 1 if there is a clear line of sight from the creature/terrain spot to space {loc_x,loc_y}, and 0 otherwise.
void damage_nearby(short damage_amount,short radius,short damage_type,short good_evil_or_all)
Does damage_amount damage of type damage_type to all characters visible to and within radius spaces of creature/terrain spot. If good_evil_or_all is 0, only party-friendly creatures are damaged. If good_evil_or_all is 1, only hostile characters are damaged. If good_evil_or_all is 2, everyone nearby is damaged.
Damage types - 0 - weapon, 1 - fire, 2 - poison, 3 - general magic, 4 - unblockable, 5 - cold, 6 – acid
short dist_to_char(short which_char)
Returns the distance of the creature/terrain spot from character which_char.
short dist_to_loc(short x,short y)
Returns the distance from the creature/terrain spot to location {x,y}.
short dist_to_party()
Returns the distance of the creature/terrain spot from the nearest party member.
Note: NPC's that have joined the party WILL NOT be considered as actually part of the party with respect to this call. This is probably a bug and not a feature, since another side effect of this quirk is that joined NPC's cannot open and close doors or search containers.
short floor_in_this_spot()
Returns the floor type the creature or terrain script is located on. This does not work outdoors.
void force_status_nearby(short status_amount,short radius,short what_status,short good_evil_or_all)
For all characters visible to and within radius spaces of creature/terrain spot, changes what_status by an amount equal to status_amount. This change cannot be resisted. If good_evil_or_all is 0, only party-friendly creatures are affected. If good_evil_or_all is 1, only hostile characters are affected. If good_evil_or_all is 2, everyone nearby is affected.
short get_memory_cell(short which_cell)
It returns the value of that creature or terrain script’s memory cell which_cell.
short get_nearest_char(short radius)
Returns the number of the character nearest to the creature/terrain spot which the creature/terrain spot has a clear sight line to. Returns -1 if no such character.
short get_nearest_evil_char(short radius)
Returns the number of the character nearest to the creature/terrain spot which the creature/terrain spot has a clear sight line to and which is hostile to the party. Returns -1 if no such character.
short get_nearest_good_char(short radius)
Returns the number of the character nearest to the creature/terrain spot which the creature/terrain spot has a clear sight line to and which is friendly to the party. Returns -1 if no such character.
void heal_nearby(short heal_amount,short radius,short good_evil_or_all)
Heals heal_amount damage to all characters visible to and within radius spaces of creature/terrain spot. If good_evil_or_all is 0, only party-friendly creatures are healed. If good_evil_or_all is 1, only hostile characters are healed. If good_evil_or_all is 2, everyone nearby is healed.
short my_loc_x()
Returns the x coordinate of the creature or terrain spot’s location. This does not work outdoors.
short my_loc_y()
Returns the y coordinate of the creature or terrain spot’s location. This does not work outdoors.
void restore_energy_nearby(short energy_amount,short range,short good_evil_or_all)
Restores energy_amount spell energy to all characters visible to and within radius spaces of creature/terrain spot. If good_evil_or_all is 0, only party-friendly creatures are energized. If good_evil_or_all is 1, only hostile characters are energized. If good_evil_or_all is 2, everyone nearby is energized.
void set_memory_cell(short which_cell,short new_value)
It sets the value of that creature or terrain script’s memory cell which_cell to new_value.
short set_script_mode(short what_setting)
For the currently running script (terrain or creature), sets how often it is run. Values for what_setting are
| 0 | call every 8 moves, but not if party is far away |
| 1 | Call every 8 moves, even if party is far away |
| 2 | Call every move, but not if party is far away |
| 3 | Call every move, even if party is far away |
void status_nearby(short status_amount,short radius,short what_status,short good_evil_or_all,short penalty)
For all characters visible to and within radius spaces of creature/terrain spot, changes what_status by an amount equal to status_amount. For hostile effects, resistances apply. The higher penalty is, the harder the effect is to resist. If good_evil_or_all is 0, only party-friendly creatures are affected. If good_evil_or_all is 1, only hostile characters are affected. If good_evil_or_all is 2, everyone nearby is affected.
short terrain_in_this_spot()
Returns the terrain type the creature or terrain script is located on. This does not work outdoors.
Terrain Script Calls
These calls can only be made from a terrain script. Note that none of these functions should ever be called outdoors.
short char_on_me()
Returns the number of the character standing on the terrain spot, or -1 if there is none.
short char_who_activated_script()
terrain scripts are called when a character steps on or searches them. This returns the number of the character that activated the script.
short get_mechanism_difficulty()
Gets the current complexity of the terrain script’s mechanism. See the chapter on terrain scripts for more information.
short get_physical_strength()
Gets the current physical strength of the terrain script. See the chapter on terrain scripts for more information.
void set_mechanism_difficulty(short new_difficulty)
Sets the current complexity of the terrain script’s mechanism to new_difficulty. See the chapter on terrain scripts for more information.
void set_physical_strength(short new_strength)
Sets the current physical strength of the terrain script to new_strength. See the chapter on terrain scripts for more information.
Movement, AI Functions
These calls are used to move around and otherwise manipulate creatures. Some of them can only ever be used inside a creature script. In general, you will probably only ever use any of these in a creature script.
short am_i_doing_action()
This function can only be called in a character script. Returns 1 if the character currently has a movement path set or a hostile target, 0 otherwise.
short approach_char(short which_char_or_group,short char_to_approach,short within_dist)
Has the character move closer to character char_to_approach. If the character is within within_dist, does not move any closer. Returns 1 if the character doesn’t start moving (because the target character is close, dead, or can’t be reached, or because the character is already moving somewhere), 0 otherwise. If this function is called while the character is already moving, nothing happens and 0 is returned.
void approach_ter_script(short which_char,short which_ter_script, short distance)
Has the character move closer to the terrain spot with script which_ter_script. If the character is within within_dist, does not move any closer. Returns 1 if the character doesn’t start moving (because the target script doesn’t exist or can’t be reached, or because the character is already moving somewhere), 0 otherwise.
short approach_waypoint(short which_char_or_group,short waypoint_to_approach,short within_dist)
Has the Creature/Group start to approach waypoint_to_approach until they are within within_dist spaces of it. Returns 1 if the character doesn’t move (because it is close already or can’t find a path there), 0 otherwise.
void fidget(short which_char_or_group,short fidget_chance)
If character is moving, nothing happens. If not, there is a percentage chance equal to fidget_chance that the character will select a visible nearby spot randomly and move to it.
short flee_char(short which_char,short target_char,short new_dist)
Has the Creature/Group move away from target_char until it is at least new_dist spaces away. Returns 1 if the character doesn’t move (because it is the right distance already or can’t find a good point), 0 otherwise.
short maintain_dist_to_char(short which_char_or_group,short target_char,short new_dist)
Has the Creature/Group move to a random point a distance close to new_dist from character target_char. Returns 1 if the character doesn’t move (because it is the right distance already or can’t find a good point), 0 otherwise.
short move_to_loc_x_y(short which_char_or_group,short x,short y)
Has the character move as close a possible to location {x,y}. If the character is already moving, the old destination is forgotten. Returns 1 if the character doesn’t move (because it is close already or can’t find a path there), 0 otherwise.
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 return_to_start(short which_char_or_group,short what_dist)
Has the character return to the point it started at. Returns 0 if the character is not there and can move closer, returns 1 if it is there or if the path there is completely blocked.
If the character is currently moving, this call will leave the current destination unchanged and the call returns 0. If you want the character to return to start no matter what, use the stop_moving call first.
void stop_moving(short which_char_or_group)
Immediately makes the Creature/Group stop moving and forget the path it was traveling along.
Combat and Targeting Calls
These calls are used to control creatures. Some of them can only ever be used inside a creature script. In general, you will probably only ever use any of these in a creature script.
void do_attack()
This call can only be used inside a creature script, and only has an effect if the creature in question has a legitimate hostile target. In this case, the creature will select an attack and use it against the enemy. The attack might be a spell, a hostile ability, or a melee attack. If the target is far away and a melee attack is selected, the creature will move closer to its target. Action points for the creature’s actions are deducted automatically. This call can be used even when not in combat.
void do_attack_tactic(short which_tactic)
This call is exactly like do_attack, except that you have the option to force the character to strongly prefer a certain sort of attack. The options for which_tactic are:
| 0 | Act normally. (As if do_attack was used.) |
| 1 | Strongly prefer firing missiles or using innate special ability. |
| 2 | Strongly prefer to cast a spell. |
| 3 | Strongly prefer to use an item in its inventory. |
short get_aggression(short which_char)
Returns the current aggression of which_char.
short get_courage(short which_char)
Returns the current courage of which_char.
short get_strategy(short which_char, short dummy)
Returns the current strategy of which_char. See set_strategy for the meanings of the different strategy values. The value of dummy is ignored.
short get_target()
This call can only be used inside a creature script. Returns the current hostile target of the creature, or -1 if there is no target.
short select_target(short which_char_or_group,short within_range,short other_criterion)
Has the Creature/Group search for and set its hostile target to the best enemy within within_range spaces. This only sets the hostile target. It does not actually make the character do anything. If an appropriate target is found, the call returns 1, 0 otherwise.
If this character has been alerted (by seeing a foe or use of the alert_char function), the character is hostile to the party, and no foes are visible within within_range spaces, the character picks a random member of the party to be its target. It will then hunt the party down (possibly from a long way away).
The field other_criterion allows you to give special criterion for when selecting the target:
| 0 | Takes any target available. |
| 1 | The target must be wounded. |
| 2 | The target must be heavily wounded. (i.e. Has lost over half its health.) |
Advanced: The character’s aggression (which always defaults to 100) affects whether the character can get a target. When the call tries to get a target, the aggression is the percentage chance that the character will be able to get a target (so if aggression is 75, has a 75% chance of getting a target and within_range is reduced by a quarter). Also, the range is reduced to the aggression percentage (so if aggression is 75 and within_range is 8, it is changed to 6).
void set_aggression(short which_char_or_group,short new_value)
Sets the aggression value of the Creature/Group to new_value, which should be from 0 to 100.
A note about aggression. If a character tries to get a target and its aggression level prevents it, the creature’s turn ends immediately.
void set_courage(short which_char_or_group,short new_value)
Sets the courage value of the Creature/Group to new_value, which should be from 0 to 100. A character whose courage is 0 always flees.
void set_strategy(short which_char_or_group,short new_value)
Sets the strategy value of the Creature/Group to new_value, which has meanings as follows:
| 0 | Regular creature. |
| 1 | Archer/caster. Always seeks to maintain a safe distance from its target. |
| 10 | Regular creature, game never changes its target. (Normally, the game will switch a creature’s target to someone much closer.) |
| 11 | Archer/caster, game never changes its target. |
void set_target(short which_char_or_group,short what_target_or_group)
Manually sets the hostile target for the Creature/Group to what_target. If the value what_target_or_group is the number of a character (i.e. less than 120), sets the target to that character. If the value is for a group (i.e. 1000 + x, for group x), sets the target to be a random member of that group. If the target given is not legitimate (because the given creature is dead, doesn’t exist, or is not hostile), the hostile target is set to -1.
short target_ok()
This call can only be used inside a creature script. Returns 1 if the creature has a hostile target and it is alive, 0 otherwise.
short who_hit_me()
This call can only be used inside a creature script. It is used by a creature script to determine if the creature has been attacked. The call returns -1 if the character has been attacked, and otherwise returns the number of the creature who last attacked it. This value is remembered by the creature but it is set back to -1 at the end of every turn/combat round (so your script gets one chance to check this, and then it is set back to -1).
Grouping Calls
These calls are all used to manage groups: to make them, destroy them, and see who is in them. Remember that group 0 is reserved for the party, and that the other groups are numbered 1 to 7.
To use a call like set_name or set_level on a group, add 1000 to the number of the group and give that for the value of which_char_or_group. (So to change the level of everyone in group 3 to 45, use the call “set_level(1003,45)”.)
void add_char_to_group(short which_char,short which_group)
Places character which_char in group which_group.
void add_range_to_group(short first_char,short last_char,short which_group)
Places the range of characters from first_char to last_char into group which_group.
short char_in_group(short which_char,short which_group)
Returns 1 if character which_char is in group which_group, 0 otherwise.
void clear_all_groups()
Removes all characters from all groups (except group 0).
short first_group_member(short which_group)
Returns the first character in the group (the first character added to it), or -1 if the group is empty.
short num_chars_in_group(short which_group)
Returns the number of characters in group which_group.
short random_group_member(short which_group)
Returns a randomly selected member of group which_group, or -1 if the group is empty. Remember that group 0 is the party.
void remove_char_from_group(short which_char,short which_group)
Takes character which_char out of group which_group.
short what_group_in(short which_char)
Returns the group the character is in, or -1 if the character is in no group. If the character is in multiple groups, returns the first one.
If this call is used in a creature's script, which_char(ME) returns the group the creature is in.
Messaging Calls
These calls are all used to pass messages to characters and terrain scripts, and for those scripts to check for and handle the messages. Remember that, right after a character’s or terrain’s script is run, its message is set back to -1, so if you don’t check for a message once, the creature/terrain will miss it.
These calls have no effect outdoors.
void broadcast_char_message(short message_range,short what_message,short must_match_attitude)
This call only has an effect when called from a creature or terrain script. This call broadcasts to every visible creature within message_range spaces of the creature/terrain spot the message what_message. If the message is being broadcast from a creature script and must_match_attitude is 1, the message is only given to creatures with the same attitude as the one sending the message. If the message is being broadcast from a terrain script, must_match_attitude is ignored.
void broadcast_message_from_x_y(short x,short y,short what_message,short message_range)
This call gives message what_message to every creature and terrain script that is within message_range spaces of {x,y}, and can be seen from {x,y}.
void broadcast_terrain_message(short message_range,short what_message)
This call only has an effect when called from a creature or terrain script. This call broadcasts to every visible terrain script within message_range spaces of the creature/terrain spot the message what_message.
void give_char_message(short which_char,short what_message)
This gives message what_message to character which_char.
void give_ter_script_message(short which_ter_script,short what_message)
This gives message what_message to terrain script which_ter_script. You can find out the number of a terrain script by selecting it in the editor.
short my_current_message()
This call only has an effect when called from a creature or terrain script. Returns the character/terrain spot’s current message, or -1 if there is no message.
Advanced Item Management Calls
These calls have to do with getting information on items in the party's inventory. You can search through a character's items, see what he or she has, and destroy or take them away. Please be very careful with these calls! People work very hard to assemble their gear, and it should not be taken away arbitrarily.
Each character has 40 item slots, numbered 0 to 39. The first 13 (numbered 0 .. 12) are equipped items. The rest are items in the pack.
The equipped item slots are numbered as follows:
| 0 | Armor |
| 1 | Weapon |
| 2 | Missile |
| 3 | Boots |
| 4 | Helmet |
| 5 | Shield |
| 6 | Necklace |
| 7 | Bracelet |
| 8 | Ring |
| 9 | Gloves |
| 10 | Cloak |
| 11 | Pants |
| 12 | Ammunition |
Important note: You can not use ME for which_char for these calls. You must give the actual number for the creature. Inside a creature script, this can be gotten with the my_number() call.
void destroy_char_item(short which_char,short which_slot)
Destroys the item held by character which_char in slot which_slot. Be very, very careful when using this call.
If you destroy an item in a pack (i.e. not equipped), all items in higher slots shift down.
short get_item_variety(short item_type)
Returns the variety of item type item_type (which is from 1 to 499). For the list of what the different item varieties are, consult the section on scripting item types.
short item_type_in_slot(short which_char,short which_slot)
Returns the type of item held by character which_char in slot which_slot. The item type will be from 1 to 499, or -1 if there is no item in that slot.
void take_item_char_item(short which_char,short which_slot,short loc_x,short loc_y)
Takes the item held by character which_char in slot which_slot and moves it to space {loc_x,loc_y} in the current town. Do not use this call outdoors.
NPCs Joining Party Calls
These calls are used to assign characters to travel with the party. When not in combat, these characters will just follow the party around.
A character who joins the party must have its own script. When in combat mode, they will act according to its script. When do_attack is called, the character will look for targets and attack them. It will not, however, move too far from the party when hunting targets.
short add_char_to_party(short which_char)
Attempts to take character which_char and add it to the party. Character slots 4 and 5 are reserved for characters traveling with the party. If both of these slots are full, the call fails. You can't use this command when outdoors or in combat. It functions best when used during a conversation.
Returns 1 if the character is added to the party, 0 otherwise.
When a character is added to the party, its character ID remains unchanged. The calls character_in_party and remove_char_from_party will refer to this character ID.
short character_in_party(short char_flag)
If a character with character ID char_flag is in the party, returns their character number (which will be 4 or 5). Otherwise, returns -1.
short remove_char_from_party(short char_flag)
Checks if a creature with character ID char_flag is in the party. If so, erases that character. It disappears, and no items are dropped. Returns 1 if a creature is erased, 0 otherwise.
short this_char_is_in_party()
This call can only be used inside a creature's script. Returns 1 if the creature is part of the party, 0 otherwise.
Splitting Up the Party Calls
You can split up the party, so the player only gets to play with one of his or her characters for a while.
You can only split the party indoors. You must make sure that the split character can’t leave town without reuniting the party.
The call try_to_split_party splits up the party and moves the lone character somewhere else in the town. The reunite_party call restores the party at the location where they split up.
void reunite_party()
If the party is not split up, this call does nothing. Otherwise, it immediately reunites the party at the point where they were split up.
void split_off_one_char(short dest_x,short dest_y,short telep_noise,short which_char)
Splits up the party (so character which_char is active and the rest are absent). The lone active character is placed at {dest_x,dest_y}. If telep_noise is 0, the split is silent. If it is 1, a teleport noise plays.
short try_to_split_party(short dest_x,short dest_y,short telep_noise)
Splits up the party (so only one character is active and the rest are absent). Asks the player to choose a character, with the option of canceling. If the player cancels, the party is not split and the call returns 0. Otherwise, the lone active character is placed at {dest_x,dest_y} and the call returns 1. If telep_noise is 0, the split is silent. If it is 1, a teleport noise plays.
Custom Item Ability Calls
These calls are only used for coding the effects of items with custom abilities. When such an item is used, it calls a state in the scenario script. These calls can only be made in that state.
short who_is_custom_item_target()
If the item is used on enemies (like wands), returns the number of the character it was targeted on.
short who_used_custom_item()
Returns the number of the party member who used the item.
Custom Character Ability Calls
These calls are only used for coding the custom special abilities. When such an ability is used, it calls a state in the scenario script. However, these calls can be used in any sort of script. There are 4 special ability slots, numbered 0 to 3.
void change_custom_abil_uses(short which_char,short which_abil,short what_change)
For character which_char, changes the number of uses of ability which_abil by what_change (which can be negative).
short get_custom_abil_uses(short which_char,short which_abil)
For character which_char, returns the number of uses of ability which_abil the character currently has.
void init_special_abil(short which_abil,string abil_name,short what_state_to_call)
This call should probably be placed in the state LOAD_SCEN_STATE in the scenario script. For custom ability which_abil, sets its name to abil_name and the state in the scenario script that is called when the ability is used to what_state_to_call.
short who_used_custom_abil()
This call returns the number of the character in the party who used the custom ability.
Cutscene Calls
These calls are used to manually create cutscenes, dramatic scenes where the player watches what goes on. These calls can position characters, move them around, shift the screen view, and pause the action. None of these calls can be used outdoors.
Note that calls that move characters or shift the view do not actually redraw the screen. You need to use the force_instant_terrain_redraw call for that.
When you have a cutscene and want to leave the party where you moved them, be sure to use a block_entry call.
void erase_text_bubbles()
Erases all text bubbles on all characters and terrain spots.
void force_instant_terrain_redraw()
Immediately redraws all of the terrain. You need to use this call whenever you want the changes made by the Cutscenes calls to be displayed to the player.
void force_view_center(short x,short y)
Shifts the terrain view so its center is at {x,y}. Be sure that {x,y} is somewhere in the town visible to the party.
void march_party(short x,short y)
Has your party walk a space in the animation. Moves the lead character to spot {x,y}, and has each following character move to the space vacated by the previous character.
void pause(short tenths_of_second)
Stops the game for tenths_of_second tenths of a second.
void relocate_character(short which_char,short x,short y)
Moves character which_char to {x,y}. This call doesn't check whether the character can legally be there, so be careful not to move a character into solid terrain or onto another character. If the character is dead or doesn't exist, nothing happens.
Note: The ME paramater doesn't work with relocate_character.
void set_character_facing(short which_char_or_group,short direction)
Changes a character which_char's facing. Values for direction: 0 - north, 1 - nw, 2 - west, 3 - sw, 4 - south, 5 - se, 6 - east, 7 - ne.
void set_character_pose(short which_char_or_group,short pose)
Sets which pose (version of the graphic) to use for the character. The change will not be visible until you use the force_instant_terrain_redraw call. Note that not all poses are available for the smaller graphic template. When the cutscene is done, you should restore all poses to 0.
The pose values are: 0 - standing. 1 - attacking. 2 - combat ready. 5 - sitting in chair facing north. 6 - sitting in chair facing west. 7 - sitting in chair facing south. 8 - sitting in chair facing east. 11-14 - death poses 1-4.
void set_total_visibility(short mode)
Changes how the game determines whether spaces out of view of the party are visible or not. If mode is 0, the player can not see spots of out view (the normal setting). If mode is 1, the player will be able to see every spot on the screen, whether visible to characters or not. This is used to show areas in cutscenes that are out of view. If you set every space as visible, be sure to set them as not visible before ending the cutscene.
String Manipulation Calls
These calls are designed to give the scenario designer a lot more control over the text displayed to the player. They’re a little complicated, but much more powerful.
Blades of Avernum maintains a string buffer. It is a 255 character long chunk of text in memory. You can clear this buffer, append chunks of text to it, and then dump the buffer into a string variable.
For example, here is a bit of code.
string sample_string;
clear_buffer(); // empties out the string buffer.
append_string(“Hello, “); // puts this text into the buffer
append_string(“friend.”); // adds this text to the end of the buffer
get_buffer_text(sample_string); // the buffer is copied into string variable sample_string
print_str(sample_string); // prints “Hello, friend.” to the text area
These calls were added for Scenario Format Version 2, only use them with Mac version 1.1 or later or Windows version 1.0 or later.
void append_char_name(short which_char)
Appends the name of the character which_char to the end of the string buffer.
void append_number(short num)
Appends the number num to the end of the string buffer.
void append_string(string source_string)
Appends the text source_string to the end of the string buffer. If the result would be longer than 255 characters, the text is truncated.
void clear_buffer()
Empties the text buffer. Sets it to a blank string.
void get_buffer_text(string dest_string)
Dest_string must be a string variable. Copies the text in the buffer into dest_string.
Debugging Procedures
These are all debugging functions, used to provide information while you write a scenario. They probably should be removed before you actually release your scenario to the public.
void print_num(short num)
Prints the number num in the text area.
void print_nums(short a,short b,short c)
Prints the numbers a, b, and c in the text area.
turn_on_debug_mode()
Enables debug mode for your scenario. To turn on debugging mode, type “}”, followed by “=” (so a right bracket, followed by an equals sign). To turn off debugging mode, type an equals sign. Once on, you can use the following commands:
| Shift-’k’ | Kills all hostile monsters in the whole town. |
| Shift-’m’ | Magic map. All creatures in the area will show up on the map. Type Shift-’m’ again to turn this off. |
| Shift-’g’ | Enter ghost mode. You will be able to walk through walls, and even through blackness. Type Shift-’g’ again to turn this off. |
| Shift-’h’ | Heals and restores spell energy for everyone in your group. |
| Shift-‘l’ | Add light. Gives the party 100 more turns of light. |
| Shift-‘i’ | Advances the time in the scenario one day. |
| Shift-‘s’ | Set special items. Dialog boxes will come up asking you for two numbers. The first number you give is the number of a special item. The second number is the number of that special item the party would be set to have> (so if you enter 12 and 4, the party will have 4 of special item 12.) |
| Shift-‘f’ | Set Stuff Done Flags. You will be asked for 3 numbers. The first two numbers are the coordinates of a stuff done flag. If the third number is –1, you will be told the value of that flag in the text area. Otherwise, that SDF will be set to the third number. (So if you enter 5, 23, and –1, then the text area will tell you the value of SDF(5,23). If you enter 5, 23, and 8, then SDF(5,23) will be set to 8. |
This call should definitely be removed before you release your scenario.
Debug mode is automatically turned off whenever you load a saved game or enter a new scenario.