Projekt:Adventure 2.0/Autoren-Handbuch/Scripting-Anleitung

Bei Fragen oder Problemen am besten an Kamel:J* wenden, der das hier alles verbockt hat.

---

Im Adventure2 gibt es 2 Arten von Unterseiten: Die Spielseiten und die Item-Seiten:

Spiel- und Item-Seiten

Die Spielseiten werden (mehr oder weniger fortlaufend) durchnummeriert. Bitte die Vorlage:Adventure2/Seite verwenden! Das Bild sollte 550x300px groß sein, oder zumindest das richtige Seitenverhältnis haben. Mit Hilfe der imagemap-Extension können da drin auch gleich Bereiche definiert werden, mit denen man später irgendwas anstellen können soll. Dabei werden einfach die Links so gesetzt, dass sie nicht auf eine Wikiseite zeigen, sondern stattdessen mit "#" beginnen, gefolgt von irgendeinem Bezeichner. Wie auch sonst fast für alles, sind als einzige Zeichen für den Bezeichner die Kleinbuchstaben und der Unterstrich erlaubt.

Ein guter Online-Editor für das Zeug ist [1]. Den Code findet man dann unten auf der Seite (ganz einfach bei "Code" aufklappen - ich habs da zuerst übersehen).

Die Itemseiten heißen einfach "item/" gefolgt vom Namen des Items in Kleinbuchstaben. Auch auf die Itemseite gehört ein Bild (50x50 Pixel oder wenigstens quadratisch, wenn's geht transparent). Bitte die Vorlage:Adventure2/Item verwenden! Auf beiden Seitenarten können hinter dem Bild Ereignisse (sog. Events) festgelegt werden, die steuern, wie sich der Spieler durch's Adventure bewegen kann. Ereignisse sollten immer auf der Seite platziert werden, zu der sie gehören. Ereignisse auf Spielseiten können nur aufgerufen werden, wenn der Spieler sich auf der entsprechenden Seite befindet, Ereignisse auf Itemseiten nur dann, wenn der Spieler das Item besitzt.

Ereignisse

Die Ereignisse Werden mit der Vorlage:A2Event eingebunden. Da hinein kommt dann der Text für die Ereignis-Definition in der extra dafür entwickelten Mini-Programmiersprache A2l. Beim Drücken auf Vorschau und nach dem Abspeichern wird der Programmcode auf der entsprechenden Spiel- oder Itemseite ausgegeben. Wenn alles geklappt hat, steht dort der Code genau so wie er eingegeben wurde. Wenn etwas schief gegangen ist, fügt der Parser hinter das "end." eine zusätzliche Zeile mit der Fehlerbeschreibung an.

Ereignisse in A2l

Das Grundgerüst eines Ereignisses sieht etwa so aus:

event [name];
  on <trigger>;
 [if <condition>;]
 [do <action>;]
  end.

Die spitzen und eckigen Klammern gehören nicht wirklich da hin: die spitzen (<>) signalisieren einen Platzhalter, die eckigen ([]) bedeuten, dass der Inhalt darin auch weggelassen werden kann, wenn er nicht gebraucht wird.

Event-Name

Man darf jedem Event einen Namen geben. Das ist vor allem nützlich, um anderen sagen zu können, um welches Event es geht, oder für die Fehlersuche. Der Eventname darf aus beliebigen Kleinbuchstaben und Unterstrichen bestehen.

Trigger

Es können ein oder mehrere Trigger definiert werden, die festlegen, was der Auslöser für das Ereignis sein soll. Möglich sind dabei:

• enter(<page>) (ausgelöst beim Betreten einer Seite oder beim Laden eines Spielstands)
• leave(<page>) (ausgelöst vor dem Verlassen einer Seite - Vorsicht, vielleicht noch mit Nebeneffekten verbunden)
• click(<region>) (ausgelöst beim Klicken auf eine Region auf der Spielseite (hier ohne das "#"-Zeichen))
• activate(<item>) (ausgelöst beim Klicken auf ein Item)
• combine(<item1>, <item2>) (ausgelöst, wenn Item1 auf Item2 gezogen wird (drag&drop). Hier ist es oft sinnvoll auch combine(<item2>, <item1>) zu verwenden, so dass man auch mit dem anderen Item anfangen kann)
• apply(<item>, <region>) (ausgelöst, wenn das Item auf eine Bildregion gezogen wird)

Die Platzhalter sind durch die Namen der Items/Seiten/Regionen zu ersetzen.

• add(<item>)
• remove(<item>)

Es können auch mehrere Trigger, per Komma getrennt, angegeben werden; das Ereignis tritt dann bei jedem der Trigger ein.

Condition

Manchmal sollen bestimmte Voraussetzungen erfüllt sein, damit das Ereignis auch tatsächlich durch den Trigger ausgelöst wird. Das können sein:

• page(<page>) oder page(@<pageclass>) (der Spieler muss sich auf der entspr. Seite aufhalten)
• have(<item>) oder have(:<itemclass>)(der Spieler hat das entspr. Item)
• any(...) (wahr wenn irgendeine der durch Komma getrennten Bedingungen wahr ist)
• all(...) (wahr wenn alle der durch Komma getrennten Bedingungen wahr sind)
• not(...) (wahr wenn die Bedingung innen falsch ist und anders herum)

Wenn keine Bedingung gebraucht wird, kann sie weggelassen werden.

Action

Das was dann passieren soll, wird durch eine oder mehrere, mit Komma getrennte, Aktionen angegeben:

• goto(<page>) (auf eine andere Spielseite wechseln)
• add(<item>) (ein Item hinzufügen)
• remove(<item>) (ein Item entfernen)
• print("<text>") oder print('<text>') (Text ausgeben)
• setTimeout(<sekunden>) (Starte den Timer und führe alle Aktionen die danach kommen erst aus, wenn der Timer durchgelaufen ist. Wenn der Timer vorher gestoppt wird oder die Seite verlassen wird, werden die Dinge danach nicht ausgeführt. Wenn schon ein Timer läuft mach gar nix.)
• clearTimeout() (Timer abbrechen)

Die Aktion kann weggelassen werden, was allerdings nicht so richtig viel Sinn macht (dann lieber weg mit dem ganzen Ereignis).

Für Fortgeschrittene

Seiten- und Itemklassen

Ich benutze hier einfach mal ein Beispiel:

Manchmal hat man Seiten oder Items die sich aus irgendeinem Grund ähnlich verhalten. Geht man etwa in einen dunklen Raum wird es dann hell, wenn man ein Licht dabei hat - egal ob Fackel oder Taschenlampe. Dafür kann man dann den Items Fackel und Taschenlampe eine gemeinsame Klasse zuweisen, indem man auf die Itemseiten schreibt:

item;
  provides :light;
  end.

Weitere Klassen würde man einfach mit Komma getrennt dahinter schreiben. Die Itemklasse kann man dann auf der entsprechenden Spielseite in der Condition mit have(:light) abfragen.

Andersherum gibt es natürlich auch bestimmte Items, die sich in bestimmten Umgebungen anders verhalten - z.B. kann man unterwasser die Fackel nicht anmachen. Dafür kommt dann auf die Spielseite:

page;
  provides @underwater;
  end.

Die lässt sich dann in der Condition auf der Itemseite mit page(@underwater) wieder abfragen.

Auch die remove-Funktion unterstützt die Angabe einer Klasse - in dem Fall werden dann alle Elemente entfernt, die auf die Klasse passen: z.B: remove(:light);

In den meisten Triggern lassen sich ebenfalls Klassen verwenden. Um das triggernde Item zu entfernen kann in der Action die Syntax remove(${<triggerfunktion><index>}) verwendet werden - <triggerfunktion> ist dann add/remove/activate etc. und index die Nummer des Operanden (eigentlich immer 1, außer bei combine, da ist auch die 2 möglich). Passt die angegebene Triggerfunktion nicht, dann passiert einfach stattdessen nichts. Beispiel:

event;
  on activate(:light);
  if page(4);
  do remove(${activate1}), print("Du versuchst Licht zu machen, aber im Dunkeln ist das extrem schwierig. Deine Lampe fällt dir dabei auf den Boden und geht kaputt.");
 end.

Overlays

Overlays ermöglichen das hinzufügen und wegnehmen von Objekten auf einer Seite - das können Gegenstände sein, oder aber irgendwas ganz anderes. Warum das nötig ist zeigt folgendes Beispiel: In einem Raum sollen 6 Gegenstände vom Spieler in beliebiger Reihenfolge aufgenommen werden können. Wenn man das versucht, mit einzelnen Seiten umzusetzen braucht man eine für jede Kombination von noch vorhandenen Gegenständen: also 2^6 = 64. Damit das nicht sein muss, platziert man alle Gegenstände mit Overlays auf der Seite.

Diese Geschichte/Dieses Märchen ist hier noch nicht zuende erzählt. Hat jemand Lust, hier weiter zu schreiben? []Bücherregal

Wie das genau geht, werde ich hier in Kürze noch ausführlich dokumentieren. Ein (vielleicht nicht ganz so gutes) Beispiel kann man sich schon mal auf Seite 30 ansehen.

Testen

Ob der eigene Code zumindest syntaktisch okay ist, kann man schon in der Vorschau sehen. Wenn einfach nur der Code (mit Zeilennummern) angezeigt wird, ist alles gut gegangen; wenn eine Zeile rot markiert wurde, hat der Parser dich nicht verstanden. Schau dir in dem Fall die Fehlermeldung an (steht in blauem Text unter der roten Zeile) und korrigiere deinen Code.

Anschließend kannst du dir dann anschaun, wie sich deine Seiten und Dinge im Adventure verhalten. Dazu benutzt du am besten die Debug-Version, da kannst du dann nämlich direkt auf bestimmte Spielseiten springen oder Items laden. Außerdem kannst du dort im Event-Log sehen, welche Trigger ausgeführt wurden (schwarz) und welche Events dadurch ausgelöst wurden (grün) bzw. aufgrund nicht erfüllter Bedingungen nicht ausgelöst wurden (rot+kursiv).

Kommentare

Code kann kommentiert werden, so dass andere Autoren wissen warum da irgendwas so gemacht wurde, wie es gemacht wurde. Kommentare sind im C/C++-Style, das heißt an beliebiger Stelle entweder // Kommentar (bis zum Ende der Zeile) oder /* Kommentar */ (geht auch innerhalb einer Zeile oder über mehrere Zeilen).

Links

[] Debug-Version
 Siehe auch:  Items-Bilder, Seiten-Bilder
[] zum Autorenhandbuch | zur Projektseite