AddToMenu()
===========

FUNKTION
--------
::

        varargs string AddToMenu(string  menuetext,
                                 mixed   ids,
                                 mapping minfo,
                                 mixed   rate,
                                 mixed   msg,
                                 mixed   refresh,
                                 mixed   delay,
                                 mixed   d_msg);

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

        /std/pub.c

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

        Die Erlaeuterung der Parameter beschraenkt sich im Folgenden
        zunaechst auf die Grundfunktionalitaet bei Verwendung fester
        Werte. Die Moeglichkeiten zur Realisierung dynamischen Verhaltens
        sind in den Fussnoten zu den einzelnen Parametern beschrieben.

        menuetext
          Der Text steht als kurze Beschreibung im Menue.
        ids
          String oder Array von Strings, mit denen sich die Speise bzw. das
          Getraenk beim Bestellen ansprechen laesst.
        minfo
          Mapping mit Eintraegen fuer:
          P_HP      LP-Heilung in Punkten [*]
          P_SP      KP-Heilung in Punkten [*]
          P_FOOD    Saettigungswirkung der Speise [*]
          P_DRINK   Saettigungswirkung des Getraenks [*]
          P_ALCOHOL Alkoholgehalt des Getraenks [*]
          P_VALUE   Preis der Speise bzw. des Getraenks [*]
        rate [*]
          Heilrate in Punkten pro HeartBeat.
        msg [**]
          Meldung beim Essen:
          Array mit 2 Strings: (1) fuer Empfaenger, (2) fuer Andere.
          Verfuegbare Platzhalter sind weiter unten im Abschnitt "Beispiel"
          dokumentiert.
        refresh
          Mapping mit Eintraegen fuer:
            PR_USER (Kontingent fuer einzelnen Spieler) [*]
            PR_ALL  (Zusatzkontingent fuer alle) [*]
          Alternativ: 0 fuer unbegrenzte Verfuegbarkeit
          Einem Key muessen dabei zwei Werte zugeordnet werden:
          Der Erste gibt die Hoehe des Kontingents an, der Zweite legt
          fest, alle wieviel reset()s das Kontingent wieder aufgefuellt
          wird.
          Verwendung des Mappings erfordert Inkludieren von pub.h.
        delay [*]
          Zahl der Sekunden, um die verzoegert die Heilung eintritt,
          z.B. weil das Essen erst zubereitet werden muss.
        d_msg [**]
          Meldung beim Bestellen, falls die Heilung verzoegert wird
          Array mit 2 Strings: (1) fuer Empfaenger, (2) fuer Andere.

          

        [*] Dieser Parameter kann statt eines festen Zahlenwerts mit 
            folgenden Werten gefuellt werden:

            1) Mapping <racemodifier> der Form:
                   ([ 0 : <standardwert> ,
                    <rasse_1> : <wert_1>, 
                    ... , 
                    <rasse_n> : <wert_n> ]).
               Die Eintraege in diesem Mapping werden gegen die Rasse des
               bestellenden Spielers geprueft und entsprechend die 
               zugehoerigen Werte verwendet.
            2) string <func>: Aufruf erfolgt mittels 
                 call_other(this_object(), func, empfaenger);
               gerufen (aber: siehe Hinweise).
            3) closure <func>: Aufruf erfolgt mittels
                 funcall(func, empfaenger);
            4) Array der Form  ({string <obj>, string <func>}) oder
                               ({object <obj>, string <func>})
               Aufruf erfolgt mittels
                 call_other(obj, func, empfaenger);
               (aber: siehe Hinweise). <obj> ist folglich als Objektpointer 
               oder dessen object_name() anzugeben. <func> wird mittels 
               function_exists() auf Existenz ueberprueft.

               HINWEISE: im Falle von Lieferverzoegerung ("delay") und
               Preis (P_VALUE) wird bei allen Funktionsaufrufen NICHT der 
               Empfaenger, sondern der Zahler uebergeben.
               Im Falle der Kontingent-Liste ("refresh") kann nur die
               verfuegbare Menge modifiziert werden, nicht die Zeit
               bis zum Wieder-Auffuellen.

        [**] Zur Erzeugung variabler Meldungen koennen folgende Werte
             eingetragen werden:

             1) closure <func>: Aufruf erfolgt mittels 
                  funcall(func, zahler, empfaenger, ident, minfo);
             2) string <func>: Aufruf erfolgt mittels
                  call_other(this_object(), func, zahler, empfaenger, 
                             ident, minfo);
             <func> bekommt Zahler und Empfaenger als Objektpointer,
             ident als String und minfo als Mapping mit den 
             jeweiligen Heilwerten uebergeben. minfo entspricht hierbei
             den Daten, die als dritter Parameter an AddToMenu()
             uebergeben wurden.
             HINWEIS: wenn in das minfo-Mapping keine int-Festwerte 
             eingetragen wurden, werden diese gemaess den Regeln unter [*]
             geprueft; Funktionen/Closures werden ggf. ausgewertet und 
             deren Rueckgabewerte an die Funktion <func> uebergeben.
             WICHTIG: Die Rueckgabewerte der Funktion werden nicht 
             ausgewertet. Jeder, der anstatt einer Meldung einen 
             Funktionsaufruf programmiert, muss fuer die Ausgabe der
             Meldungen selbst sorgen.

                   

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

        Mit dieser Funktion werden Speisen oder Getraenke in die Karte
        von Kneipen und Restaurants eingefuegt.

RUECKGABEWERT
-------------
::

        Rueckgabewert ist ein String "menuentry%d", wobei %d eine Nummer
        ist, die darueber Auskunft gibt, den wievielten Eintrag in die
        interne Karte der Kneipe diese Speise bzw. dieses Getraenk
        darstellt. Im Prinzip handelt es sich bei dem String um einen Key
        fuer ein Mapping, in dem die Speisen bzw. Getraenke gespeichert
        sind.

BEMERKUNGEN
-----------
::

        Die aelteren Funktionen 'AddDrink' bzw. 'AddFood' werden zwar mithilfe
        dieser maechtigeren Funktion aus Gruenden der Abwaertskompatibilitaet
        simuliert, sollen aber nicht mehr eingesetzt werden.

        

        Die alten Platzhalter && etc. (s.u.) werden weiterhin unterstuetzt,
        sollten aber fuer bessere Wartbarkeit nicht mehr verwendet werden.

        

        Fuer das Testen der Kneipe gibt es in jeder Kneipe den Befehl
        'pubinit'. Hiermit lassen sich die Speisen und Getraenke durch-
        checken. Steht in der Ausgabe bei einem Getraenk/Essen ein FAIL,
        so wird die entsprechende Speise (oder Getraenk) NICHT an Spieler
        verkauft. Ausnahmen fuer Speisen/Getraenke mit hoeheren maximalen
        Werten sind durch Balance-EM zu genehmigen.

BEISPIEL
--------
::

        include <pub.h>

        create()
        {
        AddToMenu("'Opa's Drachenkeule'",({"drachenkeule","keule"}),
        ([P_HP:63,P_SP:63,P_FOOD:9,P_VALUE:528]), 5,
        ({"Du isst die Keule mit einem schlechten Gewissen.",
          "@WER1 isst die Keule mit einem schlechten Gewissen."}),
        ([ PR_USER : 4; 1 , PR_ALL : 20; 3 ]), 9,
        ({"Der unsichtbare Kneipier schneidet einem Rentner ein grosses "
          "Stueck aus dessen Keule und bereitet sie Dir zu. Komisch, muss "
          "wohl ein Tippfehler auf der Karte gewesen sein.",
          "Der unsichtbare Kneipier schneidet einem hilflosen Opa ein "
          "Stueck aus dessen Keule und braet diese fuer @WEN1."}) );
        }

        1) Name der Speise (des Getraenks) auf der Karte (bei menue).

           AddToMenu("'Opa's Drachenkeule'",     

        2) ids mit denen sich bestellen laesst (z.B. "kaufe keule").

           ({"drachen","drachenkeule","keule"}),

        3) Heilung fuer LP und KP, Saettigung (P_FOOD oder P_DRINK,
           P_ALCOHOL nach Belieben setzen), Preis (P_VALUE). 
           HP und SP muessen nicht gleich sein. Speisen und Getraenke,
           die nur eines von beiden heilen, sind auch moeglich.

           ([P_HP:63,P_SP:63,P_FOOD:9,P_VALUE:528]),

        4) Heilung pro Heartbeat (in diesem Beispiel je 5 KP/LP).

    

           5,

        5) Meldungen fuer Spieler und Umstehende die bei Genuss ausgege-
           ben werden (also NICHT der Bestell-Text).

           ({"Du isst die Keule mit einem schlechten Gewissen.",
             "@WER1 isst die Keule mit einem schlechten Gewissen."}),

           Die Ausgabe-Strings werden vor der Ausgabe mit dem Empfaenger
           als Objekt an replace_personal() uebergeben. Fuer die
           moeglichen Platzhalter siehe dort.

          

        6) Die Speise ist in ihrer Anzahl begrenzt. Fuer jeden Spieler
           sind 4 Keulen pro reset() da. Ausserdem gibt es noch einen
           "Notvorrat" von 20 Keulen, der alle 3 reset()s aufgefuellt
           wird. Aus diesem (so noch vorhanden) werden die Spieler
           versorgt, wenn ihr "persoenlicher Vorrat" aufgebraucht ist.

           ([ PR_USER : 4; 1 , PR_ALL : 20; 3 ]),

           

           HINWEIS: bei Benutzung des Mappings muss <pub.h> inkludiert 
           werden!

           

           Wenn man keine reset-abhaengigen Speisen haben moechte, traegt
           man hier eine 0 ein.

        7) Die Zahl ist die Wartezeit in Sekunden, die der Wirt z.B. fuer
           die Zubereitung und Auslieferung an den Spieler braucht.

           9,

         

        8) Letztendlich die Meldungen an Spieler und Umstehende, die bei Be-
           stellung (hier 'kaufe keule') ausgegeben werden.

           ({"Der unsichtbare Kneipier schneidet einem Rentner ein grosses "
           "Stueck aus dessen Keule und bereitet sie Dir zu. Komisch, muss "
           "wohl ein Tippfehler auf der Karte gewesen sein.",
           "Der unsichtbare Kneipier schneidet einem hilflosen Opa ein "
           "Stueck aus dessen Keule und braet diese fuer @WEN1."}));

LISTE DER ALTEN PLATZHALTER (DEPRECATED):
-----------------------------------------
::
           &&  - pl->name(WER,2)
           &1& - pl->name(WER,2)
           &2& - pl->name(WESSEN,2)
           &3& - pl->name(WEM,2)
           &4& - pl->name(WEN,2)
           &1# - capitalize(pl->name(WER,2))
           &2# - capitalize(pl->name(WESSEN,2))
           &3# - capitalize(pl->name(WEM,2))
           &4# - capitalize(pl->name(WEN,2))
           &!  - pl->QueryPronoun(WER)
           &5& - pl->QueryPronoun(WE);
           &6& - pl->QueryPronoun(WESSEN)
           &7& - pl->QueryPronoun(WEM)
           &8& - pl->QueryPronoun(WEN)
           &5# - capitalize(pl->QueryPronoun(WER))
           &6# - capitalize(pl->QueryPronoun(WESSEN))
           &7# - capitalize(pl->QueryPronoun(WEM))
           &8# - capitalize(pl->QueryPronoun(WEN))

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

        AddFood(), AddDrink(), /sys/pub.h
        RemoveFromMenu(), replace_personal()

Last modified: Sam, 01. Okt 2011, 23:40 by Arathorn