
AddExtraLook()
**************

AddExtraLook() varargs int AddExtraLook(string look, [int duration,
string key,

   string lookende, object ob]);


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

   /std/living/description.c


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

   Der Extralook erscheint in der Langbeschreibung des Lebewesens.
   Eintraege koennen mit dieser Funktion hinzugefuegt werden. Dies ist der
   bevorzugte Weg, wenn ansonsten extra ein Objekt im Spielerinventar abgelegt
   werden muesste.


   Alle Parameter bis auf <look> sind optional.


ARGUMENTE
=========

   - string look:
     String, der in der Langbeschreibung des Lebewesens zusaetzlich ausgegeben
     wird.
     Kann auch ein Funktionsname sein, wenn <ob> angegeben wird (s.u.).
   - int duration:
     > 0: Wie lang bleibt der Extralook gueltig (in Sekunden)? Anschliessend
          wird er automatisch geloescht.
     0:   Dieser Eintrag bleibt unbegrenzt gueltig.
     < 0: Dieser Eintrag bleibt bis zum Ende/Reboot bestehen.
   - string key:
     Schluesselwort, unter dem der Eintrag registriert wird und mit dem man ihn
     auch mittels RemoveExtraLook() entfernen kann. Sollte natuerlich
     moeglichst eindeutig sein. ;-) Wenn <key> nicht angeben wird, wird der
     Objektname (object_name()) benutzt.
   - string lookende:
     String, der an das Lebewesen (nur bei Spielern) ausgegeben wird, wenn der
     eingetragene Extralook abgelaufen ist.
     Kann auch ein Funktionsname sein, wenn <ob> angegeben wird.
   - object ob:
     Wenn hier ein Objekt angegeben wird, werden <look> und <lookende> als
     Funktonsnamen aufgefasst. Diese Funktionen werden in <ob> aufgerufen, wenn
     der Extralook des Lebewesen angezeigt wird bzw. der eingetragene Extralook
     abgelaufen ist. Diese Funktionen bekommen das jeweilige Lebenwesen als
     Objekt uebergeben. Sie muessen einen String zurueckliefern, der ausgegeben
     wird. Dieser String wird direkt so ausgeben, also selber fuer Zeilenumbruch
     etc. sorgen!
     WICHTIG: Das Objekt sollte nach Moeglichkeit eine Blueprint sein, da das
     ganze nix mehr ausgibt, sobald der Clone zerstoert wird, falls hier
     einer angeben wird. Wenn ihr keine BP uebergebt: Wisst, was ihr tut. ;-)


RUECKGABEWERTE
==============

   > 0, falls der Eintrag erfolgreich registriert wurde.
   < 0 sonst.
     -1: <key> war nicht gueltig und es konnte keiner ermittelt werden.
     -2: <look> war kein gueltiger String.
     -3: <duration> war kein Integer.
     -4: unter <key> gibt es schon einen Eintrag.


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

   Die Strings <look> und <lookende> werden vor Ausgabe durch
   replace_personal() geschickt, daher ist die Verwendung von @WER1, @WESSEN1
   usw. moeglich (s. replace_personal). Dies gilt aber _nicht_ fuer den Fall,
   dass die entsprechenden Funktionen in <ob> gerufen werden, dann muessen die
   Funktionen selber umbrechen, etc.
   Nach replace_personal() werden die Strings noch von break_string() auf 78
   Zeilen umgebrochen, allerdings bleiben dabei vorhandene Umbrueche erhalten.
   Die Meldung von <lookende> bzw. der Funktionsaufruf erfolgt, wenn der
   Extralook der Lebewesen das erste Mal nach Ablauf der Gueltigkeit aufgerufen
   wird.


BEISPIELE
=========

   # einfacher Eintrag, "fuer die Ewigkeit"
   living->AddExtraLook("@WER1 hat den Drachengott der SSP besiegt.");

   # Eintrag der nach 1h automatisch weg ist.
   living->AddExtraLook("@WER1 ist ganz mit Marmelade bedeckt.", 3600);


   # Eintrag mit bestimmten Schluessel, damit man ihn wieder entfernen kann.
   living->AddExtraLook("@WER1 ist ganz mit Marmelade bedeckt.", 3600,
                        "humni_marmeladen_look");


   # Mit "Ende"-Meldung, aber kein eigener Schluessel.
   living->AddExtraLook("@WER1 ist patschnass.", 1200, 0,
                        "Du bist endlich wieder trocken. Puuh.");


   # Mit Objekt, was den Extralook dynamisch erzeugt
   living->AddExtraLook("get_my_special_extralook", 3600, 0, 0, this_object());
     In diesem Fall muss this_object() natuerlich die Funktion
     "get_my_special_extralook()" definieren, die einen String zurueckgibt.

   # Mit Objekt, was den Extralook und die Endemeldung dynamisch erzeugt
   living->AddExtraLook("get_my_special_extralook", 3600, 0,
                        "extralookende", this_object());


SIEHE AUCH
==========

   RemoveExtraLook(),
   replace_personal(), break_string()
   P_INTERNAL_EXTRA_LOOK

14.05.2007, Zesstra