Wrapper fuer ReceiveMsg() ueberarbeitet
1) Rueckgabewerte in Containern entfallen
Diese muessten ein (tief) geschachteltes Mapping sein, was vermutlich
niemand mehr auswertet.
2) Alternativen nur versuchen, solange der Fehler von ReceiveMsg()
MSG_SENSE_BLOCK ist - alle anderen Fehler sind sehr wahrscheinlich
"permanent" fuer die Dauer des Aufrufs.
3) Rueckgabewert in Livings geaendert
Der Rueckgabe ist jetzt der Rueckgabewert von ReceiveMsg() fuer die
zuletzt versuchte Meldung. Dies ermoeglicht die Feststellung, dass eine
Meldung zugestellt wurde (wenn auch nicht welche), was das ist, was
die meisten Aufrufer interessieren duerfte. Gleichzeitig ist der Wert
jetzt einfacher auszuwerten.
4) Manpages umstrukturiert und -formuliert
5) ReceiveSay() nur noch Spezialfall von ReceiveMultiSense()
Change-Id: Id9dbe227236f07b577be2626c99a13ff89fd7997
diff --git a/doc/sphinx/lfun/ReceiveMultisense.rst b/doc/sphinx/lfun/ReceiveMultisense.rst
index cafa5bc..1c2666c 100644
--- a/doc/sphinx/lfun/ReceiveMultisense.rst
+++ b/doc/sphinx/lfun/ReceiveMultisense.rst
@@ -4,83 +4,74 @@
FUNKTION
--------
- public int* ReceiveMultisense(struct msg_s* msgs,
- string action = 0, int commontypes = 0)
-
+ public void ReceiveMultisense(struct wave_s* msgs, string action = 0, int commontypes = 0)
+
DEFINIERT IN
------------
/std/living/comm.c
/std/room/comm.c
- /sys/living/comm.h
ARGUMENTE
---------
- struct msg_s* msgs
- Die Auszugebenden Nachrichten mit Zusatzinformationen. (S.u.)
+ struct wave_s* msgs
+ Die auszugebenden Nachrichten mit Zusatzinformationen. (s.u.)
string action
- action wird als action an ReceiveMsg() weitergegeben.
+ action wird als <action> an ReceiveMsg() weitergegeben.
int commontypes
- Muss einen oder mehrere Veroderte messagetypes aus
+ Muss einen oder mehrere veroderte messagetypes aus
:doc:`ReceiveMsg` enthalten. Diese werden bei jedem Aufruf von
- :doc:`ReceiveMsg` mit dem jeweiligen Messagetyp aus msgs verodert.
+ :doc:`ReceiveMsg` mit dem jeweiligen Messagetyp aus <msgs> verodert.
BESCHREIBUNG
------------
- sendet die in msgs angegebenen Nachrichten an den Empfaenger, bis eine
- zugestellt werden konnte oder das ende von msgs erreicht wurde.
+ Versucht, eine der in <msgs> angegebenen Nachrichten an den Empfaenger zuzustellen.
- msgs ist aufgebaut wie folt:
- Der struct msg_s ist in /std/living/comm_structs.c definiert. Er hat
- die Eintraege string msg, int type, string prefix.
- Das Array wird abgearbeitet, bis eine Nachricht zugestellt werden konnte
- oder das Ende erreicht ist. msg wird vor der Ausgabe an
- :doc:`../sefun/replace_personal` uebergeben, als erstes Objekt wird das aufrufende
- Objekt uebergeben, als zweites this_player(), sofern vorhanden. msg wird
- automatisch auf 78 Zeichen umgebrochen, vorhandene Zeilenumbrueche werden
- dabei beibehalten. Fuer prefix findet keine Ersetzung statt.
+ Das Array <msgs> wird der Reihe nach abgearbeitet, bis eine Nachricht zugestellt werden konnte, das Ende von <msgs> erreicht wurde oder eine Nachricht *aus anderen Gruenden* als einem blockierten Sinn abgelehnt wurde. Der Grund fuer letzteres ist, dass andere Fehler von ReceiveMsg() (fast) immer auch bei allen (weiteren) Alternativen auftreten werden.
+
+ <msgs> ist ein Array von struct wave_s. Diese ist in /secure/simul_efun/comm.c definiert (und steht allen Programmen automatisch zur Verfuegung). Sie hat die Eintraege string msg, int type, string prefix.
+ wave_s.msg wird vor der Ausgabe von :doc:`../sefun/replace_personal` verarbeitet. Als erstes Objekt wird das aufrufende Objekt uebergeben, als zweites this_player(), sofern vorhanden. wave_s.msg wird automatisch auf 78 Zeichen umgebrochen, vorhandene Zeilenumbrueche werden dabei beibehalten. Fuer wave_s.prefix findet keine Ersetzung statt.
RUECKGABEWERT
-------------
- Ein Integer-Array mit folgenden Werten:
+in Lebewesen
+^^^^^^^^^^^^
+ Der Rueckgabe ist der Rueckgabewert von ReceiveMsg() fuer die zuletzt versuchte Meldung.
- 0
- Der Rueckgabewert von :doc:`../lfun/ReceiveMsg`.
- 1
- Information, welche Meldung zugestellt wurde. -1 steht fuer keine
- Meldung, ein wert >= 0 fuer die jeweilige Position in msgs.
+ Wenn dies einen Erfolg (MSG_DELIVERED, MSG_BUFFERED) darstellt, wurde irgendeine Meldung erfolgreich zugestellt.
+ Falls es MSG_SENSE_BLOCK ist, sind alle versuchten Sinne blockiert und keine Nachricht wurde zugestellt.
+ Ist es ein anderer Fehler ist, wurde keine Nachricht zugestellt (und ggf. nicht alle versucht).
- Raeume definieren standardmaessig ebenfalls ein ReceiveMultisense(), welches in
- jedem Objekt im Raum ReceiveMultisense() mit den uebergebenen Argumenten aufruft.
- In diesem Fall ist der Rueckgabe der kleinste von allen gerufenen
- ReceiveMultisense() zurueckgelieferte Wert.
+in Containern/Raeumen
+^^^^^^^^^^^^^^^^^^^^^
+
+ Die Funktion hat keinen Rueckgabewert. Der Grund hierfuer ist, dass dieser ein ggf. tief verschachteltes Mapping waere, was keiner mehr prueft.
BEISPIEL
--------
.. code-block:: pike
- inherit "/std/living/comm_structs";
this_player().ReceiveMultisense(
({
- (<msg_s>
+ (<wave_s>
msg: "Ein Drache landet neben Dir.",
type: MT_LOOK),
- (<msg_s>
- message: "Du hoerst ein rumpeln, als waere gerade etwas grosses "
+ (<wave_s>
+ message: "Du hoerst ein Rumpeln, als waere gerade etwas Grosses "
"neben Dir eingeschlagen.",
type: MT_LISTEN),
- (<msg_s>
+ (<wave_s>
msg: "Du spuerst einen heftigen Luftzug.",
type: MT_FEEL)})
MA_MOVE_IN);
-
+
SIEHE AUCH
----------
:doc:`ReceiveMsg`, :doc:`../sefun/replace_personal`
-Letzte Aenderung: 07.10.2021, Bugfix
+Letzte Aenderung: 21.09.2022, Zesstra
diff --git a/doc/sphinx/lfun/ReceiveSay.rst b/doc/sphinx/lfun/ReceiveSay.rst
index 33ceee1..386aa7e 100644
--- a/doc/sphinx/lfun/ReceiveSay.rst
+++ b/doc/sphinx/lfun/ReceiveSay.rst
@@ -4,9 +4,9 @@
FUNKTION
--------
- public int* ReceiveSay(string msg, string prefix = 0,
+ public void ReceiveSay(string msg, string prefix = previous_object().Name(WER, 1) + " sagt: ",
struct msg_s sense_blocked =
- ({(<msg_s>
+ ({(<wave_s>
msg: "@WER1 bewegt die Lippen, Du hoerst jedoch nichts.",
type: MT_LOOK)}))
@@ -15,56 +15,44 @@
/std/living/comm.c
/std/room/comm.c
- /sys/living/comm.h
-
+
ARGUMENTE
---------
string msg
- Die auszugebende Meldung. Sie wird vor der Ausgabe an
- :doc:`../sefun/replace_personal` uebergeben, als erstes Objekt wird das aufrufende
- Objekt uebergeben, als zweites this_player(), sofern vorhanden. msg wird
- automatisch auf 78 Zeichen umgebrochen, vorhandene Zeilenumbrueche werden
- dabei beibehalten.
+ Die auszugebende Meldung.
string prefix
- prefix wird als prefix an :doc:`ReceiveMsg` weitergegeben. Eine
- Ersetzung mittels :doc:`replace_personal` findet nicht statt.
- Wird kein Wert uebergeben, wird
- previous_object().Name(WER, 1) + " sagt: " verwendet. Hierzu muss Name()
- am aufrufenden Objekt definiert sein und etwas sinnvolles zurueckgeben.
- struct msg_s sense_blocked
- Ersatzmeldungen fuer taube Spieler. enthaelt Structs vom Typ msg_s.
- Dieser ist in /std/living/comm_structs.c definiert und enthaelt die
- Eintraege string msg, int type, string prefix.
- Das Array wird von vorne nach hinten
- abgearbeitet, bis eine Nachricht zugestellt werden konnte oder das Ende
- erreicht ist. Auch hier findet fuer msg eine Ersetzung mittels
- :doc:`../sefun/replace_personal` statt, fuer prefix nicht.
+ prefix wird als prefix an :doc:`ReceiveMsg` weitergegeben. Wird kein Wert uebergeben, wird ``previous_object().Name(WER, 1) + " sagt: "`` verwendet.
+ struct wave_s \*alt
+ Ersatzmeldungen, falls das Lebewesen die Meldung aufgrund eines blockierten Sinns nicht wahrnehmen kann. Details siehe unten.
BESCHREIBUNG
------------
- Sendet msg per :doc:`ReceiveMsg` mit den ueblichen Argumenten von
- "sage" an den Empfaenger. D.h.: MT_LISTEN, MA_SAY, Name(WER, 1) + " sagt: ". Hierzu
- muss das aufrufende Objekt :doc:`name` definiert haben und dort
- etwas sinnvolles zurueckgeben. Falls ein anderer prefix gewaehlt wurde,
- wird dieser statt Name(WER, 1) " sagt: " verwendet.
+ Sendet msg per :doc:`ReceiveMsg` mit den ueblichen Argumenten von "sage" an den Empfaenger, d.h.: ``MT_LISTEN``, ``MA_SAY``, ``Name(WER, 1) + " sagt: "``.
+ Hierzu muss das aufrufende Objekt :doc:`Name` definiert haben und dort etwas sinnvolles zurueckgeben. Falls ein anderer Praefix gewaehlt wurde, wird dieser statt ``Name(WER, 1) " sagt: "`` verwendet.
+
+ <msg> wird vor der Ausgabe an :doc:`../sefun/replace_personal` uebergeben, als erstes Objekt wird das aufrufende Objekt uebergeben, als zweites this_player(), sofern vorhanden. msg wird automatisch auf 78 Zeichen umgebrochen, vorhandene Zeilenumbrueche werden dabei beibehalten.
+
+ Falls der Empfaenger eine Nachricht aufgrund eines blockierten Sinns nicht empfangen kann (und **nur** dann), wird versucht, alternative Nachrichten aus dem Array <alt> zuzustellen. Dieses Array enthaelt structs vom Typ wave_s. Das Array wird von vorne nach hinten abgearbeitet, bis eine Nachricht erfolgreich zugestellt werden konnte, das Ende erreicht ist oder eine Nachricht *aus anderen Gruenden* als einem blockierten Sinn abgelehnt wurde. Der Grund fuer letzteres ist, dass andere Fehler von ReceiveMsg() (fast) immer auch bei allen (weiteren) Alternativen auftreten werden.
+ wave_s ist in /secure/simul_efun/comm.c definiert und enthaelt die Eintraege string msg, int type, string prefix. In <alt> ist der Default fuer wave_s.prefix 0!
+ Auch hier findet fuer wave_s.msg eine Ersetzung mittels :doc:`../sefun/replace_personal` statt, fuer wave_s.prefix nicht.
RUECKGABEWERT
-------------
- Ein Integer-Array mit folgenden Werten:
+in Lebewesen
+^^^^^^^^^^^^
+ Der Rueckgabe ist der Rueckgabewert von ReceiveMsg() fuer die zuletzt versuchte Meldung.
- 0
- Der Rueckgabewert von :doc:`../lfun/ReceiveMsg`.
- 1
- Information, welche Meldung zugestellt wurde. -1 steht fuer msg, ein wert
- >= 0 fuer die jeweilige Position in sense_blocked.
+ Wenn dies einen Erfolg (MSG_DELIVERED, MSG_BUFFERED) darstellt, wurde irgendeine Meldung erfolgreich zugestellt.
+ Falls es MSG_SENSE_BLOCK ist, sind alle versuchten Sinne blockiert und keine Nachricht wurde zugestellt.
+ Ist es ein anderer Fehler ist, wurde keine Nachricht zugestellt (und ggf. nicht alle aus <alt> versucht).
- Raeume definieren standardmaessig ebenfalls ein ReceiveSay(), welches in
- jedem Objekt im Raum ReceiveSay() mit den uebergebenen Argumenten aufruft.
- In diesem Fall ist der Rueckgabe der kleinste von allen gerufenen
- ReceiveSay() zurueckgelieferte Wert.
+in Containern/Raeumen
+^^^^^^^^^^^^^^^^^^^^^
+
+ Die Funktion hat keinen Rueckgabewert. Der Grund hierfuer ist, dass dieser ein ggf. tief verschachteltes Mapping waere, was keiner mehr prueft.
BEISPIEL
--------
@@ -77,16 +65,16 @@
"Das hast Du prima gemacht, @WER2!",
Name(WER, 1) + " lobt Dich: ",
({
- (<message_>
+ (<wave_s>
msg: "@WER1 nickt Dir laechelnd zu.",
type: MT_LOOK),
- (<msg_s>
+ (<wave_s>
msg: "Jemand klopft Dir lobend auf die Schulter.",
type: MT_FEEL)}));
SIEHE AUCH
----------
- :doc:`ReceiveMsg`, :doc:`../sefun/replace_personal`, :doc:`name`
+ :doc:`ReceiveMsg`, :doc:`../sefun/replace_personal`, :doc:`Name`
-Letzte Aenderung: 07.10.2021, Bugfix
+Letzte Aenderung: 21.09.2022, Zesstra