Lpc Manpages

StartSequence()

FUNKTION:
     int StartSequence(mapping descr);

DEFINIERT IN:
     /std/player/sequence.c

ARGUMENT:
     descr
          Ein Mapping mit den Eigenschaften der Sequenz, die der Spieler
          sehen soll. Alle Eigenschaften ausser SEQ_SEQUENCE sind optional.
          In <sequence.h> sind folgende Eigenschaften definiert:

          SEQ_SEQUENCE
          Array, das die eigentliche Sequenz enthaelt. Es kann beliebig aus
          Elementen folgender Typen zusammengesetzt sein:
            int              Pause in Sekunden
            string           String, der an den Spieler ausgegeben wird
            ({string,string}) Der 1. String wird an den Spieler, der 2. an
                               alle anderen Lebewesen im Raum ausgegeben
            ({string})       String an alle Lebewesen im Raum
            closure          Die Closure wird ausgewertet und das Ergebnis
                               an ihrer Stelle weiterverarbeitet  (*)
            ({closure,...})  ebenso; dabei erhaelt die Closure alles ab
                               dem 2. Array-Element als Argumente
          Alle Strings werden direkt vor ihrer Ausgabe einer Bearbeitung
          unterzogen.  (**)

          SEQ_ID
          Ein beliebiger mixed-Wert, der die Sequenz identifiziert
          (default==1). Die Sequenz-ID der gerade laufenden Sequenz kann
          durch Aufruf von SequenceRunning() im fraglichen Spielerobjekt
          abgefragt werden.

          SEQ_PRIORITY
          Zahlenwert, der die Prioritaet der Sequenz angibt (default==0). 
          Sequenzen hoeherer Prioritaet koennen beim Startversuch laufende
          Sequenzen niedrigerer Prioritaet abbrechen, um selbst ablaufen zu
          koennen. Andernfalls wird die neue Sequenz schon beim Startversuch
          abgewiesen. Hinweis: Laufende Sequenzen sollten nach Moeglichkeit
          abgewartet werden, deshalb sollte diese Option nur bei triftigem
          Grund genutzt werden!

          SEQ_NO_INPUT
          Ist diese Option gesetzt, so kann der Spieler waehrend der Sequenz
          keine Befehle eingeben. Ist es ein String, so wird dieser beim
          Eingabeversuch als Fehlermeldung an den Spieler ausgegeben
          (anstelle einer Standard-Fehlermeldung). Ist es eine Closure, so
          wird sie beim Eingabeversuch ausgewertet und ihr der Eingabestring
          als Argument uebergeben. Ihr Ergebnis wird wie ein normaler Wert
          weiterverarbeitet, man kann also z. B. mit dem Rueckgabewert 1 die
          Ausfuehrung des Befehls blockieren.

          SEQ_END_FUNC
          Ist diese Option mit einem String oder einer Closure besetzt, so
          wird die angegebene Funktion am Ende der Sequenz aufgerufen,
          unabhaengig davon, ob sie planmaessig auslief oder abgebrochen
          wurde. Ist es ein String, so wird die Funktion in demjenigen
          Objekt aufgerufen, das die Sequenz gestartet hat; Closures
          unterliegen dieser Einschraenkung nicht. - Als erstes Argument
          wird eine der folgenden Integerzahlen uebergeben, die die
          Abbruchursache angibt:
            0                = Sequenz regulaer beendet
            SEQ_OVERRIDDEN   = Start einer neuen Sequenz erzwang Abbruch
            SEQ_OBJ_LOST     = aufrufendes Objekt nicht mehr vorhanden
                                 (siehe auch Eigenschaft SEQ_NEED_OBJ)
            SEQ_PLAYER_LOST  = Spieler nicht mehr zur Aufnahme der Sequenz
                                 faehig (z. B. durch Tod) 
            SEQ_UNSTABLE     = Instabilitaet (call_out verloren)
            SEQ_UNKNOWN      = sonstiger Fehler
          Als weitere Argumente werden die Array-Elemente von SEQ_END_ARGS
          uebergeben, falls vorhanden.

          SEQ_END_ARGS
          Der hierin enthaltene Wert wird der SEQ_END_FUNC als 2. Argument
          uebergeben. Ist es ein Array, dann werden seine Elemente als 2.,
          3. usw. Argument expandiert.

          SEQ_FAIL_MSG
          Mapping, das zu den einzelnen Abbruchursachen (siehe SEQ_END_FUNC)
          Strings definiert, die im jeweiligen Fehlerfall dem Spieler
          angezeigt werden. Die meisten Felder sind mit Standardmeldungen
          vorbelegt. Strings, die nicht mit '\n' enden, werden vor der
          Ausgabe einem break_string() unterzogen.

          SEQ_CALLING_OBJ
          Das Objekt, das die Sequenz gestartet hat. Diese Eigenschaft wird
          von StartSequence() automatisch richtig gesetzt und kann
          weggelassen werden.

          SEQ_NEED_OBJ
          Wenn diese Option gesetzt ist, bricht die Sequenz ab, sobald das
          sequenzaufrufende Objekt nicht mehr vorhanden ist. Was genau
          "vorhanden" heisst, haengt vom genauen Inhalt dieser Option ab:
          Inhalt:         Die Sequenz laeuft, solange...
            SEQ_EXISTING    das aufrufende Objekt existiert
            SEQ_AS_ROOM     der Spieler im aufrufenden Objekt ist
            SEQ_IN_ROOM     beide im selben Raum sind
            SEQ_CARRIED     der Spieler das aufrufende Objekt in seinem
                              Inventory hat
            SEQ_WORN        der Spieler die aufrufende Ruestung angezogen hat
            SEQ_WIELDED     der Spieler die aufrufende Waffe gezueckt haelt
          Diese Werte lassen sich mit bitweisem Oder | kombinieren. Zur
          Fortsetzung der Sequenz genuegt es, wenn nur eine der jeweils
          geforderten Bedingungen erfuellt ist. Wenn nicht, wird die Sequenz
          beendet und ggf. die in SEQ_END_FUNC angegebene Funktion mit dem
          Fehlerwert SEQ_OBJ_LOST aufgerufen.

          SEQ_NOTIFY
          Wenn diese Option mit einem String oder einer Closure belegt ist,
          wird unmittelbar vor jedem Schritt der Sequenz die angegebene
          Funktion in demjenigen Objekt aufgerufen, das die Sequenz
          gestartet hat. Zuvor wird sicherheitshalber getestet, ob das
          Objekt noch existiert. Die Closure kann theoretisch an ein anderes
          Objekt gebunden sein, aber dies wird nicht von Sicherheitschecks
          begleitet.
          Notify-Aufrufe ermoeglichen dem sequenzstartenden Objekt unter
          anderem, eigene Abbruchbedingungen zu realisieren und ggf.
          previous_object()->StopSequence() aufzurufen, wenn die
          Moeglichkeiten von SEQ_NEED_OBJ nicht ausreichen.

          SEQ_REPLACE
          Mapping mit Elementen der Form ([string:string]). Wenn Strings der
          Form "@@Schluesselstring@@" in der Sequenz auftreten, werden sie
          durch den jeweiligen Ersatzstring ersetzt. Die Ersetzung geschieht
          dynamisch erst unmittelbar vor der Ausgabe und wird auch auf
          etwaige Ergebnisstrings von Closures angewendet. Der
          Schluesselstring muss bei der Definition der Ersetzung ohne "@@"
          angegeben werden. Die Standard-Ersetzungen fuer "@@der Spieler@@",
          "@@er@@" usw. (**) koennen nicht umdefiniert werden.

BESCHREIBUNG:
     Der Spieler, in dem diese Funktion aufgerufen wird, sieht die in
     descr[SEQ_SEQUENCE] aufgelistete Sequenz.

     Die Sequenz beendet sich selbst, wenn der letzte Eintrag abgearbeitet
     ist oder ein Anlass fuer die vorzeitige Beendigung vorliegt (siehe
     StopSequence).

RUECKGABEWERT:
     1, falls der Start der Sequenz erfolgreich war, sonst 0.

BEMERKUNGEN:

     (*)   Weiterverarbeitung von Closure-Rueckgabewerten in SEQ_SEQUENCE:
           Ein Closure-Ergebnis wird nur weiterverarbeitet, wenn es eine
           Zahl, ein String oder Array of String ist. Rekursive
           Closure-Auswertung ist ausgeschlossen. Wenn keine
           Weiterverarbeitung gewuenscht wird, sollte die Closure den
           Ergebnistyp void haben.

     (**)  Automatische Verarbeitung von Strings in SEQ_SEQUENCE:
           Die Strings "@@er@@", "@@Er@@", "@@erName@@" und "@@ErName@@"
           sowie ihre deklinierten Formen werden durch das
           geschlechtsspezifische Pronomen bzw. den Namen des Spielers
           ersetzt. Dabei fuehren gross geschriebene Anfangsbuchstaben zu
           gross geschriebenem Ergebnis. Der Possessivfall kann mit
           "@@sein@@" bzw. "@@seinName@@" gebildet werden; eventuelle
           Deklination muss ausserhalb dieses Strings erfolgen, z. B.
           "@@sein@@e Tasche". Ausserdem finden evtl. benutzerdefinierte
           Ersetzungen statt (siehe SEQ_REPLACE). Die fertigen Strings
           werden automatisch mit break_string() umgebrochen, wenn sie
           nicht schon mit '\n' abgeschlossen sind.

BEISPIEL:

     // Lachkrampf starten:

     mapping myseq;
     myseq =
     ([ SEQ_SEQUENCE:
          ({ "Du brichst ploetzlich in schallendes Gelaechter aus!",
             3,
             "Du kannst Dich vor Lachen kaum noch halten!",
             2,
             "Pruuuust! Aufhoeren!",
             3,
             "Du kruemmst Dich vor Lachen und kriegst kaum noch Luft.",
             3,
             "Allmaehlich beruhigst Du Dich wieder." }),
        SEQ_NO_INPUT:
             "Das geht jetzt nicht. Du geierst Dich gerade schief und krumm.",
        SEQ_END_FUNC:
             "heilung" ]);
     this_player()->StartSequence( myseq );

     void heilung( int failure )
     {
       if (failure) return;
       this_player()->heal_self(10);
       tell_object( this_player(), "Dir wird klar: Lachen ist gesund!\n" );
     }

SIEHE AUCH:
     StopSequence, SequenceRunning, /doc/beispiele/monster/arnold.c