AvernumScript/Appendix/Basic Script and IO Calls

unknown 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 string str, followed by the number num_to_print, followed by the string str2.

Example:

print_big_str(“You are hit for “, 10000, “ damage.”); // Prints “You are hit for 10000 damage.” to the text window.

unknown print_big_str_num(string str,short num_to_print,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.

Values for do_blockage are:

0	– Allow access/entry.
1	– Block access/entry.

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); // Would return 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()

Self explainatory.

Returns:

0	– Party is not in combat mode.
1	– Party is in combat mode.

short is_outdoor()

Returns:

0	– Party is not in outdoor mode.
1	– Party is in outdoor mode.

Notes:

• Being in combat whilst outdoors does not count as being in outdoor mode.

short is_town()

Self explainatory.

Returns:

0	– Party is not in town mode.
1	– Party is in town mode.

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 text to_print 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 incidental sounds are turned off, they stay off unless this call is used to turn them on again.

Values for on_or_off are:

0	– Incidental sounds are turned on.
1	– Incidental sounds are turned off.

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).

Notes:

• See Constants, which lists constants and their known values (if any), that can be used for new_state.

void set_state_continue(short new_state)

Exactly like set_state(), except that it doesn’t stop running the script.

Notes:

• Despite the official documentation saying that set_state_continue() works exactly like set_state(), set_state_continue() does work in predefined states (at least some of them), and possibly all of them.
• See Constants, which lists constants and their known values (if any), that can be used for new_state.