AOQML-Manual

Wichtig für die Bearbeitung und Darstellung hier im Wiki: Es gibt ein SyntaxDarstellungssystem. Um wunderbare Beispiele anzeigen zu lassen, muss ein xml-Code lediglich von diesem Tag umschlossen sein: <code xml>...</code>. Will man dazu noch eine Zeilenanzeige, nutzt man dieses <code xml n>...</code>.

Inhaltsverzeichnis

AOQML Syntax

Das Grundprinzip von AOQML entspricht dem von HTML/XML: Texte zwischen den Tags werden grundsätzlich, d.h. ggf. unter den durch die Tags bestimmten Bedinungen, ausgegeben, also dem Spieler angezeigt. Alle Texte, die vom Programm ausgewertet werden, sind also als Attribute angegeben. Auch diese werden ggf. ausgegeben, aber eben erst nach einer Bearbeitung durch den ZB-XML-Player. Mit anderen Worten: Steuerwerte befinden sich niemals zwischen den Tags.

Tags werden in spitze Klammern eingeschlossen. Jeder Tag erfordert ein öffnendes (z. B. <challenge>) und ein schließendes Element. Schließende Elemente werden mit einem / nach der Klammer begonnen (</challenge>). Alles, was zwischen den beiden Tags steht, ist der Bedingung oder Aktion unterworfen, die das Tag bestimmt. Tags können verschachtelt werden, dabei muss darauf geachtet werden, dass die Ebenen sauber getrennt sind. Das heißt, man darf kein Tag schließen, wenn nicht alle unterhalb dieses Tags geöffneten geschlossen sind:
richtig:

<tag1>
  <tag2>
  </tag2>
</tag1>

falsch:

<tag1>
  <tag2>
  </tag1>
</tag2>

Es gibt einige Tags, die kein zweites zum Schließen erfordern. Bei diesen wird das / an das Ende gesetzt:

<set attribute="cash" inc="20"/>

Außerdem kann man eine Szene (beispielsweise nach einem include oder choice, das zu einer Abzweigung führt) vorzeitig abbrechen lassen, wenn folgender Code eingegeben wird:

<quest status="continue" />

Aufbau der XML-Datei

link: Beispiel einer Zufallsbegnung in aoqml zur Veranschaulichung

Grundgerüst

Jede Datei muss mit diesem Grundgerüst beginnen:

<?xml version="1.0" encoding="UTF-8"?>
<scene xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xsi:noNamespaceSchemaLocation="http://spiel.antamar.org/Antamar/xml/aoqml/aoqml.xsd">
...
</scene>

Erst wird der Inhalt der datei als XML nach Sprachversion 1.0 definiert, danach folgt das Tag <scene>...</scene>. Außerhalb dieses Tags darf nichts stehen, mit Ausnahme der XML-Definition und Kommentare, die wie folgt gemacht werden können:

<!-- hier folgt eine Erklärung -->

Formatierung

Für bessere Lesbarkeit und Übersicht bitte alle Ebenen um zwei Stellen (zwei Leerzeichen) gegenüber der darüber liegenden Ebene einrücken:

<Ebene1>
  <Ebene2>
    <Ebene3>
      <Ebene4>
      </Ebene4>
    </Ebene3>
  </Ebene2>
</Ebene1>

Zeichensatz

Im Kopf der Datei wird als Kodierung UTF-8 festgelegt. Das muss dann auch eingehalten werden. Das lässt sich in den (Speichern-)Optionen eures Editors einstellen. (Kodierung, Format, Zeichensatz oder wie auch immer das benannt ist.) Ohne BOM (Byte Order Mark).

Sonstige Formalitäten

Einrückungen immer zwei Leerzeichen
keine Zeilenumbrüche im Text

AOQML-Tags

Bisher können folgende Tags benutzt werden (alphabetische Liste):

action - Aktionen die den Helden betreffen, z.B. Annahme einer Arbeit / Einsperren im Kerker
case - für Fallunterscheidungen → switch und Zufallsauswahlen → random
challenge - für Proben auf Talente und Eigenschaften
chat - für das Einbinden eines Chatfensters.
choice - gibt dem Spieler verschiedene Auswahlmöglichkeiten vor
countdown - zeigt an, wie lange eine Variable noch besteht
defeat - Kampfergebnis: Held besiegt → fight
delay - Reise des Helden verzögern
desc - Liefert eine Beschreibung
drop - Gegenstand aus Ausrüstungsliste entfernen
eval - Tag zum berechnen einfacher und komplexer mathematischer Funktionen
else - Fallunterscheidungen: Default-Option → switch
escape - Kampfergebnis: Held flüchtet → fight
exists - zur Prüfung, ob ein Gebäude/Raum an der aktuellen Questlocation existiert
failure - Prüfergebnis / Probe negativ → challenge, has
fetch - gespeicherten Wert abrufen → store
fight - Kampf
function - spezielle Funktionen
get - Attribute des Helden abfragen
Gott - "Übersetzt" den namen einer Gottheit in eine Glaubensrichtung
has - auf vorhandene Ausrüstung und Talente prüfen
if - für bedingte Text- oder Wertauswahl
img- um Bilder einzubinden
include - andere Questdateien einbinden
item wählt ein zufälligen Gegenstand aus der DB
inventar- Tag der verschiedene Gegenstände in sich speichert um z.B. Truhen oder ähnliches zu simulieren.
paths - geografische Richtungsnavigation
q - wörtliche Rede
quest - zur Steuerung der Queste, z. B. um eine Quest als (noch nicht) abgeschlossen zu markieren
random - Zufallsauswahl
restrict - Stellt sicher das bestimmte AOQML-Teile nur einmal pro Held ausgeführt werden.
replay - gespeicherte Aktionsfolge abrufen → retain
retain - Aktionsfolge speichern → replay
reverse - Held muss an den zuletzt besuchten Ort zurückkehren
rivals - im Kampf Gegner festlegen
scene - oberstes Tag, definiert Beginn und Ende der XML-Datei
select - Auswahl eines/mehrerer Helden bei Gruppenbegegnungen
set - Werte des Helden verändern
store - Wert speichern um später darauf zugreifen zu können → fetch
success - Prüfergebnis / Probe positiv → challenge, has
switch - Fallunterscheidung
take - Gegenstand in die Ausrüstungsliste legen
victory - Kampfergebnis: Gegner durch Held besiegt

Weiter können auch die üblichen (X)HTML-Tags verwendet werden, um Text zu formatieren. Es kann z. B. das HTML-<p>-Tag verwendet werden, um Textabsätze zu erzeugen. Der <q>-Tag sollte für wörtliche Rede benutzt werden. Anderes XHTML sollte aber sparsam verwendet werden, um das CSS-Design von Antamar berücksichtigen.

Sonstiges

Besondere Werte (Würfelergebnisse berechnen, Zufall und Wahrscheinlichkeit, ..)

Zufälligen Gegenstand aus der Datenbank auswählen
s. item-Tag

Zählen

Beispiel eines AOQML-Zahlencounter zum zählen von irgendwas.

Zufallsauswahl aus mehreren Möglichkeiten

Will man z.B. einen von mehreren Gegenständen einer Liste abfragen, muss man einfach nur eine normale Abfrage wie bei einem Gegenstand machen und jeweils ein | zwischen die unterschiedlichen Namen setzen. Sollte auch bei Gegnern, Waffen oder anderem klappen. Beispiele: <take item="Einfacher Holzbecher|Schere|Hartwurst"/> (für variable Beutestücke) <set quality="cash" inc="200|300|400|500"/> (wenn man genau 2, 3, 4 oder 5 D vergeben will)

So einfach ist es leider nicht! Die Auswahl mit dem "|" funktioniert nur für zwei Möglichkeiten. Für mehrere muss man einen <random>-Block vorschalten:

<random>
 <case><store name="Gegenstand">Holzkamm</store></case>
 <case><store name="Gegenstand">Dolch</store></case>
 <case><store name="Gegenstand">Amboss</store></case>
</random>
<take item="${Gegenstand}"/>

--Handborons 18:33, 24. Jul. 2008 (CEST)

ODER und UND

Will man prüfen, ob der Held einen von mehreren möglichen Gegenständen bei sich trägt, kann man das mit dem Operator "|" erreichen:

<has item="Messer|Dolch|Schwert">
 <success>
  Entweder Messer oder Dolch oder Schwert vorhanden.
 </success>
 <failure>
  Weder Messer noch Dolch noch Schwert vorhanden.
 </failure>
</has>

Siehe oben - die ODER-Abfrage mit "|" funktioniert vorerst nur mit zwei Optionen. --Handborons 10:18, 2. Okt. 2008 (CEST)

Man kann auch auf überprüfen, ob mehrere Gegenstände vorhanden sind:

<has item="Messer+Dolch">
 <success>
  Messer und Dolch vorhanden.
 </success>
 <failure>
  Entweder nur Messer oder nur Dolch oder keins von beiden vorhanden.
 </failure>
</has>

nützliche Listen

Wohin mit fertigen Questen?

Fertige Questen, also vollständige Bündel von vielen durchgesehenen und korrekt codierten Dateien bitte gezippt an Athuran schicken. --Athuran 13:05, 23. Jul. 2008 (CEST)

AntamarWiki β