Manpages fuer vItems
Manpages fuer AddVItem, RemoveVItem, GetVItemClones
und present_vitem erstellt.
Change-Id: I8f51e3799fd7cb785f90918ed2c9ca0bf84b75a6
diff --git a/doc/sphinx/lfun/AddVItem.rst b/doc/sphinx/lfun/AddVItem.rst
new file mode 100644
index 0000000..c76a070
--- /dev/null
+++ b/doc/sphinx/lfun/AddVItem.rst
@@ -0,0 +1,181 @@
+AddvItem()
+==========
+
+FUNKTION
+--------
+
+ public varargs void AddvItem(string key, int refresh, mapping shadowprops,
+ string path, mapping props)
+
+
+DEFINIERT IN
+------------
+
+ /std/container/vitems.c
+
+ARGUMENTE
+---------
+
+ key
+ Eindeutige Bezeichnung des vItems und mit dieser wieder loeschbar. Das
+ vItem wird im Raum auch unter dieser ID ansprechbar sein.
+ refresh
+ Refresheinstellungen des vItems, nachdem es mitgenommen wurde
+ shadowprops
+ Properties des vItems *im Raum* (optional, wenn <path> genutzt)
+ path
+ Vorlage/Templat des vItems und Blueprint fuer Clones (optional)
+ props
+ Properties, welche in Clones von der Vorlage gesetzt werden (optional)
+
+BESCHREIBUNG
+------------
+
+ Dem Container/Raum wird ein virtuelles Item hinzugefuegt. Dieses ist
+ kein im Container vorhandenes reales Objekt, kann aber (weitgehend) wie ein
+ solches untersucht und behandelt werden.
+
+ Falls das vItem ein reales Objekt als Templat hat (d.h. <path> angegeben
+ wird), kann das vItem standardmaessig mitgenommen werden, es wird dafuer
+ automatisch erzeugt. (Das Mitnehmen ist aber wie immer mit P_NOGET
+ verhinderbar.)
+
+ Das Mapping <shadowprops> enthaelt die Properties, welche das vItem
+ im Container beschreiben. Hat das vItem ein Templat, werden alle
+ Properties, welche *nicht* in <shadowprops> enthalten sind, aus dem
+ Templat entnommen. Auf diese Weise kann man einem Objekt im Raum
+ unterschiedliche Eigenschaften geben.
+
+ Wird ein vItem mitgenommen, wird <path> geclont und die im Argument <props>
+ angegebenen Properties in ihm gesetzt. Auf diese Weise kann man das
+ genommene Objekt noch individuell konfigurieren.
+
+ Zu beachten ist: in <shadowprops> enthaltene Properties *ersetzen* (nicht
+ ergaenzen) im Regelfall diejenigen im Templat *und* in <props>. In <props>
+ enthaltene Properties *ersetzen* wiederum diejenigen im Templat.
+ Ausnahmen sind Properties, welche ein Mapping oder ein Array enthalten:
+ Deren Inhalt wird *hinzugefuegt*. Dies betrifft insbesondere die Properties:
+ P_DETAILS, P_READ_DETAILS, P_SMELLS, P_SOUNDS, P_TOUCH_DETAILS, P_IDS,
+ P_CLASS, P_ADJECTIVES.
+ Will man dies nicht, kann man den Propertynamen so angeben:
+ VI_PROP_RESET(P_DETAILS), was dazu fuehrt, dass P_DETAILS vor dem
+ Hinzufuegen geloescht wird.
+
+ Nachdem ein vItem mitgenommen wurde, ist es im Raum nicht mehr ansprechbar.
+ Es wird es je nach <refresh> wieder verfuegbar:
+
+ - VI_REFRESH_NONE
+ Es wird erst nach dem Neuladen/Neuerstellen des Containers wieder
+ verfuegbar.
+ - VI_REFRESH_ALWAYS
+ Es wird mit dem naechsten Reset wieder verfuegbar. *Vorsicht!*
+ - VI_REFRESH_REMOVE
+ Es wird mit dem naechsten Reset wieder verfuegbar, wenn das geclonte
+ Objekt nicht mehr im Raum ist.
+ - VI_REFRESH_DESTRUCT
+ Es wird mit dem naechsten Reset wieder verfuegbar, wenn das geclonte
+ Objekt nicht mehr existiert.
+ - VI_REFRESH_MOVE_HOME
+ Das geclonte Objekt wird im naechsten Reset 'zurueckgeholt', d.h.
+ zerstoert und das vItem ist wieder im Raum verfuegbar.
+ - VI_REFRESH_INSTANT
+ Es ist abweichend vom Normalverhalten sofort nach Mitnehmen wieder
+ verfuegbar und mitnehmbar. **Vorsicht!**
+
+
+BEMERKUNGEN
+-----------
+
+ * vItems koennen geschachtelt werden, falls es sich um vItems mit Vorlagen
+ handelt.
+ * vItems sind verhaeltnismaessig aufwendig. Sie sollten nur verwendet
+ werden, wenn sie einen Mehrwert ggue. einfachen Details haben. Es bringt
+ nichts, jedes Detail gegen ein vItem zu ersetzen.
+ * Es kann aber praktisch sein, komplexe Detailbaeume an einem vItem zu
+ verankern, wenn man diesen Detailbaum ein- oder ausblenden will.
+
+BEISPIELE
+---------
+
+ .. code-block:: pike
+
+ // Ein einfaches VItem ohne Templat, nicht nehmbar
+ AddVItem("regal", VI_REFRESH_NONE,
+ ([P_LONG: "Das Wandregal hat 3 schwarze Bretter.",
+ P_GENDER: NEUTER,
+ P_IDS: ({"wandregal"}), // "regal" hat es automatisch
+ P_DETAILS: ([
+ "bretter": "Die Regelbretter sind ganz zerkratzt.\n",
+ "kratzer": "Da war wohl jemand achtlos.\n"
+ ]),
+ P_TOUCH_DETAILS: ([
+ SENSE_DEFAULT: "Du erspuerste tiefe Kratzer.\n",
+ "kratzer": Oha, die Kratzer sind ganz schoen tief!\n",
+ ]),
+ P_READ_DETAILS: ([SENSE_DEFAULT:
+ "Auf dem Regal ist eingraviert: 'Dies ist ein vItem-Test.'\n"
+ ]),
+ P_SMELLS: ([SENSE_DEFAULT:
+ "Das Regal riecht gar nicht. Wirklich nicht.\n"]),
+ ]) );
+
+ // Ein VItem mit Templat, nehmbar
+ AddVItem("schaufel", VI_REFRESH_REMOVE, 0, "/items/schaufel");
+
+ // Ein VItem mit Templat, nicht nehmbar
+ AddVItem("schaufel", VI_REFRESH_NONE, ([P_NOGET:1]), "/items/schaufel");
+
+ // Ein VItem, welches P_DETAIL komplett ueberschreibt und alle Details
+ // loescht.
+ AddVItem("schaufel", VI_REFRESH_REMOVE,
+ ([VI_PROP_RESET(P_DETAILS): ([]) ]),
+ "/items/schaufel");
+
+ // Eine Zwiebel im Raum, eine andere Beschreibung hat als die im
+ // Spielerinventar
+ AddVItem("zwiebel", VI_REFRESH_REMOVE,
+ ([P_LONG: "Die Zwiebel sieht etwas vertrocknet aus.\n",
+ P_DETAILS: ([ ({"blatt","blaetter"}): "Sie haengen herab.\n"]),
+ ]),
+ "/items/kraeuter/zwiebel",
+ // Die hier gesammelte Zwiebel ist besonders toll
+ ([P_ZWIEBEL_TYP: EXTRA_STARK]) );
+
+ // Eine modifizierte Eisenstange
+ AddVItem("eisstange", VI_REFRESH_REMOVE,
+ 0,
+ "/items/eisenstange",
+ ([P_LONG:BS("Diese Eisstange eignet sich hervorragend dazu, "
+ "mit ihr auf jemanden einzuschlagen.\n"),
+ P_SHORT:"Ein Eisstange.",
+ P_NAME: "Eisstange",
+ VI_PROP_RESET(P_IDS): ({"stange", "eisstange"}),
+ VI_PROP_RESET(P_MATERIAL): ([MAT_ICE: 100]),
+ VI_PROP_RESET(P_DAM_TYPE): ({DT_BLUDGEON, DT_COLD}),
+ P_WEIGHT: 5000,
+ P_VALUE: 500,
+ VI_PROP_RESET(P_SMELLS): ([SENSE_DEFAULT:
+ "Das Eis riecht nach Vanille!\n"]),
+ ])
+ );
+
+ // Ein Ueberraschungs-Ei - verwandelt sich beim Nehmen in was anderes.
+ // (Keine tolle Idee, soll nur zeigen, dass es geht.)
+ AddVItem("ue-ei", VI_REFRESH_REMOVE,
+ ([P_SHORT:"Ein Ue-Ei.",
+ P_LONG: BS("Da liegt tatsaechlich ein Ue-Ei auf dem Boden. "
+ "Wenn man es nimmt, verwandelt es sich in etwas anderes."),
+ VI_PROP_RESET(P_IDS): ({"ue-ei","ei"}),
+ ]),
+ "/items/schaufel"
+ );
+
+
+SIEHE AUCH
+----------
+
+ :doc:`RemoveVItem`, :doc:`AddItem`, :doc:`RemoveItem`
+ :doc:`../std/vitems`
+
+Last modified: 03.04.2019, Zesstra
+
diff --git a/doc/sphinx/lfun/GetVItemClones.rst b/doc/sphinx/lfun/GetVItemClones.rst
new file mode 100644
index 0000000..0ae6659
--- /dev/null
+++ b/doc/sphinx/lfun/GetVItemClones.rst
@@ -0,0 +1,32 @@
+GetVItemClones()
+================
+
+FUNKTION
+--------
+
+ public object* GetVItemClones()
+
+DEFINIERT IN
+------------
+
+ /std/container/vitems.c
+
+BESCHREIBUNG
+------------
+
+ Es werden alle zur Zeit in diesem Container/Raum anwesenden virtuellen
+ vItems (also deren Objekte) zurueckgeliefert.
+
+RUeckGABEWERT
+-------------
+
+ Ein Array von Objekten.
+
+SIEHE AUCH
+----------
+
+ :doc:`AddVItem`, :doc:`RemoveVItem`, :doc:`AddItem`, :doc:`RemoveItem`
+ :doc:`../std/vitems`
+
+Last modified: 19.03.2019, Zesstra
+
diff --git a/doc/sphinx/lfun/RemoveVItem.rst b/doc/sphinx/lfun/RemoveVItem.rst
new file mode 100644
index 0000000..1ee3322
--- /dev/null
+++ b/doc/sphinx/lfun/RemoveVItem.rst
@@ -0,0 +1,38 @@
+AddvItem()
+==========
+
+FUNKTION
+--------
+
+ public varargs void RemoveVItem(string key)
+
+DEFINIERT IN
+------------
+
+ /std/container/vitems.c
+
+ARGUMENTE
+---------
+
+ key
+ Eindeutige Bezeichnung des vItems - im Raum unter dieser ID ansprechbar
+
+BESCHREIBUNG
+------------
+
+ Das unter <key> eingetragene vItem wird aus dem Container/Raum wieder
+ entfernt.
+
+ Es wird hierbei ggf. auch das zuletzt mitgenommene Objekte
+ zerstoert, falls dieses noch im Raum herumliegt (z.B. Spieler nimmt das
+ vItem und laesst es fallen). Es werden jedoch keine in der Vergangenheit
+ erzeugten Objekten, die wirklich mitgenommen wurden, entfernt.
+
+SIEHE AUCH
+----------
+
+ :doc:`AddVItem`, :doc:`AddItem`, :doc:`RemoveItem`
+ :doc:`../std/vitems`
+
+Last modified: 19.03.2019, Zesstra
+
diff --git a/doc/sphinx/lfun/present_vitem.rst b/doc/sphinx/lfun/present_vitem.rst
new file mode 100644
index 0000000..b0ca1d2
--- /dev/null
+++ b/doc/sphinx/lfun/present_vitem.rst
@@ -0,0 +1,38 @@
+present_vitem()
+===============
+
+FUNKTION
+--------
+
+ public object present_vitem(string complex_desc)
+
+DEFINIERT IN
+------------
+
+ /std/container/vitems.c
+
+BESCHREIBUNG
+------------
+
+ Es wird ein von <complex_desc> angesprochendes vItem (als Objekt)
+ zurueckgeliefert. Dies wird mittels id() geprueft.
+
+RUeckGABEWERT
+-------------
+
+ Das Objekt des vItems oder 0.
+
+BEMERKUNGEN
+-----------
+
+ Nummerierungen (z.B. present_vitem("fackel 5") funktionieren in diesem Fall
+ *nicht*.
+
+SIEHE AUCH
+----------
+
+ :doc:`AddVItem`, :doc:`RemoveVItem`, :doc:`AddItem`, :doc:`RemoveItem`
+ :doc:`../std/vitems`
+
+Last modified: 19.03.2019, Zesstra
+