Specials Functions

Index

1. Communications Functions
2. Flow Control Functions
3. Functions for All objects
4. Functions for Item objects
5. Functions for Individuals objects
6. Functions for Players
7. Functions for Merger Objects
8. Functions for Door Objects
9. Functions for Location Objects
10. Functions to Read and Manipulate Specials Attributes
11. Functions to Manipulate Numbers
12. Functions for Random Numbers
13. Miscellaneous Functions

1. Communications Functions

These are functions that can be used to send messages to single players or to all players in a room or a variation

send_actor

Format:	send_actor({phrase});
Desc:	Used to send a message to the player who is using the special.
Example:	send_actor("The ogre takes your ", get_name("primary"), "from you!\n");

send_room

Format:	send_room({phrase});
Desc:	Used to send a message to all players in a particular room.
Example:	send_room( "The ceiling gives way and collapses upon all in the room!\n");

send_room_except

Format:	send_room_except({phrase});
Desc:	Used to send a message to all players in a particular room except the actor.
Example:	send_room(get_name("actor"), " pulls the sword from the stone!\n");

send_room_except_dual

Format:	send_room_except_dual( {param}, {param}, {phrase});
Desc:	Used to send a message to all players in a particular room except the two indicated by the two params. The two params must be individuals or this will raise an error.
Example:	send_room_except_dual("actor", "primary", get_name("actor"), " knocks ", get_name("primary"), " over the head with a rock!\n");

send_obj_room

Format:	send_obj_room( {param}, {phrase});
Desc:	Used to send a message all players in a room where a particular object exists. If the object is contained by something, it sends the message to the location that contains the object.
Example:	send_obj_room("this", "The ", get_name("this"), " glows with an eerie yellow light!\n");

send_all

Format:	send_all( {phrase});
Desc:	Used to send a message all players in the mud.
Example:	send_all("An earthquake ravages the ground beneath your feet!\n");

send_all_except

Format:	send_all_except( {param}, {phrase});
Desc:	Used to send a message all players in the mud except the indicated player.
Example:	send_all_except("actor", "A soul-wrenching scream echoes throughout the land\n");

send_to

Format:	send_all_except( {param}, {phrase});
Desc:	Sends a message to an indicated player. If it is sent to a mobile, it just does nothing.
Example:	send_to("primary", get_name("actor"), " tosses something at you. Your skin starts to itch!\n");

send_holder

Format:	send_holder( {param}, {phrase});
Desc:	Sends a message to either the person holding the object indicated or if not held, the room it is lying in.
Example:	send_holder("this", "The ", get_name("this"), " starts to glow red-hot!\n");

tell_ind

Format:	tell_ind( {param}, {phrase});
Desc:	Performs a tell from the first parameter individual to the second parameter player. If the second parameter is a mobile, it just does nothing.
Example:	tell_ind("primary", "actor", "Could you spare a coin for a poor old man?\n");

2. Flow Control Functions

These are functions that can be used to jump around in the code.

goto

Format:	goto( {codemarker});
Desc:	Jumps to the indicated code marker in the code stack.
Example:	goto_if_less("weak", get_strength("actor"), 15);
	send_actor("You lift the warhammer with ease!\n");
	goto("end");
	weak:
	send_actor("It is way too heavy to lift by one so weak.\n");
	return_invalid_criteria();
	end:

goto_if_eq

Format:	goto_if_eq( {codemarker}, {value1}, {value2});
Desc:	Jumps to the indicated code marker in the code stack if the number or string value1 is equal to the number or string value2
Example:	goto_if_eq("nearly", get_counter(), 1);
	send_actor("You are running out of time!\n");
	goto("end");
	nearly:
	send_actor("You have one second left!.\n");
	end:

goto_if_neq

Format:	goto_if_neq( {codemarker}, {value1}, {value2});
Desc:	Jumps to the indicated code marker in the code stack if the number or string value1 is not equal to the number or string value2
Example:	goto_if_neq("timeleft", get_counter(), 1);
	send_actor("You have one second left!\n");
	goto("end");
	timeleft:
	send_actor("You are rapidly running out of time!.\n");
	end:

goto_if_less

Format:	goto_if_less( {codemarker}, {value1}, {value2});
Desc:	Jumps to the indicated code marker in the code stack if the number in value1 is less than the number in value2
Example:	goto_if_less("weak", get_strength("actor"), 15);
	send_actor("You lift the warhammer with ease!\n");
	goto("end");
	weak:
	send_actor("It is way too heavy to lift by one so weak.\n");
	return_invalid_criteria();
	end:

return_invalid_criteria

Format:	return_invalid_criteria();
Desc:	Exits the special with results that cause the command running the special to terminate. For instance, if the command get causes your special to be run and you return_invalid_criteria, it will stop running the get command.
Example:	goto_if_less("weak", get_strength("actor"), 15);
	send_actor("You lift the warhammer with ease!\n");
	goto("end");
	weak:
	send_actor("It is way too heavy to lift by one so weak.\n");
	return_invalid_criteria();
	end:

force_termination

Format:	force_termination();
Desc:	Exits the special with results that cause the ability to stop executing.
Example:	goto_if_less("end", 15, get_strength("actor"));
	send_actor("You strain but can't seem to pry the stone free!\n");
	force_termination();
	end:

force_success

Format:	force_success();
Desc:	Exits the special with results that cause the ability to succeed
Example:	goto_if_neq("end", 1, ind_holds("actor", "orboffire@lavacave"));
	force_success();
	end:

force_failure

Format:	force_failure();
Desc:	Exits the special with results that cause the ability to fail
Example:	goto_if_neq("end", 1, ind_holds("actor", "cursedlocket@castle"));
	force_failure();
	end:

3. Functions for All Objects

These are functions that manipulate values for all objects

get

Format:	get( {param}, {attribute});
Desc:	Gets the attribute listed from the parameter given
Example:	send_actor(get("actor", "title"), " stoops down to pick up the amulet.\n");
	end:
Possible Attributes:

name	the name of the object in {name}@{area} format
title	the title of the object
strength	strength of an individual
dexterity	dexterity of an individual
intelligence	how smart an individual is
health	current health of an individual
maxhealth	The top health a player can be
constitution	The constitution of the player (tied to maxhealth)
experience	Total global experience for this individual
location	gets the current location string

set

Format:	set( {param}, {attribute}, {value});
Desc:	Sets the attribute listed for the parameter given to the value indicated
Example:	goto_if_less("end", 15, get("actor", "strength"));
	send_actor("The gods take pity on your and raise your strength slightly.\n");
	set("actor", "strength", 20);
	end:
Possible Attributes:

name	the name of the object in {name}@{area} format
title	the title of the object
strength	strength of an individual
dexterity	dexterity of an individual
intelligence	how smart an individual is
health	current health of an individual
constitution	The constitution of the player (tied to maxhealth)
experience	Total global experience for this individual

force_success

Format:	destroy_this_obj();
Desc:	Destroys the object that the special is attached to, breaking out of the special
Example:	send_actor("The ", get("this", "title"), " crumbles away in your hands!\n");
	destroy_this_obj();

get_parent_name

Format:	get_parent_name();
Desc:	Returns the name of the parent of this clone. If not a clone, returns nothing.
Example:	goto_if_eq("fill", get_parent_name("primary"), "brasslantern@global");
	goto_if_neq("end", get_parent_name("primary"), "brasslamp@global");
	fill:
	send_holder("You fill the ", get("primary", "title"), " with the ", get("this", "title"), ".\n");
	set_a_counter("primary", "eachsecond", 10800);
	destroy_this_obj();
	goto("end");
	end:

is_individual

Format:	is_individual({param});
Desc:	Detects if the MudObject in question is an individual object. Returns a 1 if individual, 0 if not
Example:	goto_if_eq("ind", 1, is_individual("primary"));
	goto_if_eq("light", 1, is_itemflag_set("primary", "lightable"));
	goto("end");
	light:
	set_itemflag("primary", "lit");
	goto("end");
	ind:
	damage_individual("primary", 25);
	fight_player("primary");
	end:

clone_object

Format:	clone_object({objname}, {this\|primary\|secondary\|inloc\|actor\|none});
Desc:	Creates a copy of the object and places it in the location specified by the second parameter. Inloc refers to placing the object in the room that the object the special is attached to resides in.
Example:	send_actor("As you grab the rod, it turns to gold in your hands!\n");
	clone_object("goldrod@global", "actor");
	destroy_this_obj();

add_status

Format:	add_status({param}, {status_string);
Desc:	Marks an object with a particular status that will stay until removed or object reload.
Example:	goto_if_eq("remove", has_status("actor", "protection"), 1);
	send_actor("You grip the shaft and feel protection surround you!\n");
	add_status("actor", "protection");
	goto("end");
	remove:
	send_actor("You grip the shaft and feel protection drain from you!\n");
	remove_status("actor", "protection");
	end:

remove_status

Format:	remove_status({param}, {status_string);
Desc:	Removes the mark on an object that indicates a particular status was set to that object
Example:	goto_if_eq("remove", has_status("actor", "protection"), 1);
	send_actor("You grip the shaft and feel protection surround you!\n");
	add_status("actor", "protection");
	goto("end");
	remove:
	send_actor("You grip the shaft and feel protection drain from you!\n");
	remove_status("actor", "protection");
	end:

has_status

Format:	has_status({param}, {status_string);
Desc:	Indicates whether an object is marked with a particular status or not
Example:	goto_if_eq("remove", has_status("actor", "protection"), 1);
	send_actor("You grip the shaft and feel protection surround you!\n");
	add_status("actor", "protection");
	goto("end");
	remove:
	send_actor("You grip the shaft and feel protection drain from you!\n");
	remove_status("actor", "protection");
	end:

move_object

Format:	move_object({objname}, {param});
Desc:	Moves an object from its current location to another one
Example:	goto_if_eq("notmove", has_status("actor", "enchanted"), 1);
	send_actor("The orb flies into your hands from nowhere!\n");
	move_object("glowingorb@global", "actor");
	goto("end");
	notmove:
	send_actor("Nothing happens.");
	end:

object_exists

Format:	object_exists({param});
Desc:	Checks to see if there is an object attached to a param or not
Example:
	In the works

attach_special

Format:	attach_special({param}, {specialname});
Desc:	Attaches the special indicated by the second parameter to the object indicated by the first parameter.
Example:
	In the works

remove_special

Format:	remove_special();
Desc:	Removes the special that is currently running from the object it is attached to
Example:
	In the works

4. Functions for Item Objects

These are functions that manipulate values for item objects

is_itemflag_set

Format:	is_itemflag_set({param}, {flagname});
Desc:	Checks if the itemflag indicated by flagname is set or not. Returns 1 for set, 0 for not.
Example:
	In the works

set_itemflag

Format:	set_itemflag({param}, {flagname});
Desc:	Sets the itemflag indicated in parameter two on the object indicated in parameter one
Example:
	In the works

clr_itemflag

Format:	clr_itemflag({param}, {flagname});
Desc:	Clears the itemflag indicated in parameter two on the object indicated in parameter one
Example:
	In the works

5. Functions for Individuals Objects

These are functions that manipulate values for individual objects such as mobiles and players

ambush_individual

Format:	ambush_individual({mobilename}, {targetname});
Desc:	Clones the mobile indicated in parameter one and places it in the room with targetname, attacking targetname
Example:
	In the works

damage_individual

Format:	damage_individual({param}, {value});
Desc:	Damages the individual indicated by parameter one the amount indicated in parameter two. Kills them if they run out of health.
Example:
	In the works

fight_player

Format:	fight_player({param});
Desc:	Causes the individual in parameter one to start fighting the player running this special.
Example:
	In the works

is_indflag_set

Format:	is_indflag_set({param}, {flagname});
Desc:	Checks to see if the individual flag is set on the object in parameter one for the flag in parameter two. Returns 1 for set, 0 for cleared.
Example:
	In the works

set_indflag

Format:	set_indflag({param}, {flagname});
Desc:	Sets the individual flag indicated in parameter two on the object in parameter one.
Example:
	In the works

clr_indflag

Format:	clr_indflag({param}, {flagname});
Desc:	Clears the individual flag indicated in parameter two on the object in parameter one.
Example:
	In the works

ind_holds

Format:	ind_holds({param}, {object name\|object type});
Desc:	Indicates if a particular individual holds an object or certain type of object, such as a lit object.
Example:
	In the works
Possible Types:

fire	Anything that is burning
lit	Anything that is producing light, whether burning or glowing

6. Functions for Players

These are functions that manipulate values for players and perform actions on players

trans_player

Format:	trans_player({locationname});
Desc:	Transports the player running this special to the location indicated
Example:
	In the works

add_ability

Format:	add_ability({param}, {abilityname});
Desc:	Adds an ability to the player indicated by the first parameter
Example:
	In the works

remove_ability

Format:	remove_ability({param}, {abilityname});
Desc:	Removes an ability from the player indicated by the first parameter
Example:
	In the works

has_ability

Format:	has_ability({param}, {abilityname});
Desc:	Determines if the player indicated in parameter one has the ability indicated in parameter two. Returns 1 for the player has it, 0 for not
Example:
	In the works

boot_off

Format:	boot_off();
Desc:	Kicks the player off of the game.
Example:
	In the works

award_quest

Format:	award_quest({questname});
Desc:	Awards a quest indicated by questname to the player running the special, or the actor.
Example:
	In the works

advance_experience

Format:	advance_experience({param}, {abilityname}, {success\|failure}, {number});
Desc:	Awards experience points to the player indicated in parameter one to the ability listed in parameter two. The amount increased is influenced by the difficulty, specified in parameter four. It also is influenced by parameter three which awards higher experience for successfully using the ability.
Example:
	In the works

push_prompt

Format:	push_prompt({param}, {promptname}, {promptstring});
Desc:	Pushes a prompt onto the player's prompt stack. This means that the player will see this prompt until you pop his prompt off the stack, at which time it will revert back to the old prompt. Promptname is what you will call it and can be any single-word name you want. Promptstring is what the player will see as their prompt. Don't forget to pop off the prompt or you will annoy some players.
Example:
	In the works

pop_prompt

Format:	pop_prompt({param}, {promptname});
Desc:	Pops a prompt off the player's prompt stack. This means that the prompt will be destroyed and the old prompt will once again be in place. Promptname is what you called the prompt when you pushed it on.
Example:
	In the works

start_busy

Format:	start_busy({param});
Desc:	Marks a player as busy until stop_busy is called. This means the player can't perform many actions as they are busy tying a knot, loading a bow, etc.
Example:
	In the works

stop_busy

Format:	stop_busy({param});
Desc:	Clears a player so they are not marked as busy anymore and can resume normal actions.
Example:
	In the works

7. Functions for Merger Objects

These are functions that manipulate values for merger objects, from food to money.

decrement_number_of

Format:	decrement_number_of({param}, {number});
Desc:	Decreases the number of the merger indicated by the first parameter by the amount indicated in the second parameter.
Example:
	In the works

increment_number_of

Format:	increment_number_of({param}, {number});
Desc:	Increases the number of the merger indicated by the first parameter by the amount indicated in the second parameter.
Example:
	In the works

get_number_of

Format:	get_number_of({param});
Desc:	Gets the number of the merger indicated by the first parameter.
Example:
	In the works

8. Functions for Door Objects

These are functions that manipulate values for door objects.

get_door_state

Format:	get_door_state({param});
Desc:	Gets the door state as a string, either open, closed, locked, or mlocked.
Example:
	In the works

set_door_state

Format:	set_door_state({param}, {open\|closed\|locked\|mlocked});
Desc:	Sets the door state as a string, either open, closed, locked, or mlocked. Only with open can players traverse the door.
Example:
	In the works

9. Functions for Location Objects

These are functions that manipulate values for location objects.

get_loc_by_dir

Format:	get_loc_by_dir({currentlocname@area}, {the_direction});
Desc:	Gets the location from the location in parameter one to the direction in parameter two.
Example:
	In the works

display_loc

Format:	display_loc({param}, {locname@area});
Desc:	Displays the location in parameter two to the player in parameter one.
Example:
	In the works

10. Functions to Read and Manipulate Specials Attributes

These are functions that manipulate specials and their attributes.

decrement_counter

Format:	decrement_counter();
Desc:	Decreases the counter value by one. The counter is a value that remains attached to that special on that object even after the special is done executing.
Example:
	In the works

increment_counter

Format:	increment_counter();
Desc:	Increases the counter value by one. The counter is a value that remains attached to that special on that object even after the special is done executing.
Example:
	In the works

get_counter

Format:	get_counter({param}, {specialname\|this});
Desc:	Gets the counter value from the special indicated in parameter two attached to the object in parameter one. If "this" is passed as parameter two, it uses the special that is running the code for the counter.
Example:
	In the works

set_counter

Format:	set_counter({param}, {specialname\|this}, {value});
Desc:	Sets the counter value from the special indicated in parameter two attached to the object in parameter one. If "this" is passed as parameter two, it uses the special that is running the code for the counter. It sets the counter to the number in parameter three.
Example:
	In the works

set_param

Format:	set_param({primary\|secondary\|this}, {name@area});
Desc:	Replaces the default setting of the passed in parameters (this, primary, secondary) indicated in parameter one with the object in parameter two.
Example:
	In the works

get_store_int

Format:	get_store_int();
Desc:	Returns the storage integer which can be used to pass numbers out of this special execution for future executions. Much like the counter variable.
Example:
	In the works

set_store_int

Format:	set_store_int({value});
Desc:	Sets the storage integer which can be used to pass numbers out of this special execution for future executions. Much like the counter variable.
Example:
	In the works

get_target_str

Format:	get_target_str({value});
Desc:	Gets whatever is in the target string slot. Usually this is the player's input.
Example:
	In the works

11. Functions to Manipulate Numbers

These are functions that manipulate numbers and often return results

increment_number

Format:	increment_number({value}, {offset});
Desc:	Adds the value in offset to the value in the first parameter and returns the result.
Example:
	In the works

decrement_number

Format:	decrement_number({value}, {offset});
Desc:	Subtracts the value in offset to the value in the first parameter and returns the result.
Example:
	In the works

12. Functions for Random Numbers

These are functions that get and use random numbers

get_random

Format:	get_random({maxnumber});
Desc:	Gets a random number between 0 and the maxnumber passed in. Returns the results.
Example:
	In the works

select_rand_param

Format:	select_rand_param({param}, {param}, {param}, ...);
Desc:	Selects from an unlimited number of parameters one at random and returns it.
Example:
	In the works

13. Miscellaneous Functions

is_string_eq

Format:	is_string_eq({string}, {string}, {string}, ...);
Desc:	Is the first string equal to any of the unlimited number of following strings passed in. Returns 1 for equal, 0 for not equal.
Example:
	In the works

test_for_success

Format:	test_for_success({abilityname}, {difficulty});
Desc:	Given an ability and the difficulty of the maneuver, returns a value between 0 and 100 on the measure of success the player had in performing the ability.
Example:
	In the works

exit_tutorial

Format:	exit_tutorial();
Desc:	Exits a tutorial and places the player back into the tutorial chain, asking if they would like to use the next tutorial. Only works if the player is marked as being in a tutorial. This function will cause the special to exit.
Example:
	send_actor("The tutorial will be listed here soon!\n");
	exit_tutorial();