From the NannyMUD documentation

LAST CHANGE

2001-09-09

NAME

        living_functions - Functions for living objects.

INHERITS

        /obj/hook

INCLUDES

        log.h

FUNCTIONS

SETUP FUNCTIONS

        set_con
        set_dex
        set_gender
        set_int
        set_str
        setmin
        setmmin
        setmmout
        setmout
        silent_wear
        silent_wield
        wear
        wield

QUERY FUNCTIONS

        calc_armour_class
        can_put_and_get
        query_ac
        query_age
        query_alignment
        query_alt_attack
        query_attack
        query_attackers
        query_con
        query_dex
        query_exp
        query_fighting
        query_ghost
        query_hunting
        query_int
        query_invis
        query_mmsgin
        query_mmsgout
        query_msgin
        query_msgout
        query_name
        query_real_name
        query_str
        query_wc
        query_weight
        query_weapon_in_use
        query_wielded
        query_wielded_objects
        query_wimpy
        test_if_any_here

OTHER FUNCTIONS

        add_attacker
        add_top_attacker
        add_weight
        attack
        attack_object
        attacked_by
        clean_up
        delete_attacker
        died
        invis
        remove_hunting
        run_away
        say_wet
        show_age
        show_stats
        silent_stop_wearing
        start_hunting
        stop_fight
        stop_wearing
        stop_wielding
        transfer_all_to
        vis

DESCRIPTION

        The living_functions is an object that contains those functions that
        are used both for player objects and monster objects, like all
        functions related to combat.

        This document deals with the functions in the object that can be of
        use from outside. Several other, private, functions exists.

FUNCTION

NAME
        set_con - Set living's constitution


SYNTAX
        void set_con(int i) 

DESCRIPTION
        This function sets the value of the object's constitution stat.
        This determines the amount of hitpoints the object can have.




FUNCTION

NAME
        set_dex - Set living's dexterity


SYNTAX
        void set_dex(int i)

DESCRIPTION
        This function sets the value of the object's dexterity stat. This
        influences the object's weaponclass (probability to hit, and amount
        of damage done).




FUNCTION

NAME
        set_gender - Set living's gender


SYNTAX
        void set_gender(mixed g)

DESCRIPTION
        This function sets the objects gender. It can an integer or a string
        as an argument. Valid arguments are:
        0               Sets the gender to 0 (neuter).
        1               Sets the gender to 1 (male).
        2               Sets the gender to 2 (female).
        "male"          Sets the gender to 1 (male).
        "female"        Sets the gender to 2 (female).
        Any other string than the above will set the gender to 0 (neuter).




FUNCTION

NAME
        set_int - Set living's intelligence


SYNTAX
        void set_int(int i) 

DESCRIPTION
        This function sets the value of the objects intelligence stat.
        This determines the amount of spellpoints the object can have.




FUNCTION

NAME
        set_str - Set living's strength


SYNTAX
        void set_str(int i)

DESCRIPTION
        This function sets the value of the objects strength stat.
        This determines objects carrying capability.




FUNCTION

NAME
        setmin - Set living's entrance message


SYNTAX
        int setmin(string m) 

DESCRIPTION
        Using this function, you can set the message written to a location
        when the object enters it. Doing so for anything but a wizard is a
        bad idea, since much depends on such messages being standard.




FUNCTION

NAME
        setmmin - Set living's magical entrance message


SYNTAX
        int setmmin(string m) 

DESCRIPTION
        Calling this function sets the 'magic enter' message. This is
        basically only useful for wizards and their command 'goto'.




FUNCTION

NAME
        setmmout - Set living's magical exit message


SYNTAX
        int setmmout(string m) 

DESCRIPTION
        Calling this function sets the 'magic leave' message. This is
        basically only useful for wizards and their commands 'home' and
        'goto'.




FUNCTION

NAME
        setmout - Set living's exit message


SYNTAX
        int setmout(string m) 

DESCRIPTION
        Using this function, you can set the message written to a location
        when the object leaves it. Doing so for anything but a wizard is a
        bad idea, since much depends on such messages being standard.




FUNCTION

NAME
        silent_wear - Silently wears a piece of armour


SYNTAX
        mixed silent_wear(object a) 

DESCRIPTION
        This function tries to make the object wear the armour 'a' without
        giving any messages.


RETURN VALUES
        If an armour of that type where already worn, it returns that armour,
        else it returns zero (0) on success, and 1 on failure.




FUNCTION

NAME
        silent_wield - Silently wields a weapon


SYNTAX
        int silent_wield(object w)

DESCRIPTION
        This makes the object wield the object w. No messages are normally
        given, but if a cursed weapon is already wielded, a message is
        written. If the cursed property has a string value that isn't an
        empty string, the value is used for the message.


RETURN VALUES
  1 on success
  0 on failure




FUNCTION

NAME
        wear - Make living wear an item


SYNTAX
        mixed wear(object a) 

DESCRIPTION
        This functon uses silent_wear to try to wear an armour, and give a
        message while doing so.


RETURN VALUES
        If an armour of that type was already worn, it returns that armour,
        else it returns zero (0).




FUNCTION

NAME
        wield - Make living wield an item


SYNTAX
        int wield(object w) 

DESCRIPTION
        This function makes the object wield the weapon w. This is done by
        calling silent_wield() and adding some messages.


RETURN VALUES
  1 on success
  0 on failure




FUNCTION

NAME
        calc_armour_class - Calculates living's armour class


SYNTAX
        int calc_armour_class()

DESCRIPTION
        This function calculates the ac of the object, taking worn armour
        into account. For monsters, natural armour are also included. The
        reult is returned from the function.




FUNCTION

NAME
        can_put_and_get - Return whether living can take and put stuff


SYNTAX
        int can_put_and_get(mixed str)

DESCRIPTION
        This function returns 0 if the player is a ghost, or if the argument
        'str' is given, else it returns 1. This has to effect that you can
        look at a players inventory (unless he's a ghost) but you cannot
        take things from it.        




FUNCTION

NAME
        query_ac - Return living's pre-calculated armour class


SYNTAX
        int query_ac()

DESCRIPTION
        This functions returns the (earlier calculated) ac. For players, 
        this is the sum of the class of all worn armours/ divided by three. 
        For monsters, there is also a part that depends on level.




FUNCTION

NAME
        query_age - Return living's heartbeat age


SYNTAX
        int query_age() 

DESCRIPTION
        This function returns the object's age in heartbeats. A heartbeat is
        at least two seconds.




FUNCTION

NAME
        query_alignment - Return living's alignment


SYNTAX
        int query_alignment() 

DESCRIPTION
        This function returns the object's alignment, as an integer. See
        monster.r for rules on monster alignments.




FUNCTION

NAME
        query_alt_attack - Return alternate opponent being attacked


SYNTAX
        object query_alt_attack()

DESCRIPTION
        This function returns the second element of the attackers array, as
        an object, or zero if there wasn't one.




FUNCTION

NAME
        query_attack - Return opponent being attacked


SYNTAX
        object query_attack();

DESCRIPTION
        Most of the time, returns the opponent that a living object is
        currently attacking. Obviously, if it is not in combat, this will
        return a 0.


NOTE
        If this function is called in a monster during its attack
        (for example from a hook, remote_weapon_hit, etc), then it is
        possible that query_attack will not return the object that the
        monster is currently attacking.  Rather, query_attack() returns
        the object that most of the monsters hits are directed at.  If
        you need to find out what the monster is actually hitting right
        at that instant, rely on the arguments to the hook or the remote
        function where possible.




FUNCTION

NAME
        query_attackers - Return entire attackers array


SYNTAX
        mixed query_attackers()

DESCRIPTION
        This function returns an array of all opponents this living
        object is currently attacking.




FUNCTION

NAME
        query_con - Return living's consitution


SYNTAX
        int query_con()

DESCRIPTION
        This returns the object's constitution, an integer usually in the
        range 1-20.




FUNCTION

NAME
        query_dex - Return living's dexterity


SYNTAX
        int query_dex()

DESCRIPTION
        This function returns the object's dexterity. Dexterity affects the
        object's weaponclass, which is used to see if an attack is a hit,
        and how much damage it deals.




FUNCTION

NAME
        query_exp - Return living's experience points


SYNTAX
        int query_exp() 

DESCRIPTION
        This function returns the object's experience points.




FUNCTION

NAME
        query_fighting - Return if living is fighting object


SYNTAX
        int query_fighting(object ob)

DESCRIPTION
        This function returns 1 if we are currently fighting the object 'ob',
        i.e. 'ob' is in our list of attackers.




FUNCTION

NAME
        query_ghost - Return if living is ghost


SYNTAX
        int query_ghost() 

DESCRIPTION
        This function returns the value of the ghost variable, i.e. 0 or 1.
        This happens only for player objects, as monster objects are
        destroyed when the monsters die.




FUNCTION

NAME
        query_hunting - Return hunting array or if hunting arg


SYNTAX
        varargs mixed query_hunting(mixed arg)

DESCRIPTION
        This function returns 1 if 'arg' is present in the hunting array, or
        zero if it isn't. If not given an argument, a copy of the hunting
        array is returned.




FUNCTION

NAME
        query_int - Return living's intelligence


SYNTAX
        int query_int() 

DESCRIPTION
        This function returns the value of the objects intelligence stat.
        This determines the amount of spellpoints the object can have.




FUNCTION

NAME
        query_invis - Return if living is invisible


SYNTAX
        status query_invis() 

DESCRIPTION
        This function returns the invisibility status of the object.




FUNCTION

NAME
        query_mmsgin - Return living's magical entrance message


SYNTAX
        string query_mmsgin()  

DESCRIPTION
        This function returns the 'magic enter' message.




FUNCTION

NAME
        query_mmsgout - Return living's magical exit message


SYNTAX
        string query_mmsgout() 

DESCRIPTION
        This function returns the 'magic exit' message.




FUNCTION

NAME
        query_msgin - Return living's entrance message


SYNTAX
        string query_msgin()   

DESCRIPTION
        This function returns the 'enter' message given to a locations
        when this object enters it.




FUNCTION

NAME
        query_msgout - Return living's exit message


SYNTAX
        string query_msgout()  

DESCRIPTION
        This function returns the 'exit' message given to a location when
        this object leaves it.




FUNCTION

NAME
        query_name - Return living's name


SYNTAX
        string query_name() 

DESCRIPTION
        This function returns the capitalised name of the object. If the
        object is invisible, "Someone" is returned.




FUNCTION

NAME
        query_real_name - Return living's name, ignoring invisibility


SYNTAX
        string query_real_name() 

DESCRIPTION
        This function returns the real_name variable. This will always be
        in lowercase letters only, and unaffected by invisibility.




FUNCTION

NAME
        query_str - Return living's strength


SYNTAX
        int query_str() 

DESCRIPTION
        This function returns the value of the object's strength stat.
        This determines the player's carrying capability.




FUNCTION

NAME
        query_wc - Return living's weaponclass


SYNTAX
        int query_wc()

DESCRIPTION
        This function returns the objects current weaponclass.




FUNCTION

NAME
        query_weight - Return living's carried weight


SYNTAX
        int query_weight() 

DESCRIPTION
        This function returns how much weight the object is curently
        carrying.




FUNCTION

NAME
        query_weapon_in_use - Is a weapon in use, or what weapon is used.


SYNTAX
        varargs mixed query_weapon_in_use(object weapon)

DESCRIPTION
        If called without arguments, or a non-object argument, this
        function returns the object which is currently used as a
        weapon.

        If called with an object as argument, that argument is
        compared to the weapon currently used. If the two are the same
        object, non-zero is returned. If they are not the same, zero
        is returned.




FUNCTION

NAME
        query_wielded - Return living's used weapon in an array


SYNTAX
        object *query_wielded()

DESCRIPTION
        This function returns the currently used weapon, in an
        array. If no weapon is currently in use, it will return zero.




FUNCTION

NAME
        query_wielded_objects - Return living's wielded weapons in an array


SYNTAX
        object *query_wielded_objects()

DESCRIPTION
        This function returns an array of the weapons that have been
        wielded. The array might be empty.




FUNCTION

NAME
        query_wimpy - Return living's wimpy value


SYNTAX
        int query_wimpy() 

DESCRIPTION
        This function returns how wimpy, in hitpoints, the object is.




FUNCTION

NAME
        test_if_any_here - Return if any other players are here


SYNTAX
        int test_if_any_here()

DESCRIPTION
        This function checks if there's a player other than the object
        present in the room.


RETURN VALUES
        1 if there is a player other than the object itself present, else 0.




FUNCTION

NAME
        add_attacker - Add an object to the attackers array


SYNTAX
        int add_attacker(mixed who)

DESCRIPTION
        This adds 'who' to the array of attackers, unless it is this object,
        or already in the array. In those cases, the function returns zero,
        else it returns the nunber of attackers currently in the array.




FUNCTION

NAME
        add_top_attacker - Add an object to the top of the attackers array


SYNTAX
        int add_top_attacker(mixed who)

DESCRIPTION
        This works just like add_attacker, but the new attacker is added at
        the other end of the array.




FUNCTION

NAME
        add_weight - Add carried weight to object


SYNTAX
        varargs int add_weight(int w,int test) 

DESCRIPTION
        This function is used to add carried weight to the object. It returns
        1 on success and zero on failure. If the argument 'test' is non-zero,
        the weight is not actually added, and the function can then be used
        to test if the object could carry 'w' extra weight.




FUNCTION

NAME
        attack - Perform attack on object


SYNTAX
        varargs int attack(object who)

DESCRIPTION
        This function performs an attack on the object 'who'. The function
        returns 1 if the attack proceeded normally (including a miss!) and
        zero if not.




FUNCTION

NAME
        attack_object - Make this object attack specified object


SYNTAX
        varargs void attack_object(object ob,int ignore,int special)

DESCRIPTION
        This makes the object attack the object 'ob'. The 'ignore' flag is
        used to skip some sanity checks (don't unless you know what you are
        really doing), while with the 'special' flag the object 'ob' is
        used as attacker instead of this object.




FUNCTION

NAME
        attacked_by - Obsolete function to add given object to attackers


AVAILABILITY
        This function will soon be obsolete.

SYNTAX
        void attacked_by(object ob) 

DESCRIPTION
        This function adds the given object, if any, to the attackers by
        calling add_attacker(ob). Don't use this function. It will be
        removed sooner or later.




FUNCTION

NAME
        clean_up - Called when the object should destroy itself


SYNTAX
        status clean_up(int arg)

DESCRIPTION
        This function is called by the driver to allow the object to destruct
        itself if it has no environment. The call is done if there has been
        no function calls to the object for a while.




FUNCTION

NAME
        delete_attacker - Remove an object from the attacker array


SYNTAX
        varargs int delete_attacker(mixed who)

DESCRIPTION
        This function removes 'who' from the array of attackers. It returns
        the new size of that array.




FUNCTION

NAME
        died - Called when this living dies


SYNTAX
        int died(object killer)

DESCRIPTION
        This function contains the code that is run when a living dies.
        In effect, calling this function kills the object. The argument is
        considered the killer, but if not given, the current attacker is
        used.


RETURN VALUES
        The function returns 1 if the object dies succesfully, else zero.




FUNCTION

NAME
        invis - Make this object invisible


SYNTAX
        varargs status invis(mixed arg)

DESCRIPTION
        Calling this function makes the object invisible. Providing an
        argument will inhibit the standard message.




FUNCTION

NAME
        remove_hunting - Remove argument from the hunting array


SYNTAX
        varargs void remove_hunting(mixed arg)

DESCRIPTION
        This function removes 'arg' from the hunting array. 




FUNCTION

NAME
        run_away - Make this object flee


SYNTAX
        varargs string run_away(int silently) 

DESCRIPTION
        This function makes the object run away in a randomly chosen
        direction. Unless the argument 'silently' is given, a message is
        written to the object.


RETURN VALUES
  ""      The object was destructed trying to run away.
  "dir"   The object ran in the 'dest' direction.
  0       The action was blocked by a hook.




FUNCTION

NAME
        say_wet - Send the wetness message


SYNTAX
        void say_wet(int time)

DESCRIPTION
        This function delivers an appropriate message when the object gets
        wet.




FUNCTION

NAME
        show_age - Print or return object's age


SYNTAX
        mixed show_age(int r)

DESCRIPTION
        This function gives the objects age in days, hours, minutes and
        seconds. If the flag is given, the result is returned, else it is
        just written.

        Age is measured in heartbeats, and for monsters it is only updated
        while the monster is in a fight - and then it dies. Thus, this
        function has little real meaning for monsters.




FUNCTION

NAME
        show_stats - Print object's stats


SYNTAX
        void show_stats(int flag) 

DESCRIPTION
        This function prints a list of some of the stats of the object:
        level, paragonlevel, money, hp, max hp, sp, max sp, xp, ac, c,
        weapon, armours, carried weight, carrying capability, gender, qp,
        max qp, pk status, alignment, str, int, con, dex and age.

        If the flag is given, a list of quests and puzzles are included.




FUNCTION

NAME
        silent_stop_wearing - Silently removes a piece of armour


SYNTAX
        void silent_stop_wearing(mixed o) 

DESCRIPTION
        Calling this function makes the object stop wearing a piece of
        armour. If the argument is a string, the worn armour of that type is
        removed. If the argument is an object, that object is removed.




FUNCTION

NAME
        start_hunting - Add arg to the hunting array


SYNTAX
        varargs void start_hunting(mixed arg)

DESCRIPTION
        This function adds 'arg' to the hunting array, provided it wasn't
        there already.




FUNCTION

NAME
        stop_fight - Make object cease fighting


SYNTAX
        void stop_fight();

DESCRIPTION
        If a living object is engaged in combat, calling this function
        will stop its fighting.


NOTE
        Unless stop_fight() is immediately called in its opponent as
        well, the first creature will resume its fight as soon as
        it is hit again.


NOTE
        Use this function for 'scrolls of taming' and the like.
        If you don't want players to be fight a certain monster or
        under certain circumstances, you might want to redefine the
        hit_player function.




FUNCTION

NAME
        stop_wearing - Remove the specified piece of armour


SYNTAX
        void stop_wearing(string name) 

DESCRIPTION
        This function makes the object remove the specified armour type by
        using silent_stop_wearing, and writing a few messages.




FUNCTION

NAME
        stop_wielding - Unwield wielded weapon


SYNTAX
        varargs int stop_wielding(mixed weapon, int all) 

DESCRIPTION
        Calling this function makes the object stop wielding a weapon.
        If no argument is specified, the currently wielded weapon
        from the weapon-array is unwielded.

        The function returns an integer, which is the number of weapons
        that were unwielded.




FUNCTION

NAME
        transfer_all_to - Move object's entire inventory


SYNTAX
        void transfer_all_to(mixed dest)

DESCRIPTION
        Calling this function moves all objects of the inventory to the
        destination. Despite it's name, the function uses move_object(),
        not transfer.




FUNCTION

NAME
        vis - Make this object visible


SYNTAX
        varargs status vis(mixed arg)

DESCRIPTION
        This function makes an invisible object visible. Providing an
        argument inhibits the standard message.