SearchPath()
************


FUNKTION
========

   public int SearchPath(string from, string to, int para,
                         closure callback)


DEFINIERT IN
============

   /p/daemon/pathd.c
   <sys/pathd.h>


ARGUMENTE
=========

   from     - Der Startpunkt
   to       - Der Endpunkt
   para     - Die Parawelt in der gesucht wird (Normalwelt: 0)
   callback - Closure, die am Ende der Pfadsuche gerufen wird


BESCHREIBUNG
============

   Diese Funktion berechnet - sofern moeglich - den kuerzesten Pfad zwischen
   <from> und <to> in der (Para-)Welt <para>.


   Die Pfadsuche wird anhand von Daten ueber von Spielern gelaufene Wege
   durchgefuehrt. D.h. Gebiete, die von Spielern nicht (in letzter Zeit mal)
   betreten werden, sind auch dem Pfaddaemon nicht bekannt. Auch kann es
   Gebiete geben, wo zwar gebietsintern Pfade bekannt sind, aber keine Wege
   in den Rest vom MG.

   Da diese Suche im Allgemeinen SEHR aufwendig sein kann, wird sie meistens
   nicht sofort fertig, sondern dauert eine Weile. Wenn sie fertig ist, wird
   die Closure <callback> aufgerufen und ihr die Argumente <from>, <to>,
   <parawelt>, <kosten>, <path> und <cmds> uebergeben. Die Bedeutung
   dieser Argumente ist unten erklaert.

   Eine Suche nach einem Pfad in einer Parawelt fuehrt durch Raeume der
   gewuenschen Parawelt und durch Raeume der Normalwelt.


RUeCKGABEWERT
=============

    1      - Suche wurde gestartet
    2      - Pfad gefunden (und callback gerufen)
   -1      - es laeuft schon ein Suchauftrage fuer die UID des anfragenden
             Objektes
   -2      - es laufen bereits zuviele Suchanfragen
   -3      - <from> und/oder <to> sind nicht bekannt


   An <callback> uebergebene Argumente am Ende der Pfadsuche:
       <from> - Startpunkt des Weges (string)
       <to>   - Zielpunkt des Weges (string)
       <para> - Parawelt des Weges (int)
       <costs>- Kosten des Wege. (int) Je hoeher, desto
                laenger/unguenstiger. 0, wenn kein Pfad gefunden
       <path> - Array mit Raumnamen, die durchlaufen werden (string*)
                0, wenn kein Pfad gefunden
       <cmds> - Array mit Kommandos zum Ablaufen des Weges (string*)
                0, wenn kein Pfad gefunden


BEMERKUNGEN
===========

   Es ist natuerlich nicht dazu gedacht, Spielern fertige Routen zwischen
   Orten zu geben - bzw. nur in Ausnahmefaellen.
   Pfadabfrgen werden geloggt.

   Die Angabe <costs> sagt grob etwas ueber die Laenge und vor allem ueber die
   "Qualitaet" des Pfades aus. Die steigt bei Paraweltwechseln, wenig
   abgelaufenen Verbindungen zwischen Raeumen oder wenn eine Verbindung kein
   normaler Ausgang ist.

   Die Closure <callback> sollte nicht zuviele Ticks verbrauchen.


BEISPIEL
========

   #include <pathd.h>
   void suchergebnis(string from, string to, int para, int costs, string*
        path, string* cmds) {
        tell_object(find_player("zesstra"), sprintf(
            "Ergebnis Pfadsuche von %s nach %s in Para %d fuer %d:\n %O\n %O\n",
            from, to, para, costs, path, cmds));
   };

   ...
   mixed res=PATHD->SearchPath("/gilden/abenteurer",
                               "/d/ebene/dancer/lucky/room/pova_la3",
                               0, #'suchergebnis);

22.12.2015, Zesstra