Specials Functions 



Index

1.  Communications Functions
2.  Flow Control Functions
3.  Functions for All Objects
4.  Functions for Item Objects
5.  Functions for Individual 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</A>("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

   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

   Example:
      send_actor(get("actor", "title"), " stoops down to pick up the amulet.\n");


set

   Format: set({param}, {attribute}, {value});
   Desc: Sets the attribute listed for the parameter given to the value indicated

   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

   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:


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_title("primary"), " 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:



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 Individual 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: get_counter({param}, {specialname|this}, {value});

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