RegisterHelperObject()
======================

FUNKTION
--------
::

     int RegisterHelperObject(object helper, int type, 
                              string|closure callback);

DEFINIERT IN
------------
::

     /std/living/helpers.c

ARGUMENTE
---------
::

     object helper
       Das Objekt, das bei einem Lebewesen als Hilfsobjekt registriert 
       werden soll. Das Objekt muss sich dazu nicht im Inventar des
       Lebewesens befinden.
     int type
       Helfertyp, einer der in /sys/living/helpers.h definierten Typen:
       - HELPER_TYPE_AERIAL fuer die Flug-/Segelunterstuetzung
       - HELPER_TYPE_AQUATIC fuer Tauchunterstuetzung
     string|closure callback
        Closure oder Funktionsname als String; dies ist die Funktion, die im
        Objekt helper gerufen wird, um abzufragen, ob es sich aktuell fuer
        zustaendig erklaert oder nicht.

BESCHREIBUNG
------------
::

     Das Objekt "helper" wird als Hilfsobjekt fuer bestimmte Aktivitaeten wie
     zum Beispiel Fliegen oder Tauchen registriert. 

     

     Die als Callback uebergebene Funktion wird bei der Abfrage der 
     P_*_HELPERS-Properties (siehe unten) aufgerufen und deren 
     Rueckgabewert in der Property vermerkt. 

     

     Der Rueckgabewert der Callback-Methode muss im Wertebereich 
     0..10000 liegen, wobei ein Wert von 0 bedeutet, dass das Hilfsobjekt 
     sich gerade nicht zustaendig fuehlt. Bei den Werten >0 ist es dem 
     abfragenden Objekt ueberlassen, wie es diese Daten bewertet.

     Die Funktion muss existieren und public sein, d.h. von aussen gerufen 
     werden koennen.

     

     Die Funktion bekommt das Spielerobjekt und das abfragende Objekt als
     Parameter uebergeben.

HINWEIS
-------
::

     Es ist ein Unterschied, ob sich ein Objekt via UnregisterHelperObject()
     als Helfer austraegt, oder ob der Aufruf der Callback-Funktion eine
     0 zurueckgibt. Im letzteren Fall ist das Objekt nach wie vor 
     registriert und kann trotzdem vom abfragenden Objekt als 
     funktionsfaehig angesehen werden.

RUECKGABEWERTE
--------------
::

      1  Objekt wurde erfolgreich registriert (HELPER_SUCCESS)
     -1  angegebenes Hilfsobjekt existiert nicht (HELPER_NO_CALLBACK_OBJECT)
     -2  angegebenes Hilfsobjekt ist bereits fuer diese Art der
         Unterstuetzung registriert (HELPER_ALREADY_LISTED)

BEISPIELE
---------
::

     a) Eine luftgefuellte Blase will sich als Tauch-Helfer am Spieler
     anmelden und ist zustaendig, solange sich noch Luft in ihr befindet:

     int luft = 5; // globale Variable z.B. fuer Luftinhalt von 5 Atemzuegen

     // Registrierung im Spielerobjekt
     if ( TP->RegisterHelperObject(ME, HELPER_TYPE_AQUATIC,
          "DivingCallback") == HELPER_SUCCESS ) {
       tell_object(TP, "Du kannst jetzt mit Hilfe der Luftblase unter Wasser "
         "atmen.\n");
     }

     // hier koennen natuerlich auch noch komplexere Dinge ablaufen, z.B.
     // wenn ein Wert zurueckgegeben werden soll, der nicht nur 0 oder 1 ist.
     public int DivingCallback(object player, object caller) {
       return (environment(ME)==player && luft>0);
     }

     b) Ein Spieler befindet sich in einem Raum mit einem steilen Abhang, den
     man hinunterspringen kann. Dies geht aber nur dann gefahrlos, wenn es
     Hilfsobjekte gibt, die den (Segel)flug erlauben:

     // cmd_springen() sei die Funktion, die bei der Eingabe des Befehls durch
     // den Spieler aufgerufen wird.
     static int cmd_springen(string str) {
       [...]
       // Property abfragen
       mapping helpers = TP->QueryProp(P_AERIAL_HELPERS);
       // Liste der Werte fuer die einzelnen Unterstuetzungsobjekte ermitteln
       int *values = m_values(helpers,0);
       // Spieler schonmal runterbewegen, die Folgen seines Handelns spuert
       // er dann, wenn er unten angekommen ist.
       TP->move(zielraum, M_GO|M_SILENT);
       // "helpers" ist immer ein Mapping, das pruefen wir nicht extra.
       // Wenn die Liste der Objekte noch mindestens ein Element enthaelt,
       // nachdem alle unzustaendigen Hilfsobjekte (Rueckgabewert der
       // Callback-Funktion == 0) rausgerechnet wurden, existiert mindestens
       // ein geeignetes Hilfsobjekt.
       if ( sizeof(values-({0})) ) {
         tell_object(TP, "Sanft segelst Du den Hang hinab.\n");
       }
       else {
         tell_object(TP, BS("Todesmutig springst Du den Hang hinab und "
           "schlaegst hart unten auf. Du haettest vielleicht daran denken "
           "sollen, Dir geeignete Hilfsmittel fuer so eine Aktion zu "
           "besorgen.");
         TP->Defend(800, ({DT_BLUDGEON}), ([SP_NO_ACTIVE_DEFENSE:1]), ME);
       }
       return 1;
     }

SIEHE AUCH
----------
::

     Funktionen:  UnregisterHelperObject(), GetHelperObject()
     Properties:  P_HELPER_OBJECTS, P_AERIAL_HELPERS, P_AQUATIC_HELPERS
     Sonstiges:   /sys/living/helpers.h

05.02.2015 Arathorn