Bearbeiten von „Projekt:Adventure 2.0/Autoren-Handbuch/Scripting-Anleitung“

Bei Fragen oder Problemen am besten an [[Kamel:J*]] wenden, der das hier alles verbockt hat.
----
<div class="beispiel">'''Tipp:'''<br/> Hier rechts in der Spalte findest du zu vielen Dingen echte Beispiele aus dem Adventure 2.0</div>

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 [http://www.maschek.hu/imagemap/imgmap]. 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!

[[Kategorie:Adventure 2.0|Scripting-Anleitung]]
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, malt der Parser die Zeile rot an und schreibt drunter, was das Problem ist. Der Pfeil ↑ zeigt dabei (meistens) auf das erste fehlerhafte Wort.

==Ereignisse in A2l==
<div class="beispiel">[[Projekt:Adventure 2.0/2|Beispiel]]</div>
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:
;<code>enter(<page>)</code>
:ausgelöst beim Betreten einer Seite oder beim Laden eines Spielstands
;<code>leave(<page>)</code>
:ausgelöst vor dem Verlassen einer Seite - Vorsicht, vielleicht noch mit Nebeneffekten verbunden
;<code>click(<region>)</code>
:ausgelöst beim Klicken auf eine Region auf der Spielseite
:hier ohne das "#"-Zeichen
:Die Regionen für die Pfeile aus dem Bild raus heißen: _l (links), _r (rechts), _u (oben), _d (unten)
;<code>activate(<item>)</code>
:ausgelöst beim Klicken auf ein Item
;<code>combine(<item1>, <item2>)</code>
:ausgelöst, wenn Item1 auf Item2 gezogen wird
:drag&drop). Hier ist es oft sinnvoll auch <code>combine(<item2>, <item1>)</code> zu verwenden, so dass man auch mit dem anderen Item anfangen kann
;<code>apply(<item>, <region>)</code>
:ausgelöst, wenn das Item auf eine Bildregion gezogen wird
;<code>add(<item>)</code>
:ausgelöst beim Hinzufügen des Items zum Inventar
;<code>remove(<item>)</code>
:ausgelöst beim Entfernen des Items aus dem Inventar

Die Platzhalter sind durch die Namen der Items/Seiten/Regionen zu ersetzen. Es können auch mehrere Trigger, per Komma getrennt, angegeben werden; das Ereignis tritt dann bei jedem der angegebenen 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:
;<code>page(<page>)</code> oder <code>page(@<pageclass>)</code>
:der Spieler muss sich auf der angegebenen Seite aufhalten
;<code>have(<item>)</code> oder <code>have(:<itemclass>)</code>
:der Spieler muss das angegebene Item im Inventar haben
;<code>any(...)</code>
:wahr wenn irgendeine der durch Komma getrennten Bedingungen wahr ist
;<code>all(...)</code>
:wahr wenn alle der durch Komma getrennten Bedingungen wahr sind
;<code>not(...)</code>
: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:
; <code>goto(<page>)</code>
:Auf eine andere Spielseite wechseln
;<code>add(<item>)</code>
:Ein Item hinzufügen
:<code>remove(<item>)</code>
:Ein Item entfernen
;<code>print("<text>")</code> oder <code>print('<text>')</code>
:Text ausgeben. Für wörtliche Rede kannst du die deutschen Anführungszeichen innendrin verwenden (die findest du rechts in den Klick-Sonderzeichen)
:Beispiel: <code>do print("Dort steht: „Eintritt strengstens erlaubt.“");</code>
;<code>setTimeout(<sekunden>)</code>
: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.
:Beispiel: <code>do setTimeout(20), print("Dieser Text wird erst nach 20 Sekunden ausgegeben");</code>
;<code>clearTimeout()</code>
:Den Timer abbrechen
;<code>showOverlay(<overlay>)</code> und <code>hideOverlay(<overlay>)</code>
:Overlays anzeigen oder ausblenden. ({{s}} [[#Overlays|Absatz zu Overlays]])
;<code>ask("<Frage?>", <sect>="<text>", …)</code>
:Frage den Benutzer was er tun will, oder bau einen Dialog zusammen: Hinter der Frage können mehrere mit Komma getrennte Optionen angegeben werden. <sect> gibt den Namen für die Option an <text> ist der Text, der dem Benutzer für die Option angezeigt wird. Die Namen können dann mit <code>click(…)</code> benutzt werden wie Bildregionen. Statt der doppelten können auch hier wieder einfache Anführungszeichen verwendet werden.
:Beispiel: <code>do ask("Was möchtest du malen?", optkamel="Ein Kamel natürlich!", optoase="Eine Oase.");</code>
;<code>play(<channel>, "<audiodatei>")</code> und <code>stop(<channel>)</code>
:Musik und Geräusche im Adventure steuern. ({{s}} [[#Audio|Audio]]) 

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

==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 [http://kamelopedia.net/index.php/Projekt:Adventure_2.0?debug=1 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 <code>// Kommentar </code> (bis zum Ende der Zeile) oder <code>/* Kommentar */</code> (geht auch innerhalb einer Zeile oder über mehrere Zeilen).

==Für Fortgeschrittene==

===Audio===
Anders als in der restlichen Kamelopedia bitte nicht mit dem Widget einbinden – denn im Adventure 2.0 gibt es drei getrennte Audiokanäle, die vom Spieler einzeln an- und ausgeschaltet werden können: Musik, Hintergrunz und Geräusche.

====Beispielcode====
Im Code sind die englischen Bezeichnungen zu verwenden:
 event;
   on enter(23);
   do play(music, "Adventure Soundtrack.oga");
   end.

====Musik-Kanal (music)====
Hier kommt Hintergrundmusik rein. Musik wird immer weitergespielt: Wenn das Stück zuende ist, geht's von vorn los und die Musik bleibt bestehen, wenn man die Seite wechselt.

====Hintergrunz-Kanal (background)====
Gedacht für Hintergrundgeräusche der Szenerie, also Geräusche, die es in der Spielwelt tatsächlich gibt: Donnergrollen, Insektensummen, Livemusik. Auch Hintergrunz wird im Endlosdurchlauf gespielt. Wenn man die Seite wechselt, hören die Geräusche auf.

Es empfiehlt sich den Musikkanal anzuhalten, damit die Geräusche auch richtig zur Geltung kommen:

 event;
   on enter(27);
   do stop(music), play(background, "audio.oga");
   end.

====Geräusche-Kanal (noise)====
Was in diesen Kanal reinkommt, wird nur ein einziges mal abgespielt. Gedacht für kurze Töne oder Geräusche, die durch Dinge verursacht werden, die passieren, oder die der Spieler tut: Zersplitterndes Glas, ein platzender Autoreifen, Klicken eines Lichtschalters.

===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 <code>have(:light)</code> 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 <code>page(@underwater)</code> 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: <code>remove(:light);</code>

In den meisten Triggern lassen sich ebenfalls Klassen verwenden. Um das triggernde Item zu entfernen kann in der Action die Syntax <code>remove(${<triggerfunktion><index>})</code> 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. Es werden dann nur so viele Overlays benötigt, wie Gegenstände auf der Seite sind.

Overlays werden mit der [[Vorlage:Adventure2/Overlay]] eingefügt:

 <nowiki>{{Adventure2/Seite</nowiki>
  |bild=...
  |bereiche=
 ...
  |overlays=
 <nowiki>{{Adventure2/Overlay|<id>|<css>|<content>}}</nowiki>
  |left= |right= |up= |down=
  |code=
 ...
 }}

Der Parameter <code><id></code> steht für den Namen des Overlays, <code><css></code> für die css-Angaben: hier sollten mindestens <code>left</code> (oder <code>right</code>) und <code>top</code> (oder <code>bottom</code>) gesetzt werden, vielleicht auch noch <code>display: none</code>. <code><content></code> ist der Inhalt des Overlays. Beispiel:
 <nowiki>{{Adventure2/Overlay|hammer|right:70px; bottom: 0px; display: none;|[[Datei:Hammer.png|link=]]}}</nowiki>

Das [[:Bild:Hammer.png]] enthält dann den anzuzeigenden Inhalt, d.h. hier den Hammer, so wie er im Bild dargestellt werden soll, natürlich mit transparentem Hintergrund. Da für jedes Overlay auch ein Klick-und-drop-Bereich definiert wird, sollten keine breiten transparenten Ränder usw. im Bild sein und der Bereich auch nicht unnötig mit <code>width</code> oder <code>height</code> groß gemacht werden.

Für Overlays gibt es zwei eigene Aktionen: <code>showOverlay(<id>)</code> und <code>hideOverlay(<id>)</code>, mit denen sich Overlays anzeigen oder verstecken lassen. 

Ist <code>display:none</code> nicht gesetzt, so wird das Item beim Betreten der Seite angezeigt, ansonsten nicht. Wenn beides möglich sein soll (z.B. je nachdem, ob der Spieler das Item schon im Inventar hat), kann man <code>display:none</code> zunächst setzen, und wenn nötig, das Overlay beim Betreten der Seite einblenden:

 event enter;
   on enter(30);
   if not(have(hammer));
   do showOverlay(hammer);
   end.

Am Rande sei noch bemerkt, dass sich mit Overlays, etwa zusammen mit Widgets, auch andere Dinge realisieren lassen, wie z.B. Eingabefelder.

===Pseudo-Items (Zustände) ===
Items, die mit einem Unterstrich beginnen, sind Pseudo-Items. Das bedeutet, sie werden nicht unten im Inventar angezeigt, codieren dafür aber irgendeinen Zustand. Der Spieler sieht sie also nicht, von der Scripting-Seite her lassen sie sich aber verwenden wie ganz normale Items. 

Pseudo-Items machen das Adventure kompliziert: Bitte daher nur dort benutzen, wo es wirklich Sinn ergibt. Bitte dokumentiere im Quellcode mit <span style="white-space: nowrap">/* Kommentaren */</span> ausführlich, was das Pseudo-Item codiert, und wann das Pseudo-Item benutzt wird und warum der Zustand überhaupt nötig ist. Denk dran, dein Item wird niemand je zu Gesicht bekommen, achte also darauf, dass spieltechnisch Sinn ergibt, dass sich der Zustand ändert. 

Auch muss nicht jede Änderung im Adventure gespeichert werden: Es ist relativ egal, wenn eine vom Spieler geöffnete Tür später wieder zu ist (zumindest wenn sie sich einfach wieder öffnen lässt), die Tür braucht also keinen eigenen Status. Und die sich daraus ergebenden Inkonsistenzen schieben wir einfach auf den Hausmeister …

==Links==
{{s}} [http://kamelopedia.net/index.php/Projekt:Adventure_2.0?debug=1 Debug-Version], [[Projekt:Adventure_2.0/Übersicht|Seiten- und Itemübersicht]]<br/>
{{sa}} [[:Kategorie:Commons:_Adventure2-Item|Items-Bilder]], [[:Kategorie:Commons:_Adventure2-Seite|Seiten-Bilder]] <br/>
{{s|Zurück}} [[Projekt:Adventure_2.0/Autoren-Handbuch|zum Autorenhandbuch]] | [[Projekt:Adventure_2.0|zur Projektseite]]