ReceiveMsg()
============

public varargs int ReceiveMsg(string msg, int msg_typ, string msg_action,
                              string msg_prefix, mixed origin)


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

    /std/npc/comm.c
    /std/player/comm.c
    /std/room/items.c
    /sys/living/comm.h

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

    string msg
      String mit der uebermittelten Nachricht. Muss nicht umgebrochen sein,
      da ReceiveMsg() das ebenfalls erledigt.
    int msg_typ
      Nachrichtentyp(en) fuer Filterung und Flags fuer Behandlung/Umbruch.
      Siehe unten fuer mit | kombinierbare Konstanten.
    string msg_action (optional)
      Ausloesende Aktion, wird auch fuer Ignorieren verwendet.
      Default ist query_verb(). Siehe unten fuer alternative Konstanten.
    string msg_prefix (optional)
      String, welcher ggf. im break_string() als indent verwendet wird.
      Default ist 0 (kein Indent)
    mixed origin (<object>) (optional)
      Das die Meldung ausloesende Objekt, wird fuer Ignorieren verwendet.
      Default: previous_object()

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

    ReceiveMsg() wird benutzt, um einem Lebewesen eine Nachricht zu senden.
    Dabei ruft es das sonst uebliche tell_object() fuer Spieler bzw.
    catch_tell() im NPC auf.

    Gerade fuer Nachrichten an Spieler bietet die Methode weitere Features,
    die bisher sonst haendisch zu implementieren waren:
    1) Pruefung auf Empfangbarkeit, je nach 'msg_typ', zB
       MT_LOOK nur an Nichtblinde
       MT_LISTEN nur an Nichttaube
       MT_DEBUG nur an Magier/Testspieler
       Bei gesetztem MSG_ALL_SENSES muessen alle fuer die angegebenen Typen
       relevanten Sinne des Empfaengers benutzbar sein, nicht nur einer.
    2) Pruefen auf Ignorieren von
       - Aktion ('msg_action')
         - mit 'msg_action' || query_verb()
       - Urheber ('origin')
         - fuer sendende Spieler mit origin->query_realname()
         - fuer sendende NPCs mit origin->Name(RAW))
    3) Speicherung in der tmhist (Typ MT_COMM)
    4) Speicherung im Kobold (Typ MT_COMM + aktiver Kobold)
    5) Umbrechen unter Beruecksichtigung von indent, 'msg_typ'-Flags
       fuer Umbruch und P_PREPEND_BS

    Raeume definieren standardmaessig ebenfalls ein ReceiveMsg(), welches in
    jedem Objekt im Raum ReceiveMsg() mit den uebergebenen Argumenten aufruft.
    In diesem Fall ist der Rueckgabe der kleinste von allen gerufenen
    ReceiveMsg() zurueckgelieferte Wert.

  Zur einfacheren Verwendung gibt es einige Wrapper-Funktionen, siehe
  :doc:`ReceiveMultisense`, :doc:`ReceiveNotify`, :doc:`ReceiveSay` und
  :doc:`ReceiveTeilemit`.

RUeCKGABEWERT
-------------
::

    > 0 fuer Erfolg, < 0 fuer Misserfolg, s.u.
    MSG_DELIVERED    bei erfolgreicher Zustellung
    MSG_BUFFERED     bei Zwischenspeicherung durch den Kobold

    MSG_FAILED       nicht naeher spezifizierter Fehler bei Zustellung
    MSG_IGNORED      Nachricht wurde ignoriert (Absender, origin)
    MSG_VERB_IGN     Nachricht wurde ignoriert (Kommandoverb, msg_action)
    MSG_MUD_IGN      Absendendes Mud wurde ignoriert.
    MSG_SENSE_BLOCK  Passende Sinne des Empfaenger sind blockiert (z.B.
                     blind, taub)
    MSG_BUFFER_FULL  Kobold kann sich nichts mehr merken

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

    Fuer saemtliche Alternativmeldungen im Falle einer nicht erfolgreich
    zugestellten Nachricht ist der Aufrufer von ReceiveMsg() verantwortlich.

    NPCs:
    * ReceiveMsg() ruft zwecks Abwaertskompatibilitaet catch_tell() auf
    * empfohlen ist, in NPCs nun ReceiveMsg() zu ueberschreiben.
      * catch_tell() muss weiterhin fuer andere tell_object()
        ueberschrieben  werden

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

    #1.1 Nachricht an einen Spieler, zB in der Wueste
    this_player()->ReceiveMsg("Die Sonne brennt dir auf den Kopf.",
                              MT_FEEL|MT_LOOK);

    #1.2 Nachricht an einen Spieler von einem NPC mit Indent
    // bei aktivem Editor+Kobold landet dieser Text auch im Kobold
    this_player()->ReceiveMsg("Du haust ja ganz schoen rein!",
                              MT_COMM|MT_FAR|MSG_DONT_STORE,
                              MA_TELL,
                              "Arkshat teilt dir mit: ");

    #1.3 Nachricht an einen Spieler mit Fallback-Kaskade
    // Achtung, bei MT_COMM oder Ignorieren gibt es natuerlich auch
    // Misserfolgs-Rueckgaben. Bei einem normalen Kommando wie diesem
    // hier ist das unproblematisch und daher sinnvoll:
    if(this_player()->ReceiveMsg(
         "Du drueckst den Knopf und es oeffnet sich knirschend "
         "ein kleines Fach in der Wand.", MT_LOOK) < MSG_DELIVERED &&
       this_player()->ReceiveMsg(
         "Du drueckst den Knopf und irgend etwas scheint sich "
         "knirschend zu oeffnen. Das Geraeusch kam von der Wand.",
         MT_LISTEN) < MSG_DELIVERED) // leider blind UND taub ... also:
      this_player()->ReceiveMsg(
        "Du drueckst den Knopf und irgend etwas scheint zu passieren, "
        "aber leider siehst und hoerst du nichts.", MT_FEEL);


    #2.1 Im NPC als Empfaenger auf ein TM reagieren
    public varargs int ReceiveMsg(string msg, int msg_typ, string msg_action,
                                  string msg_prefix, mixed origin) {
      int ret = MSG_DELIVERED;  // Default

      // eine OOC-Kommunikation?
      if(msg_typ&MT_COMM) {
        if(strstr(msg, "hilfe")>=0)
          if(environment(origin)==environment()) {
            origin->ReceiveMsg("Ich werd dir gleich helfen!",
                               MT_COMM|MSG_DONT_STORE, MA_TELL,
                               "Arkshat teilt dir mit: ");
          } else {
            origin->ReceiveMsg("Hilf dir selbst, dann hilft dir Gott!",
                               MT_COMM|MT_FAR|MSG_DONT_STORE,
                               MA_TELL,
                               "Arkshat teilt dir mit: ");
          }
        else if(...)
        [...]
      } else if(msg_typ&MT_LISTEN && msg_action==MA_SAY) {
        [...]
      }

      return ret;
    }


    #3.1 als Sender an viele, Variante mit eigenem filter
    // Achtung: siehe 3.3. send_room() loest vieles.
    // Living nickt nur seinen Nichtgegnern zu
    object *all = filter(all_inventory(environment(this_player())),
                         #'living) - ({this_player()});
    all -= this_player()->PresentEnemies();
    all->ReceiveMsg(this_player()->Name()+
                    " nickt dir verstohlen zu und scheint bereit.",
                    MT_LOOK, MA_EMOTE);

    #3.2 als Sender an viele, Variante mit einzelnem Iterieren
    // Achtung: siehe 3.3. send_room() loest vieles.
    // Living trinkt etwas, jeder im Raum soll es sehen oder hoeren
    object ob = first_inventory(environment(this_player()));
    do {
      if(living(ob) && ob!=this_player())
        ob->ReceiveMsg(this_player()->Name()+" trinkt einen Schnaps aus.",
                       MT_LOOK|MT_LISTEN,
                       MA_DRINK);
      ob = next_inventory(ob);
    } while(ob);

    #3.3 als Sender an viele, Variante mit send_room
    // Living gruesst seine Freunde
    // send_room() ruft ReceiveMsg mit allen entsprechenden Parametern
    object *exclude = this_player()->PresentEnemies();
    send_room(this_object(),
              this_player()->Name()+" gruesst dich.",
              MT_LOOK|MT_LISTEN,
              MA_EMOTE,
              0,
              exclude);

    #3.4 als Sender an viele mit send_room und ReceiveMsg()
    // Living gruesst seine Freunde, seine Feinde sehen das
    // send_room() ruft ReceiveMsg mit allen entsprechenden Parametern
    object *exclude = this_player()->PresentEnemies();
    send_room(this_object(),
              this_player()->Name()+" gruesst dich.",
              MT_LOOK|MT_LISTEN, MA_EMOTE, 0, exclude);
    exclude->ReceiveMessage(
      this_player()->Name()+" gruesst, aber nicht dich.",
      MT_LOOK|MT_LISTEN, MA_EMOTE);

KONSTANTEN FUER PARAMETER
-------------------------
::

    Saemtlich in "/sys/living/comm.h". Hier nicht notwendigerweise
    immer aktuell oder vollstaendig.

    <msg_typ>
      MT_UNKNOWN      unspez. Nachrichtentyp (nicht verwenden). Es wird
                      versucht, aufgrund <msg_action> den Typ zu erraten.
      MT_LOOK         alles, was man sieht
      MT_LISTEN       alles, was man hoert
      MT_FEEL         alles, was man fuehlt
      MT_TASTE        alles, was man schmeckt
      MT_SMELL        alles, was man riecht
      MT_MAGIC        alle sonstigen (uebersinnlichen) Wahrnehmungen
      MT_NOTIFICATION Statusmeldungen, Kommandobestaetigungen
      MT_COMM         alle OOC-Kommunikation, d.h. nicht durch o.g. Sinne
                      abgedeckt.
      MT_FAR          alles, was aus der Ferne / einem anderen Raum kommt.
                      muss mit min. einem anderen Typ kombiniert werden
      MT_DEBUG        Debugmeldungen, sehen nur Magier im Magiermodus
      MT_NEWS         Mails & MPA

      MSG_DONT_BUFFER Nachricht darf nicht im Kobold gespeichert werden
      MSG_DONT_STORE  Nachricht darf nicht in die Comm-History
      MSG_DONT_WRAP   Nachricht nicht per break_string umbrechen
      MSG_DONT_IGNORE Nachricht kann nicht ignoriert werden
      MSG_ALL_TYPES   alle relevanten Sinne fuer die angegebenen Nachrichten-
                      typen muessen benutzbar sein (UND statt ODER).
      MSG_ALERT       Nachricht loest eine vom Spieler konfigurierte
                      Benachrichtigung aus (z.B. Piepston)

      MSG_BS_LEAVE_LFS    wie BS_LEAVE_MY_LFS fuer break_string()
      MSG_BS_SINGLE_SPACE wie BS_SINGLE_SPACE fuer break_string()
      MSG_BS_BLOCK        wie BS_BLOCK fuer break_string()
      MSG_BS_NO_PARINDENT wie BS_NO_PARINDENT fuer break_string()
      MSG_BS_INDENT_ONCE  wie BS_INDENT_ONCE fuer break_string()
      MSG_BS_PREP_INDENT  wie BS_PREPEND_INDENT fuer break_string()

    <msg_action> (optional)
      MA_UNKNOWN     Unspez. Aktion. Es wird der Default query_verb()
                     benutzt bzw. versucht, die Aktion zu erraten.
      MA_PUT         Jemand legt etwas hin und gibt jemanden etwas
      MA_TAKE        Jemand nimmt etwas
      MA_GIVE        Jemand gibt jemandem etwas
      MA_MOVE_IN     Jemand betritt den Raum
      MA_MOVE_OUT    Jemand verlaesst den Raum
      MA_MOVE        Jemand bewegt sich 
      MA_FIGHT       Jemand kaempft
      MA_WIELD       Jemand zueckt eine Waffe
      MA_UNWIELD     Jemand steckt eine Waffe weg
      MA_WEAR        Jemand zieht etwas an
      MA_UNWEAR      Jemand zieht etwas aus
      MA_EAT         Jemand isst etwas
      MA_DRINK       Jemand trinkt etwas
      MA_SPELL       Jemand wirkt einen Spell
      MA_LOOK        Jemand sieht etwas an, untersucht etwas
      MA_LISTEN      Jemand horcht oder lauscht an etwas
      MA_FEEL        Jemand betastet etwas
      MA_SMELL       Jemand schnueffelt herum
      MA_SENSE       Jemand macht eine uebersinnliche Wahrnehmung
      MA_READ        Jemand liest etwas
      MA_USE         Jemand benutzt etwas
      MA_SAY         Jemand sagt etwas
      MA_REMOVE      Etwas verschwindet
      // MA_CHAT        Chatkrams (z.B. teile-mit, Teamkampfchat)
      MA_CHANNEL     Ebenen
      MA_EMOTE       (r)Emotes, Soulverben (remotes mit Typ MT_COMM|MT_FAR)
      MA_SHOUT       Rufen (nicht: shout()!)
      MA_SHOUT_SEFUN Rufen ueber shout(SE)

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

    Wrapper-Funktionen: :doc:`ReceiveMultisense`, :doc:`ReceiveNotify`, :doc:`ReceiveSay`, :doc:`ReceiveTeilemit`
    Verwandt: send_room(SE)
    Lfuns:    TestIgnore(L)
    Efuns:    tell_object(E), catch_tell(L), catch_msg(L)
              query_verb(E), query_once_interactive(E), break_string(SE)

Letzte Aenderung: 22.01.2022