drink_soft()
============

FUNKTION
--------
::

    public varargs int drink_soft(int strength, int testonly, string mytext)

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

    /std/living/life.c

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

    strength: Wird zu dem augenblicklichen Saettigungsgrad (P_DRINK) addiert.
    testonly: Ist das Flag gesetzt, wird dem Spieler kein DRINK zugefuehrt.
              Darf nur zum Testen der Heilstelle verwendet werden und muss
              im normalen Betrieb auf '0' stehen!
    mytext: Wer selber einen Text bei Misserfolg ausgeben lassen moechte,
            darf sich hier was nettes ausdenken.
            Achtung: Das unterdrueckt nicht die "Durst"-Meldung, die bei
            negativem strength auftritt, wenn P_DRINK wieder 0 ist.

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

    Es wird geprueft, ob dem Spieler der angebene Wert "strength" auf
    aktuelle P_DRINK addiert werden kann oder nicht. Ist dies moeglich,
    wird es gemacht, es sei denn das testonly != 0.

    Sollen neben P_DRINK noch weitere Props manipuliert werden - bspw. zur
    Heilung eines Lebewesens - bietet sich die Funktion consume() an.

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

     0, wenn strength + P_DRINK > P_MAX_DRINK
    >0, wenn Erfolg

BEMERKUNG
---------
::

    drink_soft() bitte anstatt eigener Manipulationen von P_DRINK und
    P_MAX_DRINK verwenden.

    Achtung: Immer erst VOR einer Heilung ausfuehren und bei Erfolg heilen.

    Bei Heilstellen sollte eine evtl. Heilung des Spielers mit der eigens
    dafuer eingerichteten Funktion check_and_update_timed_key realisiert
    werden.

BEISPIEL
--------
::

    int heilstelle() {
      if(this_player()->drink_soft(10, 0, "Du blubberst nicht ueberzeugt "
                                   "in der Limonade. Das ist zu viel.\n")) {
        // Platz fuer 10 "Trinken" war noch, diese sind jetzt bereits addiert
        // Nachricht an den Spieler:
        tell_object(this_player(), break_string("Du nimmst einen grossen "
                    "Schluck zuckersuesse Limonade.", 78));

        // alle anderen im Raum bekommen es ggf auch mit:
        // 1) filter(..., #'living) ergibt die Lebewesen im Raum
        // 2) filter_objects(..., "ReceiveMsg") ruft ReceiveMsg an jedem
        // 3) ReceiveMsg(...) bekommt die Folgeparameter
        filter_objects(filter(all_inventory(environment(this_player())),
                              #'living) - ({this_player()}),
                       "ReceiveMsg",
                       this_player()->Name()+
                         " trinkt einen Schluck Limonade.",
                       MT_LOOK|MT_LISTEN,
                       MA_DRINK);

        // Rassenabhaengige Heilung: Sofort oder in Schritten
        // Tragbare Heilungen sollten auch eher buffer_hp/_sp benutzen.
        if(this_player()->QueryProp(P_REAL_RACE)=="Saufziege")
          this_player()->heal_self(30);
        else {
          this_player()->buffer_hp(30,5);
          this_player()->buffer_sp(30,5);
        }
      }

      return 1;
     }

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

     Aehnlich:  consume, drink_alcohol, eat_food
     Heilung:   heal_self, restore_spell_points, restore_hit_points, 
                buffer_hp, buffer_sp
     Timing:    check_and_update_timed_key
     Enttanken: defuel_drink, defuel_food
     Props:     P_DRINK, P_FOOD, P_ALCOHOL, P_SP, P_HP,
                P_DEFUEL_TIME_DRINK
     Konzepte:  heilung, enttanken, food

9. August 2015 Gloinson