From the NannyMUD documentation

LAST CHANGE

2005-09-15 by Gabe

NAME

        puzzled - A puzzle daemon.

INCLUDES

        puzzled.h

LOCATION

        /obj/util/puzzled

FUNCTIONS

SETUP FUNCTIONS

        int add_puzzle(string puzzle)

QUERY FUNCTIONS

        string query_areas()
        int query_all_puzzles(void | string area)
        int query_solved_puzzles(object player, void | string area)
        string *query_puzzles(object player)
        string *query_top_list()
        int query_top_score(string player)

OTHER FUNCTIONS

        int remove_puzzle(string puzzle)
        string *query_added_puzzles()

DESCRIPTION

        This daemon keeps track of open puzzles. A puzzle is defined as open
        by being added to this daemon. In most cases, this should be done from
        each wizard's castle at reboot.

        The purpose of declaring a puzzle open is that it becomes available
        for counting. Although a puzzle is open it does not mean that other
        creators can see its name - in that sense, it is still secret. The
        total number of open puzzles residing in your area is publicly
        available though.

        If you do not want your puzzles to be open, simply do NOT add them
        to this daemon. To promote your area, it is recommended that you do
        declare your puzzles open, to attract players to your area when they
        notice there are more puzzles to solve.

        The daemon can also be used to remove or rename your old puzzles,
        be they open or not. Talk to an admin if you so desire.
        
        The daemon also keeps track of the top 1000 puzzlers, that is
        the players that have the highest number of open puzzles solved.

        The daemon will never close any puzzles. The removal takes place at
        reboot when closed areas no longer add their puzzles to the daemon.

FUNCTION

NAME
        add_puzzle - Mark a puzzle as open.


SYNTAX
        int add_puzzle(string puzzle)

DESCRIPTION
        Use this function from your castle to mark your puzzles as open. It 
        is highly recommended that your puzzle names start with your name
        followed by an underscore, e.g. "gabe_something", and that you do
        NOT include the word puzzle in the name. It returns true if the
        puzzle was not added previously.




FUNCTION

NAME
        query_areas - Which areas have open puzzles?


SYNTAX
        string *query_areas()

DESCRIPTION
        This function returns all areas that have at least one open puzzle.
        The area is most often a wizard name, but not always. You will see
        "mainland" and "antharis" in this list for puzzles that are not in
        a specific wizard area.




FUNCTION

NAME
        query_all_puzzles - How many open puzzles are there?


SYNTAX
        int query_all_puzzles(void | string area)

DESCRIPTION
        This function returns the total number of puzzles known to be open.
        If you specify an area, it will return the number in that area.




FUNCTION

NAME
        query_solved_puzzles - How many open puzzles has a player solved?


SYNTAX
        int query_solved_puzzles(object player, void | string area)

DESCRIPTION
        This function returns the number of open puzzles solved by the given
        player. If you specify an area, it will return the number solved in
        that area alone.




FUNCTION

NAME
        query_puzzles - Which puzzles has a player solved in my area?


SYNTAX
        string *query_puzzles(object player)

DESCRIPTION
        This function returns the names of the puzzles that the given player
        has solved in your area. You can only see the names of puzzles from
        your own area.




FUNCTION

NAME
        query_top_list - The puzzler top list.


SYNTAX
        string *query_top_list()

DESCRIPTION
        This function simply returns the names of the top 1,000 players that
        have solved the most open puzzles, with the most prominent puzzler
        first.




FUNCTION

NAME
        query_top_score - The puzzle top list score of a player.


SYNTAX
        int query_top_score(string player)

DESCRIPTION
        The last calculated scores of the top 1000 puzzlers are cached and
        available through this function. You will always get the correct
        score for an online player. Players that are not online and not in
        the top 1000, will generate a -1.




FUNCTION

NAME
        remove_puzzle - Removes a faulty puzzle.


SYNTAX
        int remove_puzzle(string puzzle)

DESCRIPTION
        This function is only here for completeness, as you do not have to
        worry about removing puzzles. If your area is closed, your puzzles
        will automatically be removed at reboot. If you add a puzzle name
        by mistake, you can use this function to remove it, but you can only
        remove your own puzzles. It returns true if the puzzle was removed.


NOTE
        This function is only available for patching by the owner wizard.
        You cannot use it in your area code.


NOTE
        Admin wizards can remove any puzzle.




FUNCTION

NAME
        query_added_puzzles - List your added (open) puzzles.


SYNTAX
        string *query_added_puzzles(void | string area)

DESCRIPTION
        This debugging function allows you to see the puzzles that have
        successfully been added from your area.


NOTE
        This function is only available for patching by the owner wizard.
        You cannot use it in your area code.


NOTE
        Only admin wizards can use the area argument to specify any area.