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