Lpc Manpages

flasche - Standardobjekt fuer Fluessigkeitsbehaelter
====================================================

/std/flasche.c stellt ein Standardobjekt fuer viele Arten von Fluessigkeits-
behaeltern dar. Abgeleitete Objekte koennen verschliessbar sein, beliebig
viele verschiedene Fluessigkeiten mit konfigurierbaren Eigenschaften enthalten
und stellen Standardbefehlen zum trinken, giessen und entleeren des Behaelters
zur Verfuegung. Anregungen fuer dieses Standardobjekt stammen von
/obj/bottle.c, das "handling" ist jedoch viel staerker an die uebrigen Objekt-
typen angepasst und die Flexibilitaet ist deutlich groesser.

Dieses Dokument gibt einen Ueberblick ueber die Moeglichkeiten von
/std/flasche.c. Fuer die einzelnen Properties und Funktionen gibt es
jeweils noch eigene Dokumente, die den entsprechenden Aspekt im Detail
beschreiben.

Properties der Flasche
----------------------

/std/flasche.c ist direkt von /std/thing.c abgeleitet und benoetigt daher
zunaechst einmal die Standard-Properties, insbesondere sollten IMMER

P_SHORT P_LONG P_NAME P_GENDER P_ARTICLE P_MATERIAL P_WEIGHT P_VALUE

gesetzt werden. Diese Properties haben ihre uebliche Bedeutung.

Eine spezielle Property ist von Container-Objekten entlehnt:

P_TRANSPARENT - Bei einer schliessbaren Flasche (s.u.) entscheidet
                diese Property, ob der Fuellstand auch im geschlossenen
                Zustand angezeigt wird. 
                0 (default): nicht anzeigen, 1: anzeigen.

Die folgenden Properties sind spezifisch fuer Flaschen-Objekte:

P_BOTTLE_NOCLOSE  - Wenn diese Property nicht 0 ist, ist das Objekt nicht
                    schliessbar, d.h. immer offen. Default: 0
P_BOTTLE_CLOSED   - Wenn diese Property nicht 0 ist, ist das Objekt
                    geschlossen. Diese Property kann von Hand gesetzt werden,
                    wird jedoch normalerweise von den Befehlen "oeffne" bzw.
                    "schliesse" verwaltet. Default: 0
P_BOTTLE_CAPACITY - Gesamtkapazitaet des Behaelters in Milliliter.
                    Default: 500
P_BOTTLE_GULP     - Menge eines "Schlucks" in Milliliter. Die Gesamtkapazitaet
                    sollte immer durch diesen Wert teilbar sein, weil sonst
                    Restmengen im Behaelter uebrig bleiben, die vom Spieler
                    nicht getrunken werden koennen. Default: 20
P_BOTTLE_CONTENT  - Diese Property enthaelt die Eigenschaften und Mengen aller
                    enthaltenen Fluessigkeiten. Sie sollte NICHT direkt
                    veraendert werden! Stattdessen sollten die Standard-
                    funktionen (s.u.) verwendet werden. Default: ([])
                    
Eigenschaften von Fluessigkeiten
--------------------------------

Jedes von /std/flasche.c abgeleitete Objekt kann beliebig viele verschiedene
Fluessigkeiten gleichzeitig enthalten. Beim Trinken, Ausgiessen und Entleeren
wird automatisch die entfernte Gesamtmenge auf die einzelnen Fluessigkeits-
mengen verteilt und (aenderbar) die Eigenschaften des Gemischs ausgerechnet.

Die folgenden Eigenschaften koennen fuer jede Fluessigkeit getrennt mit der
Funktion "DefineLiquid" (s.u.) festgelegt werden. ALLE ZAHLENWERTE BEZIEHEN
SICH IMMER AUF 1000 MILLILITER. Die Flasche errechnet daraus selbststaendig
die korrekten Zahlen, wenn der Spieler eine bestimmte Menge trinkt.

B_LIQUID_SHORT    - Kurzbeschreibung der Fluessigkeit. Sollte eine Zeile nicht
                    ueberschreiten. Default: "Eine unbekannte Fluessigkeit"
B_LIQUID_HEAL     - Heilwirkung der Fluessigkeit. Es kann entweder eine einzige
                    Zahl angegeben werden, dann bezieht sich diese sowohl auf
                    Lebens- als auch auf Magiepunkte. Oder es kann ein 2-
                    elementiges Array angegeben werden. In diesem Fall bezieht
                    sich das 1. Element auf Lebenspunkte, das 2. auf
                    Magiepunkte. Default: 0
B_LIQUID_SOAK     - Saettigungswirkung der Fluessigkeit. Default: 0
B_LIQUID_STRENGTH - Alkoholgehalt der Fluessigkeit. Default: 0
B_LIQUID_POISON   - Giftgehalt der Fluessigkeit. Default: 0
B_LIQUID_VALUE    - "Wert" einer Fluessigkeit. Wird derzeit nicht verwendet.
                    Default: 0

Die Werte B_LIQUID_HEAL, B_LIQUID_SOAK, B_LIQUID_STRENGTH, B_LIQUID_POISON und
B_LIQUID_VALUE beziehen sich auf 1000 Milliliter der Fluessigkeit!

Intern gibt es noch die Eigenschaft

B_LIQUID_AMOUNT - Derzeit enthaltene Menge der Fluessigkeit. Diese Eigenschaft
                  sollte weder direkt gesetzt noch direkt gelesen werden,
                  dafuer stehen die Funktionen "QueryLiquidAmount" und
                  "AddLiquid" zur Verfuegung. Default: 0

Funktionen der Flasche
----------------------

- varargs void DefineLiquid(string name, mapping props);

Durch diese Funktion werden die Eigenschaften der Fluessigkeit "name"
festgelegt. "name" ist dabei ein String, der lediglich zur eindeutigen
Identifizierung einer Fluessigkeit dient. Er wird nirgendwo angezeigt.

- int AddLiquid(string name,int amount);

versucht "amount" Milliliter der Fluessigkeit "name" in den Behaelter zu
fuellen. Gibt die neue Menge der Fluessigkeit "name" oder einen Fehlercode
(<0) zurueck.

- int RemoveLiquid(string name);

entfernt die Fluessigkeit "name" aus dem Behaelter und gibt die vorher
enthaltene Menge dieser Fluessigkeit zurueck. Die Eigenschaften der
Fluessigkeit bleiben aber gespeichert! Nur die Menge ist danach 0.

- mapping ReduceTotalAmount(int loss);

reduziert die Gesamtmenge an Fluessigkeit um "loss" Milliliter.
"loss" wird dabei gleichmaessig (entsprechend der vorhandenen
einzelnen Fluessigkeitsmengen) auf die einzelnen Fluessigkeiten
verteilt. Zurueckgegeben wird ein mapping, das die Verlustmengen
der einzelnen Fluessigkeiten enthaelt.

- void Empty();

entleert den Behaelter. Alle Fluessigkeitsmengen werden auf 0
gesetzt.

- string* QueryLiquids();

gibt ein array mit den Namen aller definierten Fluessigkeiten zurueck.

- int QueryTotalAmount();

gibt die Gesamtmenge an enthaltener Fluessigkeit in Milliliter zurueck.

- int QueryLiquidAmount(string name);

gibt die Menge einer bestimmten Fluessigkeit "name" zurueck.

- int DoPour(mapping liquids);

Diese Funktion wird aufgerufen, wenn der Spieler eine bestimmte Menge an
Gesamtfluessigkeit ausgiesst. Vorher rechnet die Flasche die Gesamtmenge
noch in Einzelmengen um (das Verhaeltnis der Einzelmengen entspricht dem
Verhaeltnis der Fluessigkeitsmengen) und uebergibt diese Einzelmengen als
mapping "liquids" dieser Funktion. Wenn diese Funktion einen Wert ungleich
0 zurueckgibt, gilt das Ausgiessen als "genehmigt" und wird via 
"ReduceTotalAmount" ausgefuehrt. Gibt die Funktion dagegen 0 zurueck, wird
keine Fluessigkeit aus dem Behaelter entfernt und auch keine Meldung
ausgegeben.
Diese Funktion dient als "hook" zur Implementierung von speziellen
Ereignissen, die beim Ausgiessen von Fluessigkeit passieren sollen.
Per default gibt diese Funktion lediglich immer 1 zurueck.

- int DoDrink(mapping liquids);

Diese Funktion entspricht vollstaendig "DoPour", allerdings wird sie nicht
beim Ausgiessen, sondern beim Trinken aufgerufen.
Als default reicht hier allerdings { return 1; } nicht aus. Stattdessen
muessen hier alle Eigenschaften der getrunkenen Fluessigkeiten auf den
Spieler angewandt, also z.B. Lebens-, Magie- und Giftpunkte modifiziert
werden. Wenn der Spieler den Maximalwert der Saettigung oder des Alkohol-
levels beim Trinken ueberschreiten wuerde, gibt diese Funktion 0 zurueck,
sodass der Trinkvorgang nicht ausgefuehrt wird.

Bemerkung: Mit den obigen beiden Funktionen kann das "Mischverhalten" der
           Fluessigkeiten weitgehend beeinflusst werden. Per default geht
           die Flasche davon aus, dass sich die Fluessigkeiten gleichmaessig
           vermengen und beim Giessen und Trinken die Mischungsverhaeltnisse
           nicht veraendert werden. Das Mischen und Reduzieren der Fluessig-
           keitsmengen kann aber auch in DoPour bzw. DoDrink ausgefuehrt
           und dann 0 zurueckgegeben werden. Auf diese Weise lassen sich z.B.
           diese witzigen Spender fuer italienisches Salatdressing realisieren
           (Oel schwimmt oben, Essig ist unten).
           
- string StatusDescription();

gibt je nach P_BOTTLE_CLOSED den String "geoeffnet" oder "geschlossen"
zurueck. Kann ueberschrieben werden, um die Texte anzupassen.

- string FillingDescription();

gibt den Fuellstand des Behaelters zurueck. Per default teilt die Flasche
die Fuellung in Achtel ein und gibt
  "leer",
  "fast leer",
  "etwa zu einem Achtel gefuellt",
  "etwa zu einem Viertel gefuellt",
  ...
  "etwa zu sieben Achtel gefuellt",
  "fast voll",
  "voll"
zurueck. Kann ueberschrieben werden, um die Texte anzupassen.

- string ContentDescription(int magic);

gibt die Inhaltsbeschreibung des Behaelters zurueck. Per default sieht das
so aus:

a) "magic" ist 0.

Befindet sich nur eine Fluessigkeit im Behaelter (d.h. nur eine Fluessigkeit
hat eine Menge > 0), dann wird B_LIQUID_SHORT dieser Fluessigkeit
zurueckgegeben. Bei mehr als einer Fluessigkeit wird
"Eine Mischung aus mehreren Fluessigkeiten.\n" zurueckgegeben. Ist der
Behaelter leer, wird "Nichts.\n" zurueckgegeben.

b) "magic" ist 1.

Eine Liste der B_LIQUID_SHORT aller Fluessigkeiten mit Menge > 0 wird
zurueckgegeben. "Nichts.\n", wenn der Behaelter leer ist.

Bemerkung: Die Funktion "long" verwendet P_LONG, StatusDescription(),
           FillingDescription() und ContentDescription(0) um die
           vollstaendige Langbeschreibung der Flasche zusammen zu basteln.
           Durch Ueberschreiben dieser Funktionen kann das Erscheinungsbild
           des Objekts auf einfache Weise modifiziert werden.
           
Kommandos der Flasche
---------------------

- "oeffne <id>"

funktioniert nur bei P_BOTTLE_NOCLOSE==0. Setzt P_BOTTLE_CLOSED auf 0, falls
das noch nicht der Fall ist.

- "schliesse <id>"

Analog zu "oeffne".

- "entleere <id>"

Wie der Name schon sagt giesst dieser Befehl den gesamten Inhalt der Flasche
aus. Dabei wird natuerlich beruecksichtigt, ob die Flasche offen ist, falls
sie ueberhaupt verschliessbar ist. Die Funktion "DoPour" (s.o.) wird mit den
einzelnen enthaltenen Fluessigkeitsmengen aufgerufen.

- "giesse/schuette schluck aus <id>"
  "giesse/schuette <k> schluck aus <id>"
  
Genauso wie "entleere", giesst aber nur eine bestimmte Gesamtmenge an
Fluessigkeit aus dem Behaelter. <k> steht fuer "einen", "zwei", "drei" oder
eine Zahl. Die Umrechnung "schluck" in Milliliter ist durch P_BOTTLE_GULP
definiert. "DoPour" wird mit den Differenzmengen der einzelnen Fluessigkeiten
aufgerufen.

- "trinke schluck aus <id>"
  "trinke <k> schluck aus <id>"
  
Voellig analog zu "giesse", es wird aber "DoDrink" statt "DoPour" aufgerufen.
In "DoDrink" werden alle Auswirkungen auf den Spieler berechnet.

Wie ein bestimmter Fluessigkeitsbehaelter gefuellt werden soll, kann
/std/flasche.c naturgemaess nicht wissen. Dafuer gibt es wohl keinen
Standard. Im einfachsten Fall sollte dies aber die einzige Stelle sein,
wo man noch selbst etwas programmieren muss. Ein Beispiel ist das magische
Weinglas.

        Have the appropriate amount of fun,
        Marcel@AnderLand